Input parameters#

This page provides a quick reference for all supported namelist variables in the main_input file.

Problemsize#

This namelist is used to specify the grid.

n_r

Number of radial points in model grid

rmin

Radius of the inner domain boundary, \(r_\mathrm{min}\)

rmax

Radius of the outer domain boundary, \(r_\mathrm{max}\)

aspect_ratio

\({r_\mathrm{min}}/{r_\mathrm{max}}\)

shell_depth

\(r_\mathrm{max}-r_\mathrm{min}\)

n_theta

Number of theta points in the model grid, \(N_\theta\)

l_max

Truncation degree \(\ell_\mathrm{max}\) used in the spherical harmonic expansion

n_l

\(\ell_\mathrm{max}+1\)

nprow

Number of MPI ranks within each row of the 2-D process grid

npcol

Number of MPI ranks within each column of the 2-D process grid

ncheby

Comma-separated list indicating number of Chebyshev polynomials used in each radial subdomain (e.g., 16, 32, 16). Default: n_r [ single domain]

dealias_by

Comma-separated list indicating number of Chebyshev modes dealiased to zero. Default is 2/3 ncheby.

domain_bounds

The domain bounds defining each Chebyshev subdomain

n_uniform_domains

Number of uniformly-sized Chebyshev domains spanning the depth of the shell. Default: 1

uniform_bounds

When set to .true., each chebyshev subdomain will possess the same radial extent. Default: .false.

dr_weights

Comma-separated list of of real-valued numbers that defines the relative weighting of gridpoint spacing between subregions of uniform grid spacing when working with finite-differences and a nonuniform mesh. If left unspecified, a uniform grid spanning from rmin to rmax will be employed. dr_weights should contain the same number of elements as nr_count. Additional details may be found here.

nr_count

Comma-separated list of integer numbers that defines the number of radial points within each region of uniform grid spacing. nr_count must contain the same number of elements as dr_weights. When nr_count and dr_weights are specified, any value of n_r specified in main_input is ignored, and n_r is instead set to SUM(nr_count). Details are provided here.

radial_grid_file

String variable indicating the name of a grid-description file. When specified, and when finite-difference mode is active, Rayleigh will use the contents of this file to define the radial grid. Instructions for generating this file in the proper format are provided here.

rescale_radial_grid

Logical variable. When set to .true., the contents of radial_grid_file will be rescaled so that rmin and rmax coincide with any values specified in main_input. Default value = .false.

Numerical Controls#

This namelist provides access to Rayleigh’s run-time optimization options.

band_solve

For use with models employing either a finite-difference scheme or at least three Chebyshev domains in radius. In those models, the rows of the normally dense matrices used in the Crank-Nicolson scheme may be rearranged into a banded or block-banded form for finite-difference and Chebyshev methods respectively. Setting this variable to .true. will perform this rearrangement, and Rayleigh will execute a band, rather than dense, solve during each timestep. Using the band-solve approach can help save memory and may yield performance gains. No benefit is gained for models using one or two Chebyshev domains. The default behavior is to use a dense solve (band_solve = .false.).

static_transpose

When set to .true., buffer space used during Rayleigh’s transposes is allocated once at runtime. The default behavior (static_tranpose=.false.) is to allocate and deallocate buffer space during each transpose. On some machines, avoiding this cycle of allocation/deallocation has led to minor performance improvements.

static_config

When set to .true., sphericalbuffer configurations (e.g., p3a, s2b) are allocated once at runtime. The default behavior (static_config=.false.) is to save memory by deallocating memory associated with the prior configuration space following a transpose. If memory is not an issue, this may lead to minor performance improvements on some systems.

pad_alltoall

When set to .true., transpose buffers are padded throughout with zeros to enforce uniform message size, and a standard alltoall is used for each transpose. The default behavior (pad_alltoall=.false.) uses alltoallv and variable message sizes. Depending on the underlying alltoall algorithms in the MPI implementation used, performance my differ between these two approaches.

