Eilmer Reference Manual, v5

string, default: 'transient'
The options are: 'transient' or 'steady'

int, default: 2
Spatial dimensionality, 2 or 3

bool, default: false
Sets axisymmetric mode for 2D geometries. The axis of rotation aligns with the x-axis (at y=0).

string, default: 'predictor-corrector'
The options are: 'euler', 'pc', 'predictor-corrector', 'midpoint', 'classic-rk3', 'tvd-rk3', 'denman-rk3', 'moving-grid-1-stage', 'moving-grid-2-stage', 'backward_euler', 'implicit_rk1'. Most of the update schemes are explicit, except for the last two listed here. Note that 'pc' is equivalent to 'predictor-corrector'. If you want time-accurate solutions, use a two- or three-stage explicit stepping scheme, otherwise, (explicit) Euler stepping has less computational expense but you may get less accuracy and the code will not be as robust for the same CFL value. For example the shock front in the Sod shock tube example is quite noisy for Euler stepping at CFL=0.85 but is quite neat with any of the two- or three-stage stepping schemes at the same value of CFL. The explicit midpoint and predictor-corrector schemes produce a tidy shock up to CFL = 1.0 and the rk3 schemes still look tidy up to CFL = 1.2. If you care mainly about the end result, you might be able to use an implicit scheme with larger CFL number. We have run the 'backward_euler' scheme up to a CFL value of 50 for some of the turbulent flat-plate examples. The implicit schemes are more expensive than the low-order explicit schemes, per time-step and, at large CFL numbers, will not be time accurate. The trade-off will be something that you have to explore but, if you care only about a steady state, the 'backward_euler' scheme may get you there more quickly than any of the explicit schemes. Your mileage will vary. Note that you may use dashes or underscores when spelling the scheme names.

boolean, default: false
Normally, we allow the time step size to be determined from cell conditions and CFL number. Setting config.fixed_time_step=true forces the time step size to be unchanged from config.dt_init.

float, default: 0.5
The CFL number is ratio of the time-step divided by the time for the fastest signal to cross a cell. The time-step adjustment process tries to set the time-step for the overall simulation to a value such that the maximum CFL number for any cell is at this cfl_value. If you are having trouble with a simulation that has lots of sudden flow field changes, decreasing the size of cfl_value may help.

table of float pairs, default {{0.0, config.cfl_value},}
If you want to vary the cfl_value as the simulation proceeds, possibly starting with small values and then increasing them as the flow field settles to something not too difficult for the flow solver, you can specify a table of {time,cfl_value} pairs that are interpolated by the solver. Outside the specified range of times, the cfl_value will be the closest end-point value.

float, default: 1.0e-3
Although the computation of the time step size is usually automatic, there might be cases where this process does not select a small enough value to get the simulation started stably. For the initial step, the user may override the computed value of time step by assigning a suitably small value to config.dt_init. This will then be the initial time step (in seconds) that will be used for the first few steps of the simulation process. Be careful to set a value small enough for the time-stepping to be stable. Since the time stepping is synchronous across all parts of the flow domain, this time step size should be smaller than half of the smallest time for a signal (pressure wave) to cross any cell in the flow domain. If you are sure that your geometric and boundary descriptions are correct but your simulation fails for no clear reason, try setting the initial time step to a very small value. For some simulations of viscous hypersonic flow on fine grids, it is not unusual to require time steps to be as small as a nanosecond.

float, default: 1.0e-3
Maximum allowable time step (in seconds). Sometimes, especially when strong source terms are at play, the CFL-based time-step determination does not suitably limit the size of the allowable time step. This parameter allows the user to limit the maximum time step directly.

float, default: 1.0
By default, the full viscous effect for the signal calculation will be used within the time-step calculation. It has been suggested that the full viscous effect may not be needed to ensure stable calculations for highly-resolved viscous calculations. A value of 0.0 will completely suppress the viscous contribution to the signal speed calculation but you may end up with unstable stepping. It’s a matter of try a value and see if you get a larger time-step while retaining a stable simulation.

boolean, default: false
The default action for structured grids is to use different cell widths in each index direction. Setting config.stringent_cfl=true will use the smallest cross-cell distance in the time-step size check.

