GitHub

API

Chemistry

We utilize the chemistry API from BolometricCorrections.jl to describe the chemistry of the stellar track libraries.

Individual Tracks

An individual stellar track, containing the time evolution of properties for a single star, is represented by our AbstractTrack type. Different concrete implementations are used for different stellar evolution libraries, but all support the common access API defined below.

API

StellarTracks.AbstractTrack — Type

Abstract supertype representing individual stellar tracks. Different concrete implementations are used for different stellar libraries, but all subtypes of AbstractTrack are guaranteed to support the generic API described in the documentation.

The main way to get the properties of the modeled star when it has a particular age, assuming track is a valid concrete instance, is to call the track with the logarithmic age track(log10(age)) where age is in years. This will return a NamedTuple containing the available properties (e.g., logL, logTe) of the modeled star at that age. Not all libraries will have the same properties available.

source
BolometricCorrections.gridname — Method
gridname(::Type{<:AbstractTrack})

Returns a human-readable String identifier of the stellar evolution grid that tracks of the provided type are derived from. This should be provided for all track types.

gridname(track::AbstractBCTable) = gridname(typeof(track))

Generic method provided to return the gridname for instances of concrete subtypes of AbstractTrack.

source
Base.extrema — Method
Base.extrema(t::AbstractTrack)

Returns the minimum and maximum logarithmic age (log10(age [yr])) of the stellar model.

source
Base.keys — Method
Base.keys(t::AbstractTrack)

Returns a tuple of symbols that will be used to set the keys of the NamedTuples returned by t(logAge::Number).

source
StellarTracks.mass — Method
mass(t::AbstractTrack)

Returns the initial stellar mass of the modeled star in solar masses.

source

Concrete Implementations

StellarTracks.InterpolatedTrack — Type
InterpolatedTrack(track0, track1, track1_prefac, track2_prefac) <: AbstractTrack

Type allowing for linear interpolation between two stellar tracks of identical mass but different metallicity (track0 and track1). Simple linear interpolation between the two tracks is applied. The track can be evaluated at a particular logarithmic age by calling (track::InterpolatedTrack)(logAge::Number).

The constructor for this type is considered internal and users should not construct this type directly. Rather, tracks of this type are constructed from track libraries by calling them with the signature (tracklib::AbstractTrackLibrary)(mh::Number, M::Number) where mh is the logarithmic metallicity [M/H] and M is the initial stellar mass in solar masses.

julia> using StellarTracks.PARSEC: PARSECLibrary

julia> p = PARSECLibrary();

julia> track = p(-2.05, 1.05)
InterpolatedTrack with M_ini=1.05, MH=-2.05, Z=0.000138567, Y=0.248747, X=0.751115.

julia> track(9.0)
(logTe = 3.8820487347062302, Mbol = 3.7411721770340987, logg = 4.521853108813156, C_O = 0.0)
source

Track Sets

We define a "track set" to be a set of individual stellar tracks that share common properties (typically initial metallicity). By grouping these tracks together, we can interpolate between tracks in the set, create isochrones, and perform other similar operations.

For each EEP, age–mass relations are constructed by scanning tracks from highest to lowest initial mass and retaining only ages strictly greater than the last retained age. Equal ages retain the higher-mass sample. This top-down selection follows the canonical approach in Dotter [1]: physical nonmonotonic regions are represented by a single monotonic selection rather than multiple masses per EEP. Stellar properties use the same selected tracks. This approximation can change EEP mass intervals and therefore IMF-weighted phase counts. Selection occurs in memory and does not modify the saved track files. If selection removes a mass from every EEP of a track set, that mass is excluded from the supported mass grid rather than advertising a track with no valid points.

At each EEP, the logarithm of initial mass is interpolated linearly in logarithmic age between the selected tracks. Because the interpolation weights depend only on the track masses, the initial masses of an isochrone cannot decrease between neighboring EEPs that use the same selected tracks. Cubic interpolants do not have this property. Where the selected tracks differ between neighboring EEPs only because tracks end or start (e.g., MIST tracks that end at the start of the TP-AGB), the mass step between the two EEPs compares interpolations over different tracks and can be non-physical. At fixed age, the step from a mass $m$ at one EEP implies the time a star of mass $m$ needs to reach the next EEP. Where that time is negative, or differs by more than a factor of 3 from the time the neighboring tracks present at both EEPs take, the reported initial masses use the step interpolated from those common tracks instead, provided this changes the step by at most 1%, and all later masses shift by the same amount. Stellar properties are still evaluated at the masses given by the age-mass relations, so after such a correction m_ini differs slightly from the mass of the track that passes through the isochrone point. Where the initial masses still decrease, isochrones keep the longest sequence of points along which the initial mass strictly increases, so that a small decrease at the start of a long phase (e.g., the TP-AGB) does not remove that phase.