chebyshev

When set to .true. (the default setting), a Chebyshev collocation scheme will be employed in radius. When set to .false., a 4th-order finite-difference scheme will instead be employed for the interior points, and 2nd-order finite differences will be applied at the inner and outer radial boundaries.

Physical Controls#

This namelist controls the physical effects used in a Rayleigh simulation.

magnetism

When set to .true., the MHD approximation is employed. The default (magnetism=.false.) is to omit the effects of magnetism.

nonlinear

When set to .false., all nonlinear terms are omitted in the model. The default (nonlinear=.true.) is to include those terms.

momentum_advection

When set to .false., \(\boldsymbol{v}\cdot\boldsymbol{\nabla}\boldsymbol{v}=0\). This flag is primarily for debugging purposes. The default value is .true.

inertia

When set to .false., the material derivative of velocity is omitted (\(\frac{D\boldsymbol{v}}{Dt}=0\)). This option is primarily intended for mantle convection models. The default value is .true.

rotation

When set to .true., the Coriolis term is included in the momentum equation. The default behavior is to omit rotation in a Rayleigh model (rotation = .false.).

lorentz_forces

Set this debugging/development flag to .false. to disable the Lorentz force. Default value is .true., but this flag is ignored entirely when magnetism = .false.

viscous_heating

Determines whether viscous heating is included in the thermal energy equation. Default value is .true. Note that the user-supplied value of this variable is ignored entirely for Boussinesq models run with reference_type = 1. In those models, viscous_heating is set to .false.

ohmic_heating

Determines whether ohmic heating is included in the thermal energy equation. Default value is .true. Note that the user-supplied value of this variable is ignored entirely for Boussinesq models run with reference_type = 1. In those models, ohmic_heating is set to .false.

advect_reference_state

Determines whether the reference-state entropy is advected. The default is .true. When set to .false., the \(v_r\frac{\partial\overline{S}}{\partial r}\) term is omitted in the thermal energy equation. Note that this variable has no impact on models with an adiabatic background state.

benchmark_mode

When set to a positive value in the interval [1,4], an accuracy benchmark will be performed. The default is 0 (no benchmarking). Boussinesq benchmarks are peformed for values of 1 (nonmagnetic) and 2 (magnetic). Anelastic benchmarks are performed if benchmark_mode has a value of 3 (nonmagnetic) or 4 (magnetic).

benchmark_integration_interval

Determines the interval (in timesteps) between successive benchmark snapshot analyses.

benchmark_report_interval

Determines the interval (in timesteps) between successive benchmark report outputs. Each output contains an average over all benchmark snapshot analyses performed since the previous report.

Temporal Controls#

This namelist controls timing, time-stepping, and checkpointing in Rayleigh.

alpha_implicit

Determines the value of \(\alpha\) used in the Crank-Nicolson semi-implicit time-stepping scheme employed for linear terms. The default value is 0.5, which ensures second-order accuracy of the algorithm. A value of 1 (0) describes a fully implicit (explicit) algorithm.

max_iterations

Maximum number of timesteps for which to evolve a single instance of Rayleigh before exiting the program. Note that this value does not describe the maximum number of timesteps a model can be run for. Instead, it determines the maximum number of timesteps Rayleigh will run for during a given session (i.e. following a single call to mpiexec/mpirun). The default value is 1,000,000.

max_time_minutes

Maximum walltime (in minutes) for which to run a single instance of Rayleigh before exiting. As with max_iterations, this is specific to a given Rayleigh session. Default is \(10^8\) minutes (essentially, unlimited).

max_simulated_time

The maximum time, in simulation units, for which to evolve a Rayleigh model. Restarting a model that has already reached this limit will result in running for a single time step before exiting. The default is effectively unlimited, with a value of \(10^{20}\).

save_last_timestep

