The model module

A module which contains various classes relevant to the grid of models:

These different classes allow the program to store a grid of models and perform a number of operations, such as:

  • retrieving model properties
  • interpolate within the grid models
  • sort the models within a given evolutionary track
  • ...
class model.Model(_glb, _name=None, _modes=None)[source]

A class which contains a stellar model, including classical and seismic information.

Parameters:
  • _glb (np.array) – 1D array of global parameters for this model. Its dimension should be greater or equal to nglb
  • _name (string) – name of the model (typically the second part of its path)
  • _modes (list of (int, int, float, float)) – list of modes in the form of tuples (n,l,freq,inertia) which will be appended to the set of modes in the model.
FeH

Find [Fe/H] value for model.

The conversion from (Xs,Zs) to [Fe/H] is performed using the following formula:

\(\mathrm{[Fe/H] = \frac{[M/H]}{A_{FeH}} = \frac{1}{A_{FeH}} \log_{10} \left(\frac{z/x}{z_{\odot}/x_{\odot}} \right)}\)
Returns:the \(\mathrm{[Fe/H]}\) value
Return type:float

Note

The relevant values are given in constants

MH

Find [M/H] value for model.

The conversion from (Xs,Zs) to [M/H] is performed using the following formula:

\(\mathrm{[M/H] = \log_{10} \left(\frac{z/x}{z_{\odot}/x_{\odot}} \right)}\)
Returns:the \(\mathrm{[M/H]}\) value
Return type:float

Note

The relevant values are given in constants

MH0

Find initial [M/H] value for model.

The conversion from (X,Z) to [M/H] is performed using the following formula:

\(\mathrm{[M/H] = \log_{10} \left(\frac{z/x}{z_{\odot}/x_{\odot}} \right)}\)
Returns:the \(\mathrm{[M/H]}\) value
Return type:float

Note

The relevant values are given in constants

append_modes(modes)[source]

Append a list of modes to the model.

Parameters:modes (list of (int, int, float, float)) – list of modes which are in the form of tuples: (n,l,freq,inertia).
b_Kjeldsen2008

Return the exponent for the Kjeldsen et al. (2008) surface correction recipe, as calculated based on the Sonoi et al. (2015) scaling relation.

Returns:the Kjeldsen et al. exponent
Return type:float
beta_Sonoi2015

Return the exponent for the Sonoi et al. (2015) surface correction recipe, as calculated based on the Sonoi et al. (2015) scaling relation.

Returns:the Kjeldsen et al. exponent
Return type:float
cutoff

Find \(\nu_{\mathrm{cut-off}}\) for model.

The \(\nu_{\mathrm{cut-off}}\) value is obtained from the following scaling relation:

\(\frac{\nu_{\mathrm{cut-off}}}{\nu_{\mathrm{cut-off},\odot}} = \left(\frac{M}{M_{\odot}}\right) \left(\frac{R}{R_{\odot}}\right)^2 \left(\frac{T_{\mathrm{eff}}}{T_{\mathrm{eff},\odot}}\right)^{-1/2}\)
Returns:the \(\nu_{\mathrm{cut-off}}\) value
Return type:float

Note

The relevant values are given in constants

find_epsilon(ltarget)[source]

Find epsilon, the constant offset in a simplified version of Tassoul’s asymptotic formula:

\(\nu_n = \Delta \nu (n + \varepsilon)\)

Parameters:ltarget (int) – target l value. Only modes with this l value will be used in obtaining epsilon.
Returns:the constant offset
Return type:float
find_large_separation()[source]

Find large frequency separation using only radial modes.

Returns:the large frequency separation
Return type:float
find_mode(ntarget, ltarget)[source]

Find a mode with specific n and l values.

Parameters:
  • ntarget (int) – target n value
  • ltarget (int) – target l value
Returns:

the frequency of the mode
Return type:

float
find_mode_range()[source]

Find n and l ranges of the modes in the model.

Returns:the n and l ranges of the modes
Return type:int, int, int, int
freq_sorted()[source]

Check to see if the frequencies are in ascending order for each l value.

Returns:True if the frequencies are in ascending order.
Return type:boolean
get_age()[source]

Return age of stellar model.

This is useful for sorting purposes.

Returns:the age of the model
Return type:float
get_freq(surface_option=None, a=[])[source]

