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 naluX -i flag. By default, naluX will look for nalu.i in the current working directory to determine the mesh file as well as the run setup for execution. A sample nalu.i is shown below:

1 Sample Nalu-Wind input file for the Heat Conduction problem

# -*- mode: yaml -*-
#
# Example Nalu input file for a heat conduction problem
#

Simulations:
  - name: sim1
    time_integrator: ti_1
    optimizer: opt1

linear_solvers:
  - name: solve_scalar
    type: tpetra
    method: gmres 
    preconditioner: sgs 
    tolerance: 1e-3
    max_iterations: 75 
    kspace: 75 
    output_level: 0

realms:

  - name: realm_1
    mesh: periodic3d.g
    use_edges: no 
    automatic_decomposition_type: rcb

    equation_systems:
      name: theEqSys
      max_iterations: 2 
  
      solver_system_specification:
        temperature: solve_scalar
   
      systems:
        - HeatConduction:
            name: myHC
            max_iterations: 1
            convergence_tolerance: 1e-5

    initial_conditions:

      - constant: ic_1
        target_name: block_1
        value:
         temperature: 10.0

    material_properties:
      target_name: block_1
      specifications:
        - name: density
          type: constant
          value: 1.0
        - name: thermal_conductivity
          type: constant
          value: 1.0
        - name: specific_heat
          type: constant
          value: 1.0

    boundary_conditions:

    - wall_boundary_condition: bc_left
      target_name: surface_1
      wall_user_data:
        temperature: 20.0


    - wall_boundary_condition: bc_right
      target_name: surface_2
      wall_user_data:
        temperature: 40.0

    solution_options:
      name: myOptions

      use_consolidated_solver_algorithm: yes

      options:
      - element_source_terms:
          temperature: FEM_DIFF

    output:
      output_data_base_name: femHC.e
      output_frequency: 10
      output_node_set: no 
      output_variables:
       - dual_nodal_volume
       - temperature

Time_Integrators:
  - StandardTimeIntegrator:
      name: ti_1
      start_time: 0
      termination_step_count: 25 
      time_step: 10.0 
      time_stepping_type: fixed
      time_step_count: 0
      second_order_accuracy: no

      realms:
        - realm_1

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 Physics Realm Options 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 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 Time Integration Options 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 ABL Forcing 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.

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.

linear_solvers.name: The key used to refer to the linear solver configuration in equation_systems.solver_system_specification section.

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

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

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.

linear_solvers.tolerance: The relative tolerance used to determine convergence of the linear system.

linear_solvers.max_iterations: Maximum number of linear solver iterations performed.

linear_solvers.kspace: The Krylov vector space.

linear_solvers.output_level: Verbosity of output from the linear solver during execution.

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

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.

linear_solvers.recompute_preconditioner: A boolean flag indicating whether preconditioner is recomputed during runs. The default value is yes.

linear_solvers.reuse_preconditioner: Boolean flag. Default value is no.

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 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.

linear_solvers.bamg_output_level: The level of verbosity of BoomerAMG preconditioner. See HYPRE_BoomerAMGSetPrintLevel. Default: 0.

linear_solvers.bamg_coarsen_type: See HYPRE_BoomerAMGSetCoarsenType. Default: 6

linear_solvers.bamg_cycle_type: See HYPRE_BoomerAMGSetCycleType. Default: 1

linear_solvers.bamg_relax_type: See HYPRE_BoomerAMGSetRelaxType. Default: 6

linear_solvers.bamg_relax_order: See HYPRE_BoomerAMGSetRelaxOrder. Default: 1

linear_solvers.bamg_num_sweeps: See HYPRE_BoomerAMGSetNumSweeps. Default: 2

linear_solvers.bamg_max_levels: See HYPRE_BoomerAMGSetMaxLevels. Default: 20

linear_solvers.bamg_strong_threshold: See HYPRE_BoomerAMGSetStrongThreshold. Default: 0.25

Time Integration Options

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.

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

time_int.name: The lookup key for this time integration entry. This name must match the one provided in Simulations section.

time_int.termination_time: Nalu-Wind will stop the simulation once the termination_time has reached.

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.

time_int.time_step: The time step (\(\Delta t\)) used for the simulation. If time_int.time_stepping_type is fixed this value does not change during the simulation.

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 restart section.

time_int.time_step_count: The starting timestep counter for a new simulation. See restart for restarting from a previous simulation.

time_int.second_order_accuracy: A boolean flag indicating whether second-order time integration scheme is activated. Default: no.

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.

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.

Physics Realm Options

As mentioned previously, realms is a YAML list data structure containing at least one Physics Realm Options 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

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.

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.

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

