1. Richard Townsend
  2. gyre


Clone wiki

gyre / Running GYRE


These instructions assume you've already worked through the downloading, compiling and testing steps documented on the Getting Started page. If that's the case, then read on to learn how to run GYRE!

Making a Place to Work

First, it's always a good idea to set up a separate area to contain the various input and output files GYRE operates on. These commands will make a new subdirectory with the name $GYRE_DIR/work:

mkdir work

Grabbing a Stellar Model

The next step is to grab a stellar model which will form the basis for GYRE's calculation. There are a number of models provided beneath the $GYRE_DIR/models subdirectory; the following commands will copy a model for a 5M slowly pulsating B (SPB) star into the newly-created work area:

cp $GYRE_DIR/models/mesa/spb/spb.mesa $GYRE_DIR/work/

Creating a Namelist File

Now comes the fun part: creating a namelist input file containing the various parameters which control a GYRE run. Using a text editor, create the file $GYRE_DIR/work/gyre_ad.in with the following contents:

	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


	l = 2                     ! Harmonic degree

        outer_bound = 'ZERO' ! Use a zero-pressure outer mechanical boundary condition

	ivp_solver = 'MAGNUS_GL4' ! 4th-order Magnus solver for initial-value integrations

        grid_type = 'INVERSE' ! Scan for modes using a uniform-in-period grid; best for g modes
        freq_units = 'NONE'   ! Interpret freq_min and freq_max as being dimensionless
        freq_min = 0.15       ! Minimum frequency to scan from
	freq_max = 0.9        ! Maximum frequency to scan to
	n_freq = 250          ! Number of frequency points in scan

&shoot_grid ! Can be left empty

&recon_grid ! Can be left empty

        summary_file = 'summary.txt'                            ! File name for summary file
	summary_file_format = 'TXT'                             ! Format of summary file
        summary_item_list = 'M_star,R_star,l,n_pg,omega,E_norm' ! Items to appear in summary file
        mode_prefix = 'mode-'                      		! File-name prefix for mode files
	mode_file_format = 'TXT'                   		! Format of mode files
        mode_item_list = 'l,n_pg,omega,x,xi_r,xi_h'   		! Items to appear in mode files

(the file doesn't have to be called gyre_ad.in, but that's the convention generally followed).

Detailed information on the format of namelist input files can be found here; for now, let's just focus on some of the more-important aspects of the file above:

  • The &constants namelist is used to override constants such as the gravitational constant; here it's empty, indicating that default values should be used
  • The &model namelist tells GYRE to read an evolutionary model, in MESA format, from the file spb.mesa
  • The &mode namelist tells GYRE to consider quadrupole (ℓ=2) modes
  • The &osc namelist tells GYRE to apply a zero-pressure outer mechanical boundary condition in the oscillation equations
  • The &scan namelist tells GYRE to scan a region of dimensionless angular frequency space typically occupied by gravity modes
  • The &shoot_grid and &recon_grid namelists are empty, telling GYRE to use the stellar model grid for shooting and reconstruction calculations (see Understanding Grids to learn about more-sophisticated gridding options)
  • The &output namelist tells GYRE to write out summary data to the file summary.txt, and individual mode data to files having the prefix mode-

Running the Adiabatic Code

With the hard work done, it's now trivial to run the adiabatic code:

cd $GYRE_DIR/work
../bin/gyre_ad gyre_ad.in

