Appendix: Initial Conditions

The run control file variables that are used to specify initial conditions for a simulation are discussed in the following subsections.

For analytic fields and hydrostatic pressure, use initialConditionProgram.

Uniform Initial Conditions

The most basic method of assigning initial conditions is to assign uniform conditions throughout the entire domain using the initialCondition variable in the run control file. An example of this is shown below for an incompressible, turbulent flow. Such a problem requires the specification of the initial state for the density, pressure, velocity and turbulence quantities. Here we assume that a k-omega turbulence model is in use. We note that for any given flow problem, additional variables that are specified beyond what is necessary will be ignored.

incompressible, turbulent, uniform initial condition

initialCondition:<rho=1.0 kg/m/m/m, p=10.0 atm, v=0.0 m/s, k=0.001, omega=1000.0>

The table below summarizes all variables for the main code that can be specified, as well as their definitions and default units. Additional variables for the various Stream modules are described in their respective chapters of this document.

Variable Specification for `initialCondition`
Variable	Description	Default Units
`rho`	Density	\(\frac{kg}{m^{3}}\)
`p`	Pressure	\(Pa\)
`T`	Temperature	\(K\)
`mixture`	Species mass fractions	none
`v`	Velocity	\(\frac{m}{s}\)
`k`	Turbulent kinetic energy	\(\frac{m^{2}}{s^{2}}\)
`omega`	Specific turbulent dissipation rate	\(s^{-1}\)
`epsilon`	Turbulent Dissipation rate	\(\frac{m^{2}}{s^{3}}\)

For compressible flows of a pure substance, two thermodynamic properties must be specified to establish the thermodynamic state for an initial condition. The initialCondition variable specifies this state using pressure and temperature. Given these two quantities, the initial conditions for other derived thermodynamic quantities such as density and specific internal energy are determined from the equation of state that is being employed in the simulation. Shown below is a typical uniform initial condition specification for a turbulent, compressible flow of a pure substance.

compressible, turbulent, pure substance, uniform initial condition

initialCondition: <p=10.0 atm, T=1000.0 K, v=1.0 m/s, k=0.001, omega=1000.0>

An initial condition for compressible, turbulent flow of a mixture material is similar specified, however one must now also provide an initial condition for the composition, which in Stream is given by the mixture species mass fractions, as shown below.

compressible, turbulent, mixture material, uniform initial condition

initialCondition: <p=10.0 atm, T=1000.0 K, v=1.0 m/s, k=0.001, omega=1000.0,
                   mixture=[H2=0.1, O2=0.1, H2O=0.8]>

The names of the species provided in the mixture specification must match those given in the .mdl file which specifies the mixture material. Species in the mixture material that are not explicitly assigned in the initial condition are given a default value of zero.

Left and Right State Initial Conditions

An initial condition with uniform left and right states may be needed for some problems. The run control file variables ql and qr are used to specify these states. The specification for ql and qr is identical to that shown above for initialCondition. The left and right initial condition states are separated by a plane whose location is specified at a midpoint by using either the variable xmid, ymid or zmid. If a midpoint is not specified in the vars file, the default specification is xmid with a value of zero in which case the y-z plane through the origin is the surface separating the left and right uniform initial condition states. If ymid is specified, then the cutting plane is an x-z plane located at the ymid value, while if zmid is specified, the cutting plane is an x-y plane located at the zmid value.

With the location of the cutting plane specified, the left state, ql, is used for all cells with a cell-center coordinate less than the specified midpoint coordinate value. The right state, qr, is used for cells with a cell-center coordinate greater than the specified midpoint coordinate value. The following example shows a typical specification for a laminar compressible flow of a mixture material.

compressible, mixture material, hydrogen/oxygen initial condition split at x=0.5

ql: <p=10.0 atm,T=1000.0 K,v=0.0 m/s,mixture=[H2=1.0]>
qr: <p=1.0 atm,T=300.0 K,v=0.0 m/s,mixture=[O2=1.0]>
xmid: 0.5

Initial Condition Regions

It may be desirable to assign different initial condition values to different regions of the computational domain. For example, one may have a pipe with a 90-degree bend. In this case, if one wished to assign an initial condition for velocity that is parallel to the walls of the pipe, one would need to be able to independently specify two different conditions. Stream provides a general capability based on geometric primitives (shapes) that allows the user to specify an arbitrary number of initial condition states over various regions of the entire domain. This specification is accomplished with the run control file variable initialConditionRegions. To illustrate the use of this feature, consider the example specification below for a compressible flow of a mixture material:

compressible, mixture material, hydrogen/oxygen initial condition by region

initialConditionRegions:<
  default=state(u=0.0m/s, p=1atm, T=298K, mixture=[N2=1.0]),
  hydrogen=state(u=0.0m/s, p=1atm, T=400K, mixture=[H2=1.0]),
  oxygen=state(u=0.0m/s, p=1atm, T=200K, mixture=[O2=1.0]),
  regions=[inBox(p1=[0,0,0], p2=[1,1,1], composition=hydrogen),
  inSphere(radius=0.1m, center=[0.5,0.5,0.5], composition=oxygen)] >

In this example, the default state is first used to assign values to every cell in the computational domain. The regions that are subsequently defined are processed in order of appearance, each overwriting the state of the cells contained inside the region. Thus, for this example, the default state is replaced by the hydrogen state for cells inside the defined box and then the cells contained inside the defined sphere are assigned the oxygen state.

The table below contains a complete listing of the variables for the main code that can specified inside initialConditionRegions. As with the other initial condition specifications above, consistent units other than the default units may be specified, in which case numeric values are converted internally to the default units for use in the code. If units are not specified for a quantity, the default units for that quantity are assumed.

Variables for Initial Condition Regions Input
Variable	Description	Default Units
`rho`	Density	\(\frac{kg}{m^{3}}\)
`p`	Pressure	\(Pa\)
`T`	Temperature	\(K\)
`mixture`	Species mass fractions	none
`u`	Velocity	\(\frac{m}{s}\)
`M`	Mach Number	none
`k`	Turbulent kinetic energy	\(\frac{m^{2}}{s^{2}}\)
`omega`	Specific turbulent dissipation rate	\(s^{-1}\)
`epsilon`	Turbulent Dissipation rate	\(\frac{m^{2}}{s^{3}}\)

The geometric primitives that are currently supported for initialConditionRegions are shown in the table below.

Geometric Primitives for Initial Condition Regions Input
Primitive	Description
`inBox`	Takes two arguments p1 and p2, which define two diagonally opposing corners of the box.
`inSphere`	Takes two arguments, radius, and center, which define respectively the size and location of the sphere.
`inCylinder`	Takes three arguments, radius which defines the cylinder radius, and the points p1 and p2, which define the endpoints of the axis of the cylinder.
`inCone`	Takes four arguments, p1 and p2 which define the endpoints of the axis of the cone, and r1 and r2 which define the radius of the cone at the locations p1 and p2, respectively.
`leftPlane`	Takes two arguments, point, which defines a point on the plane, and normal, which defines a vector normal to the plane. The region included in this primitive is the semi-infinite region on the side of the plane away from the direction of the specified normal.

Interpolated Initial Conditions

Often after running a simulation for a particular geometry, one decides that a refined mesh is required. In this case, one can use the solution obtained from the old simulation as an initial guess for the new simulation by using the interpolateInitialConditions variable in the run control file as follows:

puT interpolated initial condition

interpolateInitialConditions: put.1000_cavity

When running a simulation, if the user has included the variable put in the plot_output line of the run control file, Stream writes out what is known as the puT file in the output directory along with other output files according to the value of the run control file variable plot_freq. In the above example, the value 1000 indicates the time-step number at which data was written in the previous simulation, and the name cavity is the case name of the previous simulation. The puT file (the name is an acronym for pressure(p), velocity(u), and temperature(T)) contains all the basic flow variable information associated with the run, including velocity, pressure, temperature, species, and turbulence data if the simulation is employing a turbulence model.

If one is running a new case in which the type of simulation remains constant but the grid has changed, then one simply needs to select any puT file from a previous run and use it in the above manner. Note that the name of the puT file specified in the new run must include the complete path to the file. However, if the simulation type changes between runs, there are a few special cases of interest which require additional input, the details of which follow:

By default, interpolateInitialConditions only initializes the field variables. The new run starts with timestep number zero, solution time zero, and the normal no-restart timestep history. To continue the timestep number, solution time, and previous timestep size stored in a puT file, enable:

puT time-continuation option

interpolateInitialConditions: output/put.1000_cavity
putContinuation: on