API

StellarTracks.AbstractTrackSet — Type

Abstract supertype representing a set of stellar tracks with common properties and supports common operations like interpolating between tracks and calculating isochrones. Specifically, it is assumed all individual tracks in a track set have identical initial metallicity and chemical composition. Subtypes of AbstractTrackSet are guaranteed to support the generic API described in the documentation.

Concrete instances are callable with an initial stellar mass (in solar masses), returning an interpolated track at the requested mass.

source
BolometricCorrections.gridname — Method
gridname(::Type{<:AbstractTrackSet})

Returns a human-readable String identifier of the stellar evolution grid that track sets of the provided type are derived from. This should be provided for all track set types.

gridname(trackset::AbstractTrackSet) = gridname(typeof(trackset))

Generic method provided to return the gridname for instances of concrete subtypes of AbstractTrackSet.

source
StellarTracks.mass — Method
mass(ts::AbstractTrackSet)

Returns the initial stellar masses (in solar masses) of the individual tracks contained in the track set.

source
BolometricCorrections.X — Method
X(ts::AbstractTrackSet)

Returns the common hydrogen mass fraction of the tracks contained in the track set.

source
BolometricCorrections.Y — Method
Y(ts::AbstractTrackSet)

Returns the common helium mass fraction of the tracks contained in the track set.

source
BolometricCorrections.alphaFe — Method
alphaFe(ts::AbstractTrackSet)

Returns the common α-element enhancement [α/Fe] of the tracks contained in the track set. For scaled-solar models, this is zero.

source
StellarTracks.post_rgb — Method
post_rgb(ts::AbstractTrackSet)

Returns true if the tracks in the track set include post-RGB evolution, false otherwise.

source
StellarTracks.isochrone — Method
isochrone(ts::AbstractTrackSet, logAge::Number)

Interpolates properties of the stellar tracks in the track set at the requested logarithmic age (logAge = log10(age [yr])). Returns a NamedTuple containing the properties; different libraries may have different properties available. If result = isochrone(...), EEP points are generally available as result.eep and the corresponding initial stellar masses are result.m_ini. Isochrones contain only living stars (no stellar remnants), so the largest result.m_ini is the initial mass of the most evolved living star; the exception is a MISTv2TrackSet created with wd = true.

julia> using StellarTracks.MIST

julia> ts = MISTv1TrackSet(-1, 0); # Load set of MIST tracks with [M/H] = -1, vvcrit=0

julia> isochrone(ts, 10.0) isa NamedTuple
true
source
StellarTracks.isochrone — Method
isochrone(ts::StellarTracks.AbstractTrackSet,
          bc::BolometricCorrections.AbstractBCTable,
          logAge::Number)

Returns an isochrone as a TypedTables.Table calculated using the stellar evolutionary tracks contained in ts with bolometric corrections interpolated from the provided table bc at the logarithmic age logAge. Column names can be retrieved with TypedTables.columnnames. The result can be converted to a matrix with Tables.matrix.

using StellarTracks, BolometricCorrections
p = PARSECLibrary()    # Load PARSEC library of stellar models
m = MISTv1BCGrid("JWST") # Load MIST library of BCs
isochrone(p.ts[1], m(MH(p.ts[1]), 0.0), 10.0)
Table with 35 columns and 1323 rows:
...
source

Concrete Implementations

Track Libraries

For ease of use, our main entry point is the AbstractTrackLibrary, which loads and organizes all stellar tracks available from a given library (e.g., PARSEC). Once all tracks have been loaded, subsets with common chemical compositions can be extracted. Individual tracks and isochrones can also be interpolated directly from the library instance. However, the interfaces for these interpolations are not generic as not all libraries offer the same variations in initial chemistry – e.g., most will offer variation in total metallicity (i.e., $Z$), but some also include variation in $\alpha$-element abundances. These methods are documented separately for each stellar library under their unique pages in the left panel.

