DOI: 10.5281/zenodo.10814654
title: Non-linear three-mode coupling of gravity modes in rotating slowly pulsating B stars: Stationary solutions and modeling potential

description: This repository contains the material available online that accompanies Van Beeck et al. (2024) (ArXiv link). 

It contains zipped archives that contain inlists and final data products for the MESA stellar evolution code\(^1\) (version 15140), the GYRE stellar pulsation/oscillation code\(^2\) (version 6.0.1) and the AESolver stellar oscillation mode coupling code\(^3\).

In the technical information section below you may find a description of the contents of this repository. The abstract of Van Beeck et al. (2024) is also available below.

 

Footnotes :

\(^1\): see https://docs.mesastar.org/en/r15140/ for additional details about the MESA stellar evolution code.

\(^2\): see https://gyre.readthedocs.io/en/v6.0.1/ for additional details about the GYRE stellar pulsation/oscillation code.

\(^3\): the AESolver code can be downloaded from its Github repository: https://github.com/JVB11/AESolver; its documentation may be consulted at https://jvb11.github.io/AESolver/.
description: Context.

Slowly pulsating B (SPB) stars display multi-periodic variability in the gravito-inertial mode regime with indications of non-linear resonances between modes. Several have undergone asteroseismic modeling in the past few years to infer their internal properties, but only in a linear setting. These stars rotate fast, so that rotation is typically included in the modeling by means of the traditional approximation of rotation (TAR).

Aims.

We aim to extend the set of tools available for asteroseismology, by describing time-independent (stationary) resonant non-linear coupling among three gravito-inertial modes within the TAR. Such coupling offers the opportunity to use mode amplitude ratios in the asteroseismic modeling process, instead of only relying on frequencies of linear eigenmodes, as has been done so far.

Methods.

Following observational detections, we derive expressions for the resonant stationary non-linear coupling between three gravito-inertial modes in rotating stars. We assess selection rules and stability domains for stationary solutions. We also predict non-linear frequencies and amplitude ratio observables that can be compared with their observed counterparts.

Results.

The non-linear frequency shifts of stationary couplings are negligible compared to typical frequency errors derived from observations. The theoretically predicted amplitude ratios of combination frequencies match with some of their observational counterparts in the SPB targets. Other, unexplained observed ratios could be linked to other saturation mechanisms, to interactions between different modes, or to different opacity gradients in the driving zone.

Conclusions.

For the purpose of asteroseismic modeling, our non-linear mode coupling formalism can explain some of the stationary amplitude ratios of observed resonant mode couplings in single SPB stars monitored during 4 years by the Kepler space telescope.
description: Available MESA materials ----- MESA version 15140

