Adding Evolution Models¶
Need an evolution model not listed among those pre-packaged with SPISEA? No problem! With the additional documentation provided below, you can implement your own evolution models into the SPISEA framework.
If you have questions or run into problems, please raise an issue on our Github issue tracker. If you are willing to have the new models you add be added to the SPISEA package and made available to the community, please fork or branch off of the development repository and then submit merge requests to add your changes to the package. These contributions will be added to the main branch (with attributes given!) in the next code update.
Setup: Codes, Directories, Files¶
The codes associated with the evolution
models are in evolution.py
. Each evolution model grid is implemented
as a sub-class of the StellarEvolution
object: for example, the MISTv1
sub-class corresponds to the MISTv1 model grid, etc. If you are
planning to add to an existing model grid, you will need to edit the corresponding
sub-class. If you want to add a brand new model grid, you will need to
create a new sub-class for that model.
The evolution model grids are packaged as individual isochrone files in SPISEA. These files are originally downloaded from the website for the given evolution model, modified to match the required SPISEA formatting, and then saved in the proper location in the model directory tree.
The isochrone files are stored in the
$SPISEA_MODELS/evolution/
directory. Each evolution model grid is contained
in its own sub-directory; for example,
$SPISEA_MODELS/evolution/PARSECV1.2s
contains the PARSEC
isochrones.
Each of these sub-directories has a similar structure:
---> version (if applicable)
---> iso
---> metallicity
---> rotation (if applicable)
---> individual files
The metallicity directories are named z<mass_fraction>
, where
<mass_fraction> is the mass fraction of metals. The individual
isochrone files saved as FITS tables with the name convention
iso_<logAge>.fits
, where <logAge> is the log(age) of the
population. While the <mass_fraction>
can be any
number of digits you want, SPISEA expects the <logAge> to
always have two places after the decimal.
The individual iso_<logAge>.fits
files are FITS tables (readable
by Astropy Table.), with one isochrone
(i.e., one age) per file. The column names must match those expected
by SPISEA, which are generic (col1, col2, col3, etc). The mapping
between these generic names and the detailed names actually used by the
code is defined in the <evolution sub_class>.isochrone()
function. Within this function, there is a section renaming these
generic column names to more descriptive names, such as Z, logAge,
Teff, etc. If you add new iso_<logAge>.fits
, you must make sure
this mapping is correct for the new files!
Adding New Metallicities to An Existing Model Grid¶
To general steps required to add a new metallicity to an existing model grid are:
Download the raw isochrones from the evolution model website. Ideally the user would use same age sampling as the solar metallicity model grid (see Adding New Ages to An Existing Model Grid).
Reformat the raw isochrones into SPISEA format. They should be saved in the appropriate metallicity sub-directory (see Setup: Codes, Directories, Files).
Edit the evolution object in evolution.py so it knows about the new isochrones and where they live. The following variables in the
__ init__
function need to be updated:self.z_list
: add the new metallicities (in terms of mass fraction)self.z_file_map
: edit dictionary to map new metallicities with new metallicity sub-directory names.
(optional, but highly recommended if planning to merge local edits into SPISEA development branch for community use) Add a test function to
spisea/tests/test_synthetic.py
to make sure everything is working properly.
Adding New Ages to An Existing Model Grid¶
The isochrone ages for a given evolution model are defined in the
__init__
function for the evolution model object under the
self.age_list
variable. The pre-packaged model grids have a typical age sampling of 6.0 <
logAge < 10.0, in steps of 0.01. Some models don’t offer models across
this entire age range and so the available age range is truncated (the
Ekstrom12
models only go from 6.0 < logAge < 8.0, for example). We
highly recommend that users use this same age range and sampling when adding
new models (e.g., new metallicities, etc).
If the user needs to change the available age range for an existing model grid, please let us know via the Github issue tracker.
Creating a New Model Grid¶
To create an entirely new model set, the user needs to define a new
StellarEvolution
sub-class corresponding to that object and set up
the appropriate directory structure in the
$SPISEA_MODELS/evolution
directory. Detailed documentation on
this is coming soon. In the meantime, let us know on the Github issue tracker if you’d like to
implement a new model set.