As it runs (on multiple cores, if you have a multi-core machine; see here for more details), the code will print lots of data to the screen. The output should look something like this (with parts omitted for brevity):

       l    n_pg     n_p     n_g                 Re(omega)                 Im(omega)                       chi  n_iter        n
       2     -53       0      53    0.1523203114633929E+00    0.0000000000000000E+00    0.6975803875542554E-15       6      873
       2     -52       0      52    0.1550724547350297E+00    0.0000000000000000E+00    0.6147607938601522E-14       7      873
       2     -51       0      51    0.1586240579799114E+00    0.0000000000000000E+00    0.3743325802950483E-14       6      873
       2     -13       0      13    0.5773654452018933E+00    0.0000000000000000E+00    0.1012854246656635E-14       7      873
       2     -12       0      12    0.6303134954016816E+00    0.0000000000000000E+00    0.1975405042991507E-14       6      873
       2     -11       0      11    0.6947826076531260E+00    0.0000000000000000E+00    0.1023255826813688E-14       7      873
       2     -10       0      10    0.7397083665396534E+00    0.0000000000000000E+00    0.5997113954270528E-15       8      873
       2      -9       0       9    0.8126184398032162E+00    0.0000000000000000E+00    0.1193152765254079E-15       7      873
  Time elapsed :      2.926 s

The numeric lines summarize each mode found by GYRE. The top line labels the columns as follows:

  • l : harmonic degree
  • n_pg : radial order
  • n_p : acoustic-wave winding number
  • n_g : gravity-wave winding number
  • Re(omega) : dimensionless eigenfrequency (real part)
  • Im(omega) : dimensionless eigenfrequency (imaginary part)
  • chi : convergence parameter (should be small)
  • n_iter : number of iterations required for convergence
  • n : number of grid points used

These data 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 below. Some things to watch out for:

  • The mode index n_pg should be monotonic-increasing. Missing values indicate that GYRE has skipped a mode; the fix is to increase the n_freq parameter in the &scan namelist. Missing values together with duplicate and/or non-monotonic values can also arise when GYRE's grids aren't properly resolving eigenfunctions (resulting in a misclassification); the fix is to use a finer reconstruction grid.
  • The convergence parameter chi should be small. Values comparable to or greater than unity indicate that GYRE has failed to converge properly to a mode. The fix in such cases isn't obvious, and it may be time to file a bug report!
  • The number of iterations n_iter should be smallish, up to a few tens. Larger values indicate that GYRE had some difficulty in converging to the mode, perhaps warranting further investigation.

Interpreting Output Files

Overall properties of all modes found (eigenfrequencies, inertias, etc.) are collected together in the file summary.txt. For each mode GYRE also writes a file with the name mode-NNNN.txt, containing data (eigenfrequency, eigenfunctions, etc.) specific to the mode. Here, NNNN denotes a 4-digit index which increments (starting at 0001) for each mode found. Note that this index bears no relation to the radial order n_pg; it merely serves as a unique label for the modes.

Both the sumamry file and the mode files are text-based (it's possible to write HDF5-format files instead; see the Output Files page for details). Running

head summary.txt

will print out the first 10 lines of the summary file, which should look something like this:

                       1                       2
                  M_star                  R_star
  0.9931676064300001E+34  0.2702917895210000E+12
                       1                       2                       3                       4                       5
                       l                    n_pg               Re(omega)               Im(omega)                  E_norm
                       2                     -53  0.1523203114633929E+00  0.0000000000000000E+00  0.1198714673728683E-03
                       2                     -52  0.1550724547350297E+00  0.0000000000000000E+00  0.8885617675450549E-04
                       2                     -51  0.1586240579799114E+00  0.0000000000000000E+00  0.9049565878151996E-04
                       2                     -50  0.1619275095726223E+00  0.0000000000000000E+00  0.1328834549335134E-03
                       2                     -49  0.1643699689947963E+00  0.0000000000000000E+00  0.1334849871739865E-03

The first three lines give column numbers, labels, and values for the scalar data — here, the stellar mass M_star and radius R_star, expressed in cgs units. The next two lines give column numbers and labels for the per-mode data (E_norm is the normalized mode inertia, and the other columns are the same as described above for the gyre_ad screen output); the subsequent lines then give the corresponding values (one line per mode). The mode files have a similar layout, with scalar data followed by array data representing the eigenfunctions (one line per radial grid point).

The choice of which data appear in output files isn't hardwired, but rather determined by the summary_item_list and mode_item_list parameters of the &output namelist. Changing these parameters allows you to tailor the files to contain exactly the data you need. For a full list of possible items, consult the Output Files page.