# Spatial Grids¶

GYRE discretizes the oscillation equations on a spatial grid $$\{x_{1},x_{2},\ldots,x_{N}\}$$ in the dimensionless radial coordinate $$x \equiv r/R$$. The computational cost of a calculation scales with the total number of points $$N$$ in this grid, while the grid’s resolution — i.e., the spacing between adjacent points — impacts both the number of modes that can be found by GYRE, and the accuracy of these modes (see the Limitations of the Numerical Method section for a discussion of these behaviors in the context of the stretched string BVP).

## Scaffold Grid¶

GYRE constructs a fresh spatial grid for each combination of harmonic degree $$\ell$$ and azimuthal order $$m$$ specified in the &mode namelist groups (see the Namelist Input Files chapter for more details). The starting point for each of these grids is the scaffold grid, which comprises the following:

• an inner point $$x=\xin$$;
• an outer point $$x=\xout$$;
• the subset of points of the input model grid satisfying $$\xin < x < \xout$$

By default, $$\xin$$ and $$\xout$$ are obtained from the input model grid as well, meaning that the scaffold grid is identical to the model grid. However, either or both can be overridden using the x_i and x_o parameters, respectively, of the &grid namelist group.

## Iterative Refinement¶

GYRE refines a scaffold grid through a sequence of iterations. During a given iteration, each subinterval $$[x_{k},x_{k+1}]$$ ($$k=1,2,\ldots,N-1$$) is assessed against various criteria (discusssed in greater detail below). If any criteria match, then the subinterval is refined by bisection, inserting an additional point at the midpoint

$x_{k+1/2} = \frac{x_{k} + x_{k+1}}{2}.$

The sequence terminates if no refinements occur during a given iteration, or if the number of completed iterations equals the value specified by the n_iter_max parameter of the &grid namelist group.

### Mechanical Criterion¶

The wave criterion involves a local analysis of the mechanical parts of the oscillation equations, with the goal of improving resolution where the displacement perturbation $$\vxi$$ is rapidly varying. Within the subinterval $$[x_{k},x_{k+1}]$$, the $$y_{1}$$ and $$y_{2}$$ solutions (see the Mathmatical Formalism chapter) take the approximate form

$y_{1,2}(x) \sim \exp [ \chi \, \ln x ],$

where $$\chi$$ is one of the eigenvalues of the mechanical (upper-left) $$2 \times 2$$ submatrix of the full Jacobian matrix $$\mA$$ , evaluated at the midpoint $$x_{k+1/2}$$.

In propagation zones the imaginary part $$\chi_{\rm i}$$ of the eigenvalue gives the local wavenumber in $$\ln x$$ space, and $$2\pi \chi_{\rm i}^{-1}$$ the corresponding wavelength; while in evanescent zones the real part $$\chi_{\rm r}$$ gives the local exponential growth/decay rate, and $$\chi_{\rm r}^{-1}$$ the corresponding e-folding length.

Based on this analysis, the criterion for refinement of the subinterval is

$( \ln x_{k+1} - \ln x_{k} ) \, \max (\alpha_{\rm osc} |\chi_{\rm i}|, \alpha_{\rm exp} |\chi_{\rm r}|) > 2 \pi$

This causes refinement if the subinterval width (in $$\ln x$$ space) exceeds $$\alpha_{\rm osc}^{-1}$$ times the local wavelength, or $$2\pi \alpha_{\rm exp}^{-1}$$ times the local e-folding length. The controls $$\alpha_{\rm exp}$$ and $$\alpha_{\rm exp}$$ are set via the alpha_exp and alpha_osc parameters, respectively, of the &grid namelist group.

Tip

While alpha_exp and alpha_osc default to zero, it is highly recommended to use non-zero values for these parameters, to ensure adequate resolution of solutions throughout the star. Reasonable starting choices are alpha_osc = 10 and alpha_exp = 2.

Because there are two possible values for $$\chi$$, the above refinement criterion is applied twice (once for each). Moreover, because $$\chi$$ depends implicitly on the oscillation frequency, the criterion is applied for each frequency in the grid $$\{\omega_{1},\omega_{2},\ldots,\omega_{M}\}$$.

