Quickstart¶

This page walks through the full workflow from a MESA template directory to a loaded combined_history.hdf5 ready for analysis.

1. Prepare a Template Directory¶

Create a directory containing your compiled MESA executables and inlists:

my_grid/
├── inlist_template       # MESA inlist with placeholder parameter values
├── inlist                # top-level MESA inlist (calls inlist_project)
├── inlist_pgstar         # pgstar settings (pgstar_flag = .false. recommended)
├── history_columns.list
├── profile_columns.list
├── rn                    # compiled MESA run script
├── star                  # compiled MESA binary
└── mk                    # MESA build script

See examples/inlist_template for a reference inlist showing the expected placeholder format. For details on the required format and disk space expectations, see Output Structure.

2. Preview the Grid (Dry Run)¶

Always do a dry run first — it’s instant and shows exactly what will be built:

python -m generate_star_grid.grid_utils \
    --mass 0.7:1.2 \
    --initial_Z 0.014 \
    --grid_type linear --num_points 16 \
    --dry_run

Check the model count, estimated disk usage, and example directory names before committing to a full run.

3. Run the Grid¶

Local (small grids / testing)

python -m generate_star_grid.grid_utils
–mass 0.7:1.2
–initial_Z 0.014
–grid_type linear –num_points 16
–max_workers 4

SLURM array job

Submit as a SLURM array — –array must match –num_points (0-N for N+1 points)

sbatch –array=0-499 run_array.sh

Multi-batch (large grids)

Sweep mass as inner parameter over 10 metallicities as outer batches

python -m generate_star_grid.submit_grid start
–source_dir /path/to/my_grid
–queue_file /path/to/queue.json
–outer ‘initial_z=0.001,0.002,0.005,0.01,0.014,0.02,0.025,0.03,0.035,0.04’
–inner ‘mass=0.7:1.2’
–grid_type linear –num_points 500

For SLURM runs, see Basic Usage for the full array script template. For grids too large to keep on disk at once, see Advanced Usage.

4. Combine into HDF5¶

Once all MESA runs finish, combine the per-track history.data files:

python -m generate_star_grid.make_grid \
    --parent_dir /path/to/my_grid \
    --constants M Y Z alpha \
    --save

This writes combined_history.hdf5 into the grid directory. For multi-batch grids run via submit_grid, this step runs automatically at the end of each batch.

5. Load and Analyse in Python¶

import pandas as pd

df = pd.read_hdf("/path/to/my_grid/combined_history.hdf5", key="history")

# Each unique integer in the Track column identifies one stellar evolution track
print(df["Track"].nunique(), "tracks")
print(df.columns.tolist())

# Select a single track
track = df[df["Track"] == 0]

# Plot an HR diagram
import matplotlib.pyplot as plt
for tid, grp in df.groupby("Track"):
    plt.plot(grp["log_Teff"], grp["log_L"], lw=0.5, alpha=0.5)
plt.gca().invert_xaxis()
plt.xlabel("log Teff"); plt.ylabel("log L")
plt.tight_layout(); plt.show()

See Post-Processing for more on the HDF5 structure and how to work with the data.