activate_aura: A boolean flag indicating whether an extra element is ghosted across the processor boundaries. The default value is no.

use_edges: A boolean flag indicating whether edge based discretization scheme is used instead of element based schemes. The default value is no.

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.

solve_frequency: An integer value indicating how often this realm is solved during time integration. The default value is 1.

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.

activate_memory_diagnostic: A boolean flag indicating whether memory diagnostics are activated during simulation. Default value is no.

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.

balance_nodes: A boolean flag indicating whether node balancing is performed during simulations. See also balance_node_iterations and balance_nodes_target.

balance_node_iterations: The frequency at which node rebalancing is performed. Default value is 5.

balance_node_target: The target balance ratio. Default value is 1.0.

Equation Systems

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.

equation_systems.name: A string indicating the name used in log messages etc.

equation_systems.max_iterations: The maximum number of non-linear iterations performed during a timestep that couples the different equation systems.

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:

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.

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	\(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:

# 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

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.

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]

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.

initial_conditions.user_function: Indicates that this block of YAML input must be parsed as input for a user defined function.

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

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.

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

- inflow_boundary_condition: bc_inflow
  target_name: inlet
  inflow_user_data:
    velocity: [0.0,0.0,1.0]

Open Boundary Condition

- 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

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 ABL Wall Function for more details on the actual implementation.

# 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

- 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.

- 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.

periodic_user_data

- 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.

- non_conformal_boundary_condition: bc_left
  target_name: [surface_77, surface_7]
  non_conformal_user_data:
    expand_box_percentage: 10.0

Material Properties

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

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

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.

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 \(R\)
`reference_temperature`	Reference temperature for simulations
`reference_pressure`	Reference pressure for simulations

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`

material_properties.specifications: A list of material properties with the following parameters

material_properties.specifications.name: The name used for lookup, e.g., density, viscosity, etc.

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 \(T_\mathrm{ref}\), \(P_\mathrm{ref}\), molecular weight
`ideal_gas_t_p`	Function of \(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

specifications:
   - name: density
     type: ideal_gas_t

Specification of viscosity as a function of temperature
```
- 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

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

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.

solution_options: This section defines the discretization and numerical stability approaches, as well as turbulence models.

solution_options.name: Name of solution options group.

solution_options.turbulence_model: Turbulence model used in simulation.

solution_options.options

This subsection defines additional options for the solution options.

For example, one could modify turbulence model constants:

- turbulence_model_constants:
    SDRWallFactor: 0.625

One could also define source terms, such as a momentum forcing in a box of the domain:

- 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:

- 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

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:

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]

mesh_transformation.name: Name of motion group.

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.

mesh_transformation.motion: Type of motion. Every group is free to undergo one or multiple motions simultaneously.

Mesh Motion

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:

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]

mesh_motion.name: Name of motion group.

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.

mesh_motion.motion: Type of motion the current group undergoes. Every frame is free to undergo one or multiple motions simultaneously.

Output Options

output

Specifies the frequency of output, the output database name, etc.

Example:

output:
  output_data_base_name: out/ABL.neutral.e
  output_frequency: 100
  output_node_set: no
  output_variables:
   - velocity
   - pressure
   - temperature

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

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.

output.output_start: Nalu-Wind will start writing output past the output_start timestep. Default: 0.

output.output_forced_wall_time: Force output at a specified wall-clock time in seconds.

output.output_node_set: Boolean flag indicating whether nodesets, if present, should be output to the output file along with element blocks.

output.compression_level: Integer value indicating the compression level used. Default: 0.

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

restart: This section manages the restart for this realm object.

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.

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 restart_data_base_name parameter is used exclusively for outputs.

restart.restart_frequency: The frequency at which restart files are written to the disk. Default: 500 timesteps.

restart.restart_start: Nalu-Wind will write a restart file after restart_start timesteps have elapsed.

restart.restart_forced_wall_time: Force writing of restart file after specified wall-clock time in seconds.

restart.restart_node_set: A boolean flag indicating whether nodesets are output to the restart database.

restart.max_data_base_step_size: Default: 100,000.

restart.compression_level: Compression level. Default: 0.

Time-step Control Options

time_step_control

This optional section specifies the adpative time stepping parameters used if time_int.time_stepping_type is set to adaptive.

time_step_control:
  target_courant: 2.0
  time_step_change_factor: 1.2

dtctrl.target_courant: Maximum Courant number allowed during the simulation. Default: 1.0

dtctrl.time_step_change_factor: Maximum allowable increase in dt over a given timestep.

Turbine specific input options

Actuator Turbine Model

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.

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

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.

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.

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.

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.

actuator.debug: Enable debug outputs if set to true

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.

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.