Obtain model frequencies, with optional frequency corrections.

Parameters:
  • surface_option (string) –

    specifies the type of surface correction. Options include:

    • None: no corrections are applied
    • "Kjeldsen2008": apply a correction based on Kjeldsen et al. (2008)
    • "Kjeldsen2008_scaling": apply a correction based on Kjeldsen et al. (2008).
      The exponent is based on a scaling relation from Sonoi et al. (2015).
    • "Kjeldsen2008_2": apply a correction based on Kjeldsen et al. (2008).
      The exponent is a free parameter.
    • "Ball2014": apply a one-term correction based on Ball and Gizon (2014)
    • "Ball2014_2": apply a two-term correction based on Ball and Gizon (2014)
    • "Sonoi2015": apply a correction based on Sonoi et al. (2015)
    • "Sonoi2015_scaling": apply a correction based on Sonoi et al. (2015)
      The exponent is based on a scaling relation from Sonoi et al. (2015).
    • "Sonoi2015_2": apply a correction based on Sonoi et al. (2015)
      The exponent is a free parameter.
  • a (array-like) – amplitude parameters which intervene in the surface correction
Returns:

models frequencies (including surface corrections)
Return type:

np.array

Note

If surface_option==None or a==[], the original frequencies are returned (hence modifying them modifies the Model object).

get_surface_correction(surface_option, a)[source]

Obtain corrections on model frequencies (these corrections should be added to the theorectical frequencies).

Parameters:
  • surface_option (string) –

    specifies the type of surface correction. Options include:

    • None: no corrections are applied
    • "Kjeldsen2008": apply a correction based on Kjeldsen et al. (2008)
    • "Kjeldsen2008_scaling": apply a correction based on Kjeldsen et al. (2008).
      The exponent is based on a scaling relation from Sonoi et al. (2015).
    • "Kjeldsen2008_2": apply a correction based on Kjeldsen et al. (2008).
      The exponent is a free parameter.
    • "Ball2014": apply a one-term correction based on Ball and Gizon (2014)
    • "Ball2014_2": apply a two-term correction based on Ball and Gizon (2014)
    • "Sonoi2015": apply a correction based on Sonoi et al. (2015)
    • "Sonoi2015_scaling": apply a correction based on Sonoi et al. (2015)
      The exponent is based on a scaling relation from Sonoi et al. (2015).
    • "Sonoi2015_2": apply a correction based on Sonoi et al. (2015)
      The exponent is a free parameter.
  • a (array-like) –

    parameters which intervene in the surface correction. According to the correction they take on the following meanings:

    • "Kjeldsen2008": a[0]*freq**b_Kjeldsen2008
    • "Kjeldsen2008_scaling": a[0]*freq**b_scaling
    • "Kjeldsen2008_2": a[0]*freq**a[1]
    • "Ball2014": a[0]*freq**3/I
    • "Ball2014_2": a[0]*freq**3/I + a[1]/(freq*I)
    • "Sonoi2015": a[0]*[1 - 1/(1 + (nu/numax)**beta_Sonoi2015)]
    • "Sonoi2015_scaling": a[0]*[1 - 1/(1 + (nu/numax)**beta_scaling)]
    • "Sonoi2015_2": a[0]*[1 - 1/(1 + (nu/numax)**a[1])]
Returns:

surface corrections on the model frequencies
Return type:

np.array

Note

The array operations lead to the creation of a new array with the result, which avoids modifications of the original frequencies and inertias.

glb = None

Array which will contain various global quantities

modes = None

array containing the modes (n, l, freq, inertia)

multiply_modes(constant)[source]

Multiply the frequencies by constant.

Parameters:constant (float) – constant by which the mode frequencies are multiplied
name = None

Name of the model, typically the second part of its path

numax

Find \(\nu_{\mathrm{max}}\) for model.

The \(\nu_{\mathrm{max}}\) value is obtained from the following scaling relation:

\(\frac{\nu_{\mathrm{max}}}{\nu_{\mathrm{max},\odot}} = \left(\frac{M}{M_{\odot}}\right) \left(\frac{R}{R_{\odot}}\right)^2 \left(\frac{T_{\mathrm{eff}}}{T_{\mathrm{eff},\odot}}\right)^{-1/2}\)
Returns:the \(\nu_{\mathrm{max}}\) value
Return type:float

