Working With Tags

This chapter uses a worked example to demonstrate tags — a simple yet powerful feature allowing a much greater degree of control over GYRE calculations.

Example Tag Usage

Consider applying gyre to calculate the eigenfrequencies of a red giant branch (RGB) stellar model. Because non-radial p-modes in the convective envelope couple with high-order g-modes in the radiative core, the frequency spacing of the non-radial modes is much smaller than that of the radial modes. In such cases, we ideally want to use a coarse frequency scan for the radial modes and a fine frequency scan for the non-radial modes.

The following input file, which is designed to work with the \(2\,\Msun\) RGB model in $GYRE_DIR/models/mesa/rgb/rgb.mesa, achieves this goal using tags:

&constants
/

&model
  model_type = 'EVOL'  ! Obtain stellar structure from an evolutionary model
  file = 'rgb.mesa'    ! File name of the evolutionary model
  file_format = 'MESA' ! File format of the evolutionary model
/

&mode
  l = 0          ! Harmonic degree
  tag = 'radial' ! Matching tag
/

&mode
  l = 1              ! Harmonic degree
  tag = 'non-radial' ! Matching tag
/

&mode
  l = 2              ! Harmonic degree
  tag = 'non-radial' ! Matching tag
/

&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 = 'LINEAR' ! Scan grid uniform in frequency
  freq_min = 41        ! Minimum frequency to scan from
  freq_max = 43        ! Maximum frequency to scan to
  freq_units = 'UHZ'   ! Frequency units
  n_freq = 10          ! Number of frequency points in scan
  tag_list = 'radial'  ! Pair only with 'radial' &mode groups
/

&scan
  grid_type = 'LINEAR' 	  ! Scan grid uniform in frequency
  freq_min = 41        	  ! Minimum frequency to scan from
  freq_max = 43           ! Maximum frequency to scan to
  freq_units = 'UHZ'      ! Frequency units
  n_freq = 100            ! Number of frequency points in scan
  tag_list = 'non-radial' ! Pair only with 'non-radial' &mode groups
/

&grid
  w_osc = 10  ! Oscillatory region weight
  w_exp = 2   ! Exponential region weight
  w_ctr = 100 ! Central region weight
/

&ad_output
  summary_file = 'summary.h5'                  ! File name for summary file
  summary_item_list = 'l,n_pg,freq,freq_units' ! Fields to appear in summary file
  freq_units = 'UHZ'                           ! Units of frequency-like output fields
/

&nad_output
/

Observe that each &mode namelist group has a tag option. When processing a given group, gyre pairs it up with other namelist groups that match either of the following criteria:

  • The tag_list option is not set;

  • The tag_list option is set to a comma-separated list, and at least one element of this list matches the tag option.

In the example given above, the tag_list option of the &osc namelist group is unset; therefore, this group is paired with all three &mode namelist groups, irrespective of their tag options. However, the two &scan namelist groups each set their tag_list options. In the first group the radial tag appears, and so this group is paired with the first &mode namelist group (i.e., the \(\ell=0\) mode). Likewise, in the second group the non-radial tag appears, and so this group is paired with the second and third &mode namelist groups (i.e., the \(\ell=1\) and \(\ell=2\) modes).

Tag Rules

In addition to the matching criteria given above, there are a couple of rules that must be obeyed by tags:

  • Tag names can’t contain commas (however, they can be otherwise arbitrary);

  • If a &mode namelist group doesn’t have a tag option, then only namelists without a tag_list option will be paired with it;

  • The &constants, &model, &ad_output, &nad_output, and &tide_output namelist groups don’t support tags.