Apply advection to a model.

BlockDiagonal(blocks)
BlockDiagonal(blocks, ::MapAlgorithm)

Creates a block-diagonal matrix given a vector of the blocks. The blocks must all be the same size and square.

The result of a LU factorization of a block diagonal matrix.

A connector for two systems.

• eqs

• from

• to

The DataType that should be used in the ModelingToolkit System metadata for specifying a system's coupling behavior.

A system for composing together other systems using the couple function.

• systems: Model components to be composed together

• domaininfo: Initial and boundary conditions and other domain information

• pdefunctions: A vector of functions where each function takes as an argument the resulting PDESystem after DomainInfo is added to this system, and returns a transformed PDESystem.

• ops: A vector of operators to run during simulations.

• callbacks: A vector of callbacks to run during simulations.

• init_callbacks: Objects x with an init_callback(x, Simulator)::DECallback method.

Things that can be added to a CoupledSystem:

• ModelingToolkit.Systems. If the System has a field in the metadata called :coupletype (e.g. ModelingToolkit.get_metadata(sys)[:coupletype] returns a struct type with a single field called sys) then that type will be used to check for methods of EarthSciMLBase.couple that use that type.
• Operators
• DomainInfos
• Callbacks
• Types X that implement a EarthSciMLBase.init_callback(::X, ::CoupledSystem, sys_mtk, ::DomainInfo, ::MapAlgorithm)::DECallback method
• Other CoupledSystems
• Types X that implement a EarthSciMLBase.couple2(::X, ::CoupledSystem) or EarthSciMLBase.couple2(::CoupledSystem, ::X) method.
• Tuples or AbstractVectors of any of the things above.

Domain information for a ModelingToolkit.jl PDESystem. It can be used with the + operator to add initial and boundary conditions and coordinate transforms to a ModelingToolkit.jl System or Catalyst.jl ReactionSystem.

NOTE: The independent variable (usually time) must be first in the list of initial and boundary conditions.

• partial_derivative_funcs: Function that returns spatial derivatives of the partially-independent variables, optionally performing a coordinate transformation first.

  Current function options in this package are:

  • partialderivatives_δxyδlonlat: Returns partial derivatives after transforming any variables named lat and lon

  from degrees to cartesian meters, assuming a spherical Earth.

  Other packages may implement additional functions. They are encouraged to use function names starting with partialderivatives_.

• grid_spacing: The discretization intervals for the partial independent variables.

• icbc: The sets of initial and/or boundary conditions.

• spatial_ref: The spatial reference system for the domain.

• tref: The reference time for the domain, relative to which the simulation time period will be calculated.

Initial and boundary condition components that can be combined to create an DomainInfo object.

A type to specify the algorithm used for performing a computation across a range of grid cells.

Perform computations by broadcasting.

Perform computations in parallel using multi-threading.

Operators are objects that modify the current state of a Simulator system. Each operator should be define a function with the signature:

`EarthSciMLBase.get_odefunction(::Operator, csys::CoupledSystem, mtk_sys, coord_args,
    domain::DomainInfo, u0, p, alg::MapAlgorithm)::AbstractSciMLOperator`

which should return a function that can be used as an ODE function, i.e. it should have methods f(u, p, t) and optionally f(du, u, p, t) where u is a state vector, p is parameters, t is time, and du is a cache for the result of the function. For more information, see here.

Operators should also define a function with the signature:

`EarthSciMLBase.get_needed_vars(op::Operator, csys, mtk_sys, domain::DomainInfo)`

which should return a list of variables that are needed by the operator.

A solver strategy based on implicit-explicit (IMEX) time integration. See here for additional information.

kwargs:

• stiff_sparse: Whether the stiff ODE function should use a sparse Jacobian.
• stiff_tgrad: Whether the stiff ODE function should use an analytical time gradient.

Additional kwargs for ODEProblem constructor:

• u0: initial conditions; if "nothing", default values will be used.
• p: parameters; if "nothing", default values will be used.
• name: name of the model.

A simulator strategy based on Strang splitting. Choose either SimulatorStrangThreads or SimulatorStrangSerial to run the simulation.

kwargs for ODEProblem constructor:

• u0: initial conditions; if "nothing", default values will be used.
• p: parameters; if "nothing", default values will be used.
• nonstiff_params: parameters for the non-stiff ODE system.
• name: name of the system.

# Specify the stiff ODE solver algorithm.
# `timestep` is the length of time for each splitting step.
SimulatorStrangSerial(stiffalg, timestep; stiff_kwargs...)

Perform a simulation using Strang splitting, where the MTK system is assumed to be stiff and the operators are assumed to be non-stiff. The solution will be calculated in serial.

Additional kwargs for ODEProblem constructor:

• u0: initial conditions; if "nothing", default values will be used.
• p: parameters; if "nothing", default values will be used.

• stiffalg: Stiff solver algorithm to use (see https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)