New puT files written by Stream include this continuation metadata. User-specified startTimeStep and startTime values override the corresponding puT metadata. This option does not import a previous solution field: BDF2 therefore uses its normal first-order startup treatment for the first physical timestep and uses BDF2 after that startup step.

The common modes are:

Goal	Input	Timeline behavior
Interpolate fields onto a new grid	`interpolateInitialConditions: output/put.1000_cavity`	Starts from the normal no-restart timestep number, solution time, and timestep history.
Continue from the `puT` file timeline	`interpolateInitialConditions: output/put.1000_cavity` and `putContinuation: on`	Starts from the timestep number and solution time stored in the `puT` file and restores the stored previous timestep size.
Continue from `puT` fields with an explicit timeline	`putContinuation: on` with `startTimeStep` and/or `startTime`	Uses the supplied `startTimeStep` and `startTime` values instead of the corresponding `puT` metadata.

The following changes in simulation type require values that cannot be recovered from the puT file. Supply these values with interpolateInitialConditionsOverride. Do not specify initialCondition together with interpolateInitialConditions.

When initializing an incompressible simulation from a compressible or incompressible puT file, provide the density as follows:
```
interpolateInitialConditions: output/put.1000_cavity
interpolateInitialConditionsOverride: <rho=1000.0 kg/m/m/m>
```
Density is not stored in a puT file, and incompressible flow has no equation of state from which to recover it. Density is therefore taken from the override, while velocity and pressure are taken from the puT file.
When initializing a compressible simulation from an incompressible puT file, provide a physical temperature as follows:
```
interpolateInitialConditions: output/put.1000_cavity
interpolateInitialConditionsOverride: <T=300.0 K>
```
The temperature stored by an incompressible simulation is only a nonphysical placeholder and is not suitable for initializing compressible flow.

Initial Condition Programs

Load initial_conditions and use initialConditionProgram for analytic fields and regional updates. This example varies temperature with \(x\) and adds crossflow within a box:

Analytic temperature with a regional velocity update

loadModule: initial_conditions
{
  // ... standard flow and boundary settings
  initialConditionProgram: <
    version=1,
    parameters=[T0=300 K,dTdx=10 K/m],
    base=state(p=1 atm,T=expression("T0+dTdx*x"),v=[20 m/s,0 m/s,0 m/s]),
    overlays=[
      add(name=crossflow,
          where=box(min=[0 m,-0.1 m,-0.1 m],max=[1 m,0.1 m,0.1 m]),
          fields=fields(v=[0 m/s,2 m/s,0 m/s]))
    ]
  >
}

Program Options
Option	Meaning
`version=1`	Required syntax version.
`parameters=[name=value,...]`	Optional numeric constants, with units where needed.
`states=[name=state(...),...]`	Optional named states for reuse.
`base=state(...)` or `base=name`	Required complete state evaluated at every cell center.
`overlays=[...]`	Optional spatial updates, applied in listed order.
`pressure=hydrostatic(...)`	Derive pressure from gravity and the local state; see Hydrostatic Pressure.

A program supplies the complete initial state. Do not combine it with initialCondition, initialConditionRegions, ql/qr, or an imported initial-condition source.

Expressions

Fields accept constants or expression("...") (alias expr). Expressions may use x,y,z, spherical radius r, azimuth theta, polar angle phi, pi, and named parameters. Put units in parameters or field values, outside quoted expressions. Dimensions must match the target field; bare field values use SI units.

Expressions support arithmetic, comparisons, &&, ||, !, and these functions:

Expression Functions
Type	Functions
Trigonometric	`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sinh`, `cosh`, `tanh`
Exponential and logarithmic	`exp`, `ln`/`log`, `log10`, `sqrt`, `pow`; use `pow(a,b)` for exponentiation.
Bounds and rounding	`abs`, `floor`, `ceil`, `min`, `max`, `clamp`
Conditional	`if`, `select`; only the selected branch is evaluated.

Regions and Updates

Each overlay requires a unique name and a where selector:

Region Selectors
Region	Specification
All cells	`all`
Expression	`expression("...")`; dimensionless, using coordinates and parameters.
Box	`box(min=...,max=...)`
Sphere	`sphere(center=...,radius=...)`
Cylinder	`cylinder(p1=...,p2=...,radius=...)`
Cone	`cone(p1=...,p2=...,r1=...,r2=...)`
Half-space	`halfSpace(point=...,normal=...,side=positive\|negative)`