Note

The relevant values are given in constants

print_me()[source]

Print classical and seismic characteristics of the model to standard output.

read_file(filename)[source]

Read in a set of modes from a file. This method will either call read_file_CLES(), read_file_MESA(), or read_file_agsm() according to the value of the mode_format variable in AIMS_configure.py.

Parameters:filename (string) – name of the file with the modes. The format of this file is decided by the mode_format variable in AIMS_configure.py.
Returns:True if at least one frequency has been discarded (see note below).
Return type:boolean

Note

At this stage the frequencies should be expressed in \(\mu\mathrm{Hz}\). They will be non-dimensionalised in read_model_list().

read_file_CLES(filename)[source]

Read in a set of modes from a file. This uses the “simple” or “CLES” format as specified in the mode_format variable in AIMS_configure.py.

Parameters:filename (string) – name of the file with the modes. The file should contain a one-line header followed by five columns which correspond to l, n, frequency, unused, inertia.
Returns:True if at least one frequency has been discarded (see note below).
Return type:boolean

Note

  • The fourth column is discarded.
  • Frequencies above config.cutoff`*:math:nu_{mathrm{cut-off}}` are discarded.
read_file_MESA(filename)[source]

Read in a set of modes from a file. This uses the GYRE (i.e. MESA) format as specified in the mode_format variable in AIMS_configure.py.

Parameters:filename (string) – name of the file with the modes. The file should contain a seven-line header followed by various columns which contain l, n, frequency, and inertia for each pulsation mode.
Returns:True if at least one frequency has been discarded (see note below).
Return type:boolean

Note

  • Frequencies above config.cutoff`*:math:nu_{mathrm{cut-off}}` are discarded.
read_file_agsm(filename)[source]

Read in a set of modes from a file. This uses the “agsm” format as specified in the mode_format variable in AIMS_configure.py.

Parameters:filename (string) – name of the file with the modes. This file is a binary fortran “agsm” file produced by the ADIPLS code. See instructions to the ADIPLS code for a description of this format.
Returns:True if at least one frequency has been discarded (see note below).
Return type:boolean

Note

  • Frequencies above config.cutoff`*:math:nu_{mathrm{cut-off}}` are discarded.
remove_duplicate_modes()[source]

Remove duplicate modes.

Modes are considered to be duplicate if they have the same l and n values (regardless of frequency).

Returns:True if at least one mode has been removed.
Return type:boolean

Warning

This method assumes the modes are sorted.

sort_modes()[source]

Sort the modes by l, then n, then freq.

string_to_param(string)[source]

Return a parameter for an input string.

Parameters:string (string) – string that indicates which parameter we’re seeking
Returns:the value of the parameter
Return type:float
write_file_simple(filename)[source]

Write a set of modes into a file using the “simple” format as described in read_file_simple().

Parameters:filename (string) – name of the file where the modes should be written.

Note

  • The output frequencies are expressed in \(\mathrm{\mu Hz}\)
zsx_0

Find the Z0/X0 value

Returns:the Z0/X0 value
Return type:float
zsx_s

Find the Zs/Xs value

Returns:the Zs/Xs value
Return type:float
class model.Model_grid[source]

A grid of models.

find_epsilons(ltarget)[source]

Find epsilon values in models from the grid

Parameters:ltarget (int) – target l value for which epsilons are being obtained
Returns:the epsilon values
Return type:list of floats
find_partition()[source]

Find a partition of the grid for use with Model_grid.test_interpolation()

Returns:a random partition of [0 ... n-1] into two equal halves, where n is the number of tracks in the grid
Return type:two lists of int
grid = None

Array containing the grid parameters for each evolutionary track (excluding age).

grid_params = None

Set of parameters (excluding age) used to construct the grid and do interpolations.

Note

For best interpolation results, these parameters should be comparable.

ndim = None

Number of dimensions for the grid (excluding age), as based on the Model_grid.grid_params variable

ndx = None

List containing track indices

plot_tessellation()[source]

Plot the grid tessellation.

Warning

This only works for two-dimensional tessellations.

postfix = None

Last part of the filenames which contain the model frequencies (default = ”.freq”).

