GitHub

Simple Equations

This tutorial shows how to use Decapodes to represent simple equations. These aren't using any of the Discrete Exterior Calculus or CombinatorialSpaces features of Decapodes. They just are a reference for how to build equations with the @decapodes macro and see how they are stored as ACSets.

using Catlab
using CombinatorialSpaces
using DiagrammaticEquations
using Decapodes

The harmonic oscillator can be written in Decapodes in at least three different ways.

oscillator = @decapode begin
  X::Form0
  V::Form0

  ∂ₜ(X) == V
  ∂ₜ(V) == -k(X)
end
DiagrammaticEquations.decapodeacset.SummationDecapode{Any, Any, Symbol} {Var:4, TVar:2, Op1:4, Op2:0, Σ:0, Summand:0, Type:0, Operator:0, Name:0}
Var type name
1 Form0 X
2 Form0 V
3 infer •1
4 infer V̇
TVar incl
1 2
2 4
Op1 src tgt op1
1 1 2 ∂ₜ
2 2 4 ∂ₜ
3 1 3 k
4 3 4 -

The default representation is a tabular output as an ACSet. The tables are Var for storing variables (X) and their types (Form0). TVar for identifying a subset of variables that are the tangent variables of the dynamics (Ẋ). The unary operators are stored in Op1 and binary operators stored in Op2. If a table is empty, it doesn't get printed.

Even though a diagrammatic equation is like a graph, there are no edge tables, because the arity (number of inputs) and coarity (number of outputs) is baked into the operator definitions.

You can also see the output as a directed graph. The input arrows point to the state variables of the system and the output variables point from the tangent variables. You can see that I have done the differential degree reduction from x'' = -kx by introducing a velocity term v. Decapodes has some support for derivatives in the visualization layer, so it knows that dX/dt should be called Ẋ and that dẊ/dt should be called Ẋ̇.

to_graphviz(oscillator)

In the previous example, we viewed negation and transformation by k as operators. Notice that k appears as an edge in the graph and not as a vertex. You can also use a 2 argument function like multiplication (*). With a constant value for k::Constant. In this case you will see k enter the diagram as a vertex and multiplication with * as a binary operator.

oscillator = @decapode begin
  X::Form0
  V::Form0

  k::Constant

  ∂ₜ(X) == V
  ∂ₜ(V) == -k*(X)
end
DiagrammaticEquations.decapodeacset.SummationDecapode{Any, Any, Symbol} {Var:5, TVar:2, Op1:3, Op2:1, Σ:0, Summand:0, Type:0, Operator:0, Name:0}
Var type name
1 Form0 X
2 Form0 V
3 Constant k
4 infer •1
5 infer V̇
TVar incl
1 2
2 5
Op1 src tgt op1
1 1 2 ∂ₜ
2 2 5 ∂ₜ
3 3 4 -
Op2 proj1 proj2 res op2
1 4 1 5 *

This gives you a different graphical representation as well. Now we have the cartesian product objects which represent a tupling of two values.

to_graphviz(oscillator)

You can also represent negation as a multiplication by a literal -1.

oscillator = @decapode begin
  X::Form0
  V::Form0

  k::Constant

  ∂ₜ(X) == V
  ∂ₜ(V) == -1*k*(X)
end
DiagrammaticEquations.decapodeacset.SummationDecapode{Any, Any, Symbol} {Var:6, TVar:2, Op1:2, Op2:2, Σ:0, Summand:0, Type:0, Operator:0, Name:0}
Var type name
1 Form0 X
2 Form0 V
3 Constant k
4 infer mult_1
5 infer V̇
6 Literal -1
TVar incl
1 2
2 5
Op1 src tgt op1
1 1 2 ∂ₜ
2 2 5 ∂ₜ
Op2 proj1 proj2 res op2
1 6 3 4 *
2 4 1 5 *

Notice that the type bubble for the literal one is ΩL. This means that it is a literal. The literal is also used as the variable name.

infer_types!(oscillator)
to_graphviz(oscillator)
Example block output

We can allow the material properties to vary over time by changing Constant to Parameter. This is how we tell the simulator that it needs to call k(t) at each time step to get the updated value for k or if it can just reuse that constant k from the initial time step.

oscillator = @decapode begin
  X::Form0
  V::Form0

  k::Parameter

  ∂ₜ(X) == V
  ∂ₜ(V) == -1*k*(X)
end
DiagrammaticEquations.decapodeacset.SummationDecapode{Any, Any, Symbol} {Var:6, TVar:2, Op1:2, Op2:2, Σ:0, Summand:0, Type:0, Operator:0, Name:0}
Var type name
1 Form0 X
2 Form0 V
3 Parameter k
4 infer mult_1
5 infer V̇
6 Literal -1
TVar incl
1 2
2 5
Op1 src tgt op1
1 1 2 ∂ₜ
2 2 5 ∂ₜ
Op2 proj1 proj2 res op2
1 6 3 4 *
2 4 1 5 * 
infer_types!(oscillator)
to_graphviz(oscillator)
Example block output

Often you will have a linear material where you are scaling by a constant, and a nonlinear version of that material where that scaling is replaced by a generic nonlinear function. This is why we allow Decapodes to represent both of these types of equations.

[ Info: Page built in 1 second.
[ Info: This page was last built at 2025-03-15T01:22:15.025.