More Flexible Interfaces for Specifying Simulations of Systems in CatColab

2026 ICMS - Computational Category Theory Session

Matt Cuffaro

Topos Institute

2026-07-20

Compositional Multiphysics in CatColab

CatColab, a web app for collaborative, formal, and declarative modeling.

Decapodes.jl project from GATAS group, is multiphysics software for declaratively specifying ODE/PDEs, with special emphasis on category-theoretic design, namely compositionality

How can we integrate Decapodes into CatColab?

Objectives

Introduce CatColab concepts necessary for describing the integration challenge

As a simulation target, introduce and define a “Decapode” which demonstrates compositionality and our integration strategy

Demonstrate this in action

Overview of Document Types

A model is a set of declarations for the underlying object and each of its functional and relational types. A model is described by a theory.
An instance of a model has terms are typed by those in the underlying model.
An analysis is a compilation of a model or an instance to a program

Example: ThSchema describes the relation between tables and column types \textsf{columntype}:\textsf{table}\mathrel{\mkern 3mu\vcenter{\hbox{$\scriptstyle+$}}\mkern-13mu{\to}}\textsf{column}

…has database schemas as models, and a possible analysis might be compiling to SQL CREATE TABLE statements

An instance is a set of data in those tables, and an analysis might be compiling to SQL INSERT statements

Decapodes.jl

How are multiphysics models implemented in Julia?

Discrete
Exterior
Calculus
Applied
Partial
Ordinary
Differential
EquationS

(Morris et al. 2024)

Decapodes.jl

Provides…

a DSL for specifying and composing physical models in their mathematical formulation
- includes passing custom functions into the simulation
- simulation code can be exported, inspected, and edited for debugging
defines discretization of operators in the exterior calculus
compiles models to simulation code

Unites

CombinatorialSpaces.jl (discretizing space and operators)
DiagrammaticEquations.jl (representing equations as diagrams)

Why integrate?

Several reasons I’m motivated by a CatColab integration: 1. expose multiphysics simulation to a broader audience 2. quicken the multiphysics workflow through structured editing 3. the theory in CatColab underlying the DEC model is itself an artifact; in Decapodes, it is a body of inference rules

Decapodes.jl

The DSL:

heat_eq = @decapode begin
    u::Form0
    k::Constant
    ∂ₜ(u) == k * Δ(u)
end

Objects are forms and morphisms are operators. Equality is established by paths.

Stored in an in-memory database called an ACSet (Patterson et al. 2022)

The instance functions as the “diagram” concept in CatColab.

Concrete Objective: Klausmeier

# See Klausmeier Equation 2.a
# `w` is surface water
# `a` is rainfall
# `-w` water uptake is a loss
# downwards advection
Hydrodynamics = @decapode begin
  (n,w)::DualForm0
  dX::Form1
  (a,ν)::Constant

  ∂ₜ(w) == a - w - w * n^2 + ν * L(dX, w)
end

# See Klausmeier Equation 2.b
# `n` is plant biomass
# `wn^2` is 
Phytodynamics = @decapode begin
  (n,w)::DualForm0
  m::Constant

  ∂ₜ(n) == w * n^2 - m*n + Δ(n)
end

What do we need to do?

We need to define

a theory which expresses the permissible operations in the DEC
a model which is populated with declarations of these operations
an instance whose terms treats the objects of a model as types
an analysis which compiles the model and its instance into a simulation target (Decapodes.jl)

What’s stopping us?

First iteration

In 2024, we did attempt an implementation! We defined a diagram of a model of the Navier-Stokes vorticity model

First Iteration

This introduced two challenges:

Lack of multiary morphisms: Instances of modal models were not yet defined
Instances could not be glued together (introduced for models)

This stimulated both a need to advance the mathematical theory.

Lists of inputs

We need structures which have “lists of inputs.” Two candidates are

monoidal categories (categories equipped with \otimes)
multicategories (categories whose morphisms accept multiple inputs)

