API Index
EarthSciMLBase.coupling_registry
EarthSciMLBase.Advection
EarthSciMLBase.ConnectorSystem
EarthSciMLBase.CoupledSystem
EarthSciMLBase.DomainInfo
EarthSciMLBase.ICBCcomponent
EarthSciMLBase.Operator
EarthSciMLBase.Simulator
EarthSciMLBase.constBC
EarthSciMLBase.constIC
EarthSciMLBase.periodicBC
EarthSciMLBase.zerogradBC
EarthSciMLBase.ConstantWind
EarthSciMLBase.MeanWind
EarthSciMLBase.add_dims
EarthSciMLBase.add_metadata
EarthSciMLBase.add_scope
EarthSciMLBase.couple
EarthSciMLBase.dims
EarthSciMLBase.domains
EarthSciMLBase.get_dv
EarthSciMLBase.get_mtk
EarthSciMLBase.get_mtk_ode
EarthSciMLBase.graph
EarthSciMLBase.grid
EarthSciMLBase.icbc
EarthSciMLBase.init_u!
EarthSciMLBase.ivar
EarthSciMLBase.observed_expression
EarthSciMLBase.observed_function
EarthSciMLBase.ode_step!
EarthSciMLBase.operator_compose
EarthSciMLBase.operator_step!
EarthSciMLBase.param_to_var
EarthSciMLBase.partialderivative_transforms
EarthSciMLBase.partialderivatives
EarthSciMLBase.partialderivatives_δxyδlonlat
EarthSciMLBase.pvars
EarthSciMLBase.register_coupling
EarthSciMLBase.run!
EarthSciMLBase.single_ode_step!
EarthSciMLBase.steplength
EarthSciMLBase.strang_step!
EarthSciMLBase.systemhash
EarthSciMLBase.time_range
EarthSciMLBase.timesteps
EarthSciMLBase.utype
API Documentation
EarthSciMLBase.coupling_registry
— ConstantA registery for functions to couple systems together, defined by their system hashes.
EarthSciMLBase.Advection
— TypeApply advection to a model.
EarthSciMLBase.ConnectorSystem
— TypeA connector for two systems.
eqs
from
to
EarthSciMLBase.CoupledSystem
— TypeA system for composing together other systems using the couple
function.
systems
: Model components to be composed togetherdomaininfo
: Initial and boundary conditions and other domain informationpdefunctions
: 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.
EarthSciMLBase.DomainInfo
— TypeDomain 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 ODESystem 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 namedlat
andlon
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_
.
icbc
: The sets of initial and/or boundary conditions.
EarthSciMLBase.ICBCcomponent
— TypeInitial and boundary condition components that can be combined to create an DomainInfo object.
EarthSciMLBase.Operator
— TypeOperators are objects that modify the current state of a Simulator
system. Each operator should be define a run
function with the signature:
`EarthSciMLBase.run!(op::Operator, s::Simulator, time)`
which modifies the s.du
field in place. It should also implement:
`EarthSciMLBase.timestep(op::Operator)`
which returns the timestep length for the operator.
The Operator may also optionally implement the initialize! and finalize! methods, which will be run before the simulation starts and after it ends, respectively, if they are defined.
`EarthSciMLBase.initialize!(op::Operator, s::Simulator)`
`EarthSciMLBase.finalize!(op::Operator, s::Simulator)`
EarthSciMLBase.Simulator
— TypeSpecify a simulator for large-scale model runs. Δs
represent the grid cell spacing in each dimension; for example Δs = [0.1, 0.1, 1]
would represent a grid with 0.1 spacing in the first two dimensions and 1 in the third, in whatever units the grid is natively in. The grid spacings should be given in the same order as the partial independent variables are in the provided DomainInfo
. algorithm
should be a DifferentialEquations.jl ODE solver. kwargs
are passed on to the DifferentialEquations.jl integrator initialization.
sys::CoupledSystem
: The system to be integratedsys_mtk::ModelingToolkit.ODESystem
: The ModelingToolkit version of the systemdomaininfo::DomainInfo
: Information about the spatiotemporal simulation domainu::Array{T, 4} where T
: The system statedu::Array{T, 4} where T
: The system state derivativep::Vector
: The system parameter valuesu_init::Vector
: The initial values of the system state variablespvidx::Vector{Int64}
: The indexes of the partial independent variables in the system parameter value vectorgrid::Any
: The discretized values of the partial independent variablesobs_fs::Any
: Functions to get the current values of the observed variables with input arguments of time and the partial independent variablesobs_fs_idx::Dict{Symbolics.Num, Int64}
: Indexes for the obs_fs functionstf_fs::Any
: Functions to get the current values of the coordinate transforms with input arguments of time and the partial independent variablesintegrators::Vector
: Internal integratorsIIchunks::Vector{SubArray{CartesianIndex{3}, 1, Base.ReshapedArray{CartesianIndex{3}, 1, CartesianIndices{3, Tuple{Base.OneTo{Int64}, Base.OneTo{Int64}, Base.OneTo{Int64}}}, Tuple{Base.MultiplicativeInverses.SignedMultiplicativeInverse{Int64}, Base.MultiplicativeInverses.SignedMultiplicativeInverse{Int64}}}, Tuple{UnitRange{Int64}}, false}}
: Internal chunks of grid cells for each integrator
EarthSciMLBase.constBC
— TypeConstruct 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)]
.
EarthSciMLBase.constIC
— TypeConstruct 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)
.
EarthSciMLBase.periodicBC
— TypeConstruct 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)]
.
EarthSciMLBase.zerogradBC
— TypeConstruct 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)]
.
EarthSciMLBase.ConstantWind
— MethodConstantWind(t, vals)
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")
.
EarthSciMLBase.MeanWind
— MethodMeanWind(t, domain)
A model component that represents the mean wind velocity, where pvars
is the partial dependent variables for the domain.
EarthSciMLBase.add_dims
— Methodadd_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)
EarthSciMLBase.add_metadata
— MethodAdd the units and description in the variable from
to the variable to
.
EarthSciMLBase.add_scope
— Methodadd_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.
EarthSciMLBase.couple
— Methodcouple(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.
EarthSciMLBase.dims
— Methoddims(
icbc::EarthSciMLBase.ICcomponent
) -> Vector{Symbolics.Num}
Returns the dimensions of the independent and partial domains associated with these initial or boundary conditions.
EarthSciMLBase.domains
— Methoddomains(icbc::EarthSciMLBase.ICcomponent) -> Vector
Returns the domains associated with these initial or boundary conditions.
EarthSciMLBase.get_dv
— MethodReturn 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.
EarthSciMLBase.get_mtk
— Methodget_mtk(sys; name)
Get the ModelingToolkit representation of a CoupledSystem
.
EarthSciMLBase.get_mtk_ode
— Methodget_mtk_ode(sys; name)
Get the ODE ModelingToolkit representation of a CoupledSystem
.
EarthSciMLBase.graph
— MethodCreate a graph from a CoupledSystem using the MetaGraphsNext package.
EarthSciMLBase.grid
— Methodgrid(d, Δs)
Return the ranges representing the discretization of the partial independent variables for this domain, based on the discretization intervals given in Δs
EarthSciMLBase.icbc
— Methodicbc(di, states)
Return a vector of equations that define the initial and boundary conditions for the given state variables.
EarthSciMLBase.init_u!
— MethodInitialize the state variables.
EarthSciMLBase.ivar
— Methodivar(di::DomainInfo) -> Any
Return the independent variable associated with these initial and boundary conditions.
EarthSciMLBase.observed_expression
— Methodobserved_expression(sys, x; extra_eqs)
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.
EarthSciMLBase.observed_function
— Methodobserved_function(sys, x, coords; extra_eqs)
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
.
EarthSciMLBase.ode_step!
— MethodTake a step using the ODE solver.
EarthSciMLBase.operator_compose
— Functionoperator_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:
- They are both time derivatives of the same variable.
- The first one is a time derivative of a variable and the second one is the variable itself.
- 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)
. - 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)
.
EarthSciMLBase.operator_step!
— MethodTake a step using the operator functions.
EarthSciMLBase.param_to_var
— MethodReplace 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. ```
EarthSciMLBase.partialderivative_transforms
— Methodpartialderivative_transforms(di::DomainInfo) -> Vector{Any}
Return transform factor to multiply each partial derivative operator by, for example to convert from degrees to meters.
EarthSciMLBase.partialderivatives
— Methodpartialderivatives(di::DomainInfo) -> Any
Return the partial derivative operators for the given domain.
EarthSciMLBase.partialderivatives_δxyδlonlat
— Methodpartialderivatives_δ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.
EarthSciMLBase.pvars
— Methodpvars(di::DomainInfo) -> Any
Return the partial independent variables associated with these initial and boundary conditions.
EarthSciMLBase.register_coupling
— Methodregister_coupling(f, a, b)
Register a coupling function for two systems.
In the get_mtk
method of CoupledSystem
, the function f
is called to make any edits needed to the two systems before they are composed together, and also to return a ConnectorSystem
that represents the coupling of the two systems.
The function f
should take as two ODESystem
s and return a ConnectorSystem
, i.e. f(a::ODESystem, b::ODESystem)::ConnectorSystem
.
EarthSciMLBase.run!
— Methodrun!(s::Simulator{T, IT, FT, FT2, TG})
Run the simulation
EarthSciMLBase.single_ode_step!
— MethodTake a step using the ODE solver in the thread specified by ithread
.
EarthSciMLBase.steplength
— Methodsteplength(timesteps)
Return the time step length common to all of the given timesteps
. Throw an error if not all timesteps are the same length.
EarthSciMLBase.strang_step!
— MethodTake a step using Strang splitting, first with the ODE solver, then with the operators.
EarthSciMLBase.systemhash
— MethodReturn a unique identifier for a system.
EarthSciMLBase.time_range
— Methodtime_range(d)
Return the time range associated with this domain.
EarthSciMLBase.timesteps
— Methodtimesteps(tsteps)
Return the time points during which integration should be stopped to run the operators.
EarthSciMLBase.utype
— Methodutype(_)
Return the data type of the state variables for this domain, based on the data types of the boundary conditions domain intervals.