Runtime and solvers

Runtime(; 
        # keyword arguments

        iterations::I, 
        write_interval::I, 
        time_step::N,
        adaptive::A
    ) where {I<:Integer,N<:Number} = begin
    
    # returned Runtime struct
    Runtime{I<:Integer,F<:AbstractFloat}
        (
            iterations=iterations, 
            dt=time_step, 
            write_interval=write_interval,
            adaptive=adaptive
        )
end

This is a convenience function to set the top-level runtime information. The inputs are all keyword arguments and provide basic information to flow solvers just before running a simulation.

Input arguments

• iterations::Integer: specifies the number of iterations in a simulation run.
• write_interval::Integer: defines how often simulation results are written to file (on the current working directory). The interval is currently based on number of iterations. Set to -1 to run without writing results to file.
• time_step::AbstractFloat: the time step to use in the simulation. Notice that for steady solvers this is simply a counter and it is recommended to simply use 1.
• adaptive::Union{Nothing, AdaptiveTimeStepping}: optionally enables adaptive time stepping. Pass an AdaptiveTimeStepping object to automatically adjust dt based on the Courant number during transient simulations. Defaults to nothing, meaning a fixed time step is used.

Example

runtime = Runtime(iterations=2000, time_step=1, write_interval=2000)

struct Configuration{SC,SL,RT,HW,PP}
    schemes::SC
    solvers::SL
    runtime::RT
    hardware::HW
    postprocess::PP
end

The Configuration type is passed to all flow solvers and provides all the relevant information to run a simulation.

Inputs

• schemes::NamedTuple this keyword argument is used to pass distretisation scheme information to flow solvers. See Numerical setup for details.
• solvers::NamedTuple this keyword argument is used to pass the configurations for the linear solvers for each field information to flow solvers. See Runtime and solvers for details.
• runtime::NamedTuple this keyword argument is used to pass runtime information to the flow solvers. See Runtime and solvers for details.
• hardware::NamedTuple this keyword argument is used to pass the hardware configuration and backend settings to the flow solvers. See Pre-processing for details.

Optional keywords

• postprocess this keyword argument is used to pass any fields that need to be post-processed. See Post-processing for details.

Example

config = Configuration(
    solvers=solvers, schemes=schemes, runtime=runtime, hardware=hardware, boundaries=BCs)

function initialise!(field, value) # dummy function for documentation
    # Assign `value` to field in-place
    nothing
end

This function will set the given field to the value provided in-place. Useful for initialising fields prior to running a simulation.

Input arguments

• field specifies the field to be initialised. The field must be either a AbractScalarField or AbstractVectorField
• value defines the value to be set. This should be a scalar or vector (3 components) depending on the field to be modified e.g. for an AbstractVectorField we can specify as value=[10,0,0]

Note: in most cases the fields to be modified are stored within a physics model i.e. a Physics object. Thus, the argument value must fully qualify the model. For example, if we have created a Physics model named mymodel to set the velocity field, U, we would set the argument field to mymodel.momentum.U. See the example below.

Example

initialise!(mymodel.momentum.U, [2.5, 0, 0])
initialise!(mymodel.momentum.p, 1.25)

initialise! also accepts a functions arguments and initialises a field by evaluating the function at each cell centre. The function should have the signature f(x, y, z) and it must return either a scalar or an SVector type (requirement to work on GPUs)

potential_flow!(model, config; ncorrectors=0, pref=nothing, time=0)

Project the current velocity field onto a divergence-free potential-flow field. Velocity boundary conditions supply the initial face flux. Velocity-potential boundary conditions are inferred from pressure: fixed pressure becomes fixed zero potential, periodic patches remain periodic, and other patches use zero normal gradient.

The corrected face-volume flux is returned with the linear-solver residual.

function run!(
    model::Physics, config; 
    output=VTK(), pref=nothing, ncorrectors=0, inner_loops=0
    )

    # here an internal function is used for solver dispatch
    return residuals
end

This is the top level API function to initiate a simulation. It uses the user-provided model defined as a Physics object to dispatch to the appropriate solver.

Dispatched flow solvers

• Steady incompressible (SIMPLE algorithm for coupling)
• Transient incompressible (PISO algorithm for coupling)
• Steady weakly compressible (SIMPLE algorithm for coupling)
• Transient weakly compressible (PISO algorithm for coupling)

Input arguments

• model reference to a Physics model defined by the user.
• config Configuration structure defined by the user with solvers, schemes, runtime and hardware structures configuration details.
• output select the format used for simulation results from VTK() or OpenFOAM() (default = VTK())
• pref Reference pressure value for cases that do not have a pressure defining BC. Incompressible solvers only (default = nothing)
• ncorrectors number of non-orthogonality correction loops (default = 0)
• inner_loops number to inner loops used in transient solver based on PISO algorithm (default = 0)

Output

This function returns a NamedTuple for accessing the residuals (e.g. residuals.Ux). The fields available within the returned residuals tuple depend on the solver used. For example, for an incompressible solver, a x-momentum equation residual can be retrieved accessing the Ux field i.e. residuals.Ux. Look at reference guide for each dispatch method to find out which fields are available.

Example

residuals = run!(model, config) 

# to access the pressure residual

residuals.p 

change(model::Physics, property, value) => updatedModel::Physics

A convenience function to change properties of an exisitng Physics model.

Input arguments

• model::Physics a Physics model to modify
• property is a symbol specifying the property to change
• value is the new setting for the specified property

Output

This function return a new Physics object

Example

To change a model to run a transient simulation e.g. after converging in steady state

modelTransient = change(model, :time, Transient())