int, default: 10
The number of time steps between checks of the size of the time step. This check is expensive so we don’t want to do it too frequently but, then, we have to be careful that the flow does not develop suddenly and the time step become unstable.

float, default: 1.0e-3
The simulation will be terminated on reaching this value of time.

int, default: 100
The simulation will be terminated on reaching this number of time steps. You will almost certainly want to use a larger value, however, a small value is a good way to test the starting process of a simulation, to see that all seems to be in order.

float, default: 1.0e-3
The whole flow solution will be written to disk when this amount of simulation time has elapsed, and then again, each occasion the same increment of simulation time has elapsed.

float, default: 1.0e-3
The history-point data will be written to disk repeatedly, each time this increment of simulation time has elapsed. To obtain history data, you will also need to specify one or more history points.

boolean, default: false
If a steady-state solution is sought, then it is possible to accelerate the explicit time-stepping scheme by allowing each cell in the domain to integrate in time with their own time-step that satisfies only the local CFL condition. This is sometimes referred to as Local Time-Stepping (LTS). Setting config.with_local_time_stepping=true enables this mode of time-stepping. Note that this mode of time-stepping is only suitable for steady-state simulations.

int, default: 10000
To improve the stability of simulations that enable config.with_local_time_stepping, users can limit the largest allowable local time-step as a function of the smallest global time-step. The allowable time-step for each cell is set to be the minimum of the cell’s local time-step and the global minimum time-step multiplied by config.local_time_stepping_limit_factor. The config.local_time_stepping_limit_factor is typically set to a value between 500 and 10000.

boolean, default: false
Residual smoothing essentially applies an averaging filter on the residuals during the time-integration procedure. Residual smoothing has two advantages: (1) The averaging increases the allowable CFL for a particular explicit time-stepping scheme; and (2) The averaging ensures that the local time-step for two adjacent cells doesn’t differ by a large magnitude when using config.with_local_time_stepping, this has a stabilising effect.

string, default: 'explicit'
The options are: 'explicit', 'implicit'. When config.residual_smoothing=true, the residuals can either be smoothed via an explicit averaging method or an implicit averaging method. Explicit averaging has less computational expense, however, implicit averaging typically results in a larger stable time step.

float, default: 0.2
A weighting factor used in the residual averaging when config.residual_smoothing=true.

int, default: 2
The number of Jacobi iterations used for the implicit residual averaging when config.residual_smoothing=true and config.residual_smoothing_type='implicit'.

boolean, default: false
Normal time iteration proceeds on all blocks simultaneously, however, such a time-marching calulation may be very expensive computationally. Setting config.block_marching=true enables a sequencing of the time integration such that at any one instant, only two slices of blocks are being integrated. The i-direction is the marching direction and the assumed dominant (supersonic) flow direction. The blocks are assumed to be in a regular array with a fixed number of blocks in the j- and k-directions to the entire flow domain.

int default: 1, 1, 1
are the number of blocks in each index direction. To make the best of block marching, you should have config.nib set to a fairly large number. Since the array of blocks is assumed regular, you cannot have very complicated geometries. Simple ducts, nozzles and plates are the intended applications. As seen in the examples, it may be convenient to define the full domain with one or more calls to the constructor FBArray:new. There is a restriction that the overall flow domain be assembled as a single structured array of FlowBlock objects.

boolean, default: false
By default, the integration begins in each set of blocks from the initial gas state set up in the preparation phase of the simulation. Some advantage may be gained following integration of the first block slices by initializing subsequent block slices with the downstream (east boundary) flow states. Setting config.propagate_inflow_data=true propagates these data across each new block slice, before the integration process for the slice begins.

boolean, default: false
Usually, a single set of solution files (after marching over all block slices) is all that is required. Sometimes, when debugging a troublesome calculation, it may be useful to have a solution written after the time-integration process for each pair of block slices. Set this parameter true to get these intermediate solutions written.

int, default: 2
Before applying the flux calculator, high-order reconstruction is applied. Setting config.interpolation_order=1 results in no reconstruction of intra-cell flow properties.