prefix = None

Root folder with grid of models (including final slash).

range(aParam)[source]

Find range of values for the input parameter.

Parameters:aParam (str) – name of the parameter for which to find the range

Warning

The input parameter can only be one of the grid parameters or an age/mHe parameter.

read_model_list(filename)[source]

Read list of models from a file and construct a grid.

Parameters:filename (string) –

name of the file with the list. The first line of this file should contain a prefix which is typically the root folder of the grid of models. This followed by a file with multiple columns. The first 8 contain the following information for each model:

  1. the second part of the path. When concatenated with the prefix on the first line, this should give the full path to the model.
  2. The stellar mass in \(\mathrm{g}\)
  3. The stellar radius in \(\mathrm{cm}\)
  4. The stellar luminosity in \(\mathrm{g.cm^2.s^{-3}}\)
  5. The metallicity
  6. The hydrogen content
  7. The stellar age in \(\mathrm{Myrs}\)
  8. The effective temperature in \(\mathrm{K}\)

The following columns contain the parameters specified in the AIMS_configure.user_params variable.
remove_tracks(nthreshold)[source]

Removes stellar evolution tracks with fewer than nthreshold models.

Parameters:nthreshold (int) – lower limit on number of models in a stellar evolutionary track
tessellate()[source]

Apply Delauny triangulation to obtain the grid tessellation.

tessellation = None

Object containing the tessellation of the grid used for interpolation.

test_freq()[source]

Test to see if frequencies in all of the models of the grid are in ascending order for each l value.

Returns:The following items are returned
  • the effective temperatures of the models with frequencies out of order
  • the luminosities of the models with frequencies out of order
  • the effective temperatures of the models with sorted frequencies
  • the luminosities of the models with sorted frequencies
Return type:four lists of floats
test_interpolation()[source]

Test interpolation between different evolutionary tracks in a given grid.

Returns:The following four items are returned:
  • the interpolation errors
  • the first half of the partition (where the interpolation is tested)
  • the second half of the partition (used to carry out the interpolation)
  • the tessellation associated with the second half of the partition
Return type:np.array, list, list, tessellation object
tracks = None

List of evolutionary tracks contained in the grid.

user_params = None

The set of user parameters involved in the grid. This is to avoid having a different set of user parameters in AIMS_configure.py

class model.Track(aModel, grid_params)[source]

An evolutionary track.

Parameters:
  • aModel (Model) – first model to be added to evolutionary track (it does not need to be the youngest model in an evolutionary sequence). This Model is used to obtain the relevant parameters for the evolutionary track (as given by the grid_params variable).
  • grid_params (list of strings) – list of strings which are the names of the parameters which describe the evolutionary track.
age_lower

Provides the lowest age an evolutionary track.

age_range

Provides the age range for an evolutionary track.

age_upper

Provides the highest age for an evolutionary track.

append(aModel)[source]

Append a model to the evolutionary track.

Parameters:aModel (Model) – model which is being appended to the track
duplicate_ages()[source]

Check to see if you track contains models with duplicate ages.

Returns:True if there are duplicate age(s)
Return type:boolean

Warning

This method should only be applied after the track has been sorted.

find_combination(age, coef)[source]

Return a model combination at a given age which is obtained using linear interpolation.

Parameters:
  • age (float) – age of desired model in \(\mathrm{Myrs}\)
  • coef (float) – coefficient which multiplies this combination
Returns:

pairs composed of an interpolation coefficient and a model name
Return type:

tuple of (float, string)

Warning

This method assumes the track is sorted, since it applies a binary search algorithm for increased efficiency.

find_mode_range()[source]

Find n and l ranges of modes in models

Returns:the n and l ranges
Return type:int, int, int, int
find_modes(ntarget, ltarget)[source]

Return two lists, one with the ages of the models and the other with the mode frequencies corresponding to target n and l values.

This function is useful for seeing how the frequency of a particular mode changes with stellar age.

Parameters:
  • ntarget (int) – target n value
  • ltarget (int) – target l value
Returns:

lists of ages and frequencies
Return type:

list, list
grid_params = None

Names of the parameters used to construct the grid

interpolate_model(age)[source]

Return a model at a given age which is obtained using linear interpolation.

