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
cd $GYRE_DIR 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 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 / &constants / &mode l = 2 ! Harmonic degree / &osc outer_bound = 'ZERO' ! Use a zero-pressure outer mechanical boundary condition / &num ivp_solver = 'MAGNUS_GL4' ! 4th-order Magnus solver for initial-value integrations / &scan 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 / &output 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:
&constantsnamelist is used to override constants such as the gravitational constant; here it's empty, indicating that default values should be used
&modelnamelist tells GYRE to read an evolutionary model, in MESA format, from the file
&modenamelist tells GYRE to consider quadrupole (ℓ=2) modes
&oscnamelist tells GYRE to apply a zero-pressure outer mechanical boundary condition in the oscillation equations
&scannamelist tells GYRE to scan a region of dimensionless angular frequency space typically occupied by gravity modes
&recon_gridnamelists 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)
&outputnamelist tells GYRE to write out summary data to the file
summary.txt, and individual mode data to files having the prefix
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_pgshould be monotonic-increasing. Missing values indicate that GYRE has skipped a mode; the fix is to increase the
n_freqparameter in the
&scannamelist. 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
chishould 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_itershould 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
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
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.