float, default: 0.0
The time (in seconds) to wait before increasing the interpolation order. If the delay is enabled, the simulation will begin using interpolation_order=1. After the delay time, the interpolation order will switch to that specified in the configuration. This delay is useful to help with robustness during transient starts because the first order spatial reconstruction is very reliable (albeit less accurate as compared to high order reconstruction).

boolean, default: true
By default, we apply a limiter to the flow-field reconstruction.

boolean, default: true
By default, we do extrema clipping at end of each scalar-field reconstruction. Setting config.extrema_clipping=false suppresses clipping.

string, default: 'rhou'
String to choose the set of interpolation variables to use in the interpolation, options are 'rhou', 'rhop', 'rhoT' and 'pT'.

string, default: 'adaptive_hanel_ausmdv'
Selects the flavour of the flux calculator. Options are:

float, default: -0.30
The value of relative velocity change (normalised by local sound-speed) across a cell-interface that triggers the shock-point detector. A negative value indicates a compression. When an adaptive flux calculator is used and the shock detector is triggered, the more-dissipative flux calculation will be used in place of the default low-dissipation calculation. A value of -0.05 seems OK for the Sod shock tube and sharp-cone inviscid flow simulations, however, a higher value is needed for cases with viscous boundary layers, where it is important to not have too much numerical dissipation in the boundary layer region.

float, default: 0.20
The value of the relative tangential-velocity change (normalised by local sound speed) across a cell-interface that suppresses the use of the high-dissipation flux calculator even if the shock detector indicates that high-dissipation scheme should be used within the adaptive flux calculator. The default value is experimentally set at 0.20 to get smooth shocks in the stagnation region of bluff bodies. A smaller value (say, 0.05) may be needed to get strongly expanding flows to behave when regions of shear are also present.

float, default: 0.01
representative Mach number for the free stream. Used by the ausm_plus_up flux calculator.

int, default = 0
How many iterations of shock detector averaging. Higher values spread the influence of the shock detector further from the shock, increasing numerical dissipation but providing a smoother transition between flux calculators in adaptive schemes.

boolean, default: true
If this is true then any face that is part of a cell with S>0 will have its own S value set to 1. This is to emulate legacy behaviour and thus defaults to true. For true blending of fluxes this should be set to false.

boolean, default: false
If set to true, the shock detector field will be frozen after the number of time steps prescribed by config.shock_detector_freeze_step. Used to prevent flickering of adaptive flux methods between their constituent flux calculators.

int, default: 1000
The time step at which the shock detector field will be frozen.

boolean, default: false
If set true, viscous effects will be included in the simulation.

boolean, default: false
If set true, the update for the viscous transport terms is done separately to the update for the convective terms. By default the updates are done together in the gas-dynamic update procedure.

float, default: 0.0
The time (in seconds) to wait before applying the viscous terms. This might come in handy when trying to start blunt-body simulations.

float, default: 0.01
The per-time-step increment of the viscous effects, once simulation time exceeds config.viscous_delay.

string, default: 'none'
String specifying which model to use. Options are: 'none' 'k_omega' 'spalart_allmaras'

float, default: 0.89

float, default: 0.75

float, default: 300
The turbulent viscosity is limited to laminar viscosity multiplied by this factor.

float, default: 1.0

boolean, default: false
Set to true to activate the finite-rate chemical reactions.

string, default: 'chemistry.lua'
File name for reaction scheme configuration.

float, default: 0.0
Time after which finite-rate reactions are allowed to start.

table of float pairs, default {{0.0, 1.0},}
If you want to vary the fraction of the reaction time step per gas-dynamic time step as the simulation proceeds, you can specify a table of {time, fraction} pairs that are interpolated by the solver. If the initial flow is likely to have a harsh shock reflection with high temperatures and correspondingly high reaction rates, it may be beneficial to discard time accuracy and start with a small fraction, increasing it (to a maximum of 1.0) as the flow field settles. Outside the specified range of times, the fraction will be the closest end-point value.

float, default: 300.0
Temperature (in degrees K) below which reactions are frozen. The default value is 300.0 since most reaction schemes seem to be valid for temperatures above this, however, you may have good reasons to set it higher or lower.

