MESA Grid Directory Scanner

mesalab.analyzis.grid_analyzer.analyze_mesa_grid_directory(grid_root_path, mesa_output_subdir='LOGS', inlist_filename='inlist', inlist_alternatives=None)[source]

Searches for MESA run directories within a given grid root path and extracts stellar mass and metallicity from their inlist files.

A valid MESA run directory is defined as a subdirectory of grid_root_path that contains the mesa_output_subdir (default: ‘LOGS’), and an inlist file from which initial_mass and initial_z can be extracted.

Parameters:

grid_root_path (str) – The root directory where multiple MESA runs are located.
mesa_output_subdir (str, optional) – Subdirectory within each run directory that indicates a valid MESA run (default: “LOGS”).
inlist_filename (str, optional) – Primary inlist filename to look for (default: “inlist”).
inlist_alternatives (list of str, optional) – Alternative inlist filenames to try if the primary is not found (default: None).

Returns:

A list of dictionaries. Each dictionary has the following keys:

’path’: full path to the MESA run directory
’mass’: float, the initial_mass from the inlist
’z’: float, the initial_z from the inlist

Return type:

list of dict

Example

>>> from mesalab.analyzis import grid_analyzer
>>> results = grid_analyzer.analyze_mesa_grid_directory(
...     "/home/user/mesa_runs/",
...     mesa_output_subdir="LOGS",
...     inlist_filename="inlist",
...     inlist_alternatives=["inlist_project"]
... )
>>> for run in results:
...     print(f"Path: {run['path']}, Mass: {run['mass']}, Z: {run['z']}")

Data Reader Module

mesalab.analyzis.data_reader.extract_params_from_inlist(inlist_path)[source]

Extract initial_mass, initial_Z, and initial_Y values from a MESA inlist file.

Handles Fortran-style scientific notation (e.g., 1.0d-2, 2.5D+1) by converting it to Python-compatible form. Returns None for missing values, with warnings logged.

Parameters:

inlist_path (str) – Absolute path to the MESA inlist file.

Returns:

A tuple (mass, z, y) where elements are floats or None: if the corresponding parameter is not found.

Return type:

tuple

Example

Assuming ‘my_run/inlist_project’ contains: initial_mass = 1.0 initial_Z = 0.014 initial_Y = 0.28

>>> from mesalab.analyzis import data_reader
>>> data_reader.extract_params_from_inlist("my_run/inlist_project")
(1.0, 0.014, 0.28)

mesalab.analyzis.data_reader.scan_mesa_runs(input_dir, inlist_name)[source]

Scan a directory for MESA run subdirectories that contain both an inlist file and history.data.

Each valid subdirectory must:

Be a direct (non-hidden) subdirectory of input_dir
Contain the specified inlist_name file
Contain a LOGS/history.data file

The function attempts to extract initial_mass, initial_Z, and initial_Y from each inlist file. Only runs with both mass and z values present are included in the output.

Parameters:

input_dir (str) – Absolute path to the main directory containing MESA run subdirectories.
inlist_name (str) – Name of the inlist file expected in each subdirectory (e.g., ‘inlist’).

Returns:

Each dictionary represents a valid MESA run and contains:

’history_file_path’ (str): Full path to the history.data file
’run_dir_path’ (str): Full path to the MESA run directory
’mass’ (float): Extracted initial_mass
’z’ (float): Extracted initial_Z
’y’ (float or None): Extracted initial_Y

Returns an empty list if no valid runs are found.

Return type:

list of dict

Example

Given a directory structure like:

/path/to/mesa_grid/
├── run_M1.0_Z0.014_Y0.28
│   ├── inlist
│   └── LOGS
│       └── history.data
└── run_M2.0_Z0.006_Y0.25
    ├── inlist
    └── LOGS
        └── history.data

>>> from mesalab.analyzis import data_reader
>>> data_reader.scan_mesa_runs("/path/to/mesa_grid", "inlist")
[
    {
        'history_file_path': '/path/to/mesa_grid/run_M1.0_Z0.014_Y0.28/LOGS/history.data',
        'run_dir_path': '/path/to/mesa_grid/run_M1.0_Z0.014_Y0.28',
        'mass': 1.0,
        'z': 0.014,
        'y': 0.28
    },
    {
        'history_file_path': '/path/to/mesa_grid/run_M2.0_Z0.006_Y0.25/LOGS/history.data',
        'run_dir_path': '/path/to/mesa_grid/run_M2.0_Z0.006_Y0.25',
        'mass': 2.0,
        'z': 0.006,
        'y': 0.25
    }
]

mesalab.analyzis.data_reader.get_data_from_history_file(history_file_path)[source]

Reads a MESA history.data file into a pandas DataFrame using NumPy’s genfromtxt.

This function handles the specific structure of MESA history.data files, which contain a few descriptive lines followed by column headers and numerical data. It attempts to parse all columns as numeric values and ensures that ‘model_number’ is an integer column, if present.

Parameters:

history_file_path (str) – The absolute path to the MESA history.data file.

Returns:

A DataFrame containing the parsed history data.: Returns an empty DataFrame if the file is missing or cannot be parsed.

Return type:

pandas.DataFrame

Exception:: If there’s an error loading or processing the file, it is logged and an empty DataFrame is returned instead.

Example

Assuming a valid ‘history.data’ file exists at the given path:

>>> from mesalab.analyzis import data_reader
>>> df = data_reader.get_data_from_history_file('/path/to/some_mesa_run/LOGS/history.data')
>>> if not df.empty:
...     print(df.head())
...     print(f"Total models: {len(df)}")
...     print(f"Columns available: {list(df.columns)}")
... else:
...     print("Failed to load history.data or file was empty.")

Data Analysis Performer

mesalab.analyzis.mesa_analyzer.perform_mesa_analysis(args, analysis_results_sub_dir, detail_files_output_dir, gyre_input_csv_name: str = 'sorted_blue_loop_profiles.csv', rsp_output_subdir: str = None)[source]

Coordinates the analysis of MESA runs, including blue loop analysis, data aggregation, and saving summary and detailed results.

Parameters:

args (argparse.Namespace) – Command-line arguments containing input_dir, inlist_name, analyze_blue_loop, blue_loop_output_type, force_reanalysis.
analysis_results_sub_dir (str) – Path to the directory for summary/cross-grid CSVs.
detail_files_output_dir (str) – Path to the directory for detailed blue loop CSVs.
gyre_input_csv_name (str) – The desired filename for the CSV containing profiles information for the GYRE workflow. Defaults to ‘sorted_blue_loop_profiles.csv’.
rsp_output_subdir (str, optional) – Base directory where MESA RSP inlists should be saved. Defaults to None, in which case the RSP inlists will be generated relative to the original MESA run directories.

Returns:

A tuple containing:

pd.DataFrame: The main summary DataFrame of analysis results.

pd.DataFrame: A combined DataFrame of detailed blue loop data for plotting
(combined_detail_data_for_plotting).

dict: A dictionary where keys are metallicities (Z) and values are
lists of full, untrimmed history DataFrames for plotting (full_history_data_for_plotting).

str: The full path to the generated GYRE input CSV file. Returns an empty string
if the CSV was not generated.

list: A list of paths to the generated RSP inlist files.

Return type:

tuple