`Inlists' / work directory

Unzipping the archive work_files_MESA.zip generates a work directory called 'work' from which MESA runs can be initiated using the configuration necessary, in order to obtain the MESA models necessary to reproduce the results in Van Beeck et al. (2024).

This work directory contains many files and directories, which can be classified into different types:



Several inlists may be recognized, which are called 'inlist_xxxx'. In addition to the regular inlist available for a MESA run\(^1\), one may find:



inlist_base_parameters



Contains the base/common parameters for the MESA models.



inlist_controls_michielsen



Contains a specific controls parameter similar to Michielsen et al. (2021).



inlist_controls_pedersen



Contains a set of specific controls parameters similar to Pedersen et al. (2021).



inlist_kap_pedersen



Contains the setting used to reproduce the specific opacity table used during the run.



inlist_nuclear_net_pedersen



Contains the star_job options necessary to use the specific extended nuclear network for the reproduction of the MESA simulations. 



inlist_variable_parameters



This is the most important inlist for any potential user: it contains the variable parameters used in Van Beeck et al. (2024).



inlist_xtra_coeff_cb



Contains parameters necessary for a custom sub-module that increases the meshgrid resolution of the near-core zone in order to resolve the Brunt-Väisälä frequency peak.





The standard MESA 'clean', 'mk' (make), 're' (restart) and 'rn' (run) files, as well the standard README.rst, star and stash.py file. (Note that the star file should be replaced with the star file of your local install before compiling MESA)

Modified history and profiles lists: 'hist.list' and 'prof.list' .\(^2\)

A make directory containing a modified makefile:



The makefile contains commands to compile specific submodules for the MESA runs that enable functionalities necessary to reproduce the results.



An empty experiments directory

An empty LOGS directory

An empty photos directory

A runstarex directory containing many different sub-modules used to modify the runstarextras.f90 module in order to reproduce results. Documentation is provided within the respective sub-modules.

A shell_subscripts directory that contains shell helper scripts used to initiate a MESA run using the 'new_mesa_run.sh' shell script that may be found in the top level of the work directory.

A src directory containing a MESA run.f90 script that calls a heavily modified runstarextras.f90 script that utilizes the many sub-modules defined in the runstarex directory.

A nuclear_nets directory containing different nuclear networks that are used for the MESA runs.




Before compiling MESA to reproduce the results of Van Beeck et al. (2024), please ensure that the custom opacity table of Moravveji et al. (2015) is used by MESA. Instructions on how to download the custom file that sets up MESA to use the opacity table of Van Beeck et al. (2024) may be found in Moravveji et al. (2015)\(^3\). If this is not done before compilation, an error will occur when trying to run MESA using the provided custom inlists!\(^4\)


Data products

The zipped archive mesa_models.zip contains the generated MESA model output. It contains four sub-directories:



gyre



This sub-directory contains the necessary MESA output profiles used to initiate GYRE runs.



history



This sub-directory contains generated history files of the latest run\(^5\), as well as a pgstar.dat file\(^5\).



preMS



This sub-directory contains a pgstar.dat file\(^5\), preMS history files\(^5\) and ZAMS models (that could be used to start the MS runs\(^6\)).



profiles



This sub-directory contains the 'regular' MESA output profile output (containing specific requested columnar data, including a specific adiabatic derivative profile\(^7\)).




 

Footnotes for the MESA materials :

\(^1\):  see https://docs.mesastar.org/en/r15140/ for additional information on the files that determine the parameters of the MESA run, the inlists. Here, the standard 'inlist' file is modified to read additional inlists that are necessary to reproduce the results of Van Beeck et al. (2024).

\(^2\):  check https://docs.mesastar.org/en/r15140/ for additional information on the history and profile list files and their parameters.

\(^3\): the opacity table used in Van Beeck et al. (2024) is that of Moravveji et al. (2015).

\(^4\): this specific error can of course be avoided if the provided inlists are adjusted to not use this custom opacity table.

\(^5\): these files are not of relevance for the reproduction of the results of Van Beeck et al. (2024).

\(^6\): alternatively one can first let a pre-MS run generate a novel ZAMS model, which can then serve as input for the MS run.

\(^7\): see appendix C.2 of Van Beeck et al. (2024) for additional information about the specific adiabatic derivative that was computed using MESA.

 

Available GYRE materials ----- GYRE version 6.0.1

Inlists (and run scripts)

The zipped archive inlists_scripts_GYRE.zip contains the necessary inlists and utility scripts used to produce the necessary output created for Van Beeck et al. (2024) (using the GYRE code). When unzipped it creates a directory called gyre_inlists that contains the usual GYRE .in inlist file, as well as two shell scripts used to run GYRE and a sub-directory, sub_shell_scripts, which contains several helper shell scripts that are utilized by the two shell scripts in the top level directory, run_GYRE.sh and run_extras_GYRE.sh.

These top level shell scripts are used to run GYRE (check their commented content for additional information on the parameters used in the shell scripts). Specifically, run_extras_GYRE.sh uses the run_GYRE.sh a numerous amount of times in order to generate the necessary GYRE models for Van Beeck et al. (2024).

When attempting to reproduce the results, some lines that call run_GYRE.sh should be uncommented in run_extras_GYRE.sh to ensure that all necessary GYRE detail files are produced. It is recommendable to do this gradually, and not to uncomment all lines at once... As an example, one single block of GYRE run command is uncommented, which generates the GYRE model output for the \(\Delta  \mathrm{X}_{\mathrm{c,\,2}_{(b)}}\) model of Van Beeck et al. (2024).



Before using the provided scripts to run GYRE in order to reproduce the results of Van Beeck et al. (2024), please ensure that the path to the input MESA models (profiles -- GYRE output) is correct, by adjusting the parameter 'file' in the gyre_grid.in inlist.\(^8\) The naming of the output files should/can be handled using the provided shell scripts.


Command line output

The zipped archive command_line_output_GYRE.zip contains files that reveal the command line output of the GYRE runs used to generate the GYRE linear oscillation models for Van Beeck et al. (2024).

These files can found within a specific set of directories whose names reveal what models are related to this output. One may find in the top directory of the created command_line_output_files_GYRE directory (after unzipping) three sub-directories named M4, M6 and M8 which refer to the initial mass of the MESA models used for the GYRE runs: 4, 6 and 8 solar masses, respectively. Within these sub-directories one may find a file named overview_gi_modes.txt that contains information on the computed number of gravito-inertial modes using GYRE. The format and content of these files is described below. Additionally, the output is further divided into sub-directories that describe the rotation rate of the GYRE models: either the sub-directory is called rot20, in which case the models rotate at 20% of the Roche critical rotation rate, or the sub-directory is called rot60, meaning the model output described in the files in this directory rotate at 60% of the Roche critical rotation rate. Further discrimination is made between different models using the output file name, which is structured in the following generic way:

gyre_models_OP_pedersen_Xc..._rot..._M..._logD..._l..._m... .gyre.output

where the three dots refer to numerical values that differ among models. These represent (from left to right), the central hydrogen mass fraction (Xc), the model rotation rate\(^9\), the initial mass of the MESA models, the logarithm of the minimal radiative envelope mixing level (see Van Beeck et al. (2024)), the spherical degree of the modes (according to GYRE) and their azimuthal order.

File content for overview_gi_modes.txt :

These text files contain data tables in which the columns are:




Xc
rot
k
m
l_comp_n
u_comp_n
l_exc_n
u_exc_n


Core hydrogen mass fraction of the models
GYRE model rotation rate (% of Roche critical rotation rate)
Mode ordering number
Azimuthal order
Lower bound of the radial order range of the computed modes
Upper bound of the radial order range of the computed modes
Lower bound of the exclusion range of the computed modes (for damped quadrupole or excited dipole modes).
Upper bound of the exclusion range of the computed modes




Data products

The zipped archive gyre_models.zip contains the generated GYRE (linear oscillation) models for Van Beeck et al. (2024). These models are stored within a specific set of directories: the top level directory is called gyre_models and it contains two sub-directories, rot_20 and rot_60. The numerical part of the names of these sub-directories refer to the rotation rate of the GYRE model output\(^9\). Within those directories one may find another set of sub-directories that have names that refer to the core hydrogen mass fraction of the MESA models used to compute the GYRE models (i.e., of the form Xc...). Each of those sub-directories contain two sub-directories themselves: the ad and nad directories, which indicate which of the simulations were performed adiabatically (ad), and which of the simulations were performed non-adiabatically (nad). These sub-directories contain the GYRE output files, which are either summary files or detail files.

Schematically, the structure of the zipped archive can thus be represented as:

gyre_models (TOP DIRECTORY)

--> rot_... (rotation rate sub-division)

--> --> Xc... (core hydrogen mass fraction sub-division)

--> --> --> ad/nad (adiabaticity sub-division).

The names of the stored summary files contain additional information about the models, and are saved although they are not used as input for the AESolver mode coupling code. A typical name for a summary file is:

Z..._M..._logD..._aov..._fov..._g_mode_summary_l..._m... .h5

where the dots refer to the numerical values for the specific parameters. Z refers to the initial metallicity of the MESA model, whereas M refers to its initial mass. logD indicates the logarithm of the minimal radiative envelope mixing level; and aov and fov refer to the \(\alpha_{\mathrm{CBM}}\) and \(f_{\mathrm{CBM}}\) convective boundary mixing efficiency parameters described in the first chapter of Van Beeck (2023, PhD Thesis). The numerical values following l and m refer to the spherical degree (according to GYRE) and azimuthal order of the computed modes.

The names of the stored detail files (i.e., GYRE mode profiles) are typically of the following form:

Z..._M..._logD..._aov..._fov..._g_mode_detail_l..._m..._n+.... .h5

in which the symbols have the same meaning as that of the summary files, and where the numerical part following n+ indicates the radial order of a given computed mode.

 

Footnotes for the GYRE materials:

\(^8\): this is an adaptation of the standard GYRE inlist that ensures that all GYRE mode profiles that are necessary to start the non-linear mode coupling calculations (using the AESolver code) are generated.

\(^9\): in % of the Roche critical rotation rate.

 

Available AESolver materials

Inlists

The zipped archive inlists_aesolver.zip contains the different inlists used to generate the data products (i.e., the mode coupling models). These inlists are formatted as .toml files.\(^{10}\)

The names of the these `toml inlists' reflect the information contained within the final data products of the 'runs' they will initiate, and can be deconstructed in the following way: 

