Example Walkthrough

This chapter provides a walkthrough of a example GYRE project, to illustrate the typical steps involved. For this example, we’ll be focusing on finding 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 parameters which control a GYRE run. Using a text editor, create the file gyre.in in your work directory with the following content cut-and-pasted in:

&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' ! Use a zero-pressure outer mechanical boundary condition
/

&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 parameter
  w_exp = 2  ! Exponential region weight parameter
  w_ctr = 10 ! Central region weight parameter
/


&ad_output
  summary_file = 'summary.h5'                         ! File name for summary file
  summary_item_list = 'l,n_pg,freq,freq_units,E_norm' ! Items 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' 	      ! Items to appear in detail files
  freq_units = 'CYC_PER_DAY'                   	      ! Units of freq output items
/

&nad_output
/

This file is an example of a Fortran ‘namelist’ file, containing multiple namelist groups. Each group begins with the line &name (where name is the name of the group); a list of parameter-value pairs then follows, and the group ends with a slash /. Detailed information on the namelist groups expected in GYRE’s input files 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 &constants namelist group is empty, telling GYRE to use default values for fundamental constants;

  • the &model namelist group tells GYRE to read an evolutionary model, in MESA format, from the file spb.mesa;

  • the two &mode namelist groups tells GYRE to search first for dipole (\(\ell=1\)) and then quadrupole (\(\ell=2\)) modes;

  • the &osc namelist group tells GYRE to apply a zero-pressure outer mechanical boundary condition in the oscillation equations;

  • the &scan namelist group tells GYRE to scan a region of dimensionless angular frequency space typically occupied by gravity modes;

  • the &grid namelist group tells GYRE how to refine the model spatial grid;

  • the &ad_output namelist group tells GYRE what adiabatic data to write to which output files; summary data to the file summary.h5, and individual mode data to files having the prefix mode.;

  • the &nad_output namelist 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 code 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 parameters from (here, gyre.in):

gyre [6.0]
----------

OpenMP Threads   : 4
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
   Refined 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 GYRE Fundamentals and Understanding Grids chapters). Next, GYRE attempts to bracket roots of the discriminant function (again, see the GYRE Fundamentals chapter) by searching for changes in its sign:

Starting search (adiabatic)

Evaluating discriminant
  Time elapsed :     0.845 s

Finally, for each bracket found GYRE uses a root solver to converge to the eigenfrequency. Each row of output here corresponds to a mode that GYRE has successfully found:

Root Solving
   l    m    n_pg    n_p    n_g       Re(omega)       Im(omega)        chi n_iter
   1    0      -9      0      9  0.50907836E+00  0.00000000E+00 0.6678E-14      7
   1    0      -8      0      8  0.58398491E+00  0.00000000E+00 0.1352E-13      6
   1    0      -7      0      7  0.66078111E+00  0.00000000E+00 0.1666E-13      7
   1    0      -6      0      6  0.73734087E+00  0.00000000E+00 0.3141E-13      6
   1    0      -5      0      5  0.89820448E+00  0.00000000E+00 0.1363E-13      6
   1    0      -4      0      4  0.11322842E+01  0.00000000E+00 0.6270E-13      7
   1    0      -3      0      3  0.13377876E+01  0.00000000E+00 0.6789E-13      6
  Time elapsed :      0.424 s

Mode Search
-----------

Mode parameters
   l : 2
   m : 0

Building frequency grid (REAL axis)
   added scan interval :  0.5000E+00 ->  0.1500E+01 (100 points, INVERSE)

Building spatial grid
   Refined 6 subinterval(s) in iteration 1
   Refined 0 subinterval(s) in iteration 2
   Final grid has 1 segment(s) and 1820 point(s):
      Segment 1 : x range 0.0000 -> 1.0000 (1 -> 1820)

Starting search (adiabatic)

Evaluating discriminant
  Time elapsed :     0.728 s

Root Solving
   l    m    n_pg    n_p    n_g       Re(omega)       Im(omega)        chi n_iter
   2    0     -16      0     16  0.51863360E+00  0.00000000E+00 0.1733E-13      7
   2    0     -15      0     15  0.55636039E+00  0.00000000E+00 0.1193E-13      5
   2    0     -14      0     14  0.59457063E+00  0.00000000E+00 0.2694E-13      7
   2    0     -13      0     13  0.62301082E+00  0.00000000E+00 0.4294E-13      7
   2    0     -12      0     12  0.67563432E+00  0.00000000E+00 0.3675E-13      7
   2    0     -11      0     11  0.74334407E+00  0.00000000E+00 0.6647E-14      6
   2    0     -10      0     10  0.79690602E+00  0.00000000E+00 0.2893E-13      7
   2    0      -9      0      9  0.87152970E+00  0.00000000E+00 0.2285E-13      7
   2    0      -8      0      8  0.99746970E+00  0.00000000E+00 0.6653E-14      6
   2    0      -7      0      7  0.11297111E+01  0.00000000E+00 0.2909E-13      7
   2    0      -6      0      6  0.12531594E+01  0.00000000E+00 0.1250E-15      7
  Time elapsed :      0.628 s

The columns appearing are as follows:

l

harmonic degree \(\ell\)

m

azimuthal order \(m\)

n_pg

radial order \(n\) (in the Eckart-Osaki-Scuflaire-Takata scheme)

n_p

acoustic-wave winding number \(n_{\rm p}\)

n_g

gravity-wave winding number \(n_{\rm g}\)

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)

chi

convergence parameter

n_iter

number of iterations required for convergence

These values are printed to screen primarily to give an idea of GYRE’s progress; more-detailed information about the modes found is given in the output files, discussed in the following chapter. 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-13). 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_iter should be moderate; values above 20 or so indicate that GYRE is having problems converging.

  • The mode radial order n_pg should 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.h5

  • For each mode found, a detail file with the name detail.lL.nN.h5, where L and N are the harmonic degree and radial order of the mode, respectively.

The following chapter discusses how to read and analyze these files.