• timestep: Length of each splitting time step

• stiff_kwargs: Keyword arguments for the stiff ODEProblem constructor and solver.

• alg: Algorithm for performing gridded computations.

WARNING: Is is not possible to change the parameters using this strategy.

# Specify the number of threads and the stiff ODE solver algorithm.
# `timestep` is the length of time for each splitting step.
SimulatorStrangThreads(threads, stiffalg, timestep; stiff_kwargs...)
# Use the default number of threads.
SimulatorStrangThreads(stiffalg, timestep; stiff_kwargs...)

Perform a simulation using Strang splitting, where the MTK system is assumed to be stiff and the operators are assumed to be non-stiff. The solution of the stiff ODE system is parallelized across grid cells using the specified number of threads.

• threads: Number of threads to use

• stiffalg: Stiff solver algorithm to use (see https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)

• timestep: Length of each splitting time step

• stiff_kwargs: Keyword arguments for the stiff ODEProblem constructor and solver.

• alg: Algorithm for performing gridded computations.

SolverStrategy is an abstract type that defines the strategy for running a simulation.

The DataType that should be used in the ModelingToolkit System metadata for specifying a discrete system event.

Construct constant boundary conditions equal to the value specified by val.

• val: The value of the constant boundary conditions.

• partialdomains: The partial domains, e.g. [x ∈ Interval(x_min, x_max), y ∈ Interval(y_min, y_max)].

Construct constant initial conditions equal to the value specified by val.

• val: The value of the constant initial conditions.

• indepdomain: The independent domain, e.g. t ∈ Interval(t_min, t_max).

Construct periodic boundary conditions for the given partialdomains. Periodic boundary conditions are defined as when the value at one side of the domain is set equal to the value at the other side, so that the domain "wraps around" from one side to the other.

• partialdomains: The partial domains, e.g. [x ∈ Interval(x_min, x_max), y ∈ Interval(y_min, y_max)].

Construct zero-gradient boundary conditions for the given partialdomains.

• partialdomains: The partial domains, e.g. [x ∈ Interval(x_min, x_max), y ∈ Interval(y_min, y_max)].

convert(, sys; name, kwargs...)

Get the ModelingToolkit PDESystem representation of a CoupledSystem.

convert(, sys; name, compile, prune, extra_vars, kwargs...)

Get the ODE ModelingToolkit System representation of a CoupledSystem.

kwargs:

• name: The desired name for the resulting System
• compile: Whether to run mtkcompile on the resulting System
• prune: Whether to prune the extra observed equations to improve performance

Return values:

• The ModelingToolkit System representation of the CoupledSystem

eltype(_::DomainInfo{ET}) -> Any

Return the scalar data type of the state variable elements for this domain.

ConstantWind(t, vals; name)

Construct a constant wind velocity model component with the given wind speed(s), which should include units. For example, ConstantWind(t, 1u"m/s", 2u"m/s").

MeanWind(t, domain)

A model component that represents the mean wind velocity, where pvars are the partial dependent variables for the domain.

add_dims(expression, vars, dims)
add_dims(equation, vars, dims)

Add the given dimensions to each variable in vars in the given expression or equation. Each variable in vars must be unidimensional, i.e. defined like @variables u(t) rather than @variables u(..).

Example:

using EarthSciMLBase, ModelingToolkit

@parameters x y k t
@variables u(t) q(t)
exp = 2u + 3k * q + 1
EarthSciMLBase.add_dims(exp, [u, q], [x, y, t])

# output

1 + 2u(x, y, t) + 3k*q(x, y, t)

Add the units and description in the variable from to the variable to.

add_scope(sys, v, iv)

Add a system scope to a variable name, for example so that x in system sys1 becomes sys1₊x. iv is the independent variable.

arraytype(_::DomainInfo{ET, AT}) -> Any

Return the data type of the state variable array for this domain.

Create a function to return the observed function for a system with coordinates. For more information see the documentation for ModelingToolkit.build_explicit_observed_function.

copy_with_change(
    sys;
    eqs,
    name,
    unknowns,
    parameters,
    metadata,
    continuous_events,
    discrete_events,
    defaults
)

Create a copy of an System with the given changes.

couple(systems...) -> CoupledSystem

Couple multiple ModelingToolkit systems together.

The systems that are arguments to this system can be of type ModelingToolkit.AbstractSystem, CoupledSystem, DomainInfo, or any type T that has a method couple(::CoupledSystem, ::T)::CoupledSystem or a method couple(::T, ::CoupledSystem)::CoupledSystem defined for it.

couple2()

Perform bi-directional coupling for two equation systems.

To specify couplings for system pairs, create methods for this function with the signature:

EarthSciMLBase.couple2(a::ACoupler, b::BCoupler)::ConnectorSystem

where ACoupler and BCoupler are :coupletypes defined like this:

struct ACoupler
    sys