string, default: 'split'
Set how the chemistry update is included in the time-marching flow solver algorithm. Valid options are: 'split' to use an operator-splitting approach in which the chemistry update may be subcycled at a time step appropriate to the chemistry, conditions and integrator; or 'integral' to include the chemistry as part of the general source term vector for the species continuity equations: the result is that flow and chemistry are updated in a single time step (usually dictated by a flow-appropriate time step).

string, default: 'none'
Set the expression for laminar diffusion flux of species along concentration gradients. Valid options are: 'none' (no diffusion) and 'ficks_first_law' (self explanatory). Note that this option is ignored in turbulent flow, where the turbulent diffusivity is used instead.

string, default: 'none'
Set the type of formula used to compute the species diffusion coefficients in a diffusion enabled simulation. Valid options are: 'constant_lewis_number' (works with any multi-species model), 'species_specific_lewis_numbers' (requires specific gas models), and 'binary_diffusion' (requires specific gas models). Note that leaving this parameter as 'none' in a simulation where config.mass_diffusion_model='ficks_first_law' will cause a run-time error.

float, default: 1.0
Set the value for the Lewis number, which computes the species diffusion coefficients based on the thermal conductivity, in a diffusion enabled simulation with config.diffusion_coefficient_type=constant_lewis_number.

bool, default: false
Set to diffuse(/blend) conditions at the wall into the flow domain as an initial condition

int, default: 30
Set how many passes the diffusion is applied. Each pass diffuses another layer of cells into domain. So 10 passes would effect 10 layers of cells from the wall (in a structured grid).

float, default: -1.0
Set the wall temperature to use when diffusing the wall conditions. This value must be set when an adiabatic wall condition is selected since there is no initial guess of the wall temperature. If this value is set for a fixed temperature wall, then this value overrides the wall temperature for the purposes of this diffusion-style initialisation. It does not change the wall temperature selected in the boundary condition. A value of -1.0 indicates that this selection is not active and the wall boundary temperature should be used. This is default action.

string, default: "Eilmer4 simulation"
Title for the simulation

boolean, default: false
Usually, you will want the flow solver to provide its best estimate for your flow, however, there are flow situations for which the flow solver will not compute physically valid flow data. If you encounter a difficult flow situation and are prepared to fudge over a few cells, then set this parameter to true and max_invalid_cells to a non-zero value. Be cautious when using this option and use it only when you have exhausted more reasoned options. If there is a problem that is more than just a difficult patch of flow that will blow by, it may allow you to go further into a bad situation and get even more confused about what the underlying issue really is.

int, default: 0
The maximum number of bad cells that will be tolerated on decoding conserved quantities. If this number is exceeded, the simulation will stop.

boolean, default: true
If you are stuck with having to fudge over cells, you probably will want to know about them until, of course, that you don’t. Set this parameter to false to silence the reports of bad cells being fudged over.

boolean, default, true
This will be the fastest calculation, however, some boundary conditions, such as the shock-fitting need to cooperate across blocks and so will have race conditions if applied in parallel. If your simulation has such a boundary condition, set this parameter to false to favour safety above speed.

boolean, default: false
Set to true to apply user-defined source terms, as supplied in a Lua file.

string, default: "dummy-source-terms.txt"
Name of the Lua file for the user-defined source terms.

int, default: 20
Number of time steps between printing status information to the console.

int, default: 10
Number of time steps between re-parsing the job`.control` file. If the job`.control` has been edited, then the new values are used after re-parsing.

boolean, default: false
Set to true to make MHD physics active.

boolean, default: false
Set to true to calculate the temporal Discrete Fourier Transform of the pressure on a cell-by-cell basis on-the-go. Useful for large jobs where storing the number of snapshots required for Fourier decomposition is prohibitive. Results written to file DFT/jobName.DFT.bxxxx.tar.gz, with a line containing the real and imaginary components of each Fourier mode i.e. Re(A0), Im(A0), Re(A1), Im(A1), …​ Im(A_n). Requires setting of additional config options config.DFT_n_modes and config.DFT_step_interval. Use of config.fixed_time_step is also very strongly recommended, non-fixed time stepping will lead to erronous mode amplitudes and phases.