When set to .true. (default), Rayleigh will checkpoint before exiting normally. Note that this generally occurs when the maximum time or iterations is reached. This does not apply when a job is terminated by the MPI job scheduler.

checkpoint_interval

Number of iterations between successive checkpoint outputs. Default value is -1 (no checkpointing).

check_frequency

(deprecated) Same as checkpoint_interval.

quicksave_interval

Number of iterations between successive quicksave outputs. Default value is -1 (no quicksaves).

num_quicksaves

Number of quicksave slots (i.e., rapid, rolling checkpoint folders) to use for a given simulation. Default value is 3.

quicksave_minutes

Time in minutes between successive quicksaves. If this variable is set to a positive value (default is -1), the value of quicksave_interval will be ignored.

max_time_step

The maximum allowed time step. This value will respected even when if the CFL constraint admits a larger time-step size. Default value is 1.0.

min_time_step

The minimum allowable time step. If the CFL contraint forces a time-step size that falls below this value, Rayleigh will exit.

cflmin

Used for adaptive timestep control. Rayleigh ensures that the time-step size never falls below \(cflmin\times t_{CFL}\), where \(t_{CFL}\) is the minimum timestep allowed by the CFL constraint. The default value is 0.4.

clfmax

Used for adaptive timestep control. Rayleigh ensures that the time-step size never exceeds \(\mathrm{cflmax}\times t_\mathrm{CFL}\), where \(t_\mathrm{CFL}\) is the minimum timestep allowed by the CFL constraint. The default value is 0.6.

new_iteration

If desired, a simulation’s iteration numbers may be reset upon restarting from a checkpoint. Set this value to the new iteration number to use (must be greater than zero), and the old iteration number contained in the checkpoint file will ignored. The default value is 0.

IO Controls#

This namelist provides various options to control Rayleigh’s input and output cadence and structure.

stdout_file

If desired, set this variable to the name of a file to which Rayleigh’s text output is redirected. This can be useful for monitoring run progress and time-step size on systems that otherwise don’t produce the text output until a run has complete. The default value is ‘nofile,’ which indicates that Rayleigh should not redirect stdout to a file.

stdout_flush_interval

Number of lines to cache before writing to the stdout_file if used. This prevents excessive disk access while a model is evolving. The default value if 50.

jobinfo_file

Set this variable to the name of a file, generated during Rayleigh’s initialization, that contains the values assigned to each namelist variable, along with compiler and Git hash information. The default filename is ‘jobinfo.txt’

terminate_file

The name of a file that, if found in the top-level simulation directory, indicates Rayleigh should terminate execution. This can be useful when trying to exit a run cleanly before the scheduled wall time runs out. The default filename is ‘terminate’.

terminate_check_interval

Number of iterations between successive checks for the presence of the job termination file. The default value is 50.

statusline_interval

Number of iterations between successive outputs to sdout indicating time step number and size. The default value is 1, so that iteration number and time-step size are printed during every time step.

outputs_per_row

Determines the number of process columns that particpate in MPI-IO during checkpointing and diagnostic outputs. Acceptable values fall in the range [1,nprow], with a default value of 1.

integer_output_digits

Number of digits to use for all integer-based filenames (e.g., G_Avgs/00000001). The default value is 8.

integer_input_digits

Number of digits for integer-based checkpoint names to be read during a restart. The default value is 8.

decimal_places

Number of digits to use after then decimal point for those portions of Rayleigh’s text output that displayed in scientific notation. The default value is 3.

Output#

This namelist is described in extensive detail in Rayleigh/post_processing/Diagnostic_Plotting.ipynb. Please see that document for a discussion of these namelist variables and the general structure of Rayleigh’s output.

Boundary Conditions#

This namelist provides those options necessary to determine the boundary conditions employed in a Rayleigh model.

fix_tvar_top

Logical flag indicating whether thermal variable (T,S) should be fixed on the upper boundary. Default = .true.