API

StellarTracks.AbstractTrackLibrary — Type

Abstract supertype for loading the full set of all stellar tracks available from a given library (e.g., PARSEC). For some libraries (e.g., MIST), there are different model sets for other stellar input parameters (e.g., rotation vvcrit in MIST) that are not interpolated over – these should be provided as arguments to the concrete type constructors.

These are typically assembled as a collection of individual track sets, with one track set constructed for each unique set of stellar chemical compositions (i.e., [M/H]). For more details, see the documentation for AbstractTrackSet.

Concrete subtypes must implement an isochrone interpolation method. A generic method for the call signature isochrone(tracklib::AbstractTrackLibrary, logAge::Number, mh::Number) is provided. This generic method should work as long as the concrete subtype follows the chemistry API and has a field tracklib.ts containing the individual tracksets that make up the library. The tracksets must support isochrone interpolation via a method isochrone(ts::<your_type_here>, logAge::Number).

Concrete instances must support interpolation of stellar tracks at user-provided metallicities and initial stellar masses. A generic method is implemented via the signature (tracklib::AbstractTrackLibrary)(mh::Number, M::Number). This method interpolates the tracklib at logarithmic metallicity [M/H] = mh and stellar initial mass M, returning an InterpolatedTrack that can be called to evaluate the track.

source
BolometricCorrections.gridname — Method
gridname(::Type{<:AbstractTrackLibrary})

Returns a human-readable String identifier of the stellar evolution grid type provided. This should be provided for all track set types.

gridname(tracklib::AbstractTrackLibrary) = gridname(typeof(tracklib))

Generic method provided to return the gridname for instances of concrete subtypes of AbstractTrackLibrary.

source
BolometricCorrections.X — Method
X(tl::AbstractTrackLibrary)

Returns the hydrogen mass fractions of the track sets contained in the track library.

source
BolometricCorrections.Y — Method
Y(tl::AbstractTrackLibrary)

Returns the helium mass fractions of the track sets contained in the track library.

source
BolometricCorrections.Z — Method
MH(tl::AbstractTrackLibrary)

Returns the metal mass fractions of the track sets contained in the track library.

source
BolometricCorrections.MH — Method
MH(tl::AbstractTrackLibrary)

Returns the logarithmic metal abundances of the track sets contained in the track library, defined as [M/H] = log(Z/X) - log(Z⊙/X⊙). Generic method uses the Salaris et al. [17] equation to compute [M/H] from FeH and alphaFe.

source
BolometricCorrections.alphaFe — Method
alphaFe(tl::AbstractTrackLibrary)

Returns the α-element enhancement [α/Fe] of the track sets in the track library. For scaled-solar models, this is zero.

source
StellarTracks.post_rgb — Method
post_rgb(tl::AbstractTrackLibrary)

Returns true if any of the track sets in the track library include post-RGB evolution, false otherwise.

source
StellarTracks.isochrone — Method
isochrone(tracklib::AbstractTrackLibrary, logAge::Number, mh::Number)

Interpolates properties of the stellar tracks in the track library at the requested logarithmic age (logAge = log10(age [yr])) and metallicity [M/H] = mh. Returns a NamedTuple containing the properties; different libraries may have different properties available. If result = isochrone(...), EEP points are generally available as result.eep and the corresponding initial stellar masses are result.m_ini. Between metallicity grid points, only EEPs present in both bracketing isochrones are returned.

julia> using StellarTracks.MIST

julia> p = MISTv1Library(0.0); # Load the library of MIST tracks with vvcrit=0

julia> isochrone(p, 10.0, -1.65) isa NamedTuple
true
source
StellarTracks.isochrone — Method
isochrone(tracklib::AbstractTrackLibrary,
          bc::BolometricCorrections.AbstractBCTable,
          logAge::Number,
          mh::Number)

Returns an isochrone as a TypedTables.Table calculated using the stellar evolutionary tracks contained in tracklib with bolometric corrections interpolated from the provided table bc at the logarithmic age logAge and metallicity [M/H] = mh. Column names can be retrieved with TypedTables.columnnames. The result can be converted to a matrix with Tables.matrix.

