Runtime and solvers
Final steps before launching a simulation
Runtime setup
At this stage in the setup workflow, the user defines the runtime information to configure the runtime behaviour of the flow solver, including the time step to use (only meaningful for transient solutions), as well as information about how often to write results to disk. XCALibre.jl provides a the Runtime
to perform this operation.
XCALibre.Solve.Runtime
— TypeRuntime(;
# keyword arguments
iterations::I,
write_interval::I,
time_step::N
) where {I<:Integer,N<:Number} = begin
# returned Runtime struct
Runtime{I<:Integer,F<:AbstractFloat}
(
iterations=iterations,
dt=time_step,
write_interval=write_interval
)
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 use1
.
Example
runtime = Runtime(iterations=2000, time_step=1, write_interval=2000)
Configuration object
Once all the simulation configuration information has been defined, from discretisation scheme to runtime information, all settings must be wrapped in a Configuration
object. The definition, including expected input arguments, for the Configuration
object are detailed below.
XCALibre.Simulate.Configuration
— Type@kwdef struct Configuration{SC,SL,RT,HW}
schemes::SC
solvers::SL
runtime::RT
hardware::HW
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.
Example
config = Configuration(
solvers=solvers, schemes=schemes, runtime=runtime, hardware=hardware, boundaries=BCs)
Initialising fields
The last (optional) step before running the simulation is to provide an initial guess for all the fields being solved. Although this step is optional, in most cases the flow solvers will perform better when initialised. To set an initial value for a field, the initialise!
function is provided, which assigns a starting value to a given field.
XCALibre.Fields.initialise!
— Functionfunction 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 aAbractScalarField
orAbstractVectorField
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 anAbstractVectorField
we can specify asvalue=[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)
Launching flow solvers
In XCALibre.jl the run!
function is used to start a simulation, which will dispatch to the appropriate flow solver for execution. Once the simulation is complete a NamedTuple
containing residual information is returned for users to explore the convergence history of the simulation.
XCALibre.Solvers.run!
— Methodfunction 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 aPhysics
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 fromVTK()
orOpenFOAM()
(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
Restarting simulations
It should be noted that when running a simulation with run!
, the solution fields in the Physics
model are mutated. Thus, running the simulation from the previous solution is simply a matter of reissuing the run!
function. At present, this has the side effect of overwriting any existing solution files (.vtk
or .vtu
). Users must be aware of this behaviour.
In some cases, it may be desirable to solve a problem with a steady solver and use the solution to run transient simulations. This is possible using the change
function.
XCALibre.ModelPhysics.change
— Functionchange(model::Physics, property, value) => updatedModel::Physics
A convenience function to change properties of an exisitng Physics
model.
Input arguments
model::Physics
aPhysics
model to modifyproperty
is a symbol specifying the property to changevalue
is the new setting for the specifiedproperty
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())