fix_tvar_bottom

Logical flag indicating whether thermal variable (T,S) should be fixed on the lower boundary. Default = .true.

fix_dtdr_top

Logical flag indicating whether the radial derivative of thermal variable (T,S) should be fixed on the upper boundary. Default = .false.

fix_dtdr_bottom

Logical flag indicating whether the radial derivative of thermal variable (T,S) should be fixed on the lower boundary. Default = .false.

T_top

Value of thermal variable (T,S) at the upper boundary. Default = 0.

T_bottom

Value of thermal variable (T,S) at the lower boundary. Default = 1.

dTdr_top

Value of radial derivative of thermal variable (T,S) at the upper boundary. Default = 0.

dTdr_bottom

Value of radial derivative of thermal variable (T,S) at the lower boundary. Default = 0.

adjust_dTdr_top

Logical flag indicating that dTdr_top should be set based on the values of heating_integral (or luminosity) and the value of dTdr_bottom. Default value is .false. When .true., this flag only has an effect when fix_dtdr_top = .true. and heating_type > 0. When active, dTdr_top is set such that the integrated flux passing through the upper boundary is equal to the sum of those due to internal heating and any flux passing through the lower boundary due to fixed dTdr_bottom.

no_slip_top

When .true., a no-slip condition on the horizontal velocity field is enforced at the upper boundary. Default = .false.

no_slip_bottom

When .true., a no-slip condition on the horizontal velocity field is enforced at the lower boundary. Default = .false.

stress_free_top

When .true., a stress-free condition on the horizontal velocity field is enforced at the upper boundary. Default = .true.

stress_free_bottom

When .true., a stress-free condition on the horizontal velocity field is enforced at the lower boundary. Default = .true.

no_slip_boundaries

When .true., both no_slip_top and no_slip_bottom are set to .false. Default = .false.

strict_L_Conservation

In some cases, typically rotating models employing MHD or thick shells, angular momentum can leak into/out of the domain even when using stree-free boundaries. When .true., this flag replaces the upper boundary condition with an integral constraint on the \(\ell=1\) toroidal streamfunction that enforces strict conservation of angular momentum. Note that the upper boundary is neither stress-free nor no-slip in this case. Default = .false.

T_top_file

Generic-input file containing a custom, fixed (T,S) upper boundary condition.

T_bottom_file

Generic-input file containing a custom, fixed (T,S) lower boundary condition.

dTdr_top_file

Generic-input file containing a custom, fixed (\(\partial T/\partial r\), \(\partial S/\partial r\)) upper boundary condition.

dTdr_bottom_file

Generic-input file containing a custom, fixed (\(\partial T/\partial r\), \(\partial S/\partial r\)) lower boundary condition.

C_top_file

Generic-input file containing a custom upper boundary condition for the poloidal flux function C.

C_bottom_file

Generic-input file containing a custom lower boundary condition for the poloidal flux function C.

Initial Conditions#

All variables necessary to initialize velocity, temperature, pressure, and magnetic field are supplied here.

init_type
Integer value indicating how nonmagnetic variables should be initialized.
  • type -1: Restart from a checkpoint

  • type 1: Hydro Boussinesq benchmark init (Christensen et al. 2001). The temperature field is initialized with an \(\ell=4\) , m=4 perturbation on top of a conductive profile. Velocity/pressure are zero.

  • type 6: Hydro anelastic benchmark init (Jones et al. 2011). The entropy field is initialized with an \(\ell=19\) , m=19 and \(\ell=1\) , m=1 perturbation on top of a conductive profile. Velocity/pressure are zero.

  • type 7: A randomized temperature/entropy field is initialized. Velocity and pressure are set to zero.

  • type 8: Velocity, entropy/temperature, and pressure are initialized to zero, or if an associated filename is provided, they are initialized using the generic input interface.