using StellarTracks, BolometricCorrections
p = MISTv1Library(0.0)   # Load MIST library of non-rotating stellar models
m = MISTv1BCGrid("JWST") # Load MIST library of BCs
isochrone(p, m(-1.01, 0.0), 10.0, -1.01)
Table with 36 columns and 1465 rows:
...
source
StellarTracks.isochrone — Method
isochrone(tracklib::AbstractTrackLibrary,
          bcg::AbstractBCGrid, 
          logAge::Number, 
          mh::Number, 
          Av::Number)

Returns an isochrone as a TypedTables.Table calculated using the stellar evolutionary tracks contained in tracklib with bolometric corrections interpolated from the provided bolometric correction grid bcg at the logarithmic age logAge and metallicity [M/H] = mh. Column names can be retrieved with TypedTables.columnnames. The result can be converted to a matrix with Tables.matrix.

In general, the stellar evolutionary tracks and bolometric correction grid may not share the same solar abundance pattern. In this case, it is common to normalize both to a common total metallicity quantified by the metal mass fraction Z – for example, this approach is taken for normalizing the YBC bolometric grid [28]. This method specifically treats the input mh ([M/H]) as the desired logarithmic abundance for the chemical mixture used for the stellar evolutionary tracks (tracklib), converts this to a metal mass fraction, then converts that metal mass fraction into the appropriate logarithmic metallicity [M/H] for the chemical mixture used by the bolometric correction grid bcg. This "corrected" [M/H] value is used when interpolating the bolometric grid.

If mh lies outside the metallicity range of tracklib, the stellar tracks are evaluated at the nearest metallicity in tracklib while the bolometric corrections are still evaluated at mh. This is an extrapolation and is similar to what is done by the PARSEC CMD isochrone service. The idea is that stellar interiors change little at very low metallicity, so combining a [M/H] = -2.2 dex PARSEC isochrone (meaning, interior quantities only) with a [M/H] = -2.5 dex bolometric correction is a good enough approximation of true photometric quantities at [M/H] = -2.5. Whether this is actually good enough depends on your application; if such extrapolation is not acceptable, you should ensure that mh lies within the metallicity range of tracklib, for example by checking that mh is between minimum(MH(tracklib)) and maximum(MH(tracklib)). An mh outside that range is an error from bcg.

The bolometric correction table is bc_table(tl, bcg, mh, Av), so for grids indexed by [Fe/H] and [α/Fe] (e.g., MISTv2BCGrid), [α/Fe] is taken from tl (see alphaFe).

using StellarTracks, BolometricCorrections
p = MISTv1Library(0.0)   # Load MIST library of non-rotating stellar models
m = MISTv1BCGrid("JWST") # Load MIST library of BCs
isochrone(p, m, 10.0, -1.01, 0.0)
Table with 36 columns and 1465 rows:
...
source
StellarTracks.bc_table — Function
bc_table(tracklib::AbstractTrackLibrary, bcg::BolometricCorrections.AbstractBCGrid, mh::Number, Av::Number)

Returns the bolometric correction table interpolated from bcg for stars of metallicity [M/H] = mh, defined for the chemical mixture of tracklib, and V-band extinction Av. mh is converted to the metal mass fraction Z and then to the [M/H] of the chemical mixture of bcg; for grids indexed by [Fe/H] and [α/Fe] (e.g., MISTv2BCGrid), [α/Fe] is taken from tracklib (see alphaFe). These are the tables used by isochrone(tracklib, bcg, logAge, mh, Av); see apply_bc to apply them to theoretical isochrones.

source
StellarTracks.apply_bc — Function
apply_bc(iso, bc::BolometricCorrections.AbstractBCTable)

Given a theoretical isochrone iso (e.g., from isochrone(tracklib, logAge, mh)) and a bolometric correction table bc, evaluates the bolometric corrections at the effective temperatures and surface gravities of iso and applies them to its bolometric magnitudes, returning a TypedTables.Table with the columns of iso followed by the magnitude in each filter of bc. Together with bc_table, this applies several tables (e.g., for different extinctions) to one isochrone without recomputing it.

using StellarTracks, BolometricCorrections
p = MISTv1Library(0.0)   # Load MIST library of non-rotating stellar models
m = MISTv1BCGrid("JWST") # Load MIST library of BCs
iso = isochrone(p, 10.0, -1.01)
isos = [apply_bc(iso, bc_table(p, m, -1.01, Av)) for Av in (0.0, 0.5)]
source

Concrete Implementations