int, default: 5
The number of Fourier modes to be computed in the temporal Discrete Fourier Transform. Should be equal to config.max_steps / config.DFT_step_interval (see next entry).

int, default: 10
The number of steps between each increment of the temporal Discrete Fourier Transform modes. Should be equal to config.max_steps / config.DFT_n_modes.

name of Gridpro multi-block grid file

value by which to scale the grid coordinates (default: 1.0)

name of Plot3D file (needs to be in text format)

dimensionality of grid: 2 or 3

value by which to scale the grid coordinates (default: 1.0)

name of SU2 grid file

supply 'su2text' as format to import an SU2 grid

value by which to scale the grid coordinates (default: 1.0)

a Grid object. This might be created as StructuredGrid or UnstructuredGrid objects, or grid objects created during an import call.

a user-supplied tag that might be used to identify a grid or collection of grids

a string that will be used to select the initial flow condition from a dictionary when the FluidBlock is later constructucted

a table of strings that will be used to attach boundary conditions from a dictionary when the FluidBlock is later constructed

a Grid object. This might be created as StructuredGrid or UnstructuredGrid objects, or grid objects created during an import call.

a user-supplied tag that might be used to identify a grid or collection of grids

a string that will be used to select the initial flow condition from a dictionary when the FluidBlock is later constructucted

a table of strings that will be used to attach boundary conditions from a dictionary when the FluidBlock is later constructed

number of blocks to use for subdivision in i grid direction

number of blocks to use for subdivision in j grid direction

number of blocks to use for subdivision in k grid direction (has no meaning for 2D grids)

boolean, set to true if using a shock-fit WEST boundary

A table that maps boundary condition tags (as keys) to boundary condition objects (as values).

A table that maps flowstate tags (as keys) to objects that can act to fill a volume. Example objects are: FlowState object, a function of (x,y,z) that returns a FlowState and a FlowSolution object.

StructuredGrid or UnstructuredGrid object, no default
A grid object must be supplied. The type of grid (structured or unstructured) sets the type of block. The grid dimensions should also be compatible with the global setting for dimenions. (See: config.dimensions)

FlowState, FlowSolution or a user-defined function
The fluid simulation domain requires an initial set of flow properties throughout the domain. These flow properties are set block-by-block using this initialState parameter. There is no default: the user must supply something for this parameter.

Most commonly, a FlowState object is given as the initial state for a block. This sets spatially-uniform flow properties across the entire block.

A FlowSolution object might also be used to set the initial flow state in a block. Usually the FlowSolution comes from a previously completed simulation. One use for this is to start a finer resolution calculation using a coarser simulation. Another use could be to do a staged simulation: when extending the domain in a staged simulation, one might want to start with some blocks initialised from an earlier truncated domain simulation. The cells in the block are initialised by searching the FlowSolution for the nearest corresponding cell in the old solution and copying that value. No attempt at interpolating based on nearby cells or mismatch in cell centres is made.

A user-defined function can be provided as a Lua function. This allows one to provide a spatially-varying initial state. The function contract is: accepts x, y and z as parameters; returns a FlowState object. An example of initialising a shock tube with high and low pressure sections is shown in the 3D Sod shock tube case. See: dgd/examples/eilmer/3D/sod-shock-tube/sg/sod.lua. That initialisation function is repeated here:

function tube_gas(x, y, z)
   if x < 0.5 then
      p = 1.0e5; T = 348.4
   else
      p = 1.0e4; T = 278.8
   end
return FlowState:new{p=p, velx=0.0, vely=0.0, T=T}
end

table: {north=BCObject, east=BCObject, south=BCObject, west=BCObject, [top=BCObject, bottom=BCObject]}
The bcList is used to set boundary conditions on the faces of blocks with an underlying structured grid. Each table key accepts a boundary condition object. If any table entry is missing, the default-supplied boundary condition is a slip wall, WallBC_WithSlip. In 3D, the top and bottom faces can also be set. If a boundary is a connection, this can be explicitly set or you can rely on the identifyGridConnections() helper function to make that connection for you, at the grid preparation stage. That helper function is called after the blocks have been configured. An example to set a supersonic inflow on a west boundary, and an outflow on the north boundary is:

bcList={west=InFlowBC_SupersonicIn:new{flowState=inflow},
        north=OutFlowBC_Simple:new{}}

table: {tagA=BCObject, tagB=BCObject, …​}
The bcDict is used to set boundary conditions on faces of blocks with an underlying unstructured grid. The tag strings in the table should match the tags used in the underlying unstructured grid. If a boundary face is not set explicitly in this table, then a default boundary condition of a slip wall is applied (WallBC_WithSlip).

bool, default: true
By default, blocks are marked as active for inclusion in the simulation. You could disable a block’s participation in the simulation domain, setting this parameter to false. Be careful of how this block is connected to others if setting it to inactive; the flow state will not be updated in an inactive block.

string, default: FluidBlock-<id>
Set this parameter to give the block a label. This is a convenience for the user and might be useful for some custom post-processing to work with blocks that have a specific label.

float, default: 0.0
angular speed (in rad/s about the z-axis) for the rotating frame of reference.
Useful for the calculation of flow in turbomachines. The default value of 0.0 implies no rotating frame.

bool, default: true
Normally, when a turbulence model is active, turbulent flow will be allowed in all blocks. This parameter may be set false to suppress the turbulence actions for the block. Use sparingly.

StructuredGrid object, no default
A structured grid object must be supplied. The grid dimensions should also be compatible with the global setting for dimenions. (See: config.dimensions)

float, no default
The solid simulation domain requires an initial temperature throughout the domain. The temperature is set block-by-block using this initTemperature parameter. There is no default: the user must supply something for this parameter.

table: {north=BCObject, east=BCObject, south=BCObject, west=BCObject, [top=BCObject, bottom=BCObject]}
The bcList is used to set boundary conditions on the faces of blocks with an underlying structured grid. Each table key accepts a boundary condition object. If any table entry is missing, the default-supplied boundary condition is an adiabatic wall, SolidAdiabaticBC. In 3D, the top and bottom faces can also be set. If a boundary is a connection, this can be explicitly set or you can rely on the identifyGridConnections() helper function to make that connection for you, at the grid preparation stage. That helper function is called after the blocks have been configured. An example to set a fixed temperature on a west boundary, and a constant flux on the north boundary is:

bcList={west=SolidFixedTBC:new{Twall=300.0},
        north=SolidConstantFluxBC:new{}}

bool, default: true
By default, blocks are marked as active for inclusion in the simulation. You could disable a block’s participation in the simulation domain, setting this parameter to false. Be careful of how this block is connected to others if setting it to inactive; the flow state will not be updated in an inactive block.

string, default: SolidBlock-<id>
Set this parameter to give the block a label. This is a convenience for the user and might be useful for some custom post-processing to work with blocks that have a specific label.

float, no default
The modelTag is used to call the material properties set with the registerSolidModels function.

Defines a straight line from point p0 (t=0) to point p1 (t=1).

Defines a Bézier curve from the sequence of points.

Defines a NURBS from control points with weights, knot vector and degree.

Defines a circular arc from point p0 to point p0 about centre.

Defines a circular through three points starting at p0 through pmid ending at p1.

Builds a single path from a sequence of Path objects defined in segments.

Builds a spline of Bezier segments through the sequence of points.

Builds a spline from data file specifed in filename key with points listed line by line.

Builds a path based on a user-supplied function (as a function of t) specified in luaFnName key.

Derives path from underlying_path that has a uniformly-distributed set of points with parameter t.

float in radians

vector given as Vector3 object

point given as Vector3 object [default: Vector3(0.0, 0.0, 0.0) ]

unit quaternion values as array {q0, q1, q2, q3} where the unit quaternion is \(q = q_0 + q_1 \hat{i} + q_2 \hat{j} + q_3 \hat{k}\)

point given as Vector3 object [default: Vector3(0.0, 0.0, 0.0) ]

second StructuredGrid to be joined

a string specifying at which end of the current grid the other grid should be joined
allowable options are "east", "imax", "north" and "jmax". Note that the first two are equivalent, and the last two are equivalent.