.. _user_nalu_input_file:
Nalu-Wind Input File
--------------------
Nalu-Wind requires the user to provide an input file, in YAML format, during
invocation at the command line using the :option:`naluX -i` flag. By default,
:program:`naluX` will look for :file:`nalu.i` in the current working directory
to determine the mesh file as well as the run setup for execution. A sample
:download:`nalu.i` is shown below:
.. literalinclude:: nalu.i
:language: yaml
:caption: Sample Nalu-Wind input file for the Heat Conduction problem
:emphasize-lines: 6, 11, 21, 91
Nalu-Wind input file contains the following top-level sections that describe the
simulation to be executed.
**Realms**
Realms describe the computational domain (via mesh input files) and the set of
physics equations (Low-Mach Navier-Stokes, Heat Conduction, etc.) that are
solved over this particular domain. The list can contain multiple
computational domains (*realms*) that use different meshes as well as solve
different sets of physics equations and interact via *solution transfer*. This
section also contains information regarding the initial and boundary
conditions, solution output and restart options, the linear solvers used to
solve the linear system of equations, and solution options that govern the
discretization of the equation set.
A special case of a realm instance is the input-output realm; this realm type
does not solve any physics equations, but instead serves one of the following
purposes:
- provide time-varying boundary conditions to one or more boundaries within
one or more of the participating realms in the simulations. In this
context, it acts as an *input* realm.
- extract a subset of data for output at a different frequency from the
other realms. In this context, it acts as an *output* realm.
Inclusion of an input/output realm will require the user to provide the
additional `transfers` section in the Nalu-Wind input file that defines
the solution fields that are transferred between the realms. See
:ref:`nalu_inp_realm` for detailed documentation on all Realm options.
**Linear Solvers**
This section configures the solvers and preconditioners used to solve the
resulting linear system of equations within Nalu-Wind. The linear system
convergence tolerance and other controls are set here and can be used with
multiple systems across different realms. See :ref:`nalu_inp_linear_solvers`
for more details.
**Time Integrators**
This section configures the time integration scheme used (first/second order
in time), the duration of simulation, fixed or adaptive timestepping based on
Courant number constraints, etc. Each time integration section in this list
can accept one or more `realms` that are integrated in time using
that specific time integration scheme. See :ref:`nalu_inp_time_integrators`
for complete documentation of all time integration options available in Nalu-Wind.
**Transfers**
An optional section that defines one or more solution transfer definitions
between the participating `realms` during the simulation. Each
transfer definition provides a mapping of the to and from realm, part, and the
solution field that must be transferred at every timestep during the
simulation. See :ref:`nalu_inp_transfers` section for complete documentation of
all transfer options available in Nalu-Wind.
**Simulations**
Simulations provides the top-level architecture that orchestrates the
time-stepping across all the realms and the required equation sets.
.. _nalu_inp_linear_solvers:
Linear Solvers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``linear_solvers`` section contains a list of one or more linear solver
settings that specify the solver, preconditioner, convergence tolerance for
solving a linear system. Every entry in the YAML list will contain the following
entries:
.. note::
The variable in the `linear_solvers` subsection are prefixed with
``linear_solvers.name`` but only the variable name after the period should
appear in the input file.
.. inpfile:: linear_solvers.name
The key used to refer to the linear solver configuration in
`equation_systems.solver_system_specification` section.
.. inpfile:: linear_solvers.type
The type of solver library used.
================== ==========================================================
Type Description
================== ==========================================================
``tpetra`` Tpetra data structures and Belos solvers/preconditioners
``hypre`` Hypre data structures and Hypre solver/preconditioners
================== ==========================================================
.. inpfile:: linear_solvers.method
The solver used for solving the linear system.
When `linear_solvers.type` is ``tpetra`` the valid options are:
``gmres``, ``biCgStab``, ``cg``. For ``hypre`` the valid
options are ``hypre_boomerAMG`` and ``hypre_gmres``.
**Options Common to both Solver Libraries**
.. inpfile:: linear_solvers.preconditioner
The type of preconditioner used.
When `linear_solvers.type` is ``tpetra`` the valid options are
``sgs``, ``mt_sgs``, ``muelu``. For ``hypre`` the valid
options are ``boomerAMG`` or ``none``.
.. inpfile:: linear_solvers.tolerance
The relative tolerance used to determine convergence of the linear system.
.. inpfile:: linear_solvers.max_iterations
Maximum number of linear solver iterations performed.
.. inpfile:: linear_solvers.kspace
The Krylov vector space.
.. inpfile:: linear_solvers.output_level
Verbosity of output from the linear solver during execution.
.. inpfile:: linear_solvers.write_matrix_files
A boolean flag indicating whether the matrix, the right hand side, and the
solution vector are written to files during execution. The matrix files are
written in MatrixMarket format. The default value is ``no``.
**Additional parameters for Belos Solver/Preconditioners**
.. inpfile:: linear_solvers.muelu_xml_file_name
Only used when the `linear_solvers.preconditioner` is set to
``muelu`` and specifies the path to the XML filename that contains various
configuration parameters for Trilinos MueLu package.
.. inpfile:: linear_solvers.recompute_preconditioner
A boolean flag indicating whether preconditioner is recomputed during runs.
The default value is ``yes``.
.. inpfile:: linear_solvers.reuse_preconditioner
Boolean flag. Default value is ``no``.
.. inpfile:: linear_solvers.summarize_muelu_timer
Boolean flag indicating whether MueLu timer summary is printed. Default value
is ``no``.
**Additional parameters for Hypre Solver/Preconditioners**
The user is referred to `Hypre Reference Manual
<https://computation.llnl.gov/projects/hypre-scalable-linear-solvers-multigrid-methods/software>`_
for full details on the usage of the parameters described briefly below.
The parameters that start with ``bamg_`` prefix refer to options related to
Hypre's BoomerAMG preconditioner.
.. inpfile:: linear_solvers.bamg_output_level
The level of verbosity of BoomerAMG preconditioner. See
``HYPRE_BoomerAMGSetPrintLevel``. Default: 0.
.. inpfile:: linear_solvers.bamg_coarsen_type
See ``HYPRE_BoomerAMGSetCoarsenType``. Default: 6
.. inpfile:: linear_solvers.bamg_cycle_type
See ``HYPRE_BoomerAMGSetCycleType``. Default: 1
.. inpfile:: linear_solvers.bamg_relax_type
See ``HYPRE_BoomerAMGSetRelaxType``. Default: 6
.. inpfile:: linear_solvers.bamg_relax_order
See ``HYPRE_BoomerAMGSetRelaxOrder``. Default: 1
.. inpfile:: linear_solvers.bamg_num_sweeps
See ``HYPRE_BoomerAMGSetNumSweeps``. Default: 2
.. inpfile:: linear_solvers.bamg_max_levels
See ``HYPRE_BoomerAMGSetMaxLevels``. Default: 20
.. inpfile:: linear_solvers.bamg_strong_threshold
See ``HYPRE_BoomerAMGSetStrongThreshold``. Default: 0.25
.. _nalu_inp_time_integrators:
Time Integration Options
~~~~~~~~~~~~~~~~~~~~~~~~
.. inpfile:: Time_Integrators
A list of time-integration options used to advance the `realms` in
time. Each list entry must contain a YAML mapping with the key indicating the
type of time integrator. Currently only one option,
``StandardTimeIntegrator`` is available.
.. code-block:: yaml
Time_Integrators:
- StandardTimeIntegrator:
name: ti_1
start_time: 0.0
termination_step_count: 10
time_step: 0.5
time_stepping_type: fixed
time_step_count: 0
second_order_accuracy: yes
realms:
- fluids_realm
.. inpfile:: time_int.name
The lookup key for this time integration entry. This name must match the one
provided in `Simulations` section.
.. inpfile:: time_int.termination_time
Nalu-Wind will stop the simulation once the ``termination_time`` has reached.
.. inpfile:: time_int.termination_step_count
Nalu-Wind will stop the simulation once the specified ``termination_step_count``
timesteps have been completed. If both `time_int.termination_time`
and this parameter are provided then this parameter will prevail.
.. inpfile:: time_int.time_step
The time step (:math:`\Delta t`) used for the simulation. If
`time_int.time_stepping_type` is ``fixed`` this value does not
change during the simulation.
.. inpfile:: time_int.start_time
The starting time step (default: ``0.0``) when starting a new simulation.
Note that this has no effect on restart which is controlled by
`restart.restart_time` in the :inpfile:`restart` section.
.. inpfile:: time_int.time_step_count
The starting timestep counter for a new simulation. See `restart`
for restarting from a previous simulation.
.. inpfile:: time_int.second_order_accuracy
A boolean flag indicating whether second-order time integration scheme is
activated. Default: ``no``.
.. inpfile:: time_int.time_stepping_type
One of ``fixed`` or ``adaptive`` indicating whether a fixed time-stepping
scheme or an adaptive timestepping scheme is used for simulations. See
`time_step_control` for more information on max Courant number based
adaptive time stepping.
.. inpfile:: time_int.realms
A list of `realms` names. The names entered here must match
`name` used in the `realms` section. Names listed here not
found in `realms` list will trigger an error, while realms not
included in this list but present in `realms` will not be
initialized and silently ignored. This can cause the code to abort if the
user attempts to access the specific realm in the `transfers`
section.
.. _nalu_inp_realm:
Physics Realm Options
~~~~~~~~~~~~~~~~~~~~~~~
As mentioned previously, `realms` is a YAML list data structure
containing at least one :ref:`nalu_inp_realm` entry that defines the
computational domain (provided as an Exodus-II mesh), the set of physics
equations that must be solved over this domain, along with the necessary initial
and boundary conditions. Each list entry is a YAML dictionary mapping that is
described in this section of the manual. The key subsections of a Realm entry
in the input file are
=============================== =========================================================================
Realm subsection Purpose
=============================== =========================================================================
`equation_systems` Set of physics equations to be solved
`initial_conditions` Initial conditions for the various fields
`boundary_conditions` Boundary condition for the different fields
`material_properties` Material properties (e.g., fluid density, viscosity etc.)
`solution_options` Discretization and numerical stability
`mesh_transformation` Mesh transformation
`mesh_motion` Mesh motion
`output` Solution output options (file, frequency, etc.)
`restart` Optional: Restart options (restart time, checkpoint frequency etc.)
`time_step_control` Optional: Parameters determining variable timestepping
=============================== =========================================================================
In addition to the sections mentioned in the table, there are several additional
sections that could be present depending on the specific simulation type and
post-processing options requested by the user. A brief description of these
optional sections are provided below:
==================================== ===========================================================================
Realm subsection Purpose
==================================== ===========================================================================
`turbulence_averaging` Generate statistics for the flow field
`post_processing` Extract integrated data from the simulation
`solution_norm` Compare the solution error to a reference solution
`data_probes` Extract data using probes
`actuator` Model turbine blades/tower using actuator lines
`abl_forcing` Momentum source term to drive ABL flows to a desired velocity profile
`boundary_layer_statistics` Compute boundary layer statistics
==================================== ===========================================================================
Common options
``````````````
.. inpfile:: name
The name of the realm. The name provided here is used in the
`Time_Integrators` section to determine the time-integration scheme
used for this computational domain.
.. inpfile:: mesh
The name of the Exodus-II mesh file that defines the computational domain for
this realm. Note that only the base name (i.e., without the ``.NPROCS.IPROC``
suffix) is provided even for simulations using previously decomposed
mesh/restart files.
.. inpfile:: automatic_decomposition_type
Used only for parallel runs, this indicates how the a single mesh database
must be decomposed amongst the MPI processes during initialization. This
option should not be used if the mesh has already been decomposed by an
external utility. Possible values are:
========== ==========================================================
Value Description
========== ==========================================================
rcb recursive coordinate bisection
rib recursive inertial bisection
linear elements in order first n/p to proc 0, next to proc 1.
cyclic elements handed out to id % proc_count
========== ==========================================================
.. inpfile:: activate_aura
A boolean flag indicating whether an extra element is *ghosted* across the
processor boundaries. The default value is ``no``.
.. inpfile:: use_edges
A boolean flag indicating whether edge based discretization scheme is used
instead of element based schemes. The default value is ``no``.
.. inpfile:: polynomial_order
An integer value indicating the polynomial order used for higher-order mesh
simulations. The default value is ``1``. When `polynomial_order` is
greater than 1, the Realm has the capability to promote the mesh to
higher-order during initialization.
.. inpfile:: solve_frequency
An integer value indicating how often this realm is solved during time
integration. The default value is ``1``.
.. inpfile:: support_inconsistent_multi_state_restart
A boolean flag indicating whether restarts are allowed from files where the
necessary field states are missing. A typical situation is when the
simulation is restarted using second-order time integration but the restart
file was created using first-order time integration scheme.
.. inpfile:: activate_memory_diagnostic
A boolean flag indicating whether memory diagnostics are activated during
simulation. Default value is ``no``.
.. inpfile:: rebalance_mesh
A boolean flag indicating whether to rebalance mesh using stk_balance. The
default value is ``no``. If this parameter is activated, it requires that
``stk_rebalance_method`` is also set to specify the decomposition method to be
used for rebalance, e.g., RIB, RCB, etc.
.. inpfile:: balance_nodes
A boolean flag indicating whether node balancing is performed during
simulations. See also `balance_node_iterations` and
`balance_nodes_target`.
.. inpfile:: balance_node_iterations
The frequency at which node rebalancing is performed. Default value is ``5``.
.. inpfile:: balance_node_target
The target balance ratio. Default value is ``1.0``.
Equation Systems
````````````````
.. inpfile:: equation_systems
``equation_systems`` subsection defines the physics equation sets that are
solved for this realm and the linear solvers used to solve the different
linear systems.
.. note::
The variable in the `equation_systems` subsection are prefixed with
``equation_systems.name`` but only the variable name after the period should
appear in the input file.
.. inpfile:: equation_systems.name
A string indicating the name used in log messages etc.
.. inpfile:: equation_systems.max_iterations
The maximum number of non-linear iterations performed during a timestep that
couples the different equation systems.
.. inpfile:: equation_systems.solver_system_specification
A mapping containing ``field_name: linear_solver_name`` that determines the
linear solver used for solving the linear system. Example:
.. code-block:: yaml
solver_system_specification:
pressure: solve_continuity
enthalpy: solve_scalar
velocity: solve_scalar
The above example indicates that the linear systems for the enthalpy and
momentum (velocity) equations are solved by the linear solver corresponding
to the tag ``solve_scalar`` in the `linear_systems` entry, whereas
the continuity equation system (pressure Poisson solve) should be solved
using the linear solver definition corresponding to the tag
``solve_continuity``.
.. inpfile:: equation_systems.systems
A list of equation systems to be solved within this realm. Each entry is a
YAML mapping with the key corresponding to a pre-defined equation system name
that contains additional parameters governing the solution of this equation
set. The predefined equation types are
===================== ===========================================================
Equation system Description
===================== ===========================================================
LowMachEOM Low-Mach Momentum and Continuity equations
Enthalpy Energy equations
ShearStressTransport :math:`k-\omega` SST equation set
TurbKineticEnergy TKE equation system
MassFraction Mass Fraction
MixtureFraction Mixture Fraction
MeshDisplacement Arbitrary Mesh Displacement
===================== ===========================================================
An example of the equation system definition for ABL precursor simulations is
shown below:
.. code-block:: yaml
# Equation systems example for ABL precursor simulations
systems:
- LowMachEOM:
name: myLowMach
max_iterations: 1
convergence_tolerance: 1.0e-5
- TurbKineticEnergy:
name: myTke
max_iterations: 1
convergence_tolerance: 1.0e-2
- Enthalpy:
name: myEnth
max_iterations: 1
convergence_tolerance: 1.0e-2
Initial conditions
``````````````````
.. inpfile:: initial_conditions
The ``initial_conditions`` sub-sections defines the conditions used to
initialize the computational fields if they are not provided via the mesh
file. Two types of field initializations are currently possible:
- ``constant`` - Initialize the field with a constant value throughout the domain;
- ``user_function`` - Initialize the field with a pre-defined user function.
The snippet below shows an example of both options available to initialize
the various computational fields used for ABL simulations. In this example,
the pressure and turbulent kinetic energy fields are initialized using a
constant value, whereas the velocity field is initialized by the user
function ``boundary_layer_perturbation`` that imposes sinusoidal fluctations
over a velocity field to trip the flow.
.. code-block:: yaml
initial_conditions:
- constant: ic_1
target_name: [fluid_part]
value:
pressure: 0.0
turbulent_ke: 0.1
- user_function: ic_2
target_name: [fluid_part]
user_function_name:
velocity: boundary_layer_perturbation
user_function_parameters:
velocity: [1.0,0.0075398,0.0075398,50.0,8.0]
.. inpfile:: initial_conditions.constant
This input parameter serves two purposes: 1. it indicates the *type*
(``constant``), and 2. provides the custom *name* for this condition. In
addition to the `initial_conditions.target_name` this section
requires another entry ``value`` that contains the mapping of ``(field_name,
value)`` as shown in the above example.
.. inpfile:: initial_conditions.user_function
Indicates that this block of YAML input must be parsed as input for a user
defined function.
.. inpfile:: initial_conditions.target_name
A list of element blocks (*parts*) where this initial condition must be
applied. Using the alias ``all_blocks`` is equivalent to listing all
element blocks in the mesh.
Boundary Conditions
```````````````````
.. inpfile:: boundary_conditions
This subsection of the physics Realm contains a list of boundary conditions
that must be used during the simulation. Each entry of this list is a YAML
mapping entry with the key of the form ``<type>_boundary_condition`` where
the available types are:
- ``inflow``
- ``open`` -- Outflow BC
- ``wall``
- ``symmetry``
- ``periodic``
- ``non_conformal`` -- e.g., BC across sliding mesh interfaces
- ``overset`` -- overset mesh assembly description
All BC types require `bc.target_name` that contains a list of side sets
where the specified BC is to be applied. Additional information necessary for
certain BC types are provided by a sub-dictionary with the key
``<type>_user_data:`` that contains the parameters necessary to initialize a
specific BC type.
.. inpfile:: bc.target_name
A list of side set part names where the given BC type must be applied. If a
single string value is provided, it is converted to a list internally during
input file processing phase.
Inflow Boundary Condition
+++++++++++++++++++++++++
.. code-block:: yaml
- inflow_boundary_condition: bc_inflow
target_name: inlet
inflow_user_data:
velocity: [0.0,0.0,1.0]
Open Boundary Condition
+++++++++++++++++++++++
.. code-block:: yaml
- open_boundary_condition: bc_open
target_name: outlet
open_user_data:
velocity: [0,0,0]
pressure: 0.0
entrainment_method: {computed, specified}
total_pressure: {yes, no}
Wall Boundary Condition
+++++++++++++++++++++++
.. inpfile:: bc.wall_user_data
This subsection contains specifications as to whether wall models are used,
or how to treat the velocity at the wall when there is mesh motion.
The following input file snippet shows an example of using an ABL wall function at the
terrain during ABL simulations. See :ref:`theory_abl_wall_function` for more
details on the actual implementation.
.. code-block:: yaml
# Wall boundary condition example for ABL terrain modeling
- wall_boundary_condition: bc_terrain
target_name: terrain
wall_user_data:
velocity: [0,0,0]
use_abl_wall_function: yes
heat_flux: 0.0
roughness_height: 0.2
gravity_vector_component: 3
reference_temperature: 300.0
The entry `gravity_vector_component` is an integer that
specifies the component of the gravity vector, defined in
`solution_options.gravity`, that should be used in the
definition of the Monin-Obukhov length scale calculation. The
entry `reference_temperature` is the reference temperature
used in calculation of the Monin-Obukhov length scale.
When there is mesh motion involved the wall boundary velocity takes the value of
the mesh_velocity along the part represented by `bc.target_name`. In
such a scenario all information under `bc.wall_user_data` is rendered
unused.
Example of wall boundary with a custom user function for temperature at the wall
.. code-block:: yaml
- wall_boundary_condition: bc_6
target_name: surface_6
wall_user_data:
user_function_name:
temperature: steady_2d_thermal
Symmetry Boundary Condition
+++++++++++++++++++++++++++
Requires no additional input other than `bc.target_name`.
.. code-block:: yaml
- symmetry_boundary_condition: bc_top
target_name: top
symmetry_user_data:
Periodic Boundary Condition
+++++++++++++++++++++++++++
Unlike the other BCs described so far, the parameter `bc.target_name`
behaves differently for the periodic BC. This parameter must be a list
containing exactly two entries: the boundary face pair where periodicity is
enforced. The nodes on these planes must coincide after translation in the
direction of periodicity. This BC also requires a `periodic_user_data`
section that specifies the search tolerance for locating node pairs.
.. inpfile:: periodic_user_data
.. code-block:: yaml
- periodic_boundary_condition: bc_east_west
target_name: [east, west]
periodic_user_data:
search_tolerance: 0.0001
Non-Conformal Boundary
++++++++++++++++++++++
Like the periodic BC, the parameter `bc.target_name` must be a list
with exactly two entries that specify the boundary plane pair forming the
non-conformal boundary.
.. code-block:: yaml
- non_conformal_boundary_condition: bc_left
target_name: [surface_77, surface_7]
non_conformal_user_data:
expand_box_percentage: 10.0
Material Properties
```````````````````
.. inpfile:: material_properties
The section provides the properties required for various physical quantities
during the simulation. A sample section used for simulating ABL flows is shown below
.. code-block:: yaml
material_properties:
target_name: [fluid_part]
constant_specification:
universal_gas_constant: 8314.4621
reference_pressure: 101325.0
reference_quantities:
- species_name: Air
mw: 29.0
mass_fraction: 1.0
specifications:
- name: density
type: constant
value: 1.178037722969475
- name: viscosity
type: constant
value: 1.6e-5
- name: specific_heat
type: constant
value: 1000.0
.. inpfile:: material_properties.target_name
A list of element blocks (*parts*) where the material properties are applied.
This list should ideally include all the parts that are referenced by
`initial_conditions.target_name`. Using the alias ``all_blocks`` is
equivalent to listing all element blocks in the mesh.
.. inpfile:: material_properties.constant_specification
Values for several constants used during the simulation. Currently the
following properties are defined:
============================ ==============================================
Name Description
============================ ==============================================
``universal_gas_constant`` Ideal gas constant :math:`R`
``reference_temperature`` Reference temperature for simulations
``reference_pressure`` Reference pressure for simulations
============================ ==============================================
.. inpfile:: material_properties.reference_quantities
Provides material properties for the different species involved in the
simulation.
============================== ======================================
Name Description
============================== ======================================
``species_name`` Name used to lookup properties
``mw`` Molecular weight
``mass_fraction`` Mass fraction
``primary_mass_fraction``
``secondary_mass_fraction``
``stoichiometry``
============================== ======================================
.. inpfile:: material_properties.specifications
A list of material properties with the following parameters
.. inpfile:: material_properties.specifications.name
The name used for lookup, e.g., ``density``, ``viscosity``, etc.
.. inpfile:: material_properties.specifications.type
The type can be one of the following
===================== ====================================================================================
Type Description
===================== ====================================================================================
``constant`` Constant value property
``polynomial`` Property determined by a polynomial function
``ideal_gas_t`` Function of :math:`T_\mathrm{ref}`, :math:`P_\mathrm{ref}`, molecular weight
``ideal_gas_t_p`` Function of :math:`T_\mathrm{ref}`, pressure, molecular weight
``ideal_gas_yk``
``hdf5table`` Lookup from an HDF5 table
``mixture_fraction`` Property determined by the mixture fraction
``geometric``
``generic``
===================== ====================================================================================
**Examples**
#. Specification for density as a function of temperature
.. code-block:: yaml
specifications:
- name: density
type: ideal_gas_t
#. Specification of viscosity as a function of temperature
.. code-block:: yaml
- name: viscosity
type: polynomial
coefficient_declaration:
- species_name: Air
coefficients: [1.7894e-5, 273.11, 110.56]
The ``species_name`` must correspond to the entry in `reference
quantitites <material_properties.reference_quantities>` to lookup
molecular weight information.
#. Specification via ``hdf5table``
.. code-block:: yaml
material_properties:
table_file_name: SLFM_CGauss_C2H4_ZMean_ZScaledVarianceMean_logChiMean.h5
specifications:
- name: density
type: hdf5table
independent_variable_set: [mixture_fraction, scalar_variance, scalar_dissipation]
table_name_for_property: density
table_name_for_independent_variable_set: [ZMean, ZScaledVarianceMean, ChiMean]
aux_variables: temperature
table_name_for_aux_variables: temperature
- name: viscosity
type: hdf5table
independent_variable_set: [mixture_fraction, scalar_variance, scalar_dissipation]
table_name_for_property: mu
table_name_for_independent_variable_set: [ZMean, ZScaledVarianceMean, ChiMean]
#. Specification via ``mixture_fraction``
.. code-block:: yaml
material_properties:
target_name: block_1
specifications:
- name: density
type: mixture_fraction
primary_value: 0.163e-3
secondary_value: 1.18e-3
- name: viscosity
type: mixture_fraction
primary_value: 1.967e-4
secondary_value: 1.85e-4
Solution Options
````````````````
.. note::
The documentation for this section is incomplete.
.. inpfile:: solution_options
This section defines the discretization and numerical stability
approaches, as well as turbulence models.
.. inpfile:: solution_options.name
Name of solution options group.
.. inpfile:: solution_options.turbulence_model
Turbulence model used in simulation.
.. inpfile:: solution_options.options
This subsection defines additional options for the solution options.
For example, one could modify turbulence model constants:
.. code-block:: yaml
- turbulence_model_constants:
SDRWallFactor: 0.625
One could also define source terms, such as a momentum forcing in a
box of the domain:
.. code-block:: yaml
- source_terms:
momentum: body_force_box
- source_term_parameters:
momentum: [0.011, 0.0, 0.0]
momentum_box: [-1.0, 1.00001, 0.0, 10.0, 4.0, 5.0]
One can make the momentum forcing in a box dynamic to achieve a
target velocity on a face:
.. code-block:: yaml
- dynamic_body_force_box_parameters:
forcing_direction: 0
velocity_reference: 21.0
density_reference: 1.0
velocity_target_name: inlet
drag_target_name: [top, bottom]
output_file_name: forcing.dat
Mesh Transformation
```````````````````
.. inpfile:: mesh_transformation
This subsection of the realm describes a one time stationary motion undergone
by the entire mesh with entries under `mesh_transformation` describing
the motions applied to different parts in a.
Example:
.. code-block:: yaml
mesh_transformation:
- name: scale_background
mesh_parts: [ Unspecified-3-HEX ]
motion:
- type: scaling
factor: [1.2, 1.0, 1.2]
origin: [5.0, 0.05, 0.0]
- name: scale_near_body
mesh_parts: [ Unspecified-2-HEX ]
motion:
- type: scaling
factor: [1.2, 1.0, 1.2]
origin: [0.0, 0.05, 0.0]
.. inpfile:: mesh_transformation.name
Name of motion group.
.. inpfile:: mesh_transformation.mesh_parts
Mesh parts associated with respective motion group. The user may use ``all_blocks``
to apply the transformation to the entire mesh.
.. inpfile:: mesh_transformation.motion
Type of motion. Every group is free to undergo one or multiple motions simultaneously.
Mesh Motion
```````````
.. inpfile:: mesh_motion
This subsection of the of the realm describes the time-dependent rigid body motion undergone
by the entire mesh for as described by entries under `mesh_motion`.
Example:
.. code-block:: yaml
mesh_motion:
- name: trans_rot_near_body
mesh_parts: [ Unspecified-2-HEX ]
motion:
- type: rotation
omega: 12.0
axis: [0.0, 1.0, 0.0]
origin: [0.0, 0.05, 0.0]
- type: translation
start_time: 100.0
end_time: 200.0
velocity: [0.05, 0.0, 0.0]
.. inpfile:: mesh_motion.name
Name of motion group.
.. inpfile:: mesh_motion.mesh_parts
Mesh parts associated with respective motion group. The user may use ``all_blocks``
to apply the motion to the entire mesh.
.. inpfile:: mesh_motion.motion
Type of motion the current group undergoes. Every frame is free to undergo one
or multiple motions simultaneously.
Output Options
``````````````
.. inpfile:: output
Specifies the frequency of output, the output database name, etc.
Example:
.. code-block:: yaml
output:
output_data_base_name: out/ABL.neutral.e
output_frequency: 100
output_node_set: no
output_variables:
- velocity
- pressure
- temperature
.. inpfile:: output.output_data_base_name
The name of the output Exodus-II database. Can specify a directory relative
to the run directory, e.g., ``out/nalu_results.e``. The directory will be
created automatically if one doesn't exist. Default: ``output.e``
.. inpfile:: output.output_frequency
Nalu-Wind will write the output file every ``output_frequency`` timesteps. Note
that currently there is no option to output results at a specified simulation
time. Default: ``1``.
.. inpfile:: output.output_start
Nalu-Wind will start writing output past the ``output_start`` timestep. Default: ``0``.
.. inpfile:: output.output_forced_wall_time
Force output at a specified *wall-clock time* in seconds.
.. inpfile:: output.output_node_set
Boolean flag indicating whether nodesets, if present, should be output to the
output file along with element blocks.
.. inpfile:: output.compression_level
Integer value indicating the compression level used. Default: ``0``.
.. inpfile:: output.output_variables
A list of field names to be output to the database. The field variables can
be node or element based quantities.
Restart Options
```````````````
.. inpfile:: restart
This section manages the restart for this realm object.
.. inpfile:: restart.restart_data_base_name
The filename for restart. Like `output`, the filename can contain a
directory and it will be created if not already present.
.. inpfile:: restart.restart_time
If this variable is present, it indicates that the current run will restart
from a previous simulation. This requires that the `mesh` be a
restart file with all the fields necessary for the equation sets defined in
the `equation_systems.systems`. Nalu-Wind will restart from the closest
time available in the `mesh` to ``restart_time``. The timesteps
available in a restart file can be examined by looking at the ``time_whole``
variable using the ``ncdump`` utility.
.. note::
The restart database used for restarting a simulation is the
`mesh` parameter. The :inpfile:`restart_data_base_name
<restart.restart_data_base_name>` parameter is used exclusively for
outputs.
.. inpfile:: restart.restart_frequency
The frequency at which restart files are written to the disk. Default: ``500`` timesteps.
.. inpfile:: restart.restart_start
Nalu-Wind will write a restart file after ``restart_start`` timesteps have elapsed.
.. inpfile:: restart.restart_forced_wall_time
Force writing of restart file after specified *wall-clock time* in seconds.
.. inpfile:: restart.restart_node_set
A boolean flag indicating whether nodesets are output to the restart database.
.. inpfile:: restart.max_data_base_step_size
Default: ``100,000``.
.. inpfile:: restart.compression_level
Compression level. Default: ``0``.
Time-step Control Options
`````````````````````````
.. inpfile:: time_step_control
This optional section specifies the adpative time stepping parameters used if
`time_int.time_stepping_type` is set to ``adaptive``.
.. code-block:: yaml
time_step_control:
target_courant: 2.0
time_step_change_factor: 1.2
.. inpfile:: dtctrl.target_courant
Maximum Courant number allowed during the simulation. Default: ``1.0``
.. inpfile:: dtctrl.time_step_change_factor
Maximum allowable increase in ``dt`` over a given timestep.
**Turbine specific input options**
Actuator Turbine Model
``````````````````````
.. inpfile:: actuator
``actuator`` subsection defines the inputs for actuator line simulations. A
sample section is shown below for running actuator line simulations
coupled to OpenFAST with two turbines.
.. code-block:: yaml
actuator:
type: ActLineFAST
search_method: stk_kdtree
search_target_part: Unspecified-2-HEX
n_turbines_glob: 2
dry_run: False
debug: False
t_start: 0.0
simStart: init # init/trueRestart/restartDriverInitFAST
t_max: 5.0
n_every_checkpoint: 100
Turbine0:
procNo: 0
num_force_pts_blade: 50
num_force_pts_tower: 20
nacelle_cd: 1.0
nacelle_area: 1.0
air_density: 1.225
epsilon: [ 5.0, 5.0, 5.0 ]
turbine_base_pos: [ 0.0, 0.0, -90.0 ]
turbine_hub_pos: [ 0.0, 0.0, 0.0 ]
restart_filename: ""
FAST_input_filename: "Test01.fst"
turb_id: 1
turbine_name: machine_zero
Turbine1:
procNo: 0
num_force_pts_blade: 50
num_force_pts_tower: 20
nacelle_cd: 1.0
nacelle_area: 1.0
air_density: 1.225
epsilon: [ 5.0, 5.0, 5.0 ]
turbine_base_pos: [ 250.0, 0.0, -90.0 ]
turbine_hub_pos: [ 250.0, 0.0, 0.0 ]
restart_filename: ""
FAST_input_filename: "Test02.fst"
turb_id: 2
turbine_name: machine_one
.. inpfile:: actuator.type
Type of actuator source. Options are ``ActLineFAST`` and ``ActDiskFAST``. ``ActLineFAST`` is for actuator lines, and ``ActDiskFAST`` is for actuator disks. The actuator disk uses a stationary actuator line model to compute forces at the blade locations and then the average force of the blades is spread azimuthally between the blades sampling points.
.. inpfile:: actuator.search_method
String specifying the type of search method used to identify the nodes within the search radius of the actuator points. The only valid option is ``stk_kdtree``. The ``boost_rtree`` option has been deprecated by the STK search library.
.. inpfile:: search_target_part
String or an array of strings specifying the parts of the mesh to be searched to identify the nodes near the actuator points.
.. inpfile:: actuator.n_turbines_glob
Total number of turbines in the simulation. The input file must contain a number of turbine specific sections (`Turbine0`, `Turbine1`, ..., `Turbine(n-1)`) that is consistent with `nTurbinesGlob`.
.. inpfile:: actuator.debug
Enable debug outputs if set to true
.. inpfile:: actuator.dry_run
The simulation will not run if dryRun is set to true. However, the simulation will read the input files, allocate turbines to processors and prepare to run the individual turbine instances. This flag is useful to test the setup of the simulation before running it.
.. inpfile:: actuator.simStart
Flag indicating whether the simulation starts from scratch or restart. ``simStart`` takes on one of three values:
* ``init`` - Use this option when starting a simulation from `t=0s`.
* ``trueRestart`` - While OpenFAST allows for restart of a turbine simulation, external components like the Bladed style controller may not. Use this option when all components of the simulation are known to restart.
* ``restartDriverInitFAST`` - When the ``restartDriverInitFAST`` option is selected, the individual turbine models start from `t=0s` and run up to the specified restart time using the inflow data stored at the actuator nodes from a hdf5 file. The C++ API stores the inflow data at the actuator nodes in a hdf5 file at every OpenFAST time step and then reads it back when using this restart option. This restart option is especially useful when the glue code is a CFD solver.
.. inpfile:: actuator.t_start
Start time of the simulation
.. inpfile:: actuator.t_end
End time of the simulation. ``t_end`` <= ``t_max``
.. inpfile:: actuator.t_max
Max time of the simulation
.. note::
``t_max`` can only be set when OpenFAST is running from `t=0s` and ``simStart`` is ``init``. ``t_max`` can not be changed on a restart. OpenFAST will not be able to run beyond ``t_max``. Choose ``t_max`` to be large enough to accomodate any possible future extensions of runs. One can change ``t_start`` and ``t_end`` to start and stop the simulation any number of times as long as ``t_end`` <= ``t_max``.
.. inpfile:: actuator.dt_fast
Time step for OpenFAST. All turbines should have the same time step.
.. inpfile:: actuator.n_every_checkpoint
Restart files will be written every so many time steps
**Turbine specific input options**
.. inpfile:: actuator.turbine_base_pos
The position of the turbine base for actuator-line/disk simulations
.. inpfile:: actuator.num_force_pts_blade
The number of actuator points along each blade for actuator-line/disk simulations
.. inpfile:: actuator.num_force_pts_tower
The number of actuator points along the tower for actuator-line/disk simulations.
.. inpfile:: actuator.nacelle_cd
The drag coefficient for the nacelle. If this is set to zero, or not
defined, the code will not implement the nacelle model.
.. inpfile:: actuator.nacelle_area
The reference area for the nacelle. This is only used if the nacelle
model is used.
.. inpfile:: actuator.air_density
The air density. This is only used to compute the nacelle force. It should
match the density being used in both Nalu and OpenFAST.
.. inpfile:: actuator.epsilon
The spreading width :math:`\epsilon` in the Gaussian spreading function in
the `[chordwise, thickness, spanwise]` coordinate system to spread the
forces from the actuator point to the nodes.
In the case of the actuator disk, only the first value in the chordwise
direction is used for the uniform isotropic Gaussian.
.. inpfile:: actuator.epsilon_chord
This is the ratio :math:`\epsilon/c` in every direction
`[chordwise, thickness, spanwise]`. If this option is
specified, the code will choose a value of :math:`\epsilon` at every
location that
is :math:`c * \epsilon/c`. To avoid numerical instabilities,
the code will choose the maximum value between :math:`c * \epsilon/c`
and the value of ``actuator.epsilon_min`` specified.
.. inpfile:: actuator.epsilon_min
This is the minimum value of :math:`\epsilon` in the Gaussian spreading
function in the `[chordwise, thickness, spanwise]` coordinate system
to spread the forces from the actuator point to the nodes.
This option is required if the option ``actuator.epsilon_chord``
is specified.
.. inpfile:: actuator.epsilon_tower
The spreading width :math:`\epsilon` in the Gaussian spreading function in
the inertial `[x, y, z]` reference frame.
If this value is not speficied, then ``actuator.epsilon`` or
``actuator.epsilon_min`` will be used.
.. inpfile:: actuator.restart_filename
The checkpoint file for this turbine when restarting a simulation
.. inpfile:: actuator.FAST_input_filename
The FAST input file for this turbine
.. inpfile:: actuator.turb_id
A unique turbine id for each turbine
.. inpfile:: actuator.num_swept_pts
This is an optional parameter specifically for actuator disks.
This parameter determines the number of points that are placed azimuthally
between the actuator lines and spread the forcing over the disk's area.
When ``num_swept_pts`` is included the number of azimuthal points between the
lines is forced to this value at all radial locations. If ``num_swept_pts``
is omitted then the azimuthal sampling is computed automatically with
different sampling at each radial location such that the average distance
between points matches the radial spacing.
Fluid-Structure Interaction
```````````````````````````
.. inpfile:: openfast_fsi
The ``openfast_fsi`` subsection defines parameters used when
coupling with openfast for FSI simulations. A sample section
is shown below.
.. code-block:: yaml
openfast_fsi:
n_turbines_glob: 1
debug: False
sim_start: trueRestart
t_start: 4.958677685950414
t_max: 600.55
n_checkpoint: 1440
dt_FAST: 0.0008608815426997245
Turbine0:
turbine_base_pos: [1800, 1800, 0]
turbine_hub_pos: [1795, 1800, 90]
restart_filename: "nrel5mw.5760"
sim_type: "ext-loads"
blade_parts:
- ["blade1-HEX"]
- ["blade2-HEX"]
- ["blade3-HEX"]
blade_boundary_parts:
- ["blade1"]
- ["blade2"]
- ["blade3"]
az_blend_mean: 18.84955592 # radians
az_blend_delta: 1.570796327 # radians
vel_mean: 11.4
wind_dir: 240.0 # degrees
z_ref: 90.0
shear_exp: 0.0
deflection_ramping:
enable_temporal_ramping: true
enable_theta_ramping: false
enable_span_ramping: false
span_ramp_distance: 4.0
temporal_ramp_start: 0.0
temporal_ramp_end: 0.5
theta_ramp_span: 30.0 # degrees
zero_theta_ramp_angle: 58.0 # degrees
.. inpfile:: n_turbines_glob
An integer indicating the total number of turbines to be used with FSI.
.. inpfile:: debug
A boolean flag that controls additional checks and printing of
additional information, which is helpful when troubleshooting a
simulation.
.. inpfile:: sim_start
String indicating how OpenFAST should start. For FSI
simulations, we suggest that the user set this to
``trueRestart`` (no quotes).
.. inpfile:: t_start
The start time of the FSI simulation. This should be an
integer multiple of ``dt_FAST``, and should match ``t_end``
in the OpenFAST driver file. Note that OpenFAST and
Nalu-Wind record time differently, so this variable will
not necessarily fit with the parameters in the
``Time_Integrators`` section.
.. inpfile:: t_max
The FSI simulation will end if the simulation time exceeds
this value.
.. inpfile:: n_checkpoint
An integer indicating the frequency with which checkpoint files
will be written. That is, a checkpoint will be written every
``n_checkpoint`` timesteps. Commonly this is set to correspond
to the number of steps in one rotor revolution.
.. inpfile:: dt_FAST
The timestep used by OpenFAST for the FSI simulation. This should
match ``DT`` in the OpenFAST input file (with extension .fst).
Commonly, this is 1/4 of the driver/Nalu/AMR-Wind timestep.
.. inpfile:: turbine_name
This subsection includes parameters for a particular turbine. Any
name may be provided by the user. In the above example, the name
``Turbine0`` was provided. In the following, any variable appearing
in this subsection will be denoted ``turbine_name.variable_name`` for
clarity, but only the variable name should be included in the input
file.
.. inpfile:: turbine_name.turbine_base_pos
Real vector indicating the location of the base of the tower.
This should match the variable with the same name in the OpenFAST
driver input file (with extension .yaml).
.. inpfile:: turbine_name.turbine_hub_pos
Real vector indicating the location of the hub.
This should match the variable with the same name in the OpenFAST
driver input file (with extension .yaml). Note that any height
change due to rotor tilt should be included in this variable, but
the effect of yaw should not be included.
.. inpfile:: turbine_name.restart_filename
String indicating the OpenFAST checkpoint file
that the FSI simulation will start from. Do not include the
extension (.chkp). This variable will have the format
``"name.integer"``, where the ``integer`` is the number of steps taken
in the OpenFAST standalone simulation. This should be equal to
``t_end`` divided by ``dt_FAST`` from the OpenFAST standalone run.
.. inpfile:: turbine_name.sim_type
String indicating the type of OpenFAST simulation.
For FSI simulations, this should always be set to ``"ext-loads"``.
.. inpfile:: turbine_name.blade_parts
List of strings indicating the mesh element blocks
corresponding to each of the blades.
.. inpfile:: turbine_name.tower_parts
List of strings indicating the mesh element blocks
corresponding to the tower.
.. inpfile:: turbine_name.blade_boundary_parts
List of strings indicating the mesh sidesets
corresponding to the wall boundaries of each of the blades.
.. inpfile:: turbine_name.tower_boundary_parts
List of strings indicating the mesh sidesets
corresponding to the wall boundaries of the tower.
.. inpfile:: turbine_name.az_blend_mean
Real variable (in radians) indicating the mean angular position for the load blending.
The loads provided to BeamDyn are a weighted average of the loads
provided by AeroDyn and the true CFD loads provided by Nalu-Wind
during startup to help with stability while the CFD flow field develops around
the turbine structure.
The weight of the Nalu-Wind contribution takes the form
:math:`\frac{1}{2} \left[1+\text{tanh}\left(\left(\phi-\phi_\text{mean}\right)/\phi_\text{delta}\right)\right]`,
where :math:`\phi` is the angle that the turbine has rotated through
(including any initial OpenFAST runs),
:math:`\phi_\text{mean}` is the value of ``az_blend_mean``, and
:math:`\phi_\text{delta}` is the value of ``az_blend_delta``.
.. inpfile:: turbine_name.az_blend_delta
Real variable (in radians) indicating the width for load blending.
See the entry for ``az_blend_mean`` above for a complete definition.
.. inpfile:: turbine_name.vel_mean
Real variable indicating the mean wind speed at height ``z_ref``. This
should correspond to the variable with the same name in the OpenFAST
driver input file (with extension .yaml).
.. inpfile:: turbine_name.wind_dir
Real variable indicating the angle of the incoming wind in degrees. The direction
the wind is heading is measured clockwise from South. For example, wind
heading South is 0 degrees, and wind heading East is 270 degrees. By convention,
the x-axis points East, and the y-axis points North.
This should match the variable with the same name in the OpenFAST driver input
file (with extension .yaml). If the turbine is intended to be aligned with
the flow, the ``NacYaw`` variable found in the OpenFAST Elastodyn file
should be 270 degrees minus ``wind_dir``. For example, if the wind is heading East,
``NacYaw`` will be 0 degrees.
.. inpfile:: turbine_name.z_ref
Real variable indicating the reference height at which ``vel_mean`` and
``wind_dir`` apply. Often corresponds to the hub height of the turbine.
.. inpfile:: turbine_name.shear_exp
Real variable indicating the exponent used in a power-law approximation
of the incoming ABL. This variable should match the variable with the same
name in the OpenFAST driver input file (with extension .yaml).
.. inpfile:: turbine_name.deflection_ramping
The ``deflection_ramping`` sub-subsection controls the temporal and spatial
ramping of blade deflections applied in Nalu-Wind. The temporal ramping enables a smooth
transition for the blades from a rigid body motion based on the hub motion to the
full blade deflections, and improves the stability of the simulation
during startup. The span ramping enables the root section
of the blades (which are typically circular) to remain undeformed. The theta ramping
improves the quality of the elements near the mesh interface between blades.
Note that the total deflection ramping factor will be the product of the temporal,
theta, and span ramping factors. This sub-subsection should be provided for each turbine.
.. inpfile:: deflection_ramping.enable_temporal_ramping
Boolean variable indicating whether temporal deflection ramping should be used.
.. inpfile:: deflection_ramping.enable_theta_ramping
Boolean variable indicating whether spatial deflection ramping with respect to
the circumferential direction should be used.
.. inpfile:: deflection_ramping.enable_span_ramping
Boolean variable indicating whether spatial deflection ramping with respect to
the spanwise direction should be used.
.. inpfile:: deflection_ramping.span_ramp_distance
Real variable indicating the distance from the root over which to ramp deflections
if ``enable_span_ramping`` is set to true. Distance is measured in the same units
as the mesh (meters in most cases).
.. inpfile:: deflection_ramping.temporal_ramp_start
Real variable indicating the time at which temporal ramping should begin.
Prior to this time, zero blade deflections will be provided. Note that this
should correspond to time as recorded by Nalu-Wind and described in the
``Time_Integrators`` section, not as recorded by OpenFAST. Hence, this will
not correspond to ``t_start`` above.
.. inpfile:: deflection_ramping.temporal_ramp_end
Real variable indicating the time at which temporal ramping should end.
After this time, full blade deflections will be provided. Note that this
should correspond to time as recorded by Nalu-Wind and described in the
``Time_Integrators`` section, not as recorded by OpenFAST.
.. inpfile:: deflection_ramping.theta_ramp_span
Real variable (in degrees) indicating the span of the circumferenial sector over which
theta ramping is applied. See Figure 1 for an explanation of the theta
ramping parameters, where :math:`\alpha` is the weight coefficient for the theta
ramping. The total deflection ramping is the product of the theta, span,
and temporal ramping.
.. figure:: figures/ramp.png
:align: center
Explanation of the theta ramping parameters.
.. inpfile:: deflection_ramping.zero_theta_ramp_angle
Real variable (in degrees) indicating the location of the beginning of the
circumferential sector over which no deflections are applied,
and the end of the sector over which deflections are ramped.
See Figure 1 for an explanation of the theta ramping parameters,
where :math:`\alpha` is the weight coefficient for the theta ramping.
The total deflection ramping is the product of the theta, span,
and temporal ramping.
Turbulence averaging
````````````````````
.. inpfile:: turbulence_averaging
``turbulence_averaging`` subsection defines the turbulence
post-processing quantities and averaging procedures. A sample
section is shown below
.. code-block:: yaml
turbulence_averaging:
forced_reset: no
time_filter_interval: 100000.0
averaging_type: nalu_classic/moving_exponential
specifications:
- name: turbulence_postprocessing
target_name: interior
reynolds_averaged_variables:
- velocity
favre_averaged_variables:
- velocity
- resolved_turbulent_ke
compute_tke: yes
compute_reynolds_stress: yes
compute_resolved_stress: yes
compute_temperature_resolved_flux: yes
compute_sfs_stress: yes
compute_temperature_sfs_flux: yes
compute_q_criterion: yes
compute_vorticity: yes
compute_lambda_ci: yes
.. note::
The variable in the `turbulence_averaging` subsection are
prefixed with ``turbulence_averaging.name`` but only the variable
name after the period should appear in the input file.
.. inpfile:: turbulence_averaging.forced_reset
A boolean flag indicating whether the averaging of all quantities in the
turbulence averaging section is reset. If this flag is true, the
running average is set to zero.
.. inpfile:: turbulence_averaging.averaging_type
This parameter sets the choice of the running average type. Possible
values are:
``nalu_classic``
"Sawtooth" average. The running average is set to zero each time the time
filter width is reached and a new average is calculated for the next time
interval.
``moving_exponential``
"Moving window" average where the window size is set to to the time
filter width. The contribution of any quantity before the moving window
towards the average value reduces exponentially with every time step.
.. inpfile:: turbulence_averaging.time_filter_interval
Number indicating the time filter size over which to calculate the
running average. This quantity is used in different ways for each filter
discussed above.
.. inpfile:: turbulence_averaging.specifications
A list of turbulence postprocessing properties with the following parameters
.. inpfile:: turbulence_averaging.specifications.name
The name used for lookup and logging.
.. inpfile:: turbulence_averaging.specifications.target_name
A list of element blocks (parts) where the turbulence averaging is applied.
.. inpfile:: turbulence_averaging.specifications.reynolds_average_variables
A list of field names to be averaged.
.. inpfile:: turbulence_averaging.specifications.favre_average_variables
A list of field names to be Favre averaged.
.. inpfile:: turbulence_averaging.specifications.compute_tke
A boolean flag indicating whether the turbulent kinetic energy is
computed. The default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_reynolds_stress
A boolean flag indicating whether the reynolds stress is
computed. The default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_resolved_stress
A boolean flag indicating whether the average resolved stress is
computed as :math:`< \bar\rho \widetilde{u_i} \widetilde{u_j} >`.
The default value is ``no``. When this option is turned on, the Favre
average of the resolved velocity, :math:`< \bar{\rho} \widetilde{u_j} >`, is
computed as well.
.. inpfile:: turbulence_averaging.specifications.compute_temperature_resolved_flux
A boolean flag indicating whether the average resolved temperature flux is
computed as :math:`< \bar\rho \widetilde{u_i} \widetilde{\theta} >`. The
default value is ``no``. When this option is turned on, the Favre average
of the resolved temperature, :math:`< \bar{\rho} \widetilde{\theta} >`, is
computed as well.
.. inpfile:: turbulence_averaging.specifications.compute_sfs_stress
A boolean flag indicating whether the average sub-filter scale stress is
computed. The default value is ``no``. The sub-filter scale stress model is
assumed to be of an eddy viscosity type and the turbulent viscosity computed
by the turbulence model is used. The sub-filter scale kinetic energy is used
to determine the isotropic component of the sub-filter stress. As described
in the section :ref:`supp_eqn_set_mom_cons`, the Yoshizawa model is used to
compute the sub-filter kinetic energy when it is not transported.
.. inpfile:: turbulence_averaging.specifications.compute_temperature_sfs_flux
A boolean flag indicating whether the average sub-filter scale flux of
temperature is computed. The default value is ``no``. The sub-filter scale
stress model is assumed to be of an eddy diffusivity type and the turbulent
diffusivity computed by the turbulence model is used along with a constant
turbulent Prandtl number obtained from the Realm.
.. inpfile:: turbulence_averaging.specifications.compute_favre_stress
A boolean flag indicating whether the Favre stress is computed. The
default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_favre_tke
A boolean flag indicating whether the Favre stress is computed. The
default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_q_criterion
A boolean flag indicating whether the q-criterion is computed. The
default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_vorticity
A boolean flag indicating whether the vorticity is computed. The
default value is ``no``.
.. inpfile:: turbulence_averaging.specifications.compute_lambda_ci
A boolean flag indicating whether the Lambda2 vorticity criterion
is computed. The default value is ``no``.
Data probes
```````````
.. inpfile:: data_probes
``data_probes`` subsection defines the data probes. A sample
section is shown below
.. code-block:: yaml
data_probes:
output_frequency: 100
output_format: text
search_method: stk_octree
search_tolerance: 1.0e-3
search_expansion_factor: 2.0
gzip_level: 0
write_coords: true
specifications:
- name: probe_bottomwall
from_target_part: bottomwall
line_of_site_specifications:
- name: probe_bottomwall
number_of_points: 100
tip_coordinates: [-6.39, 0.0, 0.0]
tail_coordinates: [4.0, 0.0, 0.0]
output_variables:
- field_name: tau_wall
field_size: 1
- field_name: pressure
specifications:
- name: probe_profile
from_target_part: interior
line_of_site_specifications:
- name: probe_profile
number_of_points: 100
tip_coordinates: [0, 0.0, 0.0]
tail_coordinates: [0.0, 0.0, 1.0]
plane_specifications:
- name: sample_plane
corner_coordinates: [0.0, 0.0, 0.0]
edge1_vector: [1.0, 0, 0]
edge2_vector: [0, 2.0, 0]
edge1_numPoints: 11
edge2_numPoints: 21
offset_vector: [0, 0, 1]
offset_spacings: [0, 2]
only_output_field: velocity
output_variables:
- field_name: velocity
field_size: 3
- field_name: reynolds_stress
field_size: 6
.. note::
The variable in the `data_probes` subsection are prefixed
with ``data_probes.name`` but only the variable name after the
period should appear in the input file.
.. inpfile:: data_probes.output_frequency
Integer specifying the frequency of output.
.. inpfile:: data_probes.output_format
String specifying the output format for the data probes. Currently
available options are ``text`` or ``exodus``. If not specified, the
default is text. Multiple output formats can be specified like the
following:
.. code-block:: yaml
output_format:
- text
- exodus
.. inpfile:: data_probes.search_method
String specifying the search method for finding nodes to transfer
field quantities to the data probe lineout.
.. inpfile:: data_probes.search_tolerance
Number specifying the search tolerance for locating nodes.
.. inpfile:: data_probes.search_expansion_factor
Number specifying the factor to use when expanding the node search.
.. inpfile:: data_probes.gzip_level
Optional input, applies to sample planes only. Integer specifying
amount of compression to apply to sample plane output. The default
``gzip_level=0``, means no compression. To apply compression, use
``gzip_level`` from 1 to 9, with 9 indicating maximum compression
(and slowest speed). Generally ``gzip_level=1`` or
``gzip_level=2`` is sufficient.
.. inpfile:: data_probes.write_coords
Optional input, applies to sample planes only. Boolean specifying
whether the sample plane x,y,z coordinates and indices are to be
included with every sample plane output. The default is
``write_coords=true``. For ``write_coords=false``, a separate
coordinate file will be written at the beginning of the output
sequence if it does not already exist.
.. inpfile:: data_probes.time_performance
Optional input, applies to sample planes only. Boolean specifying
whether to display timing information when writing sample planes.
.. inpfile:: data_probes.specifications
A list of data probe properties with the following parameters
.. inpfile:: data_probes.specifications.name
The name used for lookup and logging.
.. inpfile:: data_probes.specifications.from_target_part
A list of element blocks (parts) where to do the data probing.
.. inpfile:: data_probes.specifications.line_of_site_specifications
A list specifications defining the lineout
================= =============================================================
Parameter Description
================= =============================================================
name File name (without extension) for the data probe
number_of_points Number of points along the lineout
tip_coordinates List containing the coordinates for the start of the lineout
tail_coordinates List containing the coordinates for the end of the lineout
================= =============================================================
.. inpfile:: data_probes.specifications.plane_specifications
A list specifications defining the sampling plane
================== =============================================================
Parameter Description
================== =============================================================
name File name (without extension) for the sampling plane
corner_coordinates List containing the coordinates for the corner of the plane
edge1_vector List containing the vector defining the first edge of the plane (with origin at corner)
edge2_vector List containing the vector defining the second edge of the plane (with origin at corner)
edge1_numPoints Number of points along edge 1
edge2_numPoints Number of points along edge 2
offset_vector [Optional] List containing the vector defining the offset direction for additional planes
offset_spacings [Optional] List containing how far each plane is to be offset in the offset_vector direction
only_output_field [Optional] Only include the output of this variable in the sample plane output.
================== =============================================================
.. inpfile:: data_probes.specifications.output_variables
A list of field names (and field size) to be probed.
.. inpfile:: data_probes.lidar_specifications
Allows line_of_site sampling along trajectories tracing the rosette pattern
of a spinner LIDAR.
.. inpfile:: data_probes.lidar_specifications.from_target_part
The mesh part containing the spinner LIDAR center coordinates.
.. inpfile:: data_probes.lidar_specifications.scan_time
The time for a scan by the simulated spinner LIDAR.
.. inpfile:: data_probes.lidar_specifications.number_of_samples
The number of lines generated by the spinner LIDAR sampling. For the text
output, this will generate a separate file for each line.
.. inpfile:: data_probes.lidar_specifications.points_along_line
The number samples along each lines. This should be chosen based on the
spatial resolution of the underlying mesh, the LIDAR. measurements and the
`beam_length` parameter.
.. inpfile:: data_probes.lidar_specifications.center
The location of the spinner LIDAR aperture.
.. inpfile:: data_probes.lidar_specifications.beam_length
The maximum length over which to sample the velocity on a particular line.
The spatial resolution of the sampling is computed from this and the
`number_of_samples` parameter.
.. inpfile:: data_probes.lidar_specifications.axis
The orientation vector for the LIDAR measurements.
.. inpfile:: data_probes.lidar_specifications.output
Output type for subsampling LIDAR. Either `text` or `netcdf` (default).
.. inpfile:: data_probes.lidar_specifications.type
Type of LIDAR scan pattern. `scanning`, `radar` or `spinner` (default).
.. inpfile:: data_probes.lidar_specifications.warn_on_missing
Warn if points aren't found in the simulation domain. `yes` or `no` (default).
.. inpfile:: data_probes.lidar_specifications.reuse_search_data
Save cached search data per line. `yes` (default) or `no`.
.. inpfile:: data_probes.lidar_specifications.always_output
Output even if no points intersect domain. `yes` or `no` (default).
.. inpfile:: data_probes.lidar_specifications.scanning_lidar_specifications
Block specifying parameters for the scanning lidar sampling
========================== ===================================================================
Parameter Description
========================== ===================================================================
beam_length Required. Length over which to measure, e.g. 50.
axis Required. Zero angle vector for the angular sweep, e.g. [1,0,0].
center Required. Location of the scanning LIDAR, e.g. [0,0,0].
stare_time Default 1 second. Time line spends at a particular scan angle.
sweep_angle Default 20 degrees. Extent of angular sweep between sweep_angle/2 to -sweep_angle/2.
step_delta_angle Default 1 degree. Measurement interval of scan angles over the sweep
reset_time_delta Default 1 second. Time to reset LIDAR after sweep.
ground_direction Default [0,0,1]. Orthogonal orientation vector for the LIDAR
elevation_angles Default none. A list of angles in degrees to change to after each sweep
========================== ===================================================================
.. inpfile:: data_probes.lidar_specifications.radar_specifications
Block specifying parameters for the radar sampling
========================== ===================================================================
Parameter Description
========================== ===================================================================
axis Required. Zero angle vector for the angular sweep, e.g. [1,0,0].
center Required. Location of the radar, e.g. [0,0,0]. Ideally outside of the bounding box.
bbox Optional. Six values (m) describing [bottom-left, top-right] of radar clip box
box_1 Optional. Along with other vertex specifications in (m) describes the radar clip box.
beam_length Required. Sets the maximum length of the line sampled. Also used if line does not intersect box.
sweep_angle Default 20 degrees. Extent of angular sweep between -sweep_angle/2 to sweep_angle/2.
angular_speed Default 30 degrees/s. Speed of the angular sweep.
reset_time_delta Default 1 second. Time to reset LIDAR after sweep.
ground_direction Default [0,0,1]. Orthogonal orientation vector for the radar
elevation_angles Default none. A list of angles in degrees to change to after each sweep
========================== ===================================================================
.. inpfile:: dataprobes.lidar_specifications.radar_cone_grid
========================== ===================================================================
Parameter Description
========================== ===================================================================
cone_angle Required. cone half angle in degrees centered on radar_specifications.axis
num_circles Required. Number of rays along the cone angle
lines_per_cone_circle Required. Number of rays around the cone circumference
========================== ===================================================================
.. inpfile:: dataprobes.lidar_specifications.radar_cone_filter
Implements a few options for filtering the spherical cap of a cone. `truncated_normal{n}` rules with `n=1,2,3`
weight the filtering based on truncated normal distribution, with with the circle of the cone being 1,2, or 3
sigma away. This means that the sampling is more weighted toward the center of the cone with higher `n`. `radau`
has weight function = 1, optionally changeable to a Gaussian reaching half of its peak value at the cone circle.
========================== ===================================================================
Parameter Description
========================== ===================================================================
cone_angle Required. cone half angle in degrees centered on radar_specifications.axis
quadrature_type Required. Type of quadrature. `radau` or `truncated_normal{n}` (n=1,2,3), or `truncated_normal_halfpower`.
radau_points Optional. If `radau` quadrature is used, number of integration points
radau_weight_type Default `unity`. `gaussian_halfpower` is also supported.
lines_per_cone_circle Required. Number of rays around the cone circumference
========================== ===================================================================
.. inpfile:: dataprobes.lidar_specifications.misc
The user may also set a number of parameters corresponding to the hardware
configuration of the spinner LIDAR.
========================== ===================================================================
Parameter Description
========================== ===================================================================
inner_prism_theta Default 90 degrees. The starting angle of the inner prism
inner_prism_rotation_rate Default 3.5 degrees per second. Rotation rate of the inner prism
inner_prism_azimuth Default 15.2 degrees. azimuthal angle of the inner prism
outer_prism_theta Default 90 degrees. The starting angle of the outer prism
outer_prism_rotation_rate Default 6.5 degrees per second. Rotation rate of the outer prism
outer_prism_azimuth Default 15.2 degrees. azimuthal angle of the outer prism
ground_direction Default [0,0,1]. Orthogonal orientation vector for the LIDAR
========================== ===================================================================
Post-processing
```````````````
.. inpfile:: post_processing
``post_processing`` subsection defines the different
post-processing options. A sample section is shown below
.. code-block:: yaml
post_processing:
- type: surface
physics: surface_force_and_moment
output_file_name: results/wallHump.dat
frequency: 100
parameters: [0,0]
target_name: bottomwall
.. note::
The variable in the `post_processing` subsection are prefixed with
``post_processing.name`` but only the variable name after the period should
appear in the input file.
.. inpfile:: post_processing.type
Type of post-processing. Possible values are:
======== ======================================
Value Description
======== ======================================
surface Post-processing of surface quantities
======== ======================================
.. inpfile:: post_processing.physics
Physics to be post-processing. Possible values are:
======================================= ================================================================
Value Description
======================================= ================================================================
surface_force_and_moment Calculate surface forces and moments
surface_force_and_moment_wall_function Calculate surface forces and moments when using a wall function
======================================= ================================================================
.. inpfile:: post_processing.output_file_name
String specifying the output file name.
.. inpfile:: post_processing.frequency
Integer specifying the frequency of output.
.. inpfile:: post_processing.parameters
Parameters for the physics function. For the
``surface_force_and_moment`` type functions, this is a
list specifying the centroid coordinates used in the moment
calculation.
.. inpfile:: post_processing.target_name
A list of element blocks (parts) where to do the post-processing
.. _nalu_inp_transfers:
ABL Forcing
```````````
.. inpfile:: abl_forcing
``abl_forcing`` allows the user to specify desired velocities
and temperatures at different heights.
These velocities and temperatures are enforced through the
use of source in the momentum and enthalpy equations.
The ``abl_forcing`` option needs to be specified in the
``momentum`` and/or ``enthalpy`` source blocks:
.. code-block:: yaml
- source_terms:
momentum: abl_forcing
enthalpy: abl_forcing
This option allows the code to implement source terms
in the momentum and/or enthalpy equations.
A sample
section is shown below
.. code-block:: yaml
abl_forcing:
search_method: stk_kdtree
search_tolerance: 0.0001
search_expansion_factor: 1.5
output_frequency: 1
from_target_part: [fluid_part]
momentum:
type: computed
relaxation_factor: 1.0
heights: [250.0, 500.0, 750.0]
target_part_format: "zplane_%06.1f"
# The velocities at each plane
# Each list include a time and the velocities for each plane
# Notice that the total number of elements in each list will be
# number of planes + 1
velocity_x:
- [0.0, 10.0, 5.0, 15.0]
- [100000.0, 10.0, 5.0, 15.0]
velocity_y:
- [0.0, 0.0, 0.0, 0.0]
- [100000.0, 0.0, 0.0, 0.0]
velocity_z:
- [0.0, 0.0, 0.0, 0.0]
- [100000.0, 0.0, 0.0, 0.0]
temperature:
type: computed
relaxation_factor: 1.0
heights: [250.0, 500.0, 750.0]
target_part_format: "zplane_%06.1f"
temperature:
- [0.0, 300.0, 280.0, 310.0]
- [100000.0, 300.0, 280.0, 310.0]
.. note::
The variables in the `abl_forcing` subsection are
prefixed with ``abl_forcing.name`` but only the variable
name after the period should appear in the input file.
.. inpfile:: abl_forcing.search_method
This specifies the search method algorithm within the
stk framework. The default option `stk_kdtree` is recommended.
.. inpfile:: abl_forcing.search_tolerance
This is the tolerance specified for the
`search_method` algorithm. A default value of 0.0001 is recommended.
.. inpfile:: abl_forcing.search_expansion_factor
This option is related to the stk search algorithm.
A value of 1.5 is recommended.
.. inpfile:: abl_forcing.output_frequency
This is the frequency at which the source term is written
to the output value. A value of 1 means the source term
will be written to the output file every time-step.
.. note::
There are now two options in the following inputs.
The can be ``momentum`` and/or ``temperature``.
.. inpfile:: abl_forcing.momentum.computed
This option allows the user to choose if a momentum source is computed
from a desired velocity (``computed``) or if a user defined
source term is directly
applied into the momentum equation (``user_defined``).
.. inpfile:: abl_forcing.momentum.relaxation_factor
This is a relaxation factor which can be used to under/over-relax
the momentum source term.
The default value is 1.
.. inpfile:: abl_forcing.momentum.heights
This is a list containing the planes at which the forcing should
be implemented. Each input is the height for that plane.
This is the naming convention in the mesh file.
.. inpfile:: abl_forcing.momentum.target_part_format
This is the format in which the planes are saved in the
mesh file.
.. inpfile:: abl_forcing.momentum.velocity_x
A set of lists containing the time in the first element,
followed by the desired velocity at each plane in the
:math:`x` direction.
.. inpfile:: abl_forcing.momentum.velocity_y
A set of lists containing the time in the first element,
followed by the desired velocity at each plane in the
:math:`y` direction.
.. inpfile:: abl_forcing.momentum.velocity_z
A set of lists containing the time in the first element,
followed by the desired velocity at each plane in the
:math:`z` direction.
.. note::
The temperature has the same inputs as the momentum source
(``abl_forcing.temperature.type``,
``abl_forcing.temperature.relaxation_factor``,
``abl_forcing.temperature.heights``, and
``abl_forcing.temperature.target_part_format``)
which take the same options.
.. inpfile:: abl_forcing.temperature.temperature
A set of lists containing the time in the first element,
followed by the desired temperature at each plane.
Boundary Layer Statistics
`````````````````````````
.. inpfile:: boundary_layer_statistics
The ``boundary_layer_statistics`` subsection defines the statistics
to be gathered from the ABL precursor calculation. This section
computes the spatial averages of velocity and (optionally)
temperature at all height levels available in the ABL mesh.
The outputs are a series of text files (``abl_*_stats.dat``)
containing the averaged profiles and a netcdf file (e.g.,
``abl_statistics.nc``) containing the time history of the averaged
quantities.
A sample section is shown below:
.. code-block:: yaml
boundary_layer_statistics:
target_name: [fluid_part]
stats_output_file: abl_statistics.nc
compute_temperature_statistics: yes
output_frequency: 5000
time_hist_output_frequency: 1
height_multiplier: 1.0e6
The various parameters to ``boundary_layer_statistics`` are
described below:
.. inpfile:: boundary_layer_statistics.target_name
A list of element blocks (*parts*) where the ABL statistics are to
be computed.
.. inpfile:: boundary_layer_statistics.time_filter_interval
The length of time, in seconds, over which to average the
statistics given in the ``abl_*_stats.dat`` files.
[*Optional*, default value: ``3600.0``]
.. inpfile:: boundary_layer_statistics.compute_temperature_statistics
A ``yes`` or ``no`` value which indicates whether to include the
averaged temperature statistics.
[*Optional*, default value: ``yes``]
.. inpfile:: boundary_layer_statistics.output_frequency
The frequency to output statistics in the ``abl_*_stats.dat`` text
files.
[*Optional*, default value: ``10``]
.. inpfile:: boundary_layer_statistics.time_hist_output_frequency
The frequency, in iterations, of the time history statistics
included in the netcdf statistics file.
[*Optional*, default value: ``10``]
.. inpfile:: boundary_layer_statistics.stats_output_file
The name of the netcdf statistics file which includes the time
history and averages.
[*Optional*, default value: ``abl_statistics.nc``]
.. inpfile:: boundary_layer_statistics.process_utau_statistics
A ``yes`` or ``no`` value to indicate whether the utau statistics
are to be included in the computations.
[*Optional*, default value: ``yes``]
.. inpfile:: boundary_layer_statistics.wall_normal_direction
Spatial index to indicate the wall normal direction in the domain.
The directions are given by x=``1``, y=``2``, z=``3``.
[*Optional*, default value: ``3``]
.. inpfile:: boundary_layer_statistics.minimum_height
Minimum height to account for negative values in the wall normal
direction.
[*Optional*, default value: ``0.0``]
.. inpfile:: boundary_layer_statistics.height_multiplier
For the purposes of determining the unique heights for the ABL
statistics, wall normal distances are multiplied by
``height_multiplier`` then converted into integers for binning.
Larger values of ``height_multiplier`` allow a higher precision to
be used in determining the unique heights and better behavior in
some meshes.
[*Optional*, default value: ``2.0e6``]
Transfers
---------
.. inpfile:: transfers
Transfers section describes the search and mapping operations to be performed
between participating `realms` within a simulation.
Simulations
-----------
.. inpfile:: simulations
This is the top-level section that orchestrates the entire execution of Nalu-Wind.