Wiki

Clone wiki

gyre / Understanding Grids


Overview

In the example provided on the Getting Started page, we used default choices for GYRE's grids. However, to get the best out of the code it's important to understand how these grids are created, and how they can be adjusted. Above all else, keep in mind the fundamental distinction between the shooting and reconstruction grids:

Eigenfrequencies depend only on the choice of the shooting grid; whereas eigenfunctions depend on the reconstruction grid, and (possibly, indirectly) also on the shooting grid.

Shooting Grid

The shooting grid is built via a sequence of operations, specified in one or more &shoot_grid namelists in the namelist input file. The op_type parameters in these namelists determines what sort of operation to apply. The first operation must always be one of the creation operations, which begin with the prefix CREATE_; this establishes a starting grid. Subsequent operations then modify this starting grid in a variety of ways.

To illustrate this process, let's play around with the model in $GYRE_DIR/models/mesa/rgb/rgb.mesa. This is a 2M star about a third of the way up the RGB, constructed to correspond loosely with model B of Dupret et al. (2009). Make a fresh working directory, copy this file into it, and create a new namelist input file with the following contents:

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

&constants
/

&mode
	l = 1				! Harmonic degree
/

&osc
        outer_bound_type = 'ZERO'	! Use a zero-pressure outer mechanical boundary condition
/

&num
	ivp_solver_type = '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 = 'UHZ'	! Interpret freq_min and freq_max as having units of microHertz
        freq_min = 39		! Minimum frequency to scan from
	freq_max = 42		! Maximum frequency to scan to
	n_freq = 200		! Number of frequency points in scan
/

&shoot_grid
	op_type = 'CREATE_CLONE'	! Clone the model grid
/

&recon_grid
	op_type = 'CREATE_CLONE'	! Clone the shooting grid
/

&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 important part here is the &shoot_grid namelist, which instructs GYRE to create a shooting grid by simply cloning the grid in the rgb.mesa stellar model file. Running gyre_ad with this input file works, but the results are a little strange. For instance, the screen output for the initial modes found looks like this:

⋮
       l    n_pg     n_p     n_g                 Re(omega)                 Im(omega)                       |D|  n_iter
       1    -209      20     229    0.1148230396341127E+02    0.0000000000000000E+00    0.6021641795993515E-13       6
       1    -206      24     230    0.1151213052641809E+02    0.0000000000000000E+00    0.8472490486273440E-13       6
       1    -199      22     221    0.1154720632182106E+02    0.0000000000000000E+00    0.9428006709616416E-13       5
       1    -218      15     233    0.1158048027951923E+02    0.0000000000000000E+00    0.4339820882011253E-13       6
       1    -201      22     223    0.1161474601481406E+02    0.0000000000000000E+00    0.3096799951972885E-12       5
       1    -214      17     231    0.1164894571637713E+02    0.0000000000000000E+00    0.3417426956777021E-13       5
⋮

The radial order n_pg is not monotonic-increasing even though the eigenfrequency is, which clearly indicates that something is going wrong. The problem is that GYRE isn't adequately resolving the modes' highly oscillatory behavior in the stellar core. The fix is to add a second &shoot_grid namelist to the input file:

&shoot_grid
	op_type = 'RESAMP_DISPERSION'	! Resample the grid based on the local dispersion relation
	alpha_osc = 10			! At least 5 points per oscillatory wavelength
	alpha_exp = 2			! At least 1 point per exponential 'wavelength'
/

(place this below the existing &shoot_grid namelist). This second namelist instructs GYRE to resample the starting grid created by the first namelist, based on the local dispersion relation for gravito-acoustic waves. Specifically, additional grid points are inserted to ensure that there are at least approximately 10 points per wavelength in oscillatory regions, and at least two points per exponential 'wavelength' (i.e., scale height divided by 2π) in evanescent regions. If we now re-run gyre_ad the calculation may take a little bit longer because the shooting grid has more points than before. However, this is a price worth paying; the screen output reveals radial orders which are now nicely behaved:

⋮
       l    n_pg     n_p     n_g                 Re(omega)                 Im(omega)                       |D|  n_iter
       1    -344       7     351    0.1147631368955241E+02    0.0000000000000000E+00    0.2579017075233130E-12       6
       1    -343       7     350    0.1150887501264132E+02    0.0000000000000000E+00    0.5768043077430822E-12       6
       1    -342       7     349    0.1154161286110121E+02    0.0000000000000000E+00    0.2430749377782188E-12       6
       1    -341       7     348    0.1157441171978760E+02    0.0000000000000000E+00    0.2320518219346954E-12       6
       1    -340       7     347    0.1160721817335924E+02    0.0000000000000000E+00    0.1166766200754657E-13       6
       1    -339       7     346    0.1164014235479612E+02    0.0000000000000000E+00    0.14286474061866276324304023E-01
⋮

Although not necessary in this case, the shooting grid can be further tweaked in a variety of ways. For instance, to make sure that that the envanescent region at the center is properly resolved, we can add another &shoot_grid namelist:

&shoot_grid
	op_type = 'RESAMP_CENTER'	! Resample the grid at the center
	n = 10				! At least 10 points in the evanescent region
/

This will ensure that at least 10 grid points span the central evanescent region.

Reconstruction Grid

The reconstruction grid is built using a very similar approach to the shooting grid. The main difference is that the sequence of operations is specified in the &recon_grid namelists, rather than the &shoot_grid namelists. Also, the CREATE_CLONE operation clones the shooting grid, rather than the stellar model grid.

In the example given above the shooting and reconstruction grids are identical. Having different grids can be useful in some circumstances; one example is quick-and-dirty eigenspectrum calculations. Suppose we modify the input file above so that the shooting and reconstruction namelists are as follows:

&shoot_grid
/

&recon_grid
/

&recon_grid
	op_type = 'RESAMP_DISPERSION'	! Resample the grid based on the local dispersion relation
	alpha_osc = 5			! At least 5 points per oscillatory wavelength
	alpha_exp = 1			! At least 1 point per exponential 'wavelength'
/

(here, we've used a little shortcut: an empty &shoot_grid and/or &recon_grid namelist is equivalent to one with op_type set to CREATE_CLONE). Rerunning gyre_ad produces the output

       l    n_pg     n_p     n_g                 Re(omega)                 Im(omega)                       |D|  n_iter
       1    -341       7     348    0.1148230396341127E+02    0.0000000000000000E+00    0.6021641795993515E-13       6
       1    -340       7     347    0.1151213052641809E+02    0.0000000000000000E+00    0.8472490486273440E-13       6
       1    -339       7     346    0.1154720632182106E+02    0.0000000000000000E+00    0.9428006709616416E-13       5
       1    -338       7     345    0.1158048027951923E+02    0.0000000000000000E+00    0.4339820882011253E-13       6
       1    -337       7     344    0.1161474601481406E+02    0.0000000000000000E+00    0.3096799951972885E-12       5
       1    -336       7     343    0.1164894571637713E+02    0.0000000000000000E+00    0.3417426956777021E-13       5

At first glance, this seems OK; but a careful comparison with the results given above reveals that the radial orders are all offset by 3. In fact, the whole eigenspectrum has been shifted to higher frequencies, as a consequence of using a shooting grid which underesolves the modes. However, because the reconstruction grid in this case does have adequate resolution, the radial orders (which depend on the eigenfunctions) behave quite reasonably.

What's the point of such an exercise? Simply put, gyre_ad runs runs faster when there is no additional resampling of the shooting grid. If only a rough characterization of the eigenspectrum is required, then this performance boost may well be worth it.

Grids for Non-Adiabatic Calculations

Particular care must be used in setting up grids for non-adiabatic calculations in gyre_nad. In the deep interior of a star, where the pulsation is very close to adiabatic, the reconstructed thermal (entropy and luminosity) eigenfunctions can show spikes in the vicinity of the points of the shooting grid. These spikes are similar to Gibbs phenomenon oscillations, and arise from the response of the almost-algebraic thermal equations to discontinuous changes in the coefficients across the grid points.

The fix appears to be relatively simple: use a reconstruction grid with points placed at the midpoints of the shooting grid. This can easily be done in versions >= 3.0 using the CREATE_MIDPOINT operation.

Updated