High-level docstrings
This section lists the main interfaces for interacting with codes that use Jutul as their foundation.
Setting up models
Jutul.SimulationModel — Type
SimulationModel(domain, system; <kwarg>)Instantiate a model for a given system discretized on the domain.
SimulationModel(g::JutulMesh, system; discretization = nothing, kwarg...)Type that defines a simulation model - everything needed to solve the discrete equations.
The minimal setup requires a JutulMesh that defines topology together with a JutulSystem that imposes physical laws.
Jutul.MultiModel — Type
MultiModel(models)
MultiModel(models, :SomeLabel)A model variant that is made up of many named submodels, each a fully realized SimulationModel.
models should be a NamedTuple or Dict{Symbol, JutulModel}.
Model API
Getters
Jutul.get_secondary_variables — Function
get_secondary_variables(model::SimulationModel)Get the secondary variable definitions (as OrderedDict) for a given model.
Secondary variables are variables that can be computed from the primary variables together with the parameters.
Jutul.get_primary_variables — Function
get_primary_variables(model::SimulationModel)Get the primary variable definitions (as OrderedDict) for a given model.
Primary variables are sometimes referred to as solution variables or primary unknowns. The set of primary variables completely determines the state of the system together with the parameters.
Jutul.get_parameters — Function
get_parameters(model::SimulationModel)Get the parameter definitions (as OrderedDict) for a given model.
Parameters are defined as static values in a forward simulation that combine with the primary variables to compute secondary variables and model equations.
Jutul.get_variables — Function
get_variables(model::SimulationModel)Get all variable definitions (as OrderedDict) for a given model.
This is the union of get_secondary_variables and get_primary_variables.
Setters
Jutul.set_secondary_variables! — Function
set_secondary_variables!(model, varname = vardef)
set_secondary_variables!(model, varname1 = vardef1, varname2 = vardef2)Set a secondary variable with name varname to the definition vardef (adding if it does not exist)
Jutul.set_primary_variables! — Function
set_primary_variables!(model, varname = vardef)
set_primary_variables!(model, varname1 = vardef1, varname2 = vardef2)Set a primary variable with name varname to the definition vardef (adding if it does not exist)
Jutul.set_parameters! — Function
set_parameters!(model, parname = pardef)Set a parameter with name varname to the definition vardef (adding if it does not exist)
Various
Jutul.number_of_degrees_of_freedom — Function
Total number of degrees of freedom for a model, over all primary variables and all entities.
Jutul.number_of_values — Function
Total number of values for a model, for a given type of variables over all entities
Systems and domains
Jutul.JutulSystem — Type
Abstract type for the physical system to be solved.
Jutul.JutulContext — Type
Abstract type for the context Jutul should execute in (matrix formats, memory allocation, etc.)
Jutul.JutulDomain — Type
Abstract type for domains where equations can be defined
Jutul.DataDomain — Type
DataDomain(domain::JutulDomain; property1 = p1, property2 = p2, ...)A wrapper around a domain that allows for storing of entity-associated data.
Example:
# Grid with 6 cells and 7 interior faces
g = CartesianMesh((2, 3))
d = DataDomain(g)
d[:cell_vec] = rand(6) #ok, same as:
d[:cell_vec, Cells()] = rand(6) #ok
d[:cell_vec, Faces()] = rand(6) #not ok!
d[:face_vec, Faces()] = rand(7) #ok!
# Can also add general arrays if last dimension == entity dimension
d[:cell_vec, Cells()] = rand(10, 3, 6) #ok
# Can add general data too, but needs to be specified
d[:not_on_face_or_cell, nothing] = rand(3) # also okJutul.DiscretizedDomain — Type
DiscretizedDomain(domain, disc = nothing)A type for a discretized domain of some other domain or mesh. May contain one or more discretizations as-needed to write equations.
Jutul.JutulDiscretization — Type
Abstract type for a Jutul discretization
Set up of system
Jutul.setup_state — Function
setup_state(model::JutulModel, name1 = value1, name2 = value2)Set up a state for a given model with values for the primary variables defined in the model. Normally all primary variables must be initialized in this way.
Arguments
name=value: The name of the primary variable together with the value(s) used to initialize the primary variable.
A scalar (or short vector of the right size for VectorVariables) will be repeated over the entire domain, while a vector (or matrix for VectorVariables) with length (number of columns for VectorVariables) equal to the entity count (for example, number of cells for a cell variable) will be used directly.
Note: You likely want to overload [setup_state!]@ref for a custom model instead of setup_state
Jutul.setup_parameters — Function
setup_parameters(model::JutulModel; name = value)Set up a parameter storage for a given model with values for the parameter defined in the model.
Arguments
name=value: The name of the parameter together with the value(s) of the parameter.
A scalar (or short vector of the right size for VectorVariables) will be repeated over the entire domain, while a vector (or matrix for VectorVariables) with length (number of columns for VectorVariables) equal to the entity count (for example, number of cells for a cell variable) will be used directly.
Jutul.setup_state_and_parameters — Function
state, prm = setup_state_and_parameters(model, init)Simultaneously set up state and parameters from a single init file (typically a Dict containing values that might either be initial values or parameters)
Jutul.setup_forces — Function
setup_forces(model::JutulModel; force_name = force_value)Set up forces for a given model. Keyword arguments varies depending on what the model supports.
Simulator interfaces
Used to run simulations once a model has been set up.
Jutul.simulate — Function
simulate(state0, model, timesteps, parameters = setup_parameters(model))
simulate(state0, model, timesteps, info_level = 3)
simulate(state0, model, timesteps; <keyword arguments>)Simulate a set of timesteps with model for the given initial state0 and optionally specific parameters. Additional keyword arguments are passed onto simulator_config and simulate!. This interface is primarily for convenience, as all storage for the simulator is allocated upon use and discared upon return. If you want to perform multiple simulations with the same model it is advised to instead instantiate Simulator and combine it with simulate!.
Arguments
state0::Dict: initial state, typically created usingsetup_statefor themodelin use.model::JutulModel: model that describes the discretized system to solve, for exampleSimulationModelorMultiModel.timesteps: Vector of desired report steps. The simulator will perform time integration untilsum(timesteps). You can also provide a single step in place of a vector. is reached, providing outputs at the end of each report step. If aInfvalue is provided as any of the time-steps, the simulator will either perform an infinite step (if no max_timestep is provided) or the simulator will perform timestepping forever until the termination criterion is met. If you passInfand no termination criterion is provided, the simulator will error.parameters=setup_parameters(model): Optional overrides the default parameters for the model.forces=nothing: Eithernothing(for no forces), a single set of forces fromsetup_forces(model)or aVectorof such forces with equal length totimesteps.restart=nothing: If an integer is provided, the simulation will attempt to restart from that step. Requires thatoutput_pathis provided here or in theconfig.config=simulator_config(model): Configuration object that holds many fine grained settings for output, linear solver, time-steps, outputs etc.
Additional arguments are passed onto simulator_config.
See also simulate!, Simulator, SimulationModel, simulator_config.
simulate(state0, sim::JutulSimulator, timesteps; parameters = nothing, kwarg...)Simulate a set of timesteps with simulator for the given initial state0 and optionally specific parameters.
Jutul.simulate! — Function
simulate!(sim::JutulSimulator, timesteps;
forces = nothing,
config = nothing,
initialize = true,
restart = nothing,
state0 = nothing,
parameters = nothing,
kwarg...
)Non-allocating (or perhaps less allocating) version of simulate!.
Arguments
initialize=true: Perform internal updates as if this is the first time
See also simulate for additional supported input arguments.
Jutul.solve_timestep! — Function
solve_timestep!(sim, dT, forces, max_its, config; <keyword arguments>)Internal function for solving a single time-step with fixed driving forces.
Arguments
sim:Simulatorinstance.dT: time-step to be solvedforces: Driving forces for the time-stepmax_its: Maximum number of steps/Newton iterations.config: Configuration for solver (typically output fromsimulator_config).
Note: This function is exported for fine-grained simulation workflows. The general simulate interface is both easier to use and performs additional validation.
Configure a simulator:
Jutul.Simulator — Type
Simulator(model; <kwarg>)Set up a simulator object for a model that can be used by simulate!. To avoid manually instantiating the simulator, the non-mutating simulate interface can be used instead.
Jutul.simulator_config — Function
simulator_config(sim; info_level = 3, linear_solver = GenericKrylov())Set up a simulator configuration object that can be passed onto simulate!.
There are many options available to configure a given simulator. The best way to get an overview of these possible configuration options is to instatiate the config without any arguments and inspecting the resulting table by calling simulator_config(sim) in the REPL.
Jutul.JutulConfig — Type
JutulConfig(name = nothing)
A configuration object that acts like a Dict{Symbol,Any} but contains additional data to limit the valid keys and values to those added by add_option!
Jutul.add_option! — Function
add_option!(opts::JutulConfig, :my_cool_option, 3, "My option has this brief description")Add an option to existing JutulConfig structure. Additional currently undocumented keyword arguments can be used to restrict valid types and values.
The options for the simulator can be set during a call to simulate or simulate! by passing a keyword argument config = ... with a JutulConfig object or by passing keyword arguments directly to simulate or simulate! that will be added to the default configuration. We can see the default options by calling simulator_config on a simulator object and showing it in the REPL:
using Jutul
sys = ScalarTestSystem()
D = ScalarTestDomain()
model = SimulationModel(D, sys)
state0 = setup_state(model, Dict(:XVar=>0.0))
sim = Simulator(model, state0 = state0)
config = simulator_config(sim)Simulator config
┌───────────────────────────┬────────────┬────────────────────────┬──────────┐
│ Option │ Value │ Description │ Values │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ info_level │ 0 │ Info level determines │ Any │
│ [Union{Float64, Int64}] │ │ the amount of runtime │ │
│ │ │ output to the │ │
│ │ │ terminal during │ │
│ │ │ simulation. │ │
│ │ │ │ │
│ │ │ 0 - gives minimal │ │
│ │ │ output (just a │ │
│ │ │ progress bar by │ │
│ │ │ default, and a final │ │
│ │ │ report) │ │
│ │ │ 1 - gives some more │ │
│ │ │ details, printing at │ │
│ │ │ the start of each step │ │
│ │ │ 2 - as 1, but also │ │
│ │ │ printing the current │ │
│ │ │ worst residual at │ │
│ │ │ each iteration │ │
│ │ │ 3 - as 1, but prints │ │
│ │ │ a table of all │ │
│ │ │ non-converged │ │
│ │ │ residuals at each │ │
│ │ │ iteration │ │
│ │ │ 4 - as 3, but all │ │
│ │ │ residuals are printed │ │
│ │ │ (even converged │ │
│ │ │ values) │ │
│ │ │ Negative values │ │
│ │ │ disable output. The │ │
│ │ │ interpretation of │ │
│ │ │ this number is │ │
│ │ │ subject to change. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ debug_level │ 0 │ Define the amount of │ Any │
│ [Int64] │ │ debug output in the │ │
│ │ │ reports. Higher │ │
│ │ │ values means more │ │
│ │ │ output. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ end_report │ true │ Output a final report │ Any │
│ [Union{Nothing, Bool}] │ │ that includes timings │ │
│ │ │ etc. If nothing, │ │
│ │ │ depends on info_level │ │
│ │ │ instead. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ id │ │ String identifier for │ Any │
│ [String] │ │ simulator that is │ │
│ │ │ prefixed to some │ │
│ │ │ verbose output. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ max_timestep_cuts │ 5 │ Max time step cuts in │ 0:10000 │
│ [Int64] │ │ a single mini step │ │
│ │ │ before termination of │ │
│ │ │ simulation. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ max_timestep │ Inf │ Max time step length. │ Any │
│ [Float64] │ │ │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ min_timestep │ 0.0 │ Min time step length. │ Any │
│ [Float64] │ │ │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ termination_criterion │ Jutul.NoT⋯ │ Termination criterion │ Any │
│ [Jutul.AbstractTerminatio │ │ (type instance). See │ │
│ nCriterion] │ │ AbstractTerminationCri │ │
│ │ │ terion for more │ │
│ │ │ details. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ max_nonlinear_iterations │ 15 │ Max number of │ 0:10000 │
│ [Int64] │ │ nonlinear iterations │ │
│ │ │ in a Newton solve │ │
│ │ │ before time-step is │ │
│ │ │ cut. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ min_nonlinear_iterations │ 1 │ Minimum number of │ 0:10000 │
│ [Int64] │ │ nonlinear iterations │ │
│ │ │ in Newton solver. │ │
│ │ │ This number of │ │
│ │ │ Newtion iterations is │ │
│ │ │ always performed, │ │
│ │ │ even if all equations │ │
│ │ │ are converged. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ failure_cuts_timestep │ false │ Cut the timestep if │ Any │
│ [Bool] │ │ exceptions occur │ │
│ │ │ during step. If set │ │
│ │ │ to false, throw │ │
│ │ │ errors and terminate. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ check_before_solve │ true │ Check convergence │ Any │
│ [Bool] │ │ before solving linear │ │
│ │ │ system. Can skip some │ │
│ │ │ linear solves if not │ │
│ │ │ using increment │ │
│ │ │ tolerances. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ always_update_secondary │ false │ Always update │ Any │
│ [Bool] │ │ secondary variables │ │
│ │ │ (even when they can │ │
│ │ │ be reused from end of │ │
│ │ │ previous step). Only │ │
│ │ │ useful for nested │ │
│ │ │ solvers │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ error_on_incomplete │ false │ Throw an error if the │ Any │
│ [Bool] │ │ simulation could not │ │
│ │ │ complete. If `false` │ │
│ │ │ emit a message and │ │
│ │ │ return. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ output_states │ true │ Return states │ Any │
│ [Bool] │ │ in-memory as output. │ │
│ │ │ For larger models │ │
│ │ │ with many time-steps, │ │
│ │ │ using `output_path` │ │
│ │ │ might be better to │ │
│ │ │ avoid filling up your │ │
│ │ │ memory. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ output_reports │ true │ Return reports │ Any │
│ [Bool] │ │ in-memory as output. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ safe_mode │ true │ Add extra checks in │ Any │
│ [Bool] │ │ simulator that have a │ │
│ │ │ small extra cost. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ extra_timing │ false │ Output extra, highly │ Any │
│ [Bool] │ │ detailed performance │ │
│ │ │ report at simulation │ │
│ │ │ end. │ │
│ │ │ This uses │ │
│ │ │ TimerOutputs.jl's │ │
│ │ │ @timeit_debug macro. │ │
│ │ │ You may have to call │ │
│ │ │ the function twice │ │
│ │ │ with this option the │ │
│ │ │ first time you use it. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ ascii_terminal │ false │ Avoid unicode (if │ Any │
│ [Bool] │ │ possible) in terminal │ │
│ │ │ output. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ linear_solver │ nothing │ The linear solver │ Any │
│ [Any] │ │ used to solve │ │
│ │ │ linearized systems. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ timestep_selectors │ TimestepS⋯ │ Time-step selectors │ Any │
│ [Any] │ │ that pick mini steps. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ timestep_max_increase │ 10.0 │ Max allowable factor │ Any │
│ [Float64] │ │ to increase time-step │ │
│ │ │ by. Overrides step │ │
│ │ │ selectors. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ timestep_max_decrease │ 0.1 │ Max allowable factor │ Any │
│ [Float64] │ │ to decrease time-step │ │
│ │ │ by. Overrides step │ │
│ │ │ selectors. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ max_residual │ 1.0e20 │ Maximum value allowed │ Any │
│ [Float64] │ │ for a residual before │ │
│ │ │ simulation is │ │
│ │ │ terminated. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ relaxation │ NoRelaxat⋯ │ Non-Linear relaxation │ Any │
│ [Jutul.NonLinearRelaxatio │ │ used. Currently │ │
│ n] │ │ supports │ │
│ │ │ `NoRelaxation()` and │ │
│ │ │ `SimpleRelaxation()`. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ cutting_criterion │ nothing │ Criterion to use for │ Any │
│ [Any] │ │ early cutting of │ │
│ │ │ time-steps. Default │ │
│ │ │ value of nothing │ │
│ │ │ means cutting when │ │
│ │ │ max_nonlinear_iteratio │ │
│ │ │ ns is reached. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ tolerances │ Dict{Symb⋯ │ Tolerances used for │ Any │
│ [Any] │ │ convergence │ │
│ │ │ criterions. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ tol_factor_final_iteratio │ 1.0 │ Value that multiplies │ Any │
│ n │ │ all tolerances for │ │
│ [Any] │ │ the final convergence │ │
│ │ │ check before a │ │
│ │ │ time-step is cut. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ output_path │ nothing │ Path to write output. │ Any │
│ [Union{Nothing, String}] │ │ If nothing, output is │ │
│ │ │ not written to disk. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ in_memory_reports │ 10 │ Limit for number of │ Any │
│ [Int64] │ │ reports kept in │ │
│ │ │ memory if output_path │ │
│ │ │ is provided. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ report_level │ 0 │ Level of information │ Any │
│ [Int64] │ │ stored in reports │ │
│ │ │ when written to disk. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ output_substates │ false │ Store substates │ Any │
│ [Bool] │ │ (between report │ │
│ │ │ steps) as field on │ │
│ │ │ each state. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ output_function │ missing │ Function on the form │ Any │
│ [Any] │ │ (state, report) -> │ │
│ │ │ state that is run │ │
│ │ │ before output is │ │
│ │ │ written to disk or │ │
│ │ │ returned. This can be │ │
│ │ │ used to remove fields │ │
│ │ │ or add data. Note │ │
│ │ │ that it is easy to │ │
│ │ │ break the restart │ │
│ │ │ functionality if you │ │
│ │ │ modify the state in a │ │
│ │ │ non-compatible way. │ │
│ │ │ Use with care. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ post_ministep_hook │ missing │ Hook to run after │ Any │
│ [Any] │ │ each ministep │ │
│ │ │ (successful or not) │ │
│ │ │ on format (done, │ │
│ │ │ report, sim, dt, │ │
│ │ │ forces, max_iter, │ │
│ │ │ cfg) -> (done, report) │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ post_iteration_hook │ missing │ Hook to run after │ Any │
│ [Any] │ │ each iteration on │ │
│ │ │ format (converged, │ │
│ │ │ report, storage, │ │
│ │ │ model, dt, forces, │ │
│ │ │ cfg, iteration) -> │ │
│ │ │ converged │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ prepare_step │ missing │ Type instance that │ Any │
│ [Any] │ │ get called with │ │
│ │ │ prepare_step before │ │
│ │ │ each Newton iteration. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ progress_color │ green │ Color for progress │ Any │
│ [Symbol] │ │ meter. │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ progress_glyphs │ default │ Glyphs │ Any │
│ [Union{Symbol, │ │ │ │
│ ProgressMeter.BarGlyphs}] │ │ │ │
├───────────────────────────┼────────────┼────────────────────────┼──────────┤
│ table_formatter │ PrettyTab⋯ │ Formatter for tables. │ Any │
│ [Any] │ │ │ │
└───────────────────────────┴────────────┴────────────────────────┴──────────┘
Linear solvers
Jutul.GenericKrylov — Type
GenericKrylov(solver = :gmres; preconditioner = nothing; <kwarg>)Solver that wraps Krylov.jl with support for preconditioning.
Jutul.LUSolver — Type
LUSolver(; reuse_memory = true, check = true, max_size = 50000)Direct solver that calls lu directly. Direct solvers are highly accurate, but are costly in terms of memory usage and execution speed for larger systems.
Preconditioners
Jutul.AMGPreconditioner — Type
AMG on CPU (Julia native)
Jutul.ILUZeroPreconditioner — Type
ILU(0) preconditioner on CPU
Jutul.JacobiPreconditioner — Type
Damped Jacobi preconditioner on CPU
Jutul.SPAI0Preconditioner — Type
Sparse Approximate Inverse preconditioner of lowest order – SPAI(0)
Jutul.LUPreconditioner — Type
Full LU factorization as preconditioner (intended for smaller subsystems)
Jutul.GroupWisePreconditioner — Type
Multi-model preconditioners
Execution contexts
Jutul.DefaultContext — Type
Default context
Jutul.ParallelCSRContext — Type
A context that uses a CSR sparse matrix format together with threads. Experimental.