end
@named asys = System([], t, metadata = Dict(:coupletype=>ACoupler))

dims(
    icbc::EarthSciMLBase.ICcomponent
) -> Vector{Symbolics.Num}

Returns the dimensions of the independent and partial domains associated with these initial or boundary conditions.

domains(icbc::EarthSciMLBase.ICcomponent) -> Vector

Returns the domains associated with these initial or boundary conditions.

endpoints(d)

Return the endpoints of the partial independent variables for this domain.

Return the coupling type associated with the given system.

Return the dependent variable, which is the first argument of the term, unless the term is a time derivative, in which case the dependent variable is the argument of the time derivative.

get_needed_vars(original_sys, simplified_sys)
get_needed_vars(original_sys, simplified_sys, extra_vars)

Return the system variables that the state variables of the final simplified system depend on. This should be done before running mtkcompile on the system. extra_vars is a list of additional variables that need to be kept.

Returns the sys_discrete_event function associated with the given system, which is meant to be a function that takes the fully coupled ModelingToolkit System and returns a discrete event that should be applied to it.

get_tref(d::DomainInfo) -> Any

Return the reference time for this simulation.

get_tspan(
    d::DomainInfo{T<:AbstractFloat}
) -> Tuple{Any, Any}

Return the time range associated with this domain, returning the values as Unix times relative to the reference time tref.

get_tspan_datetime(d)

Return the time range associated with this domain, returning the values as DateTimes.

Create a graph from a CoupledSystem using the MetaGraphsNext package.

grid(d)

Return the ranges representing the discretization of the partial independent variables for this domain, based on the discretization intervals given in Δs.

icbc(di, states)

Return a vector of equations that define the initial and boundary conditions for the given state variables.

Types that implement an:

init_callback(x, sys::CoupledSystem, sys_mtk, coord_args, domain::DomainInfo, alg::MapAlgorithm)::DECallback

method can also be coupled into a CoupledSystem. The init_callback function will be run before the simulator is run to get the callback.

Initialize the state variables.

ivar(di::DomainInfo) -> Any

Return the independent variable associated with these initial and boundary conditions.

observed_expression(eqs, x)

Return an expression for the observed value of a variable x after substituting in the constants observed values of other variables. extra_eqs is a list of additional equations to use in the substitution.

observed_function(eqs, x, coords)

Return a function to for the observed value of a variable x based on the input arguments in coords. extra_eqs is a list of additional equations to use to determine the value of x.

Take a step using the ODE solver.

operator_compose(a, b)
operator_compose(a, b, translate)

Compose to systems of equations together by adding the right-hand side terms together of equations that have matching left-hand sides. The left hand sides of two equations will be considered matching if:

1. They are both time derivatives of the same variable.
2. The first one is a time derivative of a variable and the second one is the variable itself.
3. There is an entry in the optional translate dictionary that maps the dependent variable in the first system to the dependent variable in the second system, e.g. Dict(sys1.sys.x => sys2.sys.y).
4. There is an entry in the optional translate dictionary that maps the dependent variable in the first system to the dependent variable in the second system, with a conversion factor, e.g. Dict(sys1.sys.x => sys2.sys.y => 6).

Replace the parameter p in the system sys with a new variable that has the same name, units, and description as p.

param_to_var(sys, ps)

This can be useful to replace a parameter that does not change in time in a model component with one specified by another system that does change in time (or space). For example, the code below specifies a first-order loss equation, and then changes the temperature (which determines the loss rate) with a temperature value that varies in time.

partialderivative_transforms(
    mtk_sys::ModelingToolkitBase.System,
    di::DomainInfo
) -> Vector{Any}

Return transform factor to multiply each partial derivative operator by, for example to convert from degrees to meters.

partialderivatives(di::DomainInfo) -> Any

Return the partial derivative operators for the given domain.

partialderivatives_δxyδlonlat(pvars; default_lat)

Return partial derivative operator transform factors corresponding for the given partial-independent variables after converting variables named lon and lat from degrees to x and y meters, assuming they represent longitude and latitude on a spherical Earth.

prune_observed(original_sys, simplified_sys, extra_vars)

Remove equations from an System where the variable in the LHS is not present in any of the equations for the state variables. This can be used to remove computationally intensive equations that are not used in the final model.

pvars(di::DomainInfo) -> Any

Return the partial independent variables associated with these initial and boundary conditions.

Take a step using the ODE solver with the given IIchunk (grid cell iterator) and integrator.

steplength(timesteps)

Return the time step length common to all of the given timesteps. Throw an error if not all timesteps are the same length.

A callback to periodically run the stiff solver.

Take a step using the ODE solver.

timesteps(tsteps)

Return the time points during which integration should be stopped to run the operators.

Convert the floating point parameters in sys to the element type of u.

This is only needed until https://github.com/SciML/ModelingToolkit.jl/issues/3709 is resolved.