persephone.grids#

The grids submodule provides a complete API to build and manage MESA stellar model grids, including GYRE oscillation analysis.

MESA and GYRE grid wrappers#

persephone.grids.create_grid(grid_dir, model_dir_name_template=None, mesa_version='r15140', mstar_min=1.0, mstar_max=1.2, mstar_step=0.1, z_min=0.01, z_max=0.02, z_step=None, range_mstar=None, range_z=None, default_history='persephone', default_profile='persephone', profile_columns=None, history_columns=None, parameters=None, compile_mesa=True, run_mesa=False, run_gyre=False, verbose=True, erase_existing=False, parameters_gyre=None, template_file_gyre=None, parallelise=False, nodes=2, add_details=False, rerun=False)#

Create MESA models grid with a given range of mass and metallicity.

Parameters:

  • grid_dir (str or Path object) – Directory of the grid.

  • model_dir_name_template (str) – Template to use for the model directories. If None, the template name will be mesa_model_mstar_{}_z_{} Optional, default None.

  • mesa_version (str) – MESA version installed on the system. Optional, default “r15140”.

  • mstar_min (float) – Minimal mass (in solar mass) to consider in the grid.

  • mstar_max (float) – Maximal mass (in solar mass) to consider in the grid.

  • mstar_step (float) – Mass step (in solar mass) to consider in the grid.

  • z_min (float) – Minimal metallicity to consider in the grid.

  • z_max (float) – Minimal metallicity to consider in the grid.

  • z_step (float) – Metallicity step to consider in the grid.

  • range_mstar (array-like) – Range of mass to consider (in solar mass). If provided, mstar_min, mstar_max, and mstar_step will be ignored. Optional, default None.

  • range_z (array-like) – Range of metallicity to consider. If provided, z_min, z_max, and z_step will be ignored. Optional, default None.

  • default_history (str) – Where to take the default history file: from the persephone installation (“persephone” option) or from the MESA installation (“MESA” option). Optional, default "persephone".

  • default_profile (str) – Where to take the default profile file: from the persephone installation (“persephone” option) or from the MESA installation (“MESA” option). Optional, default "persephone".

  • profile_columns (str or Path object) – MESA profile columns file to replace the one used by default by persephone. Optional, default None.

  • history_columns (str or Path object) – MESA history columns file to replace the one used by default by persephone. Optional, default None.

  • parameters (dict) – MESA inlist parameter dictionary. Keys are MESA inlist namelists, each key contains a dictionary with parameter name as keys and selected status as element.

  • compile_mesa (bool) – Whether to compile MESA or not. Optional, default True.

  • run_mesa (bool) – Whether to run MESA or not. Optional, default False.

  • run_gyre – Whether to run GYRE on the computed MESA profiles or not. run_mesa needs to be set to True for this option to have effects. Optional, default False.

  • verbose (bool) – Output verbosity.

  • erase_existing (bool) – If set to True, existing model directories will be erased when existing, otherwise they will be ignored. Optional, default False.

  • parameters_gyre (dict) – Dictionary of parameters to add to the GYRE input file. Optional, default None.

  • template_file_gyre (dict) – Template GYRE input file to replace the one used by default by persephone. Optional, default None

  • parallelise (bool) – Whether to run the MESA and GYRE runs in parallel through pathos.multiprocess. Optional, default False.

  • nodes (int) – Number of nodes used in pathos.multiprocess.ProcessPool when parallelise=True. Optional, default 2.

  • add_details (bool) – Add a GYRE details output file template if set to True and create details output directories together with the GYRE input files.

  • rerun (bool) – If set to True, MESA and GYRE will be rerun in directories where they have already been run.

persephone.grids.compile_grid(grid_dir, verbose=True)#

Compile MESA in model directories.

Parameters:

  • grid_dir (str or Path object) – Directory of the grid.

  • verbose (bool) – Output verbosity.

persephone.grids.run_grid(grid_dir, verbose=True, rerun=False, parallelise=False, nodes=2)#

Run MESA in model directories. Directories with run_mesa_done metadata set to True will be re-run only if rerun is set to True.