actuator.t_start: Start time of the simulation

actuator.t_end: End time of the simulation. t_end <= t_max

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.

actuator.dt_fast: Time step for OpenFAST. All turbines should have the same time step.

actuator.n_every_checkpoint: Restart files will be written every so many time steps

Turbine specific input options

actuator.turbine_base_pos: The position of the turbine base for actuator-line/disk simulations

actuator.num_force_pts_blade: The number of actuator points along each blade for actuator-line/disk simulations

actuator.num_force_pts_tower: The number of actuator points along the tower for actuator-line/disk simulations.

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.

actuator.nacelle_area: The reference area for the nacelle. This is only used if the nacelle model is used.

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.

actuator.epsilon: The spreading width \(\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.

actuator.epsilon_chord: This is the ratio \(\epsilon/c\) in every direction [chordwise, thickness, spanwise]. If this option is specified, the code will choose a value of \(\epsilon\) at every location that is \(c * \epsilon/c\). To avoid numerical instabilities, the code will choose the maximum value between \(c * \epsilon/c\) and the value of actuator.epsilon_min specified.

actuator.epsilon_min: This is the minimum value of \(\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.

actuator.epsilon_tower: The spreading width \(\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.

actuator.restart_filename: The checkpoint file for this turbine when restarting a simulation

actuator.FAST_input_filename: The FAST input file for this turbine

actuator.turb_id: A unique turbine id for each turbine

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

openfast_fsi

The openfast_fsi subsection defines parameters used when coupling with openfast for FSI simulations. A sample section is shown below.

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

n_turbines_glob: An integer indicating the total number of turbines to be used with FSI.

debug: A boolean flag that controls additional checks and printing of additional information, which is helpful when troubleshooting a simulation.

sim_start: String indicating how OpenFAST should start. For FSI simulations, we suggest that the user set this to trueRestart (no quotes).

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.

t_max: The FSI simulation will end if the simulation time exceeds this value.

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.

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.

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.

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).

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.

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.

turbine_name.sim_type: String indicating the type of OpenFAST simulation. For FSI simulations, this should always be set to "ext-loads".

turbine_name.blade_parts: List of strings indicating the mesh element blocks corresponding to each of the blades.

turbine_name.tower_parts: List of strings indicating the mesh element blocks corresponding to the tower.

turbine_name.blade_boundary_parts: List of strings indicating the mesh sidesets corresponding to the wall boundaries of each of the blades.

turbine_name.tower_boundary_parts: List of strings indicating the mesh sidesets corresponding to the wall boundaries of the tower.

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 \(\frac{1}{2} \left[1+\text{tanh}\left(\left(\phi-\phi_\text{mean}\right)/\phi_\text{delta}\right)\right]\), where \(\phi\) is the angle that the turbine has rotated through (including any initial OpenFAST runs), \(\phi_\text{mean}\) is the value of az_blend_mean, and \(\phi_\text{delta}\) is the value of az_blend_delta.

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.

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).

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.

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.

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).

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.

deflection_ramping.enable_temporal_ramping: Boolean variable indicating whether temporal deflection ramping should be used.

deflection_ramping.enable_theta_ramping: Boolean variable indicating whether spatial deflection ramping with respect to the circumferential direction should be used.

deflection_ramping.enable_span_ramping: Boolean variable indicating whether spatial deflection ramping with respect to the spanwise direction should be used.

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).

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.

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.

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 \(\alpha\) is the weight coefficient for the theta ramping. The total deflection ramping is the product of the theta, span, and temporal ramping.