Parameters:age (float) – age of desired model in \(\mathrm{Myrs}\)
Returns:the interpolated model
Return type:Model

Warning

This method assumes the track is sorted, since it applies a binary search algorithm for increased efficiency.

is_sorted()[source]

Check to see of models are in ascending order according to age.

Returns:True if the models ar in order of increasing age
Return type:boolean
matches(aModel)[source]

Check to see if a model matches the evolutionary track and can therefore be included in the track.

Parameters:aModel (Model) – input model being tested
Returns:True only if the model given as an argument has parameters which match those of the evolutionary track.
Return type:boolean
models = None

List of models in this evolutionary track

nmodes = None

Total number pulsation modes from all of the models in this evolutionary track

params = None

Parameters which characterise this evolutionary track

sort()[source]

Sort models within evolutionary track according to age.

test_interpolation(nincr)[source]

Test accuracy of interpolation along evolutionary track.

This method removes every other model and retrieves its frequencies by interpolation from neighbouring models. The accuracy of the interpolated frequencies and global parameters are tested by carrying out comparisons with the original models.

Parameters:nincr (int) – increment with which to carry out the interpolation. By comparing results for different values of nincr, one can evaluate how the interpolation error depends on the size of the interval over which the interpolation is carried out.
Returns:the interpolation errors
Return type:np.array
model.combine_models(model1, coef1, model2, coef2)[source]

Do linear combination of this model with another.

This method returns a new model which is the weighted sum of two models for the purposes of model interpolation. The classical parameters are combined in a self-consistent way as are the frequencies.

Parameters:
  • model1 (Model) – first model
  • coef1 (float) – weighting coefficient applied to first model
  • model2 (Model) – second model
  • coef2 (float) – weighting coefficient applied to second model
Returns:

the combined model
Return type:

Model

Warning

One should avoid negative or zero coefficients as these could lead to undefined results.

model.compare_models(model1, model2)[source]

Compare two models and find the largest frequency different for radial and non-radial modes.

Parameters:
  • model1 (Model) – first model
  • model2 (Model) – second model
Returns:

a 1D array to be used in plot_test_interpolation.py with the following measurements of the differences between the two models:

  • result[0] = maximum error on the radial modes
  • result[1] = RMS error on the radial modes
  • result[2] = RMS error on the radial modes near \(\nu_{\mathrm{max}}\)
  • result[3] = maximum error on the non radial modes
  • result[4] = RMS error on the non radial modes
  • result[5] = RMS error on the non radial modes near \(\nu_{\mathrm{max}}\)
  • result[6+[0:nglb]] = errors on the global parameters
Return type:

np.array
model.eps = 1e-06

relative tolerance on parameters used for setting up evolutionary tracks

model.find_ages(coefs, tracks, age)[source]

Find ages to which each track needs to be interpolated for a specified age. The global variable scale_age decides between the following two options:

  1. scale_age = False: each track is simply interpolated to age.
  2. scale_age = True: the age of each model along each evolutionary track, including the interpolated track, is linearly mapped onto the interval [0,1]. A dimensionless parameter eta is obtained by interpolating age onto the interval [0,1], using the linear transformation associated with the interpolated track. Using the parameter eta, a corresponding age is obtained along each track.

This diagram illustrates both types of age interpolation and shows the advantages of selecting scale_age = True.

Parameters:
  • coefs (list of floats) – interpolation coefficients used to weight each track.
  • tracks (list of Track) – evolutionary tracks involved in the interpolation.
  • age (float) – target age for the output interpolated model.
Returns:

the relevant age for each track
Return type:

list of floats

Note

  • the interpolation coefficients should add up to 1.0
  • there should be as many tracks as interpolation coefficients.
model.find_combination(grid, pt)[source]

Find linear combination of models which corresponds to interpolating the model based on the provided parameters.

The interpolation is carried out using the same procedure as in interpolate_model().

Parameters:
  • grid (Model_grid) – grid of models in which we’re carrying out the interpolation
  • pt (array-like) – set of parameters used for the interpolation. The first part contains the grid parameters, whereas the last element is the age. If the provided set of parameters lies outside the grid, then None is returned instead of an interpolated model.
Returns:

pairs of coefficients and model names
Return type:

tuple of (float,string)
model.find_interpolation_coefficients(grid, pt, tessellation, ndx)[source]