Geometry uses constants or parameter expressions, with boundary=include|exclude (default include). Combine selectors with union or intersection (at least two selectors), difference (exactly two), or complement (one).

Overlay Operations
Operation	Effect
`set(...,state=name)` or `set(...,state=state(...))`	Replace the complete state, including its optional groups.
`set(...,fields=fields(...))`	Replace listed groups. Group thermodynamic fields as `thermo=fields(...)`.
`add(...,fields=fields(...))`	Add to velocity or turbulence quantities.
`blend(...,target=fields(...),weight=...)`	Blend velocity or turbulence as `(1-weight)current + weighttarget`; weight must be in `[0,1]`.

Velocity updates may read current.v.x, current.v.y, and current.v.z. Turbulence updates may read current.k, current.omega, and current.epsilon when defined. Each overlay reads the preceding state and completes before the next overlay. Thermodynamics, composition, and model fields require whole-group replacement and cannot be added or blended.

Required State Fields

Required State Fields
Model	State fields	Hydrostatic state fields
Standard compressible	`v` and exactly one pair: `p,T`, `rho,T`, or `rho,p`	`T,v`
Standard incompressible	`rho,p,v`	`rho,v`
`compressible_flamelet_tf`	`p,T,v` and `model=fields(Z=...,C=...)`	Not supported
Compressible `cmim_avof`	`p,T,v` and material fields in `model=fields(...)`	`T,v` and material fields

Temperature and density must be positive. Compressible pressure is absolute and positive; incompressible pressure may be a finite gauge value. Supply all three velocity components as a list or vector(x=...,y=...,z=...). Include k,omega or k,epsilon when required by the standard turbulence model; k may be zero, while omega and epsilon must be positive.

For species transport, use mixture=composition(species=value,...) with active EOS species names. Fractions must lie in [0,1] and sum to one; omitted species become zero. Omit mixture for incompressible flow without species transport.

compressible_flamelet_tf obtains composition from the flamelet model: omit mixture and supply Z,C in [0,1]. Inert and PEC/detailed-chemistry flamelet extensions are not supported.

Hydrostatic Pressure

A hydrostatic program derives pressure from Stream’s gravity and reference density at initialization. Omit p from all states and updates. This example specifies an isothermal compressible column:

Isothermal hydrostatic initial condition

loadModule: initial_conditions
{
  // ... standard flow and boundary settings
  gravity: <rhoref=0.0,g=[0.0,-9.81,0.0]>
  initialConditionProgram: <
    version=1,
    pressure=hydrostatic(
      reference=plane(point=[0 m,1 m,0 m],p=1 atm),maximumStep=0.01 m),
    base=state(T=300 K,v=[0 m/s,0 m/s,0 m/s])
  >
}

For incompressible flow, replace T with rho. Pressure is integrated along the gravity line through each cell:

\[\frac{dp}{dh} = -(\rho-\rho_{\mathrm{ref}})\lVert\mathbf{g}\rVert\]

Here \(h\) increases opposite gravity; \(\rho_{\mathrm{ref}}\) is rhoref in gravity. Gravity must be finite and nonzero.

Hydrostatic Options
Option	Meaning
`reference=plane(point=...,p=...)`	Reference pressure on the gravity-normal plane through the point.
`reference=highest(p=...)` or `lowest(p=...)`	Alternative reference at the highest or lowest cell-center height in the current mesh.
`maximumStep`	Positive integration-step cap in meters; no explicit cap by default.
`relativeTolerance`	Integration tolerance in `(0,1)`; default `1e-8`.

Specify a reference. Use a plane for pressure at a physical boundary; cell-center extrema change with the mesh. Integration splits at density-affecting halfSpace boundaries, including Boolean combinations. For other selectors or discontinuities in field expressions, set maximumStep no larger than the thinnest layer to resolve.

Preview, Restart, and Mesh Adaptation

For standard compressible or incompressible laminar flow, inspect the initialized fields without advancing time:

mpirun -np 2 /path/to/stream -q initialConditionPreview case

The query writes output/initial_conditions_preview.<model>.h5 and prints field ranges and each overlay’s cell counts before and after later updates. It warns about empty or fully overwritten overlays. For turbulent, inviscid, flamelet, and CMIM cases, inspect the normal solution output.

The program runs at initialization and again on each mesh created by startup AMR. File restart and runtime AMR continue from the saved or evolving solution without reapplying the program. Required restart fields must be present.