Pipeline configuration
The modelling pipeline can be configured for various options and modelling choices.
These are set via keyword arguments, supplied upon initialisation of the instance of the PipelineConfig() class.
In the example pipeline script foam/pipeline/pipeline.py
, this instance is initialised in the beginning of the script.
The following lines are copied from the pipeline, but some of the keyword arguments have already been filled in:
from foam.pipeline import pipeline_config
pipeline_config.config = pipeline_config.PipelineConfig(star='KIC000',
observations='data_KIC000.tsv',
rotation_gyre = 0.5)
All keyword arguments are listed below, grouped in categories.
Observational data
- star
type: string
default: None
Name of the star, used for generating filenames. Do not put underscores (_
) in the starname, since these characters are used to separate the starname from the rest of the filename. - observations
type: string
default: None
Full path to the file with the observational data. - pattern_starting_pulsation
type: dictionary of list
default: None
Only required when ‘provided-pulsation’ method is included in ‘pattern_methods’.
This dictionary has two keys, ‘period’ and ‘frequency’, holding a list of periods or frequencies, respectively, to start building the pulsation pattern from when using the ‘provided-pulsation’ method.
Periods are required when periods or period spacings (‘P’ or ‘dP’) are used as observables inobservable_seismic
, and frequencies are required when frequencies (‘f’) are used as observables inobservable_seismic
. If periods or frequencies are not required, the list can containNone
instead of values.
The list should contain one pulsation per part of the split pattern, ordered the same as the file with the observations. (List of length 1 in case of continuous pattern.)
Simulated theoretical model grid
- grid_parent_directory
type: string
default: None
Parent directory of the computed grids. - grids
type: list of strings
default: None
Names of the subdirectories of the grids with different physics. - subgrid
type: string
default: ‘*’
String to only select models that have this string in their name. Mainly for testing purposes. This is used to create the grid summary files for a small subgrid of the original grid, e.g. for making a smaller grid with less free parameters to run some quick tests.
GYRE and mode information
- kval
type: int
default: 0
Meridional degree (k value) of the mode ID (k,m) of the g-mode pattern. - mval
type: int
default: 1
Azimuthal order (m value) of the mode ID (k,m) of the g-mode pattern. - rotation_gyre
type: float
default: 0.0
Rotation rate in d^-1 (CYC_PER_DAY of GYRE) that was used in GYRE to calculate the pulsation frequencies. - gyre_dir
type: string
default: os environment variable $GYRE_DIR
Path to the GYRE directory.
Modelling methodology
- pattern_methods
type: list of strings
options: ‘provided-pulsation’, ‘highest-frequency’, ‘chisq-longest-sequence’
default: [‘provided-pulsation’, ‘highest-frequency’, ‘chisq-longest-sequence’]
List of methods to construct the theoretical frequency pattern (repeats modelling for each method).‘provided-pulsation’ builds the mode pattern starting from the theoretical mode that is closest to the provided pulsation frequency or period. Can be used to provide and start from a trusted mode e.g. the highest-amplitude mode in the observed pattern.
‘highest-frequency’ will begin matching modes starting from the theoretical mode that is closest to the highest-frequency mode detected in the observed pattern.
‘chisq-longest-sequence’ will match each observed mode period to its best matching theoretical counterpart, and adopt the longest sequence of consecutive modes retrieved in this way. In the case of multiple mode series with the same length, a final pattern selection is made based on the best match between theory and observations. The rest of the theoretical pattern is then build consecutively in radial order starting from this initial ‘longest sequence’ pattern.
- merit_functions
type: list of strings
options: ‘CS’, ‘MD’
default: [‘CS’, ‘MD’]
List of merit functions (repeats modelling for each merit function).‘CS’ uses a reduced chi-squared function.
‘MD’ uses Mahalanobis distances, see Aerts et al. (2018) for its application in the context of asteroseismology.
- n_periods
type: int
default: None
Number of periods (or frequencies) in the observed pattern. Missing frequencies in interrupted patterns are not counted in this number. - n_pattern_parts
type: int
default: 1
In how many parts the observed pattern is split. Defaults to 1 assuming an uninterrupted pattern. - observable_seismic
type: list of strings
options: ‘P’, ‘dP’, ‘f’
default: [‘P’, ‘dP’]
List of asteroseismic observables to fit in the merit function (repeats modelling for each observable) options are ‘P’ (period), ‘dP’ (period-spacing), and ‘f’ (frequency). - observable_additional
type: list of strings
default: None
List of additional observables to use in the merit function. Observables other than ‘logTeff’, ‘logL’, and ‘logg’ must correspond to header items included in the MESA profiles. Set to None to use only the asteroseismic observables. - n_sigma_box
type: int
default: 3
Ignore models outside of an n-sigma error box on the surface properties (Teff, logL, logg) included in the observational data, set to None to include all models. - free_parameters
type: list
default: [‘Z’, ‘M’, ‘logD’, ‘aov’, ‘fov’, ‘Xc’]
List of varied parameters in the grid, as written in the filenames of the models in the grid (see walkthrough), that remain free parameters in the modelling. In case of a binary system where additional constraints from the companion should be taken into account (see settingspectro_companion
), this list should start with the first two entries being ‘Z’, ‘M’ representing metallicity and mass. - fixed_parameters
type: dict
default: None
Dictionary with varied parameters in the grid (dict keys) that are fixed to a certain value (dict value) to consider nested grids with fewer free parameters. These parameters should be included in the filenames, just like the free_parameters. Defaults to None to not fix any parameters. (E.g. {‘aov’: 0.0, ‘fov’: 0.0} to fix both these parameters to zero.) - evolution_parameter
type: string
default: ‘Xc’
Name of the parameter that is used to track the evolutionary steps of the model. - evolution_step
type: float
default: -0.01
Change in the evolutionary parameter from one step to the next (negative if quantity decreases, e.g. central hydrogen content Xc). Only needed when enforcing binary constraints.
Modelling binaries and enforcing constraints of the companion star
- constraint_companion
type: dictionary
default: None
Defaults to None instead of a dictionary to not include any constraints from binarity. Dictionary with the following keys holding all binary Information (q = Mass_secondary/Mass_primary):
{‘q’: <float>, ‘q_err’: <float>,’Teff’: <float>, ‘Teff_err’: <float>, ‘logg’: <float>, ‘logg_err’: <float>, ‘logL’: <float>, ‘logL_err’:<float>, ‘primary_pulsates’:<boolean>}
Set one of the observables Teff, logg, logL to None to not use that observable. - isocloud_grid_directory
type: string
default: None
The path to the isocloud grid directory. This grid of MESA history files should be constructed in the same way as the regular grid described in walkthrough, but only needs the history files. This can be the same theoretical grid as the main one that is used, but can also be an additional grid that is sparser and covers a larger range in stellar masses, since the binary companion might not fall within a grid that is more focussed on the pulsating star.
Other settings
- debugging
type: boolean
default: False
Set to True to set logger level to debug. - nr_cpu
type:int
default: None
Number of worker processes to use in multiprocessing. The default ‘None’ will cause the pools to use the number returned by os.cpu_count(). - cornerplot_axis_labels
type: dictionary, keys and values are strings
default: {‘rot’: r’$\Omega_{\mathrm{rot}}$ [d$^{-1}$]’, ‘M’: r’M$_{\rm ini}$’, ‘Z’: r’Z$_{\rm ini}$’, ‘logD’:r’log(D$_{\rm env}$)’, ‘aov’:r’$\alpha_{\rm CBM}$’,’fov’:r’f$_{\rm CBM}$’,’Xc’:r’$\rm X_c$’}
keys are the grid parameters, values are how they should be put in the labels of the cornerplots’ axis.