persephone.grids

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.compile_grid(grid_dir, verbose=True, parallelise=True, nodes=2)#

Compile MESA in model directories.

Parameters:

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

  • verbose (bool) – Output verbosity.

  • parallelise (bool) – Whether to compile MESA 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.run_grid(grid_dir, verbose=True, rerun=False, resume=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.

  • resume (bool) – If set to True, MESA will be executed through the re command and not the rn command (requiring the photo directory not to be empty). In this case, the function will behave automatically as if rerun is True. 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.

persephone.grids.analyse_grid_gyre(grid_dir, template_file=None, parameters=None, verbose=True, add_details=False, input_template=None, summary_template=None, details_template=None, 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.

  • input_template (str) – Template name to use for the GYRE input file. Optional, default None.

  • summary_template (str) – Template name to use for the summary file created by GYRE. Optional, default None.

  • details_template (str) – Template name to use for the detail files created by GYRE. Optional, default None.

  • 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=None, default_history='MESA', default_profile='MESA', profile_columns=None, history_columns=None, run_star_extras=None, parameters=None, inlist_default=False, 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, resume=False, mesa_metadata=None, input_template=None, summary_template=None, details_template=None)#

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 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 "MESA".

  • 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.

  • run_star_extras (str or Path object) – MESA run_star_extras.f90 file to override the default. 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.

  • resume (bool) – If set to True, MESA will be executed through the re command and not the rn command (requiring the photo directory not to be empty). In this case, the function will behave automatically as if rerun is True. Optional, default False.

  • mesa_metadata (dict) – MESA metadata to include in the metadata file.

  • input_template (str) – Template name to use for the GYRE input file. Optional, default None.

  • summary_template (str) – Template name to use for the summary file created by GYRE. Optional, default None.

  • details_template (str) – Template name to use for the detail files created by GYRE. Optional, default None.

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

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.

  • input_template (str) – Template name to use for the GYRE input file. Optional, default None.

  • summary_template (str) – Template name to use for the summary file created by GYRE. Optional, default None.

  • details_template (str) – Template name to use for the detail files created by GYRE. Optional, default None.

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, resume=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.

  • resume (bool) – If set to True, MESA will be executed through the re command and not the rn command (requiring the photo directory not to be empty). In this case, the function will behave automatically as if rerun is True. Optional, default False.

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.initialise_inlist(parameters=None, mesa_version=None)#

If parameters is None, create an empty inlist with only namelist names. Otherwise complete the parameters input with missing namelists.

Returns:

Dictionary with empty sub-dictionaries.

Return type:

dict

persephone.grids.parse_inlist(filename)#

Parse a MESA inlist file and return a parameters dictionary as used as input by persephone.

Returns:

  • A dictionary of dictionaries that can be passed

  • as the parameters input to persephone

  • functions.

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, alpha_mlt_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.

  • alpha_mlt_to_select (array-like) – If provided, only tracks matching one of the MLT parameter 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=None, initialisation_only=False)#

Set default values for parameter dictionary.

Parameters:

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

  • mesa_version (str) – MESA version to consider to fill the defaults, if provided and if initialisation_only is set to False. Optional, default None.

  • initialisation_only (bool) – If set to True, sub-dictionaries will be returned empty.

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, summary_template=None, details_template=None)#

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.

  • summary_template (str) – Template name to use for the summary file created by GYRE. Optional, default None.

  • details_template (str) – Template name to use for the detail files created by GYRE. Optional, default None.

Returns:

Dictionary with the default set of parameters used by persephone.

Return type:

dictionary

persephone.grids.set_parametrised(param_to_set, fun, param_fun, parameters)#

Set a parameter that depends on other input parameter of the model.

Parameters:

  • param_to_set (tuple) – Must be given as a tuple (namelist, name).

  • fun (function) – The function defining the relation between the parameter to set and other parameters. Must have the same number of elements as param_fun.

  • param_fun (list of tuple) – List of parameters on which the parameter to set depends. For each parameter, must be given as a tuple (namelist, name).

  • parameters (dict) – The complete dictionary of parameters set for the model.

Return type:

The updated parameter 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.