Find interpolation weights from the corresponding simplex.

Linear interpolation weights are obtained with the simplex by finding the barycentric coordinates of the point given by pt.

Parameters:
  • grid (Model_grid) – grid of models in which we’re carrying out the interpolation
  • pt (array-like) – set of parameters used for finding the interpolation weights. The first part contains the grid parameters (relevant to this interpolation), whereas the last element is the age (not used here). If the provided set of parameters lies outside the grid, then None is returned instead of an interpolated model.
  • tessellation – tessellation with which to carry out the interpolation.
  • ndx (list of int) – indices of the grid points associated with the tessellation
Returns:

lists of interpolation coefficients and tracks
Return type:

list of floats, list of Track
model.ftype

type used for the frequencies

alias of float64

model.get_surface_parameter_names(surface_option)[source]

Return the relevant parameter names for a given surface correction option.

Parameters:surface_option (string) – specifies the type of surface correction.
Returns:names for the surface parameters
Return type:tuple of strings
model.gtype

type used for grid data

alias of float64

model.iage = 0

index of the parameter corresponding to age in the Model.glb array

model.ifreq_ref = 10

index of the parameter corresponding to the reference frequency (used to non-dimensionalise the pulsation frequencies of the model) in the Model.glb array

model.iluminosity = 12

index of the parameter corresponding to luminosity in the Model.glb array

model.imass = 1

index of the parameter corresponding to mass in the Model.glb array

model.init_user_param_dict()[source]

Initialise the dictionaries which are related to user-defined parameters. For a given parameter, these dictionaries provide the appropriate index for for the Model.glb array as well as the appropriate latex name.

model.interpolate_model(grid, pt, tessellation, ndx)[source]

Interpolate model in grid using provided parameters.

The interpolation is carried out in two steps. First, linear interpolation according to age is carried out on each node of the simplex containing the set of parameters. This interpolation is done using the Track.interpolate_model method. Then, linear interpolation is carried out within the simplex. This achieved by finding the barycentric coordinates of the model (i.e. the weights), before combining the age-interpolated models form the nodes using the combine_models method. In this manner, the weights are only calculated once, thereby increasing computational efficiency.

Parameters:
  • grid (Model_grid) – grid of models in which we’re carrying out the interpolation
  • pt (array-like) – set of parameters used for the interpolation. The first part contains the grid parameters, whereas the last element is the age. If the provided set of parameters lies outside the grid, then None is returned instead of an interpolated model.
  • tessellation – tessellation with which to carry out the interpolation.
  • ndx (list of int) – indices of the grid points associated with the tessellation
Returns:

the interpolated model
Return type:

Model
model.iradius = 11

index of the parameter corresponding to radius in the Model.glb array

model.itemperature = 2

index of the parameter corresponding to temperature in the Model.glb array

model.ix0 = 4

index of the parameter corresponding to the initial hydrogen content in the Model.glb array

model.iz0 = 3

index of the parameter corresponding to the initial metallicity the Model.glb array

model.log0 = -1e+150

value which is returned when log(0) is calculated (rather than causing an error)

model.ltype

type used for the l values

alias of int8

model.modetype = [('n', <type 'numpy.int16'>), ('l', <type 'numpy.int8'>), ('freq', <type 'numpy.float64'>), ('inertia', <type 'numpy.float64'>)]

structure for modes

model.nglb = 13

total number of global quantities in a model (see Model.glb).

model.nlin = 10

total number of global quantities which are interpolated in a linear way (see combine_models()). These quantities are numbered 0:nlin-1

model.ntype

type used for the n values

alias of int16

model.string_to_latex(string, prefix='', postfix='')[source]

Return a fancy latex name for an input string.

Parameters:
  • string (string) – string that indicates for which parameter we’re seeking a latex name
  • prefix (string) – optional prefix to add to the string
  • postfix (string) – optional postfix to add to the string
Returns:

a fancy latex name
Return type:

string

Note

This also works for the names of the amplitude parameters for surface corrections.

model.tol = 1e-06

tolerance level for points slightly outside the grid

model.user_params_index = {}

dictionary which will supply the appropriate index for the user-defined parameters

model.user_params_latex = {}

dictionary which will supply the appropriate latex name for the user-defined parameters