1 Explanation of the theta ramping parameters.

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 \(\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

turbulence_averaging

turbulence_averaging subsection defines the turbulence post-processing quantities and averaging procedures. A sample section is shown below

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.

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.

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.

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.

turbulence_averaging.specifications: A list of turbulence postprocessing properties with the following parameters

turbulence_averaging.specifications.name: The name used for lookup and logging.

turbulence_averaging.specifications.target_name: A list of element blocks (parts) where the turbulence averaging is applied.

turbulence_averaging.specifications.reynolds_average_variables: A list of field names to be averaged.

turbulence_averaging.specifications.favre_average_variables: A list of field names to be Favre averaged.

turbulence_averaging.specifications.compute_tke: A boolean flag indicating whether the turbulent kinetic energy is computed. The default value is no.

turbulence_averaging.specifications.compute_reynolds_stress: A boolean flag indicating whether the reynolds stress is computed. The default value is no.

turbulence_averaging.specifications.compute_resolved_stress: A boolean flag indicating whether the average resolved stress is computed as \(< \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, \(< \bar{\rho} \widetilde{u_j} >\), is computed as well.

turbulence_averaging.specifications.compute_temperature_resolved_flux: A boolean flag indicating whether the average resolved temperature flux is computed as \(< \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, \(< \bar{\rho} \widetilde{\theta} >\), is computed as well.

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 Conservation of Momentum, the Yoshizawa model is used to compute the sub-filter kinetic energy when it is not transported.

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.

turbulence_averaging.specifications.compute_favre_stress: A boolean flag indicating whether the Favre stress is computed. The default value is no.

turbulence_averaging.specifications.compute_favre_tke: A boolean flag indicating whether the Favre stress is computed. The default value is no.

turbulence_averaging.specifications.compute_q_criterion: A boolean flag indicating whether the q-criterion is computed. The default value is no.

turbulence_averaging.specifications.compute_vorticity: A boolean flag indicating whether the vorticity is computed. The default value is no.

turbulence_averaging.specifications.compute_lambda_ci: A boolean flag indicating whether the Lambda2 vorticity criterion is computed. The default value is no.

Data probes

data_probes

data_probes subsection defines the data probes. A sample section is shown below

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.

data_probes.output_frequency: Integer specifying the frequency of output.

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:

output_format:
- text
- exodus

data_probes.search_method: String specifying the search method for finding nodes to transfer field quantities to the data probe lineout.

data_probes.search_tolerance: Number specifying the search tolerance for locating nodes.

data_probes.search_expansion_factor: Number specifying the factor to use when expanding the node search.

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.

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.

data_probes.time_performance: Optional input, applies to sample planes only. Boolean specifying whether to display timing information when writing sample planes.

data_probes.specifications: A list of data probe properties with the following parameters

data_probes.specifications.name: The name used for lookup and logging.

data_probes.specifications.from_target_part: A list of element blocks (parts) where to do the data probing.

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

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.

data_probes.specifications.output_variables: A list of field names (and field size) to be probed.

data_probes.lidar_specifications: Allows line_of_site sampling along trajectories tracing the rosette pattern of a spinner LIDAR.

data_probes.lidar_specifications.from_target_part: The mesh part containing the spinner LIDAR center coordinates.

data_probes.lidar_specifications.scan_time: The time for a scan by the simulated spinner LIDAR.

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.

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.

data_probes.lidar_specifications.center: The location of the spinner LIDAR aperture.

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.

data_probes.lidar_specifications.axis: The orientation vector for the LIDAR measurements.

data_probes.lidar_specifications.output: Output type for subsampling LIDAR. Either text or netcdf (default).

data_probes.lidar_specifications.type: Type of LIDAR scan pattern. scanning, radar or spinner (default).

data_probes.lidar_specifications.warn_on_missing: Warn if points aren’t found in the simulation domain. yes or no (default).

data_probes.lidar_specifications.reuse_search_data: Save cached search data per line. yes (default) or no.

data_probes.lidar_specifications.always_output: Output even if no points intersect domain. yes or no (default).

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

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

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

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

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

post_processing

post_processing subsection defines the different post-processing options. A sample section is shown below

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.

post_processing.type

Type of post-processing. Possible values are:

Value	Description
surface	Post-processing of surface quantities

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

post_processing.output_file_name: String specifying the output file name.

post_processing.frequency: Integer specifying the frequency of output.

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.

post_processing.target_name: A list of element blocks (parts) where to do the post-processing

ABL Forcing

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:

- 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

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.

abl_forcing.search_method: This specifies the search method algorithm within the stk framework. The default option stk_kdtree is recommended.

abl_forcing.search_tolerance: This is the tolerance specified for the search_method algorithm. A default value of 0.0001 is recommended.

abl_forcing.search_expansion_factor: This option is related to the stk search algorithm. A value of 1.5 is recommended.

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.

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).

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.

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.

abl_forcing.momentum.target_part_format: This is the format in which the planes are saved in the mesh file.

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 \(x\) direction.

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 \(y\) direction.

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 \(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.

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

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:

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:

boundary_layer_statistics.target_name: A list of element blocks (parts) where the ABL statistics are to be computed.

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]

boundary_layer_statistics.compute_temperature_statistics: A yes or no value which indicates whether to include the averaged temperature statistics. [Optional, default value: yes]

boundary_layer_statistics.output_frequency: The frequency to output statistics in the abl_*_stats.dat text files. [Optional, default value: 10]

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]

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]

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]

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]

boundary_layer_statistics.minimum_height: Minimum height to account for negative values in the wall normal direction. [Optional, default value: 0.0]

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

transfers: Transfers section describes the search and mapping operations to be performed between participating realms within a simulation.

Simulations

simulations: This is the top-level section that orchestrates the entire execution of Nalu-Wind.