model_x_y_jvb_2023.toml  (or model_x_jvb_2023.toml)

where 'x' refers to the main model number and 'y' is an optional additional number used to denote sub-models.

The main model numbers can be mapped in the following way to the models used in Tables 2, 3, 4, 5 and 6 of  Van Beeck et al. (2024)(ArXiv link):




Main model number
1
2
3
4
5
6
7


Model in Van Beeck et al. (2024)
fiducial
\(\Delta \mathrm{X}_{\mathrm{c,\,1}}\)
\(\Delta  \mathrm{X}_{\mathrm{c,\,2}_{(a)}}\) 
\(\Delta  \mathrm{X}_{\mathrm{c,\,2}_{(b)}}\) 
\(\Delta \mathrm{M}_{\mathrm{ini,\, 1}}\)
\(\Delta \mathrm{X}_{\mathrm{c}}|\mathrm{M}_{\mathrm{ini}}\)
\(\Delta \mathrm{M}_{\mathrm{ini,\, 2}}\)




 

The (optional) additional numbers were used to distinguish between sub-models when linearly excited \((k,m) = (0,1)\) were encountered when forming potential mode triads.\(^{11}\) Prior to the generation of the figures in Van Beeck et al. (2024) and the generation of the data within the tables of that paper, such sub-models are stitched automatically using the functionality of the AESolver code.\(^{12}\)



Before running the AESolver code using the provided inlists, please ensure that the input data paths in the inlist are filled in correctly, so that AESolver may read the input MESA and GYRE models. For more information on how to do so, please check the documentation website https://jvb11.github.io/AESolver/ .


Data products

The zipped archive aesolver_output_files.zip contains the data products generated using the inlists described in the previous sub-section.

Their names match those of the inlists. When generating the data for the tables of, and the figures in Van Beeck et al. (2024) any sub-models are automatically stitched.

An overview of the contents of these data products can be found on the documentation website (https://jvb11.github.io/AESolver/).

 

Footnotes for the AESolver materials:

\(^{10}\):  see https://toml.io/en/ for additional information on the .toml file format.

\(^{11}\): we only compute mode coupling coefficients for a specific 'type' of gravito-inertial mode triad, when the selection rules are fulfilled ; see the discussion in Section 4 of Van Beeck et al. (2024).

\(^{12}\): see the documentation website https://jvb11.github.io/AESolver/ for more information on how to perform  automatic stitching of sub-models using the AESolver inlist.