JuliaSimCompiler API

SymIR

A union of SymNum and SymArr. Use SymIR for manipulations.

struct IRState <: TransformationState{IRSystem}

An efficient data structure for structural_simplify.

Fields

• sys: The system to be transformed.

• vars: A full list of symbolic variables in the system.

• vs: bindings(sys.ir)[vs[i]] == vars[i] for all valid i::Int.

• ps: bindings(sys.ir)[ps[i]] is the i-th parameter for all valid i::Int.

• es: bindings(sys.ir)[es[i]] is the i-th equation of the system.

• incidence: incidence[i] is the incidence of the i-th equation of the system.

• par_graph: The par_graph is the bipartite graph of the equation-parameter system.

• structure: Structural information.

• info: Metadata of the system.

• classes

See also: IRSystem.

IRState(sys::IRSystem) -> IRState

Construct an IRState from an IRSystem.

struct IRSystem <: ModelingToolkit.AbstractODESystem

A system of differential-algebraic equations.

Fields

• ir: The IR that defines the system

  \[0 = F(u^{(n)}, ..., u', u, p, t).\]

• unknowns: The symbolic representation of the aforementioned u vector.

• ps: The symbolic representation of the aforementioned p vector.

• t: The symbolic representation of the aforementioned t scalar.

• info: System metadata.

• events

See also: IRSystem and ODESystem.

struct SymArr{N} <: AbstractArray{Real, N}

A symbolic IR type that represents an array. A collapsed representation of the IR is printed by default to save screen space. Use show(ir) to print the full list.

Fields

• bindings: A list of IRElements where SSAValue(x::Int) refers to the xth entry of bindings.

See also: IRElement, collapse, SymNum, and SymIR.

struct SymNum <: Real

A symbolic IR type that represents a scalar. A collapsed representation of the IR is printed by default to save screen space. Use show(ir) to print the full list.

Fields

• bindings: A list of IRElements where SSAValue(x::Int) refers to the xth entry of bindings.

See also: IRElement, collapse, SymArr, and SymIR.

Dt(name::Symbol, n)

Create a differentiated variable of order n. If n is not specified, it is 1. The third argument of Dt in printing states its "dummy"-ness. A dummy variable is a variable that appears to be differentiated in a differential-algebraic equation (DAE) system, but is not actually differentiated with respect to the structurally transformed DAE system.

Par(name::Symbol, size = ())

Create a parameter with name name and size size.

Var(name::Symbol, clock = nothing, size = ())

Create a variable with name name and size size.

previous = current for all fields in the runtime state

collapse(x::SymIR) -> SymIR

For debugging and pretty printing purposes only. The collapsed IR isn't valid for most transformations. Contract away all SSA values that are used only once and inline all constants.

Compute maps from state and partition indices to indices of child partitions

derivative(x::SymIR, t::Union{SymIR, IRElement}) -> SymIR

Compute the derivative of x with respect to t`.

sol = execute_statemachine(sm, parammap, N; dt = 1, verbose = false, save_rts = false)

Testing utility: Execute the statemachine sm for N steps with a time step of dt.

Arguments:

• sm: State machine obtained from JuliaSimCompiler.build_state_hierarchy(model)
• parammap: A parameter map with initial conditions and parameters.
• N: Number of steps to execute.
• dt: The time step.
• verbose: Verbose printing for debugging purposes
• save_rts: Save the runtime state at each time step (tihs is expensive but useful for debugging)

Returns:

A StateMachineSolution object with the following fields:

• X: A matrix nx × (N+1) of state values at each time step, starting with the initial condition.
• state_activity: A matrix of size nstates × N with a boolean indicating if the state was active at each time step.
• state_names: A vector of state names.
• runtime_states: (Only if save_rts = true) A vector containing the runtime state at each time step.

handle_clocks(ir_sys)

Run clock inference and generate discrete callbacks for each discrete-time partition.

Arguments

• ir_sys: The input system to handle clocks for.

Returns

• sss: Structurally simplified continuous-time system stripped of any discrete-time equations (these are handled by the callbacks).
• defaults: The default values.
• inits: Initialization function for discrete-time partitions.
• cbs: A callback or a CallbackSet for discrete-time partitions.

jacobian(x::SymIR, args::Union{Vector{SymIR}, Vector{IRElement}}) -> SymIR

Compute the Jacobian of x with respect to args. toexpr(jacobian(x, args), args) returns the expression of an inplace function that fills the elements of the Jacobian matrix in the first argument.

Example

using JuliaSimCompiler
const IR = JuliaSimCompiler
foo((x, y, z)) = [x^2 + y - z
                  sin(y * z) / x
                  hypot(x, y)]
x, y, z = Var.((:x, :y, :z))
args = [x, y, z]
J = IR.optimize(IR.jacobian(set_array(foo(args)), args))
J_ir! = eval(IR.toexpr(J, args; check = false))
num_args = [1, 2, 3]
J_ir = zeros(3, 3)
J_ir!(J_ir, num_args)

See also: set_array and toexpr

Ends the preceding loop.

loopstart(niter::Int)

Marks the start of a loop with niter iterations. Currently, only loops with a compile-time known number of iterations are supported.

make_array(xs::AbstractArray{<:SymNum, N}) where {N} -> SymArr

Construct a SymArr from an array of SymNums.

optimize(ir::SymIR; maxiters = 10) -> SymIR

Optimize the IR by peephole optimization, copy propagation, and global value numbering. It runs these passes until the number of statements no longer changes or when maxiters is reached.

peephole_opt!(x::SymIR) -> SymIR

Perfrom peephole optimization for SymIR in-place.

set_array(xs::AbstractArray{<:SymIR, N}, idxss::AbstractArray{<:Any, N} = CartesianIndices(xs)) where {N} -> SymIR

Construct a SymIR that sematically performs in-place operations to fill xs to an array at idxss indices.

substitute(expr::SymIR, rules; fold = true, normalize = true) -> Union{SymIR, Number}

Substitute the variables in expr according to the rules in rules. If fold is true, then the resulting expression will be folded as much as possible. If normalize is true, then the rules will be normalized before substitution. Normalization of rules is required when rules is not an instance of Dict{IRElement, Any}.

Examples

julia> using JuliaSimCompiler

julia> x = JuliaSimCompiler.Var(:x)
%1 = x

julia> JuliaSimCompiler.substitute(sin(cos(x)), [x => 1.0])
0.5143952585235492

toexpr(expr::SymIR, args...; check = true)

Convert a SymIR to a Julia expression. The args are the symbolic arguments of the expression. If check is true, the function will check perform axes checks before annotating the rest of the function body with @inbounds. If check is false, no axes checks will be performed, and no @inbounds annotation will be added. Hence, toexpr always generates safe code. One can use set_array to generate inplace code.

See also: set_array and jacobian.

structural_simplify(s::Union{IRState, IRState}; alias_eliminate = true, tearing = true, fully_determined = true, debug = false) -> ScheduledSystem

Structurally simply an IRSystem or IRState by running alias elimination, index reduction, dummy derivative, and tearing passes. The alias_eliminate and tearing keyword arguments control whether these transformation passes are performed. Note that index reduction and dummy derivative passes are always enabled to return a valid system. The debug keyword argument controls verbose printing for debugging.

The returned ScheduledSystem should behave like an ODESystem from ModelingToolkit. It can be used to generate an ODEFunction or ODEProblem.