JuliaSimCompiler API

SymIR

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

IRElement is an algebraic data type that represents an element of the symbolic intermediate representation (IR). It consists the sum types:

• SSAValue(::Int): a value that refers to a single static assignment in the IR.
• Const(x::Any, size::Vector{Int}): a constant value of any type.
• Term(op::GlobalRef, args:::Vector{IRElement}, size::Vector{Int}, foldable::Bool): an expression.

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).\]

• states: 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.

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, size = ())

Create a variable with name name and size size.

c_builtin(::Function, args::Type...)

Given a Julia function and the types of its arguments, return the equivalent function in C or nothing if no such C function exists.

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.

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

Compute the derivative of x with respect to t`.

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.

resize_jl_type(::Type; word_size = 64, float_size = 64)

Given a (numeric) type, convert it to an equivalent type with appropriate size. Integer types are converted to have word_size width. Booleans are returned as-is. Any other subtype of Real is treated as a floating-point value and converted to have float_size width.

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

to_c_type_string(::Type; word_size = 64, float_size = 64)

Given a (numeric) type, convert it to the corresponding type in C. For integer types (signed or unsigned), this is an integer with size word_size. For floating point types, this is a floating with size float_size. Bool is converted to bool. Any other subtype of Real is treated as a floating point value.

toexpr(expr, ::Symbolics.CTarget, states, ps, ps_types; word_size = 64, float_size = 64, build_fn = false)

Given a SymIR expression, construct a C function that calculates its value. states must be floating point values, and ps can be any numeric value with type indicated by the corresponding entry in ps_types. All integer types are converted to word_size-width integers in C. All floating point values are converted to float_size-width floating point values in C. Any functions in the IR that are not C-builtin functions are converted to callable C functions using @cfunction. Returns a string containing the generated C code, and an array of generated @cfunctions. If build_fn is true, instead compiles the C function and returns a Julia wrapper.

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, 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.