A modal (read, monad) double theory (\mathbb{D},T) is a double theory equipped with a monad T. A modal double model is a double functor: M: (\mathbb{D},T)\to(\mathbb{S}\textsf{pan},\textsf{List})

(Patterson and Carlson, n.d.)

Monoidal theories have the underlying theory of monoidal categories, T_{\textsf{List}}x\to x

Multicategories have the underlying theory of generalized multicategories T_{\textsf{List}}x\mathrel{\mkern 3mu\vcenter{\hbox{$\scriptstyle+$}}\mkern-13mu{\to}}x

deRham complex as a multicategory

deRham complex as a modal double model in CatColab.

…has six objects, several operations, some binary

differentials d:\Omega_i\to\Omega_{i+1} and codifferentials \widetilde{d}_i:\widetilde{\Omega}_i\to\widetilde{\Omega}_{i+1}
Hodge stars \star_i:\Omega_i\to\widetilde{\Omega}_{n-i} (and their duals \star_i^{-1})
Lie derivative L, Laplacian \Delta
wedge products \wedge:\Omega_i\times\Omega_j\to\Omega_{i+j}

Instances

We have a model now but we need to define an instance whose elements are typed by those of the DEC. u::\Omega_0,\>\partial_tu::\Omega_0,\>{k}::\textsf{Constant}

We have a notion of this, but we need one in the “modal” variant

The present code on instances (“diagrams”) made it simple enough to adapt for this purpose

However ongoing research on instances means we still don’t understand “modal instances” precisely
This means that CatColab doesn’t type-check our instance, it just holds the data.

Analysis

With the model and instance implemented, we need to define the analysis.

user defines a model
user defines instances and composes them
these documents elaborated in the type theory into one document
julia initializes, sending a JSON spec of meshes and initial conditions defined on them
the document is serialized into JSON along with simulation parameters
using StructTypes.jl, the JSON is parsed into structs carrying data necessary for building the simulation

Julia Implementation

endpoint accepts a JSON, separating the model, instance, analysis
- Decapode state variables \to symbolic variable (SymbolicUtils.jl)
```
var::BasicSymbolic{DEC.Form{idx, duality, mesh, meshdim}}    
```
analysis specifies the mesh the Decapodes materializes.
initial_conditions are dispatched on the variable and initial condition

  # initial condition parameters are built into a `GaussianIC` struct
  struct GaussianIC <: AbstractInitialConditionSpec
    mean
    var
  end
  initial_condition(var::Sym{DEC.Form{idx, duality, mesh, meshdim}}
                   ,ic::GaussianIC, geometry::Geometry)
  # produce a Gaussian on the mesh type given by `mesh`
  end

the Decapode, mesh, initial conditions, and other simulation parameters are run

Demo

I’ll show a demo of this right now

Review and Conclusion

CatColab and Julia are able to communicate through an endpoint established by Oxygen.jl
We needed to develop and implement a form of “modal instances” extending the modal double model concept to CatColab’s instances concept.
We needed to design an interface which allowed Julia to supply the permissible combinations of mesh, initial conditions, and their parameters

Future Work

Consider more sophisticated dispatch to remove
UI whose expressiveness adapts to the expertise of the user
general improvements to our Julia integration may be promising for integrating with the Julia ecosystem and the Dyad modeling platform

Thank you

Organizers of this session
My collaborators Evan Patterson, Kevin Carlson, and Kris Brown
Luke Morris

References

Morris, Luke, Andrew Baas, Jesus Arias, Maia Gatlin, Evan Patterson, and James P Fairbanks. 2024. “Decapodes: A Diagrammatic Tool for Representing, Composing, and Computing Spatialized Partial Differential Equations.” Journal of Computational Science 81: 102345.

Patterson, Evan, and Kevin Carlson. n.d. https://next.catcolab.org/math/mdt-0008.xml.

Patterson, Evan, Owen Lynch, and James Fairbanks. 2022. “Categorical Data Structures for Technical Computing.” Compositionality 4 (December): 5. https://doi.org/10.32408/compositionality-4-5.