Parameters:

  • grid_dir (str or Path object) – Directory of the grid.

  • verbose (bool) – Output verbosity.

  • rerun (bool) – If set to True, MESA will be rerun in directories where it has already been run.

  • parallelise (bool) – Whether to run the MESA and GYRE runs in parallel through pathos.multiprocess. Optional, default False.

  • nodes (int) – Number of nodes used in pathos.multiprocess.ProcessPool when parallelise=True. Optional, default 2.

persephone.grids.analyse_grid_gyre(grid_dir, template_file=None, parameters=None, verbose=True, add_details=False, rerun=False, parallelise=False, nodes=2)#

Run GYRE for each profile in model directories. Directories with run_mesa_done metadata set to True will be re-run only if rerun is set to True.

Parameters:

  • grid_dir (str or Path object) – Directory of the grid.

  • template_file (dict) – Template GYRE input file to replace the one used by default by persephone. Optional, default None

  • parameters (dict) – Dictionary of parameters to add to the GYRE input file. Optional, default None.

  • verbose (bool) – Output verbosity.

  • add_details (bool) – Add a GYRE details output file template if set to True and create details output directories together with the GYRE input files.

  • rerun (bool) – If set to True, GYRE will be rerun in directories where it has already been run. Optional, default False.

  • parallelise (bool) – Whether to run the MESA and GYRE runs in parallel through pathos.multiprocess. Optional, default False.

  • nodes (int) – Number of nodes used in pathos.multiprocess.ProcessPool when parallelise=True. Optional, default 2.

MESA and GYRE individual model wrappers#

persephone.grids.create_mesa_model(path='.', model_dir='MESA_work_dir', mesa_version='r15140', default_history='persephone', default_profile='persephone', profile_columns=None, history_columns=None, parameters=None, compile_mesa=True, run_mesa=False, run_gyre=False, parameters_gyre=None, template_file_gyre=None, verbose=True, erase_existing=False, add_details=False, rerun=False)#

Create, initialise, and (optionally) run, repository for a given stellar evolution model.

Parameters:

  • path (str or Path object) – Path where to create the model directory. Optional, default “.”.

  • model_dir (str or Path object) – Name of the model directory. Optional, default MESA_work_dir.

  • mesa_version (str) – MESA version installed on the system. Optional, default “r15140”.

  • default_history (str) – Where to take the default history file: from the persephone installation (“persephone” option) or from the MESA installation (“MESA” option). Optional, default "persephone".

  • default_profile (str) – Where to take the default profile file: from the persephone installation (“persephone” option) or from the MESA installation (“MESA” option). Optional, default "persephone".

  • profile_columns (str or Path object) – MESA profile columns file to replace the one used by default by persephone. Optional, default None.

  • history_columns (str or Path object) – MESA history columns file to replace the one used by default by persephone. Optional, default None.

  • parameters (dict) – MESA inlist parameter dictionary. Keys are MESA inlist namelists, each key contains a dictionary with parameter name as keys and selected status as element.

  • compile_mesa (bool) – Whether to compile MESA or not. Optional, default True.

  • run_mesa (bool) – Whether to run MESA or not. Optional, default False.

  • run_gyre – Whether to run GYRE on the computed MESA profiles or not. run_mesa needs to be set to True for this option to have effects. Optional, default False.

  • parameters_gyre (dict) – Dictionary of parameters to add to the GYRE input file. Optional, default None.

  • template_file_gyre (dict) – Template GYRE input file to replace the one used by default by persephone. Optional, default None

  • verbose (bool) – Output verbosity.

  • erase_existing (bool) – If set to True, existing model directories will be erased when existing, otherwise they will be ignored. Optional, default False.

  • add_details (bool) – Add a GYRE details output file template if set to True and create details output directories together with the GYRE input files.

  • rerun (bool) – If set to True and the directory already existed, MESA will be rerun.

persephone.grids.analyse_gyre(star_dir, run=False, template_file=None, parameters=None, verbose=True, add_details=False, rerun=False)#

Run GYRE for the profiles in the LOGS directory of a MESA work directory.