magnetic_init_type
Integer value indicating how magnetic field should be initialized.
  • type -1: Initialize magnetic field from a checkpoint.

  • type 1: Magnetic initialization for Christensen et al. (2001), case 1. The poloidal flux function is initialized using an \(\ell=1,m=0\) mode. THe toroidal flux function is initialized with an \(\ell=2,m=0\) mode.

  • type 7: The poloidal and toroidal flux functions are initialized to randomized values.

  • type 8: The poloidal and toroidal flux functions are intialized to zero, and then if a corresponding generic input file is specified, their initial state is read from that file.

restart_iter

Iteration number indicating the checkpoint to restart from when init_type and magnetic_init_type equal 1.

temp_amp

Amplitude of randomized temperature/entropy perturbations to use with init_type = 7.

mag_amp

Amplitude of randomized magnetic perturbations to use with magnetic_init_type = 7.

t_init_file

Name of generic input file that, if init_type=8, will be used to initialize temperature/entropy.

p_init_file

Name of generic input file that, if init_type=8, will be used to initialize pressure.

w_init_file

Name of generic input file that, if init_type=8, will be used to initialize the poloidal stream function W.

z_init_file

Name of generic input file that, if init_type=8, will be used to initialize the toroidal stream function Z.

c_init_file

Name of generic input file that, if init_type=8, will be used to initialize the poloidal stream function C.

a_init_file

Name of generic input file that, if init_type=8, will be used to initialize the toroidal stream function A.

rescale_velocity

Logical variable indicating that the velocity field should be rescaled upon restart. Default = .false.

velocity_scale

Factor by which to rescale the velocity field upon restart.

rescale_pressure

Logical variable indicating that the pressure field should be rescaled upon restart. Default = .false.

pressure_scale

Factor by which to rescale the pressure field upon restart.

rescale_tvar

Logical variable indicating that the temperature/entropy field should be rescaled upon restart. Default = .false.

tvar_scale

Factor by which to rescale the temperature/entropy field upon restart.

rescale_bfield

Logical variable indicating that the magnetic field should be rescaled upon restart. Default = .false.

bfield_scale

Factor by which to rescale the magnetic field upon restart.

Reference#

This namelist provides options to control the properties of Rayleigh’s background state.

reference_type
Determines the fluid approximation and background state used by Rayleigh.
  • type 1: Boussinesq + nondimensional

  • type 2: Anelastic + polytropic background state (dimensional)

  • type 3: Anelastic + polytropic background state (non-dimensional)

  • type 4: Custom reference-state (read from file)

poly_n

The polytropic index used to describe the background state for reference types 2 and 3.

poly_Nrho

Number of density scaleheights spanning the interval \(r_\mathrm{min}\le r\le r_\mathrm{max}\) for reference types 2 and 3.

poly_mass

Mass interior to \(r_\mathrm{min}\), used in defining the polytropic reference state for reference types 2 and 3.

poly_rho_i

Specifies the value of density at the inner boundary \(r=r_\mathrm{min}\) for the polytropic reference states of reference types 2 and 3.

pressure_specific_heat

Determines the value of the specific heat at constant pressure, \(c_\mathrm{p}\) for reference types 2 and 3.

heating_type
Integer value that determines the form of the internal heating function \(Q(r)\). The default value is 0, which indicates no internal heating is used. Allowable types are
  • type 1: \(Q(r)\propto\overline{\rho}(r)\overline{T}(r)\).

  • type 4: \(Q(r)\) is a constant function of radius.

heating_integral

Determines the heating normalization \(L\), defined such that \(L=4\pi\int_{r_\mathrm{min}}^{r_\mathrm{max}} Q(r) r^2 dr\).

luminosity

Same as heating_integral. If both are specified, the value of heating_integral will be used.

angular_velocity

Determines the frame rotation rate \(\Omega\) for rotating models employing reference type 2.

rayleigh_number

Sets the value of the Rayleigh number Ra for reference type 1.