### Thermal Criterion¶

Similar to the wave criterion discussed above, the thermal criterion involves a local analysis of the energetic parts of the oscillation equation, with the goal of improving resolution where the thermal timescale is very long and perturbations are almost adiabatic. Within the subinterval $$[x_{k},x_{k+1}]$$, the $$y_{5}$$ and $$y_{6}$$ perturbation take the approximate form

$y_{5,6}(x) \sim \exp [ \pm \tau \, (\ln x - \ln x_{k+1/2}) ],$

where $$\pm\tau$$ are the eigenvalues of the matrix formed from the energetic (bottom-rright) $$2 \times 2$$ submatrix of the full Jacobian matrix $$\mA$$, evaluated at the midpoint $$x_{k+1/2}$$.

Based on this analysis, the criterion for refinement of the subinterval is

$( \ln x_{k+1} - \ln x_{k} ) \, \alpha_{\rm thm} |\tau| > 1.$

The control $$\alpha_{\rm thm}$$ is set via the alpha_thm parameters of the &grid namelist group.

Because $$\tau$$ depends implicitly on the oscillation frequency, this criterion is applied for each frequency in the grid $$\{\omega_{1},\omega_{2},\ldots,\omega_{M}\}$$.

### Structural Criteria¶

The structural criteria have the goal of improving resolution where the stellar structure coefficients are changing rapidly. For a given coefficient $$C$$, the criterion for refinement of the subinterval $$[x_{k},x_{k+1}]$$ is

$( \ln x_{k+1} - \ln x_{k} ) \, \alpha_{\rm str} \left| \pderiv{\ln C}{\ln x} \right| > 1$

The control $$\alpha_{\rm thm}$$ is set via the alpha_thm parameter of the &grid namelist group. This criterion is applied to the $$V_2 \equiv V/x$$, $$U$$, $$A^{*}$$, $$c_{1}$$ and $$\Gamma_{1}$$ coefficients (see the structure-coeffs section).

### Central Criteria¶

All of the above criteria depend on the logarithmic subinterval width $$(\ln x_{k+1} - \ln x_{k})$$, and cannot be applied to the first subinterval $$[x_{1},x_{2}]$$ if it extends to the center of the star $$x = 0$$. In such cases, the resolve_ctr parameter of the &grid namelist group determines whether the subinterval is refined. If set to .FALSE., then no refinement occurs; while if set to .TRUE., then the refinement criteria are

$\chi_{\rm i} > 0$

or

$\alpha_{\rm ctr} | \chi_{\rm r} | > 1$

where $$\chi$$ is the eigenvalue from the local analysis (see the Mechanical Criterion section) corresponding to the solution that remains well-behaved at the origin. The first criterion causes refinement if the subinterval is in a propagation zone, and the second if the solution slope $$|\sderiv{\ln y}{\ln x}| \sim |\chi_{\rm r}|$$ exceeds $$\alpha_{\rm ctr}^{-1}$$. The control $$\alpha_{\rm ctr}$$ is set via the alpha_ctr parameter of the &grid namelist group.

Tip

While alpha_ctr defaults to zero, it is highly recommended to use a non-zero value for this parameter, to ensure adequate resolution of solutions at the center. A reasonable starting choice is alpha_ctr = 10.

Because $$\chi$$ depends implicitly on the oscillation frequency, these criteria are applied for each frequency in the grid $$\{\omega_{1},\omega_{2},\ldots,\omega_{M}\}$$.

## Limiting Controls¶

A couple of additional controls affect the iterative refinement described above. Refinement of the $$[x_{k},x_{k+1}]$$ subinterval always occurs if

$x_{k+1} - x_{k} > \Delta x_{\rm max},$

and never occurs if

$x_{k+1} - x_{k} < \Delta x_{\rm min}.$

The $$\Delta x_{\rm max}$$ and $$\Delta x_{\rm max}$$ controls are set by the dx_max and dx_min parameters, respectively, of the &grid namelist group.