Parameters:

  • star_dir (str or Path object) – MESA model directory.

  • run (bool) – Whether to run GYRE or to create only the input files. Optional, default False.

  • template_file (dict) – Template GYRE input file to replace the one used by default by persephone. Optional, default None

  • parameters (dict) – Dictionary of parameters to add to the GYRE input file. Optional, default None.

  • verbose (bool) – Output verbosity.

  • add_details (bool) – Add a GYRE details output file template if set to True and create details output directories together with the GYRE input files.

  • rerun (bool) – If set to True, GYRE will be rerun in directories where it has already been run. Optional, default False.

persephone.grids.compile_repository(star_dir, verbose=True)#

Compile MESA work repository.

Parameters:

  • star_dir (str or Path object) – MESA working directory to consider.

  • verbose (bool) – Output verbosity. Optional, default True.

persephone.grids.run_mesa_model(star_dir, verbose=True, rerun=False)#

Run MESA in selected repository.

Parameters:

  • star_dir (str or Path object) – MESA working directory to consider.

  • verbose (bool) – Output verbosity. Optional, default True.

  • rerun (bool) – If set to True, MESA will be run even if the status of run_mesa_done is True.

persephone convenience functions#

The functions are sorted by alphabetical order.

persephone.grids.check_metadata(star_dir)#

Check if the persephone metadata file exists

Parameters:

star_dir (str or Path object) – MESA working directory to consider.

Returns:

Return True if the file exists, False instead.

Return type:

bool

persephone.grids.get_detail_file(details_dir, n=1, l=0, m=0, detail_template=None)#

Get the path of a detail file in a directory details_dir.

Parameters:

  • details_dir (str or Path object) – Directory where GYRE details file are stored.

  • n (int) – mode order

  • l (int) – mode degree

  • m (int) – mode azimuthal number

  • detail_template (str) – Detail template of the detail files if not standard. Optional, default None.

Returns:

A tuple with the path of the file and a boolean stating if the file actually exists.

Return type:

tuple

persephone.grids.get_gyre_dir()#

Get GYRE directory path through the GYRE_DIR environment variable.

Returns:

The path stored in the GYRE_DIR environment variable.

Return type:

str

persephone.grids.get_gyre_summary(profile_name, template_filename=None)#

Get GYRE summary file path from corresponding profile name.

Parameters:

profile_name (str or Path instance) – Path to the model profile for which to recover GYRE summary path.

Returns:

The path for the GYRE summary file.

Return type:

str

persephone.grids.get_mesa_dir()#

Get MESA directory path through the MESA_DIR environment variable.

Returns:

The path stored in the MESA_DIR environment variable.

Return type:

str

persephone.grids.get_detail_file(details_dir, n=1, l=0, m=0, detail_template=None)#

Get the path of a detail file in a directory details_dir.

Parameters:

  • details_dir (str or Path object) – Directory where GYRE details file are stored.

  • n (int) – mode order

  • l (int) – mode degree

  • m (int) – mode azimuthal number

  • detail_template (str) – Detail template of the detail files if not standard. Optional, default None.

Returns:

A tuple with the path of the file and a boolean stating if the file actually exists.

Return type:

tuple

persephone.grids.get_listdir_gyre_details(star_dir, sort=True)#

Get absolute or relative list of GYRE details directories in a MESA model work directory.

star_dirstr or Path object

Path of the consider MESA working directory.

sortbool

Returned list will be sorted if True. Optional, default True.

Returns:

The list of GYRE details directories in the LOGS directory of star_dir.

Return type:

List

persephone.grids.get_list_gyre_summary(star_dir, sort=True, template_filename=None)#

Get absolute or relative list of GYRE summary files in a MESA model work directory.

Parameters:

  • star_dir (str or Path object) – Path of the consider MESA working directory.

  • sort (bool) – Returned list will be sorted if True. Optional, default True.

Returns:

In this order: the list of MESA profile, the corresponding list of model numbers in the history.data file, the list of GYRE summary files in the LOGS directory of star_dir.

Return type:

tuple of Lists

persephone.grids.get_list_profiles(star_dir, sort=True)#

Get absolute or relative list of MESA profiles in a MESA model work directory.

