Example Walkthrough
This chapter provides a walkthrough of a example GYRE project, to illustrate the typical steps involved. For this example, we’ll use gyre (the frontend focused on stellar oscillations) to find eigenfrequencies and eigenfunctions of dipole and quadrupole gravity modes for a MESA model of slowly pulsating B (SPB) star.
Making a Place to Work
When starting a new project, it’s a good idea to create a dedicated
work directory to contain the various input and output files that gyre
operates on. These commands will make a new directory beneath your
home directory with the name work, and then set this directory
as the current working directory:
$ mkdir ~/work
$ cd ~/work
Grabbing a Stellar Model
The next step is to grab the stellar model. There are a number of
example models provided in the $GYRE_DIR/models directory;
the following commands will copy a MESA model for a \(5\,\Msun\)
SPB star into your work directory:
$ cp $GYRE_DIR/models/mesa/spb/spb.mesa .
Assembling a Namelist File
Now comes the fun part: assembling an input file containing the
various settings that control a gyre run. Using a text
editor, create the file gyre.in in your work directory with
the following content copy-and-pasted in (use the copy button that
appears when you hover over the top-right corner of the box):
&constants
/
&model
model_type = 'EVOL' ! Obtain stellar structure from an evolutionary model
file = 'spb.mesa' ! File name of the evolutionary model
file_format = 'MESA' ! File format of the evolutionary model
/
&mode
l = 1 ! Harmonic degree
/
&mode
l = 2 ! Harmonic degree
/
&osc
outer_bound = 'VACUUM' ! Assume the density vanishes at the stellar surface
/
&rot
/
&num
diff_scheme = 'COLLOC_GL4' ! 4th-order collocation scheme for difference equations
/
&scan
grid_type = 'INVERSE' ! Scan grid uniform in inverse frequency
freq_min = 0.5 ! Minimum frequency to scan from
freq_max = 1.5 ! Maximum frequency to scan to
n_freq = 100 ! Number of frequency points in scan
/
&grid
w_osc = 10 ! Oscillatory region weight
w_exp = 2 ! Exponential region weight
w_ctr = 10 ! Central region weight
/
&ad_output
summary_file = 'summary.h5' ! File name for summary file
summary_item_list = 'l,n_pg,freq,freq_units,E_norm' ! Fields to appear in summary file
detail_template = 'detail.l%l.n%n.h5' ! File name template for detail files
detail_item_list = 'l,n_pg,omega,x,xi_r,
xi_h,c_1,As,V_2,Gamma_1' ! Fields to appear in detail files
freq_units = 'CYC_PER_DAY' ! Units of frequency-like output fields
/
&nad_output
/
This file is in namelist format, containing multiple namelist groups. Detailed information on the groups can be found in the Namelist Input Files chapter; for now, let’s just focus on some of the more-important aspects of the file above:
the
&constantsnamelist group is empty, telling gyre to use default values for fundamental constants;the
&modelnamelist group tells gyre to read an evolutionary model, in MESA format, from the filespb.mesa;the two
&modenamelist groups tells gyre to search first for dipole (\(\ell=1\)) and then quadrupole (\(\ell=2\)) modes;the
&oscnamelist group tells gyre to assume, when setting up the outer boundary conditions in the oscillation equations, that the density vanishes at the stellar surface;the
&scannamelist group tells gyre to scan a region of dimensionless angular frequency space typically occupied by gravity modes;the
&gridnamelist group tells gyre how to refine the model spatial grid;the
&ad_outputnamelist group tells gyre what adiabatic data to write to which output files; summary data to the filesummary.h5, and individual mode data to files having the prefixmode.;the
&nad_outputnamelist group is empty, telling gyre not to write any non-adiabatic data.
Running gyre
With the hard work done, it’s now trivial to run gyre:
$ $GYRE_DIR/bin/gyre gyre.in
As the frontend runs (on multiple cores, if you have a multi-core machine; see the FAQ for more details), it will print lots of data to the screen. Let’s break down this output, chunk by chunk.
First, gyre prints out its version number, tells us (in
OpenMP threads) how many cores it is running on, and indicates which
file it is reading settings from (here, gyre.in):
gyre [9.0]
----------
OpenMP Threads : 8
Input filename : gyre.in
Next, gyre loads the stellar model from the file
spb.mesa. This model comprises 1814 points and extends from
the surface all the way to the center (which is why gyre decides not
to add a central point).
Model Init
----------
Reading from MESA file
File name spb.mesa
File version 1.00
Read 1814 points
No need to add central point
gyre then prepares to search for modes with harmonic degree
\(\ell=1\) and azimuthal order \(m=0\) (not specified in
gyre.in, but assumed by default), by building a frequency grid
and a spatial grid:
Mode Search
-----------
Mode parameters
l : 1
m : 0
Building frequency grid (REAL axis)
added scan interval : 0.5000E+00 -> 0.1500E+01 (100 points, INVERSE)
Building spatial grid
Scaffold grid from model
Split 0 subinterval(s) in iteration 1
Final grid has 1 segment(s) and 1814 point(s):
Segment 1 : x range 0.0000 -> 1.0000 (1 -> 1814)
(The concepts of spatial and frequency grids are explored in greater detail in the Numerical Methods and Understanding Grids chapters). Next, gyre attempts to bracket roots of the discriminant function (again, see the Numerical Methods chapter) by scanning for changes in its sign:
Starting search (adiabatic)
Scanning frequencies
Time elapsed : 0.032 s
Finally, for each bracket found gyre uses a root solver to converge to the eigenfrequency, and then processes the mode to identify it and perform other calculations. Each row of output here corresponds to a mode that gyre has successfully found:
Finding roots
Time elapsed : 0.009 s
Processing modes
id l m n_pg n_p n_g Re(omega) Im(omega) chi n_iter
1 1 0 -9 0 9 0.50907836E+00 0.00000000E+00 0.4295E-14 7
2 1 0 -8 0 8 0.58398491E+00 0.00000000E+00 0.1803E-13 6
3 1 0 -7 0 7 0.66078111E+00 0.00000000E+00 0.9634E-14 6
4 1 0 -6 0 6 0.73734087E+00 0.00000000E+00 0.3667E-13 7
5 1 0 -5 0 5 0.89820448E+00 0.00000000E+00 0.1826E-13 6
6 1 0 -4 0 4 0.11322842E+01 0.00000000E+00 0.6427E-14 6
7 1 0 -3 0 3 0.13377876E+01 0.00000000E+00 0.9245E-14 6
Time elapsed : 0.014 s
The columns appearing are as follows:
idUnique mode index
lHarmonic degree \(\ell\)
mAzimuthal order \(m\)
n_pgRadial order \(\numpg\) within the Eckart-Scuflaire-Osaki-Takata scheme (see Takata, 2006b)
n_pAcoustic-wave winding number \(\nump\)
n_gGravity-wave winding number \(\numg\)
Re(omega)real part of dimensionless eigenfrequency \(\omega\)
Im(omega)imaginary part of dimensionless eigenfrequency \(\omega\) (zero here because we’ve performed an adiabatic calculation)
chiRoot-finding convergence parameter \(\chi\)
n_iterRoot-finding number of iterations
These values are printed to screen primarily to give an idea of gyre’s progress. Some things to watch out for:
The convergence parameter
chi, defined as the ratio of discriminant values before and after the root finding, should small (on the order of 1E-9 to 1E-15). If it is significantly larger than this, the mode may not be properly converged; and if it is significantly smaller than this, there may be numerical issues with the discretization scheme.The number of iterations
n_itershould be moderate; values above 20 or so indicate that gyre is having problems converging.The mode radial order
n_pgshould be monotonic-increasing. Departures from this behavior can happen for a number of reasons, that are discussed in the Troubleshooting chapter.
After processing the dipole modes, gyre repeats the search steps for the quadrupole modes. Once the overall run is complete, a number of output files are written:
A summary file with the name
summary.h5For each mode found, a detail file with the name
detail.lL.nN.h5, whereLandNare the harmonic degree and radial order of the mode, respectively.
The Interpreting Output Files chapter discusses how to read and analyze these files.