ekman_number

Sets the value of the Ekman number Ek for reference types 1 and 3.

prandtl_number

Sets the value of the Prandtl number Pr for reference types 1 and 3.

prandtl_number

Sets the value of the magnetic Prandtl number Pm for reference types 1 and 3.

dissipation_number

Sets the value of the dissipationg number Di for reference type 3.

modified_rayleigh_number

Sets the value of the modified Rayleigh number \(Ra^*\) for reference type 3.

gravity_power

Specifies the value of n (real number) used to determine the radial variation of gravitational acceleration g in reference type 1, where \(g\propto\left(\frac{r}{r_\mathrm{max}}\right)^n\).

ra_constants

Indicates the desired value of specified constant coefficients when reading the value from main_input instead of from a custom-refernce file. For use with override_constants or override_constant flags. Syntax is:

&Reference_Namelist
 ...
 ra_constants( 2) = 1.0
 ra_constants(10) = 14.0
 ...
/
with_custom_constants

Comma separated list of integers indicating which constant coefficients should be read from a custom-refernce file when with_custom_reference is true.

with_custom_functions

Comma separated list of integers indicating which non-constant coefficients should be read from a custom-refernce file when with_custom_reference is true.

with_custom_reference

Logical flag that indicates some constant and non-constant coefficients should be read from a custom-reference file and used to overwrite those values otherwise assigned for reference_Types 1–3. Default value is .false.

custom_reference_file

Name of file from which to read custom-reference-state information when using reference_type 4 or when augmenting reference types 1–3.

override_constants

When true, ALL constant coefficients specified in the custom-reference file will be ignored, and those specified in main_input will be used instead. Constant coefficients not specified in main_input will be assigned a value of zero. Default value is .false.

override_constant

Indicates that particular constant coefficients, rather than all, should be overridden using main_input values when using reference_type 4. Multiple constant overrides can be specified, one per line, with the syntax:

&Reference_Namelist
 ...
 override_constant( 2) = T
 override_constant(10) = T
 ...
/

Transport#

This namelist enables control of Rayleigh’s diffusivities.

{nu,kappa,eta}_type
Determines the radial profile of the associated diffusion coefficient.
  • type 1 : no radial variation

  • type 2 : diffusivity profile varies as \(\rho^{n}\) for some real number n.

  • type 3 : diffusivity profile is read from a custom-reference-state file

{nu,kappa,eta}_top
Specifies the value of the associated diffusion coefficient at the upper boundary. This is primarily used for dimensional models or those employing a custom nondimensionalization via Rayleigh’s custom-reference interface. For Rayleigh’s intrinsic nondimensional reference states, the following values are assumed:
  • reference_type 1: \(\nu_\mathrm{top}=1\), \(\kappa_\mathrm{top}=1/\mathrm{Pr}\), \(\eta_\mathrm{top}=1/\mathrm{Pm}\)

  • reference_type 3: \(\nu_\mathrm{top}=\mathrm{Ek}\), \(\kappa_\mathrm{top}=\mathrm{Ek}/\mathrm{Pr}\), \(\eta_\mathrm{top}=\mathrm{Ek}/\mathrm{Pm}\)

{nu,kappa,eta}_power

Denotes the value of the exponent n in the \(\rho^{n}\) variation associated with diffusion type 2.

hyperdiffusion
Set this to variable to .true. to enable hyperdiffusion. The default value is .false. When active, diffusivities are multiplied by an additional factor such that:
  • \(\{\nu,\kappa,\eta\}\rightarrow\{\nu,\kappa,\eta\}\left(1+\alpha\left(\frac{\ell-1}{\ell_\mathrm{max}-1}\right)^\beta\right)\)

hyperdiffusion_alpha

Determines the value of \(\alpha\) when hyper diffusion is active.

hyperdiffusion_beta

Determines the value of \(\beta\) when hyper diffusion is active.