Parameters:

  • star_dir (str or Path object) – Path of the consider MESA working directory.

  • sort (bool) – Returned list will be sorted if True. Optional, default True.

Returns:

The list of MESA profile files in the LOGS directory of star_dir.

Return type:

List

persephone.grids.get_list_profiles_grid(grid_dir, sort=True)#

Get absolute or relative list of MESA profiles in a whole model grid.

Parameters:

  • grid_dir (str or Path object) – Path of the grid.

  • sort (bool) – Returned list will be sorted if True. Optional, default True.

Returns:

The list of MESA profile files in the whole grid.

Return type:

List

persephone.grids.get_profile(filename)#

Read the profile located at filename as a MesaData object.

Parameters:

filename (str or Path instance) – The path to the file with the profile to read.

Returns:

A MesaData object as constructed by pymesa_reader.

Return type:

MesaData

persephone.grids.get_profile_model_number(star_dir)#

Return list of model numbers corresponding to the profile saved in the MESA LOGS directory.

persephone.grids.plot_evolutionary_tracks(grid_dir, diagram='Kiel', min_age=None, ax=None, figsize=(6, 6), colors=None, cmap='tab10', show_legend=True, kwargs_legend={}, mass_to_select=None, z_to_select=None, **kwargs)#

Plot evolutionary tracks of the model of the grid.

Parameters:

  • grid_dir (str or Path object) – Directory of the grid.

  • diagram (str) – Type of diagram. May be Kiel or HR. Optional, default Kiel.

  • min_age (float) – Minimum age to consider for the tracks. Optional, default None.

  • figsize (tuple) – Figure size.

  • colors (array-like or str) – List of colors to consider for the tracks. Must match the total number of tracks of the grid. It is also possible to give a single color as a string, the tracks will all be drawn with the same color in this case. Optional, default None. If not provided, the cmap argument will be automatically used to attribute a color the tracks.

  • cmap (str or Path object) – Color map to use. Optional, default tab10.

  • show_legend (bool) – Whether to show legend or not. Optional, default True.

  • kwargs_legend (dict) – Keywords arguments to pass to matplotlib.pyplot.legend.

  • mass_to_select (array-like) – If provided, only tracks matching one of the stellar masses listed in the argument will be plotted.

  • z_to_select (array-like) – If provided, only tracks matching one of the metallicity listed in the argument will be plotted.

  • **kwargs – Arguments to pass to matplotlib.pyplot.plot.

Returns:

The created figure.

Return type:

matplotlib.pyplot.figure

persephone.grids.read_status_dir(star_dir, attribute='run_mesa_done')#

Read status in metadata file in MESA directory.

Parameters:

  • star_dir (str or Path object) – MESA working directory to consider.

  • attribute (str) – Keyword to read in the persephone_metadata.h5 file. Optional, default run_mesa_done.

Returns:

The status of the considered directory relatively to the the attribute keyword``.

Return type:

bool

persephone.grids.set_default_inlist(parameters=None, mesa_version='r15140')#

Set default values for parameter dictionary.

Parameters:

parameters (dict) – Input dictionary of MESA namelist. The function will not override parameters if already set.

Returns:

Dictionary with the default set of parameters used by persephone.

Return type:

dict

persephone.grids.set_default_gyre_namelist(parameters=None, filename='profile.data.GYRE', add_details=False)#

Set default values for parameter dictionary to build GYRE input namelist. The filename file is the MESA output with the .GYRE extension.

Parameters:

  • parameters (dict) – Dictionary of parameters to include in the GYRE input file.

  • filename (str or Path object) – Name of the .data.GYRE MESA-generated file to use for the GYRE run.

  • add_details (bool) – Add a GYRE details output file template if set to True.

Returns:

Dictionary with the default set of parameters used by persephone.

Return type:

dictionary

persephone.grids.set_status_dir(star_dir, attribute='run_mesa_done', status=True)#

Set status in metadata file in MESA directory.

Parameters:

  • star_dir (str or Path object) – MESA working directory to consider.

  • attribute (str) – Keyword to set in the persephone_metadata.h5 file. Optional, default run_mesa_done.

  • status (bool) – Status to set. Optional, default True.