ThCategory versus ThCategoryExplicitSets

Old Catlab had an abstract type Category{Ob,Hom,Size<:CatSize}, where the third type parameter allowed for type dispatch to treat finite categories differently. This previous design has some odd features. Although one always has access to the Julia types of a Category’s objects and morphisms, one couldn’t get specific set of objects or morphisms. Consistent with this, the only way to build a infinite Category{Ob,Hom} from scratch was to construct a TypeCat{Ob,Hom}, but we obviously want to be able to work in categories where, e.g., the objects aren’t all of the terms of a particular type. This is improved upon by making a new theory:

@theory ThCategoryExplicitSets <: ThCategory begin
  Set′::TYPE{AbsSet}
  ob_set()::Set′
  hom_set()::Set′
end

ThCategoryExplicitSets.Meta.@wrapper Category

Thus the new Catlab Category is a wrapper type for models of the theory of categories (as shown in our first post) which also provide an explicit set for their obs and homs. Although Julia requires us, when implementing methods like id, to define the method for the entire input Ob type, we will regard such methods as only defined on elements of the Ob type which are elements of ob_set().

Beyond TypeCat and OppositeCat, Catlab now has many different ways to construct a Category. For example, CoproductCat interprets a vector of categories as its coproduct:

struct CoproductCat{O,H}
  cats::Vector{Category}
  function CoproductCat(cats::Vector{Category})
    ΣOb, ΣHom = SumSet(ob_set.(cats)), SumSet(hom_set.(cats))
    ΣObType, ΣHomType = eltype[ΣOb](), eltype[ΣHom]()   
    new{ΣObType, ΣHomType}(cats)
  end
end

Base.getindex(x::CoproductCat, i::Int) = x.cats[i]

Note above that SumSet is an implementation of ThSet which has elements of type TaggedElem{I<:Val,V}, where I is a type-level tag and V is the type of the wrapped value. By default, these tags are just integers, e.g. the type of SumSet([SetOb(Int), SetOb(String)]) is Union{TaggedElem{Val{1}, Int}, TaggedElem{Val{2}, String}}. Because SumSet is a model for ThSet, which provides a nullary method eltype, we can get the type of any particular s::SumSet via eltype[s]().

We can see how the each operation of the implementation untags values, does a computation in one of its component categories, and then retags the result.

@instance ThCategoryExplicitSets{O,H} [model::CoproductCat{O,H}] where {O,H} begin 

  id(x::O)::H =
    TaggedElem(id(model[gettag(x)], getvalue(x)), gettag(x))

  dom(x::H)::O 
    TaggedElem(dom(model[gettag(x)], getvalue(x)), gettag(x))

  codom(x::H)::O =
    TaggedElem(codom(model[gettag(x)], getvalue(x)), gettag(x))

  function compose(x::H,y::H)::H
    tx, ty = gettag(x), gettag(y)
    tx == ty || error("Cannot compose $x $y")
    TaggedElem(compose(model[tx], getvalue(x), getvalue(y)), tx)
  end
  
  ob_set()::AbsSet = SetOb(SumSet(ob_set.(model.cats)))

  hom_set()::AbsSet = SetOb(SumSet(hom_set.(model.cats)))

end

Finitely-generated categories

To give a FinCat requires us to additionally provide a finite number of morphism generators and a means of interpreting each generator as a Hom.¹

@theory ThFinCat <: ThCategoryExplicitSets begin
  Gen(src::Ob,tgt::Ob)::TYPE; 
  to_hom(f::Gen(a,b))::Hom(a,b) ⊣ [(a,b)::Ob]
  FSet′::TYPE{FinSet}
  gen_set()::FSet′
end
  
ThFinCat.Meta.@wrapper FinCat

This theory was designed to unify the interface for FinCatPresentation, FinCatGraph, and symbolic models in old Catlab. The code surface of these constructs was not very uniform: little code was written for FinCats generically because implementations could not be switched interchangeably without breaking things.

Old Catlab defined FinCat{Ob,Hom} to be Category{Ob,Hom,FinCatSize}, which had the property of forcing every FinCat to be a Category implicitly. As discussed in the last post, while this is sometimes convenient, other times it is important to be capable of making the distinction. In our new approach, FinCats and Categories have different interfaces, though we can trivially implement the Category interface given any implementation of the FinCat interface by forgetting about gen_set and to_hom.²

Models for ThFinCat which come from old Catlab include DiscreteFinCat, FinCatGraph, FinCatPresentation, and OpFinCat. We add to this PathCat (a model of a ThFinCat-like theory except we assume Path=Hom) and PreorderCat. PreorderCat is an interesting edge case because it has Gen = Hom, as both generators and homs are just pairs of objects. This revealed major ambiguities in old Catlab’s design which needed to be fixed because they use type dispatch to do different things depending on whether one is working with a generator, a hom, or a hom given as a path of generators.

FinFunctors

One of the largest breaking changes in the refactor is how FinFunctor and FinDomFunctor are handled. This is a consequence of the additional structure that FinCat has, as described above. In old Catlab, certain Julia types were assumed to be either generators, objects, or homs, such that type dispatch could determine what to do when a FinFunctor received arbitrary data (whether in the process of defining the FinFunctor or applying an existing one to some data). So calling F(x) would do something different whether it received an Ob-like Julia type vs a Hom-like type. Even if one is explicit with hom_map(F, x), it still relied on dispatch to distinguish generator-like arguments, path-like arguments, and composite morphisms. However, in general one’s category could have the same Julia type for these different roles, so this code was only correct because the few instances of FinCats did not have any such overlap.

This means when defining a FinFunctor or FinDomFunctor, one should declare whether one is sending generators to generators, paths, or homs. A new homtype keyword argument allows us to specify this:

C = FinCat(parallel_arrows(Graph, 2))

h = @acset Graph begin V=4; E=4; src=[1,1,2,3]; tgt= [2,3,4,4] end
D = FinCat(h)

F = FinFunctor((V=[1,4], E=[[1,3], [2,4]]), C, D; homtype=:list)
G = FinFunctor((V=[3,4], E=[4,4]), C, D; homtype=:generator)

The models of ThFinDomFunctor include CompositeFinDomFunctor, FinDomFunctorMap, IdentityFinDomFunctor, and OppositeFinDomFunctor. Although we could define a separate theory ThFinFunctor, instead we opt to make a FinFunctor be a FinDomFunctor whose codomain happens to be a FinCat as there is no difference in the interface, even at the level of input and return types to the operations of the theory (in both cases, generators are sent to homs in the codomain).

What really is a free diagram?

Free diagrams in Catlab refer to DiscreteDiagram, ComposableMorphisms, ParallelMorphisms, Multispan, Multicospan, BipartiteGraph, and FreeDiagram³. In old Catlab these are a bunch of related data structures which shared some overlapping interfaces. This is now made more explicit in the refactored code, where we are forced to confront this section’s titular question.

Mathematically, a free diagram is a functor out of a small (free) category. For us, this means FreeDiagram is like a functor but with a domain Graph (viewed as a free category). However, we don’t worry about including the category structure of the codomain (e.g. a pair of composable morphisms need not carry the information for how to obtain a single composite morphism). This means in order to get the mathematical definition of a free diagram out of FreeDiagram, one must also supply a codomain Category. We opt for this simplicity because a FreeDiagram is supposed to be a syntactic object; expecting them to have the complete data of a (possibly large) category is unreasonable.

Because FreeDiagram does not know what its codomain category is (just the Julia types of its objects and morphisms), the FinDomFunctor(diagram) method is no longer supported. This was only possible because it used to be that one knew the full category of structure just from the types of obs and homs (because the ThCategory implementation was determined by type dispatch).

Now let’s look at the interface:

@theory ThFreeDiagram begin 
  V::TYPE; E::TYPE; Ob::TYPE; Hom::TYPE; FSet::TYPE{FinSet};
  src(h::E)::V;
  tgt(h::E)::V;
  obset()::FSet
  homset()::FSet
  obmap(v::V)::Ob
  hommap(e::E)::Hom
end

ThFreeDiagram.Meta.@wrapper FreeDiagram

The refactor of FreeDiagrams was more than just a cosmetic reorganization of free floating methods into the above interface. This is because old Catlab’s implementations for some of these ThFreeDiagram models did not contain enough data to implement this interface. For example, a Span in old Catlab has the data of a pair of morphisms. We can imagine V={1,2,3}, E={1,2}: the morphisms give the data of hommap, but not obmap. Old Catlab effectively derived what obmap was by presupposing that we can call (co)dom on whatever Julia type Hom is; however we just mentioned that we no longer want to presume the entire category structure of the free diagram’s codomain! After all, a term of some morphism type Foo can now have many different (co)domains, as we can have many different models of ThCategory with Foo as its morphisms. Thus our new design forces us modify the Span data structure to include the extra obmap data.⁴

Just to get a flavor of what a model of ThFreeDiagram looks like, consider:

@instance ThFreeDiagram{Int,Int,Union{Ob,Foot},Hom
                       } [model::Multispan{Ob,Hom,Foot,V,W}
                         ] where {Ob, Hom, Foot, V, W} begin
  src(::Int)::Int = 1
  tgt(x::Int)::Int = x+1
  obmap(x::Int)::Union{Ob,Foot} = @match x begin 
    1 => apex(model)
    i => feet(model)[i-1]
  end
  hommap(i::Int)::Hom = model[i]
  obset()::FinSet = FinSet(length(model)+1)
  homset()::FinSet = FinSet(length(model))
end

Limits and colimits

Limits and colimits of free diagrams were controlled in old Catlab by a complicated process which involved defining methods for particular FreeDiagram{Ob,Hom} types, dispatching on the Ob and Hom types of these diagrams. In contrast, we now have a base theory for categories with limits:⁵

@theory ThCategoryLimitBase <: ThCategoryExplicitSets begin
  Limit()::TYPE{AbsLimit}
  ob(lim::Limit)::Ob
  MSpan::TYPE{Multispan}
  apex(s::MSpan)::Ob
  cone(l::Limit)::MSpan
  apex(cone(l)) == ob(l) ⊣ [l::Limit]
end

Now for any particular kind of free diagram we can define a (co)limit theory, e.g. for ParallelMorphisms:

@theory ThCategoryWithEqualizers <: ThCategoryLimitBase begin
  ParallelDiagram()::TYPE{ParallelMorphisms}
  limit(p::ParallelDiagram)::Limit
  universal(eq::Limit, p::ParallelDiagram, s::MSpan)::(apex(s) → ob(eq))
end

ThCategoryWithEqualizers.Meta.@wrapper CatWithEqualizers

Now we can implement such a theory for any given model, e.g.

@instance ThCategoryWithEqualizers{FinSetInt, FinFunction} [model::SkelFinSet] begin

  function limit(para::ParallelMorphisms)
    @assert !isempty(para)
    f1, frest = para[1], para[2:end]
    m = length(dom(para))
    eq = FinFunction(filter(i -> all(f1(i) == f(i) for f in frest), 1:m), m)
    LimitCone(Multispan(dom[model](eq), [eq]; cat=model), FreeDiagram(para))
  end 
  
  function universal(res::AbsLimit, ::ParallelMorphisms, span::Multispan)
    ι = collect(only(cone(res)))
    h = only(span)
    FinFunction(Int[only(searchsorted(ι, h(i))) for i in dom[model](h)], length(ι))
  end 
end

With the interface implemented as above, we will not get a runtime error if we try to wrap SkelFinSet() with CatWithEqualizers.

To compare to old Catlab: we are no longer dispatching on the types of Ob and Hom which appear in the diagram, so we now able to have different (co)limits for the same type of diagram, e.g. DiscreteDiagram{Int, FinFunction}. This interface no longer offers an alg keyword (for example, the many different join algorithms for pullbacks), as the GAT formalism doesn’t have a built-in notion of optional or keyword argument. In this case, whatever the default algorithm was is the one that appears in @instance. The other methods (e.g. nested_loop_limit(cospan::Multicospan)) are still preserved in the codebase, but need to be explicitly called rather than invoked via the alg keyword.

Monoidal limits

In old Catlab, there is a macro @(co)cartesian_monoidal_instance ObType HomType which generates a bunch of methods related to monoidal categories (e.g. delete, copy, swap) on the assumption that ObType and HomType have the right (co)limit methods already defined. Because the (co)limit methods are now tied to models rather than to the types themselves, we can replace this macro with an implementation of Th(Co)CartesianCategory given any model of ThCatWithUnbiased(Co)Products.⁶ We can use a wrapped model of ThCatWithUnbiased(Co)Products as our raw model for Th(Co)CartesianCategory:⁷

@instance ThCocartesianCategory{Ob, Hom} [model::TypedCatWithCoproducts{Ob,Hom}
    ] where {Ob,Hom} begin

  function swap(A::Ob, B::Ob)
    AB = coproduct(model, A, B)
    BA = coproduct(model, B, A)
    copair(model, AB, coproj2(BA), coproj1(BA))
  end
  
  ...
end

Using ⊕ and ⊗ is not as seamless as it was before because their meaning depends on a particular choice of model. And because they are binary operators, it’s not possible to use the index notation (e.g. id[MyCat](x)) to fill in the model. This is where GATlab’s @withmodel macro is helpful:

const Grph = ACSetCategory(Graph()) # raw model

X = @withmodel TypedCatWithCoproducts(Grph) (⊗,⊕) begin 
 cycle_graph(Graph, 1) ⊗ (path_graph(Graph, 2) ⊕ cycle_graph(Graph, 4))
end

Slice categories

One of the most touted features of GATlab is that slice categories can be done in a more robust way.

struct SliceOb{ObT, HomT}
  ob::ObT
  hom::HomT
end

struct SliceC{ObT, HomT}
  cat::Any 
  over::ObT
  function SliceC(cat::Category, over)
    cat = getvalue(cat) # unwrap after confirming it's at least a Category model
    new{impl_types(cat, ThCategory)...}(cat, over)
  end
end

@instance ThCategoryExplicitSets{SliceOb{<:ObT, <:HomT}, HomT
    } [model::SliceC{ObT, HomT}] where {ObT, HomT} begin

  id(x::SliceOb{<:ObT, <:HomT}) = id[model.cat](x.ob)

  compose(f::HomT, g::HomT) = compose[model.cat](f, g)
  
  ...
end

As mentioned in the first post of this series, wrapper types put us in a tricky position when we want to use the same model in the context of multiple theories. We want the model that we are slicing over to at least support the theory of categories, but we’ll likely want to use it in other theories that extend ThCategory (e.g. ThCategoryWithPullbacks, ThCategoryWithInitial). The (co)limit methods for those will not accept a wrapped Category model, but they will accept the raw model (e.g. SkelFinSet) if it happens to have those interfaces implemented. For the reason, the SliceC data structure doesn’t store the wrapped Category model but rather just stores the raw model (which could have any type). There is definitely room for improvement in the future!

Next steps

There are other interesting aspects of refactoring the Cats module (e.g. various categories of diagrams in a category), but we’ll end this post here and continue next time with discussing how various categories related to ACSets are handled!

Analogies in Planning

Do X like you would Y. That’s the essence of analogical thinking which can be surprisingly powerful in planning. We often want to restate one task in the language of another to reframe how we think about the problem. This reframing then helps us solve novel problems with solutions we already know.

Forming an analogy is a frequent cognitive process humans engage in. In cognitive psychology, this process is described as forming a structured mapping between two interrelated networks of concepts (Gentner 1983). Think: the sun is to the solar system as the nucleus is to an atom. In planning, this can translate to finding a correspondence between the ontologies that structure two planning domains.

Precisely, how do we do this? In the context of my work on task planning (Aguinaldo 2025), I use functorial data migrations to align planning domain ontologies and reinterpret the world in light of this. In other words, a migration functor gives us instructions for how to carry over data from one plan to another in a way that respects their shared structure.

If you need a refresher on how we represent plans using Double-Pushout (DPO) rewriting in AlgebraicJulia, check out this earlier blogpost or refer to (Aguinaldo et al. 2023).

In this post, we’ll walk through how a plan from the Tower of Hanoi domain can be analogically transferred into the Blocksworld domain—showing an unconventional though interesting reframing of classical problems in computer science.

Example: Tower of Hanoi and Blocksworld

Blocksworld and Tower of Hanoi are canonical planning environments, called planning domains, in the field of AI planning. The appeal of experimenting within these domains is their generality and resemblance to richer, more realistic planning problems.

In Blocksworld, blocks are stacked on one another or on table. Planning problems in this domain try to rearrange blocks to achieve a goal configuration based on the knowledge of what blocks are on top of one another or on the table at a given point in time. In Tower of Hanoi, -disks are arranged on three pegs such that a larger disk cannot sit on top of a smaller disk. In other words, disks must be arranged increasing in diameter, top to bottom, contrained to three positions, given by the three pegs. Planning problems in this domain aim to arrange all -disks on one peg based solely on the knowlege of what disks are larger than another and which peg a given disk is on.

Domain	Known	Constraints
Blocksworld	- Block is on Block - Block is on the table - Block is clear	N/A
Tower of Hanoi	- Disk is smaller than Disk - Disk is on Peg - Disk is clear	- Disk must be on one of three pegs - Disk must be smaller than the disk below it

Having been educated on the nuances between these domains, we could safely agree that they have very different qualities. But… would a four-year-old say the same?

A newcomer to this world would probably say both are basically the same–just activities that stack something on top of one another thing! By seeing things this way, they seem to have found shared meaning between these two worlds, or in other words an analogy… Let’s run with that!

This simplification leads to two very valid inquiries:

Question A. “Could I stack blocks in Blocksworld like I am in Tower of Hanoi?”

Question B. “Could I stack disks in Tower of Hanoi like I am in Blocksworld?”

Let’s see!

using Catlab
using DataMigrations;

@present OntTowerOfHanoi(FreeSchema) begin
  Disk::Ob
  Peg::Ob

  diskIsOnPeg::Hom(Disk, Peg)

  Smaller::Ob
  isSmaller_l::Hom(Smaller, Disk)
  isSmaller_r::Hom(Smaller, Disk)

  Clear::AttrType
  isClear::Attr(Disk, Clear)

  MyBool::AttrType
  MyString::AttrType
end
@acset_type TowerOfHanoi(OntTowerOfHanoi);

yTowerOfHanoi = yoneda(TowerOfHanoi{Bool,Bool,String});  
init = @acset_colim yTowerOfHanoi begin
  (disk1, disk2, disk3)::Disk
  (peg1, peg2, peg3)::Peg
  (smaller1, smaller2, smaller3)::Smaller
  isSmaller_l(smaller1) == disk1  # disk1 < disk2
  isSmaller_r(smaller1) == disk2
  isSmaller_l(smaller2) == disk2  # disk2 < disk3
  isSmaller_r(smaller2) == disk3
  isSmaller_l(smaller3) == disk1  # disk1 < disk3
  isSmaller_r(smaller3) == disk3
  diskIsOnPeg(disk1) == peg1
  diskIsOnPeg(disk2) == peg2
  diskIsOnPeg(disk3) == peg1
  isClear(disk1) == true
  isClear(disk2) == false
  isClear(disk3) == true
end;

goal = @acset_colim yTowerOfHanoi begin
  (disk1, disk2, disk3)::Disk
  (peg1, peg2, peg3)::Peg
  (smaller1, smaller2, smaller3)::Smaller
  isSmaller_l(smaller1) == disk1  # disk1 < disk2
  isSmaller_r(smaller1) == disk2
  isSmaller_l(smaller2) == disk2  # disk2 < disk3
  isSmaller_r(smaller2) == disk3
  isSmaller_l(smaller3) == disk1  # disk1 < disk3
  isSmaller_r(smaller3) == disk3
  diskIsOnPeg(disk1) == peg1
  diskIsOnPeg(disk2) == peg1
  diskIsOnPeg(disk3) == peg1
  isClear(disk1) == true
  isClear(disk2) == false
  isClear(disk3) == true
end;

@present OntBlocksworld(FreeSchema) begin
  Block::Ob

  InOn::Ob
  inOn_l::Hom(InOn, Block) 
  inOn_r::Hom(InOn, Block)

  Clear::AttrType
  isClear::Attr(Block, Clear)
  OnTable::AttrType
  isOnTable::Attr(Block, OnTable)

  MyBool::AttrType
  MyString::AttrType
end
@acset_type Blocksworld(OntBlocksworld);

  ...
  InOn => @join begin
    disk1::Disk
    disk2::Disk
    peg::Peg
    diskIsOnPeg(disk1) == peg
    diskIsOnPeg(disk2) == peg
    smaller::Smaller
    isSmaller_l(smaller) == disk1  # disk1 < disk2
    isSmaller_r(smaller) == disk2
  end  # a disk is on another if it is smaller and on the same peg
  inOn_l => disk1
  inOn_r => disk2
  ...

  ...
  # A disk, x, is on the table if it is the largest disk on a peg.
  isOnTable => (x -> begin

    # Step 1. Get the peg that the disk `x` is on
    p = diskIsOnPeg(x) 

    # Step 2. Get all the disks on the same peg as `x`
    dop = [i for (i, x) in enumerate(collect(diskIsOnPeg)) if x == p]

    # Step 3. Filter `smaller` to only relations that involve the disks 
    # that were selected
    smaller′ =  [
      i 
      for (i, rel) in enumerate(zip(collect(isSmaller_l), collect(isSmaller_r))) 
      if all(d -> d in dop, rel)
    ]

    # Step 4. Check if disk is not contained in `isSmaller_l` in `smaller′`
    !(x in collect(isSmaller_l)[smaller′]) 
  end) 
  ...

F = @migration OntBlocksworld OntTowerOfHanoi begin
  Block => Disk
  InOn => @join begin
    disk1::Disk
    disk2::Disk
    peg::Peg
    diskIsOnPeg(disk1) == peg
    diskIsOnPeg(disk2) == peg
    smaller::Smaller
    isSmaller_l(smaller) == disk1  # disk1 < disk2
    isSmaller_r(smaller) == disk2
  end  # a disk is on another if it is smaller and on the same peg
  inOn_l => disk1
  inOn_r => disk2
  Clear => Clear
  isClear => isClear
  OnTable => MyBool
  isOnTable => (x -> begin
    p = diskIsOnPeg(x) 
    dop = [i for (i, x) in enumerate(collect(diskIsOnPeg)) if x == p]
    smaller′ =  [
      i 
      for (i, rel) in enumerate(zip(collect(isSmaller_l), collect(isSmaller_r))) 
      if all(d -> d in dop, rel)
    ]
    !(x in collect(isSmaller_l)[smaller′]) 
  end) 
  MyBool => MyBool
  MyString => MyString
end;

new_init = migrate(Blocksworld,  init, F)
new_state₁ = migrate(Blocksworld, state₁, F)
new_state₂ = migrate(Blocksworld, state₂, F)
new_goal = migrate(Blocksworld, goal, F)

Some observations

Let’s check back in with our five-year-old. (Yes, they aged a year in the time we worked through this example…). So, what questions did they want to answer?

Question A. “Could I stack blocks in Blocksworld like I am in Tower of Hanoi?”

Question B. “Could I stack disks in Tower of Hanoi like I am in Blocksworld?”

Well…

# Not valid code
F⁻¹ = @migration OntTowerOfHanoi OntBlocksworld begin
  Disk => Block
  Peg => ??  # no notion of stack position
  diskIsOnPeg => ?? # no notion of blocks on "pegs"
  Smaller => ??  # smaller does not imply on top of
  isSmaller_l => ??
  isSmaller_r => ??
  Clear => Clear
  isClear => isClear
end

Conclusion

By interpreting the Tower of Hanoi plan in the Blocksworld domain, we didn’t just copy a sequence of actions, but instead transported meaning. We made sense of one domain in terms of another, and functorial data migrations gives us the formal machinery to coherently do that.

More specifically, the benefits we saw from using functorial data migrations were that:

• It automated the translations of states and plans, and
• It lets us prove that there is no analogy between two schema categories in a particular direction. (This can be done automatically by computing the homset between the schemas categories and deciding that there are no migration functors that do what you want.)

This opens the door to alternative approaches to planning, like: planning in simpler domains and transporting solutions to more complex ones, or designing algorithms that detect when analogies break down, or introducing new constraints to planning problems by reinterpreting them in new domains.

For a deeper exposition of these ideas within robot task planning, refer to (Aguinaldo, Patterson, and Regli 2025).

Cellular Sheaves for Multi-agent Control Systems

For our purposes, a multi-agent control system consists of a collection of agents with discrete LTI dynamics for each , where and are matrices, is the state variable of agent , and is the control input of agent . We suppose that agents can have bidirectional communication with other agents. The communication topology of the agents thus forms an undirected simple graph . A general multi-agent coordination problem involves each agent choosing control inputs for themselves to drive the total system towards some desired goal. The agents should make these choices using only local computation and communication with neighboring agents. Examples of coordination goals include

• Consensus, where each agent reaches the same position,
• Formation, where each agent reaches a desired displacement from neighboring agents,
• Flocking, where all agents move with the same velocity while staying a fixed distance apart from each other.

The main idea of our paper was to use cellular sheaves to model the communication structure of the multi-agent system and edge potential functions to encode the coordination goals between each pair of agents. For the rest of this section, we introduce concepts from cellular sheaves as they relate to this multi-agent setup.

A cellular sheaf on an undirected simple graph consists of

• a collection of vector spaces for each known as vertex stalks,
• a collection of vector spaces for each known as edge stalks,
• For each edges , a pair of linear maps and known as restriction maps.

The graph corresponds to the communication topology of the agents, while the vertex stalks are the state spaces of each agent. The edge stalks are then the spaces of valid communications between agents and the restriction maps encodes the view of each agents state which is passed to other agents. A simple example is an agent with a complex state space who only wants to communicate its position with other agents. In this case, it would choose projection onto the position components of its state as its restriction map to its neighbors.

There are two important vector spaces associated to any cellular sheaf:

1. The space of 0-cochains:
2. The space of 1-cochains:

A global section of is a globally consistent choice of vectors for each vertex stalk, meaning that when we pass these vectors through the incident restriction maps, they are equal. In the context of our multi-agent system, a global section is a state for each agent which agrees when communicated with neighboring agents.

To compute whether a given state is a global section, we can use the coboundary map. Given an arbitrary orientation of the edges of , the coboundary map of , denoted is the linear map defined by for all edges . It is easy to see that the zeros of the coboundary map correspond to global sections, because precisely when .

To introduce different coordination goals, we can define potential functions on each edge. For an edge , a potential on is a function which we can think of as defining a cost for each element of the edge stalk. The function defines the total cost for all edges of the cellular sheaf. Given such a , the coordination goal of our multi-agent system is In other words, we want our system to reach a state which minimizes the edge potential functions after being passed through the coboundary map. To get some intuition, the following table summarizes the edge potential functions associated with various coordination goals.

Potential Function	Coordination Goal
	Consensus
	Reach displacement of
	Reach distance of

Solving Coordination Problems

We implemented cellular sheaves with nonlinear potential functions and a solver for coordination problems in our package AlgebraicOptimization.jl. In our framework, a multi-agent optimal control problem consists of

• A cellular sheaf on a graph
• Potential functions for each edge
• Single-agent optimal control objectives (specified as JuMP.jl models in our implementation) for each vertex.

The overall problem is to then compute control inputs over a fixed time horizon which minimize each agents optimal control objective as much as possible while satisfying the coordination goal by the end of the time horizon.

Here as some examples of different coordination goals being reached by a 3 agent system, where each agents’ dynamics are given by 2-dimensional double integrators. Details on each example as well as the code to generate the plots can be found in the docs

Tree Decompositions

Let be a simple graph and a family of subsets . Then a tree is called a tree decomposition of —also a junction tree, join tree, or clique tree—if it satisfies the following properties.

1. For all vertices , the set induces a nonempty connected subgraph of .

2. For all edges , the set is nonempty.

The width of a tree decomposition is the number and the treewidth of a graph is the width of its smallest tree decomposition. Tree decompositions of small width are highly desirable, for they can be used to implement fast algorithms on graphs and graph structured data. To see how this works, we will look at an example from dynamic programming in the next section.

Dynamic Programming

Suppose we want to minimize a function where . Since , , and are finite sets, we can find the minimum in time by enumerating every triple . In general, there is no faster solution. However, if is of the form for some functions then we can do the following. For all , we compute and record the number Then we compute the minimum of the sum Both quantities can be computed in time, so the time complexity of the second procedure is . What we have done is take advantage of the fact that the variables and are not directly coupled, but rather related to each other via the variable . Another way of expressing this observation is to state that the interaction graph of admits the following tree decomposition.

This trick is generalized by Algorithm 7.1 in Vandenberghe and Andersen, 2015, which computes the minimum of a function of the form The algorithm takes a tree decomposition as one of its input parameters, and its runtime is determinded by the width of the decomposition.

Other Applications

Perhaps the most sucessful application of tree decompositions to numerical computing is in sparse matrix software. Libraries like SuiteSparse and HSL construct tree decompositions during the symbolic factorization stge of their Cholesky and LU factorization routines. Other applications include

• convex optimization
• tensor network contraction
• probabilistic inference

all of which are present in the Julia ecosystem in packages like Clarabel.jl, OMEinsumContractionOrders.jl, and JunctionTrees.jl.

Engineering

Let be a simple graph. Every permutation on the vertices of induces a tree decomposition on via a procedure called vertex elimination. Furthermore, the induced tree decomposition can be computed in almost-linear time, and the implementation in CliqueTrees.jl is in practice extremely fast. Hence, the problem of finding a tree decomposition of can be reduced to the problem of finding a permutation of . CliqueTrees.jl implements a number of algorithms for solving this problem.

Several more algorithms are implemented as package extensions.

This list includes exact, exponential-time algorithms like BT and SAT, which are guaranteed to create decompositions of minimal width, as well as linear-time heuristic algorithms like AMF and AMD that can decompose graphs with millions of vertices. Other algorithms, like MinimalChordal and RuleReduction are pre or post-processors; they are parametrized by another algorithm and work by transforming its input or output. These meta-algorithms are useful enough that some packages prefer to call their own tree decomposition algorithms through CliqueTrees.jl.

Coming Soon

In a subsequent blog post, I will discuss a categorification of tree decompositions called structured decompositions.

Data Import

First let’s load the data that is used to parameterize the model. Using the SQLite.jl library, we get each table from the relational database as a DataFrame, as in the JuMP tutorial which can be consulted for details.

import SQLite, SQLite.DBInterface
using DataFrames

filename = joinpath(@__DIR__, "commodity_nz.db");
db = SQLite.DB(filename)

function get_table(db, table)
    query = DBInterface.execute(db, "SELECT * FROM $table")
    return DataFrames.DataFrame(query)
end

df_shipping = get_table(db, "shipping")
df_products = get_table(db, "products")
df_supply = get_table(db, "supply")
df_demand = get_table(db, "demand")

df_cost = DataFrames.leftjoin(df_shipping, df_products; on = [:product])
df_cost.flow_cost = df_cost.cost_per_km .* df_cost.distance_km

Unlike the tutorial, we make df_edges containing the (src, tgt) pairs, and df_productvertex which is the product of vertices and products (commodities). We then add the supply capacities, costs, and demands to each element of the product.

places = unique([df_cost.origin; df_cost.destination])
products = unique(df_cost.product)

df_edges=unique(df_cost[:, [:origin, :destination]])
transform!(df_edges, :origin => ByRow(o -> begin
    findfirst(o .== places)
end) => :src)
transform!(df_edges, :destination => ByRow(o -> begin
    findfirst(o .== places)
end) => :tgt)

df_productvertex = crossjoin(DataFrame(place=places), DataFrame(product=products))
leftjoin!(df_productvertex, df_supply, on=[:place=>:origin, :product])
leftjoin!(df_productvertex, df_demand, on=[:place=>:destination, :product])
df_productvertex[ismissing.(df_productvertex.capacity), :capacity] .= 0.0
df_productvertex[ismissing.(df_productvertex.cost), :cost] .= 0.0
df_productvertex[ismissing.(df_productvertex.demand), :demand] .= 0.0

ACSet Structure

Now we’ll generate a schema which is appropriate to represent the multi-commodity network flow problem. We use schema inheritance to inherit from SchGraph, the schema for simple graphs. Our new objects include Commodity which is the set of commodities considered, CommodityVertex which is the product of Commodity and V, and Shipping which is the product of Commodity and E. With these additional objects, we can conveniently store all the data and variables of the optimization model. We add some additional AttrTypes to the schema as well, DecisionVar which will store the JuMP decision variables, and NumVar which stores numeric data (used to parameterize the model).

using Catlab

@present SchMultiCommodity <: SchGraph begin    
    (CommodityVertex,Commodity,Shipping)::Ob
    cv_c::Hom(CommodityVertex,Commodity)
    cv_v::Hom(CommodityVertex,V)
    s_p::Hom(Shipping,Commodity)
    s_e::Hom(Shipping,E)

    Label::AttrType
    vlabel::Attr(V,Label)
    plabel::Attr(Commodity,Label)

    NumVar::AttrType
    supplycap::Attr(CommodityVertex,NumVar) # supply capacity
    demand::Attr(CommodityVertex,NumVar) # demand
    purcost::Attr(CommodityVertex,NumVar) # purchase cost
    shipcost::Attr(Shipping,NumVar) # shipment cost
    flowcap::Attr(E,NumVar) # flow capacity

    DecisionVar::AttrType
    s::Attr(CommodityVertex,DecisionVar) # optimal supply
    x::Attr(Shipping,DecisionVar) # optimal shipment
end

to_graphviz(SchMultiCommodity, graph_attrs=Dict(:size=>"6",:ratio=>"fill"))

We next generate the ACSet types from the schema. Note that type inheritance for ACSets is handled seperately from the schema inheritance, so we inherit from HasGraph to take advantage of the Graphs module of Catlab.

@abstract_acset_type AbstractMultiCommodity <: HasGraph
@acset_type MultiCommodity(SchMultiCommodity, index=[:src,:tgt,:cv_c,:cv_v,:s_p,:s_e]) <: AbstractMultiCommodity

Now we are ready to generate an instance of an ACSet of this type with the data we set up previously. Like the original tutorial, we assume that the capacity of each edge is 30.

using JuMP

capacity = 30

multinet_acs = @acset MultiCommodity{String,Float64,JuMP.VariableRef} begin
    V=length(places)
    vlabel=places
    Commodity=length(products)
    plabel=products
    E=nrow(df_edges)
    src=df_edges.src
    tgt=df_edges.tgt
    flowcap=capacity
end

for r in eachrow(df_productvertex)
    v=only(incident(multinet_acs, r.place, :vlabel))
    p=only(incident(multinet_acs, r.product, :plabel))
    add_part!(
        multinet_acs, :CommodityVertex, 
        cv_v=v, cv_c=p,
        supplycap=r.capacity, demand=r.demand, purcost=r.cost
    )
end

for r in eachrow(df_cost)
    src=only(incident(multinet_acs, r.origin, :vlabel))
    tgt=only(incident(multinet_acs, r.destination, :vlabel))
    product=only(incident(multinet_acs, r.product, :plabel))
    add_part!(
        multinet_acs, :Shipping,
        s_p=product, s_e=only(edges(multinet_acs, src, tgt)),
        shipcost=r.flow_cost
    )
end

Next we’d like to visualize the data and the network we created. Catlab integrates with GraphViz for visualizations of graph-like objects, and because we want to customize how the vertices and edges are displayed, we write some code that generates the labels for vertices below. We rely on the ability of GraphViz to generate HTML-like labels for vertices. For more information on the syntax, please see the GraphViz documentation.

Below we write two versions of the method that will generate the label for a vertex. make_node_label_optim should be run on an ACSet of type AbstractMultiCommodity after it has been optimized, to print out a table indicating how much of each commodity was supplied by that vertex. The make_node_label_parameters prints out the data that parameterizes the model for each vertex/commodity combination: the maximum supply capacity, demand, and supply cost.

import Catlab.Graphics.Graphviz.Html

"""
Make a node label for a model that has been optimized.
"""
function make_node_label_optim(v, acs, label_dict)
    commodity_v = incident(acs, v, :cv_v)
    label = Vector{String}()
    push!(
        label, """
            <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
            <TR><TD COLSPAN="2">$(acs[v, :vlabel])</TD></TR>
            <TR><TD>Product</TD><TD>Purchased</TD></TR>
        """
    )
    for cv in commodity_v
        if JuMP.value(acs[cv, :s]) > 0
            emoji = label_dict[acs[cv, (:cv_c, :plabel)]]
            push!(
                label, """
                    <TR><TD>$(emoji)</TD><TD>$(JuMP.value(acs[cv, :s]))</TD></TR>
                """
            )
        end
    end
    push!(
        label, """
            </TABLE>
        """
    )
end

"""
Make a node label for the model parameters.
"""
function make_node_label_parameters(v, acs, label_dict)
    commodity_v = incident(acs, v, :cv_v)
    label = Vector{String}()
    push!(
        label, """
            <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
            <TR><TD COLSPAN="4">$(acs[v, :vlabel])</TD></TR>
            <TR><TD>Product</TD><TD>Supply Capacity</TD><TD>Demand</TD><TD>Purchase Cost</TD></TR>
        """
    )
    for cv in commodity_v
        emoji = label_dict[acs[cv, (:cv_c, :plabel)]]
        push!(
            label, """
                <TR><TD>$(emoji)</TD><TD>$(acs[cv, :supplycap])</TD><TD>$(acs[cv, :demand])</TD><TD>$(acs[cv, :purcost])</TD></TR>
            """
        )
    end
    push!(
        label, """
            </TABLE>
        """
    )
end

make_node_label_dict = Dict(:optim=>make_node_label_optim, :parameters=>make_node_label_parameters)

Likewise we have two similar methods for edges. The first, to be run post-optimization, prints the amount of each commodity shipped on each edge. The second prints the shipping cost of each commodity, producing a visualization of the data which parameterizes the mathematical model. Finally we define make_property_graph which generates a property graph using these methods. Because our ACSet type inherits from HasGraph, we can use the to_graphviz_property_graph method defined on any graph-like type to do the hard work, and then simply modify edge and vertex labels.

"""
Make an edge label for an optmized model.
"""
function make_edge_label_optim(e, acs, label_dict)
    ship = incident(acs, e, :s_e)
    label = Vector{String}()
    edge_label = acs[e, (:s_e, :src, :vlabel)] * " → " * acs[e, (:s_e, :tgt, :vlabel)]
    push!(
        label, """
            <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
            <TR><TD COLSPAN="2">$(edge_label)</TD></TR>
            <TR><TD>Product</TD><TD>Shipped</TD></TR>
        """
    )
    for s in ship
        if JuMP.value(acs[s, :x]) > 0.0
            emoji = label_dict[acs[s, (:s_p, :plabel)]]
            push!(
                label, """
                    <TR><TD>$(emoji)</TD><TD>$(JuMP.value(acs[s, :x]))</TD></TR>
                """
            )
        end
    end
    push!(
        label, """
            </TABLE>
        """
    )
end

"""
Make an edge label for the parameters of the model.
"""
function make_edge_label_parameters(e, acs, label_dict)
    ship = incident(acs, e, :s_e)
    label = Vector{String}()
    edge_label = acs[e, (:s_e, :src, :vlabel)] * " → " * acs[e, (:s_e, :tgt, :vlabel)]
    push!(
        label, """
            <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
            <TR><TD COLSPAN="2">$(edge_label)</TD></TR>
            <TR><TD>Product</TD><TD>Shipping Cost</TD></TR>
        """
    )
    for s in ship
        emoji = label_dict[acs[s, (:s_p, :plabel)]]
        push!(
            label, """
                <TR><TD>$(emoji)</TD><TD>$(acs[s, :shipcost])</TD></TR>
            """
        )
    end
    push!(
        label, """
            </TABLE>
        """
    )
end

make_edge_label_dict = Dict(:optim=>make_edge_label_optim,:parameters=>make_edge_label_parameters)

function make_property_graph(acs::T; labels, kwargs...) where {T<:AbstractMultiCommodity}
    pg = to_graphviz_property_graph(acs; kwargs...)   
    label_dict = Dict("milk"=>"🥛", "kiwifruit"=>"🥝")
    for v in parts(acs, :V)
        label = make_node_label_dict[labels](v, acs, label_dict)
        set_vprops!(pg, v, label=Html(join(label)), shape="plain")
    end
    for e in parts(acs, :E)
        label = make_edge_label_dict[labels](e, acs, label_dict)
        set_eprops!(pg, e, label=Html(join(label)), shape="plain")
    end
    return pg
end

Finally, we may visualize the data which parameterizes the optimization model.

to_graphviz(make_property_graph(multinet_acs, labels=:parameters, graph_attrs=Dict(:rankdir=>"TD")))

Optimization model in JuMP

Now we are ready to write the optimization model itself. We take a different approach and write methods that will add the appropriate decision variables, constraints, and objective to the ACSet. Each of them takes as argument the ACSet object and the JuMP model.

"""
Adds `s` and `x`, decision variables for how much supply to procure of a product at each vertex,
and how much of each product to ship along edges.
"""
function add_variables!(acs, model)
    acs[:, :s] = @variable(model, 0 ≤ s[i=parts(acs, :CommodityVertex)] ≤ acs[i, :supplycap])
    acs[:, :x] = @variable(model, 0 ≤ x[i=parts(acs, :Shipping)])
end

"""
Add constraints to respect total flow capacity of all products along each edge.
"""
function add_flow_constraint!(acs, model)
    for i in parts(acs, :E)
        @constraint(
            model,
            sum(acs[incident(acs, i, :s_e), :x]) ≤ acs[i, :flowcap]
        )
    end
end

"""
Add constraint that, for each product, vertex pair, the supply plus inbound
shipping, minus outbound shipping, must equal the demand.
"""
function add_conservation_constraint!(acs, model)
    for i in parts(acs, :CommodityVertex)
        v = acs[i, :cv_v]
        p = acs[i, :cv_c]

        # inbound shipping
        inbound = intersect(incident(acs, v, (:s_e, :tgt)), incident(acs, p, :s_p))

        # outbound shipping
        outbound = intersect(incident(acs, v, (:s_e, :src)), incident(acs, p, :s_p))

        @constraint(
            model,
            acs[i, :s] + 
                sum(acs[inbound, :x], init=zero(JuMP.VariableRef)) - 
                sum(acs[outbound, :x], init=zero(JuMP.VariableRef)) == acs[i, :demand]
        )
    end
end

"""
Minimize costs of shipping and costs of purchase
"""
function add_objective!(acs, model)
    @objective(
        model, Min,
        sum(acs[:, :shipcost] .* acs[:, :x]) + 
            sum(acs[:, :purcost] .* acs[:, :s])
    )
end

Finally we are ready to generate and solve the model. We import HiGHS which contains the solvers we will use. We can then add the decision variables, constraints, and objective to the model, and solve it. We then copy the optimized values of the decision variables into the acset, and visualize the solution.

# make the JuMP model
using HiGHS

model = JuMP.Model(HiGHS.Optimizer)
set_silent(model)

add_variables!(multinet_acs, model)
add_flow_constraint!(multinet_acs, model)
add_conservation_constraint!(multinet_acs, model)
add_objective!(multinet_acs, model)

optimize!(model)

to_graphviz(make_property_graph(multinet_acs, labels=:optim, graph_attrs=Dict(:rankdir=>"TD")))

We may format the solution in the same way as the original tutorial to confirm that they are the same.

"""
Format optimized decision variables for comparison. 
"""
function format_output(acs)
    df_solution_flow = DataFrame(tables(acs).Shipping)
    df_solution_flow.x = JuMP.value.(df_solution_flow.x)
    df_solution_flow = df_solution_flow[df_solution_flow.x .> 0.0, :]
    df_solution_flow.origin = acs[df_solution_flow.s_e, (:src, :vlabel)]
    df_solution_flow.destination = acs[df_solution_flow.s_e, (:tgt, :vlabel)]
    df_solution_flow.product = acs[df_solution_flow.s_p, :plabel]
    select!(df_solution_flow, Not([:s_p,:s_e,:shipcost]))
    rename!(df_solution_flow, Dict(:x => :x_flow))
    return df_solution_flow
end

format_output(multinet_acs)

I hope that this post has shown you how ACSets can helpfully structure optimization problems, joining data with the mathematical model in a single data structure, especially those models which can be represented as elaborations of graphs (of which there are many)!

Set interfaces

We saw the interface for ThSet in the previous post. Let’s reproduce it here:

@theory ThSet begin
  X::TYPE
  Bool′::TYPE{Bool}
  contains(elem::X)::Bool′
end

Any implementation of ThSet must pick a Julia datatype for its elements, and we name this type X. However, the set might be smaller than the entire type. So, part of the data one must always provide, in order to implement ThSet, is a membership predicate, contains. This evaluates to true for the elements of the Julia type X which are actually in the set.

Now we define a Julia type, SetOb, which wraps arbitrary implementations of the theory of sets:

ThSet.Meta.@wrapper SetOb # `Set` already claimed by Julia!

Our predicate contains only accepts arguments which were of the right Julia type, but we can overload the in method to be more permissive: it returns false if the input was not of the right type rather than throwing a MethodNotFound error.

Base.in(x, set::AbsSet) = try 
  ThFinSet.contains(set, x)
catch e 
  e isa MethodError || throw(e)
  false
end

Next we consider how ThFinSet extends this theory with a Julia iterator¹ and an integer cardinality, i.e. a length.

@theory ThFinSet <: ThSet begin
  Int′::TYPE{Int}
  Any′::TYPE{Any}
  length()::Int′
  iterator()::Any′ # length(collect(iterator()) == length()
end

ThFinSet.Meta.@wrapper FinSet

const AbsSet = Union{SetOb, FinSet} # `AbstractSet` already claimed by Julia!

Now, when you receive a FinSet, you know you have something which you can check for membership, get the length, and iterate over. There are no type parameters, in contrast to old Catlab:

abstract type FinSet{S,T} <: SetOb{T} end # OLD CATLAB

This extra type parameter S was needed because we wanted different code to be executed when we were working in versus when we happened to have some other type of set with Int elements. This is an example of complicated type acrobatics needed to work directly with multiple dispatch, in contrast to the model-based approach taken in the refactored code.

Set implementations

The theories of sets and finite sets will make more sense if you see some examples of implementations of them. Some of these are shown below:

""" 
Unbiased Cartesian product. `S` is either SetOb or FinSet. 
`T` is the type of the tuple elements.
"""
struct ProdSet{S<:AbsSet, T}
  sets::Vector{S}
  ProdSet(sets::Vector{S}) where {S<:AbsSet} = 
    new{S, Tuple{eltype.(sets)...}}(sets)
end

# Common method for ThSet and ThFinSet implementations
contains_set(model::ProdSet{<:Any, T}, i::T) = 
  all(e ∈ s for (s, e) in zip(model.sets, i))

@instance ThSet{T} [model::ProdSet{SetOb,T}] where T begin
  contains(i::T)::Bool = contains_set(model, i)
end

@instance ThFinSet{T} [model::ProdSet{FinSet,T}] where T begin
  contains(i::T)::Bool = contains_set(model, i)
  length()::Int = prod(length.(model.sets))
  iterator()::Any = Iterators.product(model.sets...)
end

struct FinSetInt
  n::Int
end 

@instance ThFinSet{Int} [model::FinSetInt] begin
  contains(i::Int)::Bool = 0 < i ≤ model.n
  length()::Int = model.n
  iterator()::Any = 1:model.n
end

struct SingletonSet end 

@instance ThFinSet{Nothing} [model::SingletonSet] begin
  contains(::Nothing)::Bool = true
  length()::Int = 1
  iterator()::Any = [nothing]
end

struct EmptySet end 

@instance ThFinSet{Union{}} [model::EmptySet] begin
  contains(::Union{})::Bool = false
  length()::Int = 0
  iterator()::Any = Union{}[]
end

Default implementations

Suppose I want a TypeSet, which in the previous post we saw is a particular implementation of ThSet that is specified by Julia type.

string_set = SetOb(TypeSet(String))
int_set = SetOb(TypeSet(Int))

In old Catlab, one simply writes TypeSet(String) and gets a SetOb; this is because we used to have TypeSet <: SetOb. That is no longer the case, so it seems like we’ve lost something; we have to do this tedious wrapping if we want to use TypeSet(String) as the codom of a function, since the function is expecting a model wrapped in a smart constructor, not a raw model (which could be any Julia type).

However, in all honesty, how many different implementations of SetOb are there? (not many) And how many of them simply take in a Julia type as their only data? (just one). Thus we should feel entitled to define the following shortcut:

""" Default model for a Set made out of a Julia `Type` """
SetOb(T::Type) = SetOb(TypeSet{T}())

Now it is just as easy as before (though we use SetOb rather than TypeSet):

string_set = SetOb(String)
int_set = SetOb(Int)

The general lesson is: if there is a ‘canonical’ implementation for some given data, we can define a method for the wrapper type to simply take in that data, call the canonical implementation on the data and then wrap that. This pattern for model wrapper types gets used all the time throughout the refactor. Another example would be:

FinSet(::Nothing) = FinSet(SingletonSet())

There are times where there isn’t a canonical implementation. Consider:

FinSet(s1::FinSet, s2::FinSet) = ...

We should not define a such a method. Do we want the product? The disjoint union? In those cases we really ought be explicit about which implementation we intend.

Function interfaces

Let’s look at the theory for functions in the new Catlab refactor, starting with a core theory shared by SetFunction, FinFunction, and FinDomFunction:

@theory ThFunctionCore begin
  Dom::TYPE
  Cod::TYPE
  app(e::Dom)::Cod
end

The ThFunctionCore interface states that we require function implementations to apply a function to some Julia type Dom to get elements of some other Julia type Codom.

abstract type SetFunction′ end # *only* subtyped by SetFunction

@theory ThSetFunction <: ThFunctionCore begin
  Fun′::TYPE{SetFunction′}
  DomSet::TYPE{SetOb}
  CodSet::TYPE{SetOb}
  dom()::DomSet # eltype(dom()) <: Dom
  codom()::CodSet # eltype(codom()) <: Cod
  postcompose(t::Fun′)::Fun′
end

ThSetFunction.Meta.@wrapper SetFunction

Implementations of the theory of ThSetFunction can be understand as morphisms in . For these we require that one must supply a (co)domain SetOb⁴ and be able to postcompose another function. When we eventually compose these SetFunctions (in ), the immediate result will be a sequence of functions. However, for performance considerations, we’ll want to be able to evaluate this sequence into a single SetFunction (via a force method which calls the underlying postcompose methods). Being able to repeatedly post-compose the first function in such a sequence is sufficient for this task and is often a more natural choice than precomposing.⁵

We can overload the call syntax of Julia to use the app function.

(f::SetFunction)(x) = ThSetFunction.app(f, x)

The theory of functions, now thought of as living in , is very similar:

abstract type FinFunction′ end # *only* subtyped by FinFunction

@theory ThFinFunction <: ThFunctionCore begin
  Fun′::TYPE{FinFunction′}
  DomSet::TYPE{FinSet}
  CodSet::TYPE{FinSet}
  dom()::DomSet # eltype(dom()) <: Dom
  codom()::CodSet # eltype(codom()) <: Cod
  postcompose(t::Fun′)::Fun′
end

ThFinFunction.Meta.@wrapper FinFunction <: FinFunction′

Note in both cases we did use an abstract type to avoid a chicken-egg problem: in the theory of finite functions we need to refer to the wrapper type for models of the theory of finite functions (which we can’t really define until the theory has been defined). Because only FinFunction type subtypes FinFunction′, we can treat the two types as equivalent.

The theory for a FinDomFunction is similar, where DomSet must be a FinSet but CodSet must be a SetOb.

Function instances

Let’s see a couple models of these theories to get a sense of them:

struct IdentityFunction{S<:AbsSet, T}
  set::S
  IdentityFunction(d::S) where S<:AbsSet = new{S, eltype(d)}(d)
end

@instance ThFinFunction{T,T} [model::IdentityFunction{FinSet, T}] where T begin
  dom()::FinSet = model.set
  codom()::FinSet = model.set
  app(i::T)::T = i
  postcompose(f::FinFunction′)::FinFunction′ = f
end

@instance ThSetFunction{T,T} [model::IdentityFunction{SetOb,T}] where T begin
  dom()::SetOb = model.set
  codom()::SetOb = model.set
  app(i::T)::T = i
  postcompose(f::SetFunction′)::SetFunction′ = f
end

struct FinFunctionVector{S<:AbsSet,T}
  val::AbstractVector
  codom::S
  FinFunctionVector(val::AbstractVector,codom::S) where {S<:AbsSet} =
    new{S,eltype(codom)}(val, codom)
end

@instance ThFinFunction{Int,T} [model::FinFunctionVector{FinSet,T}] where T begin
  dom()::FinSet = FinSet(length(model.val))
  codom()::FinSet = model.codom
  app(i::Int)::T = model.val[i]
  postcompose(f::FinFunction′)::FinFunction′ =
    FinFunction(FinFunctionVector(f.(model.val), codom(f)))
end

@instance ThFinDomFunction{Int,T} [model::FinFunctionVector{SetOb,T}] where T begin
  dom()::FinSet = FinSet(length(model.val))
  codom()::SetOb = model.codom
  app(i::Int)::T = model.val[i]
  postcompose(f::SetFunction)::FinDomFunction =
    FinDomFunction(FinFunctionVector(f.(model.val), codom(f)))
end

File structure and future posts

The v0.16 to v0.17 refactor is concentrated on Catlab’s CategoricalAlgebra module. This was a folder with about 15 files in it, including FinCats (826 Lines Of Code), FinSets (1507 LOC), CSets (1418 LOC), FunctorialDataMigrations (456 LOC).

In the refactored version, these large files have been broken down into smaller ones which for the most part either declare a theory or declare a data structure and show how that data structure is a model of various theories. Another major structural change is to subdivide this into a sequence of modules:

1. Cats (general machinery for categories, functors, limits, etc.)
2. SetCats (specializing machinery in Cats to Set-like categories, including FinSet)
3. Pointwise (specializing machinery in Cats to -Set-like categories, such as ACSets and VarACSets).

We’ll cover these in a follow-up blog post!

Multiple dispatch vs explicit interfaces with GATlab

The key concept underlying this change is a contrast between two strategies for controlling what method gets executed when you type something like compose(x,y). Julia is ultimately governed by a strategy called multiple dispatch. One is allowed to define the following:

# objects are sets {1,2,...,n}
# morphisms n->m are functions, expressed as vectors of length n
id(x::Int)::Vector{Int} = 1:i
compose(f::Vector{Int}, g::Vector{Int})::Vector{Int} = g[f]
dom(f::Vector{Int}) = length(f)

# there is one object (`nothing` of the unit type, `Nothing`)
# morphisms are lists of things
id(x::Nothing)::Vector = []
compose(f::Vector, g::Vector)::Vector = [f..., g...]
dom(f::Vector)::Nothing = nothing

Which code gets executed when you call compose(x,y) depends on the type of the arguments x and y. A problem occurs when two different categories have the same objects:

id(x::Int)::Matrix = I(x) # identity matrix
compose(f::Matrix,g::Matrix)::Matrix = f*g # matrix multiplication
dom(f::Matrix)::Int = first(size(f)) # number of rows

However, now we’ve defined id(x::Int) twice, a problem which Julia will warn us about. We can circumvent this limitation in two ways. The first is to use a wrapper type:

# Just an integer, but formally a different type 
# so multiple dispatch can treat it differently
struct MatrixOb
  val::Int 
end 

id(x::MatrixOb) = I(x.val)
dom(f::Matrix) = MatrixOb(first(size(f)))

This is common design pattern in Julia, advertised in the earliest work on the language, and Catlab has often taken this approach. However, it can become very inconvenient. In order to have fine-grained control over the dispatch, Catlab was forced to promote an unwieldy amount of information into the type parameters of its data structures.

Another strategy to address this problem is to control dispatch by using an extra argument parameter, a strategy known as “Holy traits” in Julia. For technical reasons, we call such a parameter a model (of a theory). Such parameters are often singleton types, like below:

struct FinSetCat end # a model

id(::FinSetCat, x::Int) = 1:i
compose(::FinSetCat, f::Vector{Int}, g::Vector{Int}) = g[f]
dom(::FinSetCat, f::Vector{Int}) = length(f)

struct MatrixCat end # a model

id(::MatrixCat, x::Int) = I(x)
compose(::MatrixCat, f::Matrix,g::Matrix) = f*g 
dom(::MatrixCat, f::Matrix) = first(size(f))

# model parameter used to control multiple dispatch
id(FinSetCat(), 4) == [1,2,3,4] 
id(MatrixCat(), 2) == [1 0; 0 1]

An advantage of the latter approach is that it captures the fact that the collection of methods id, compose, dom, etc. are grouped together into some cohesive unit (in other languages, this would be an interface or a typeclass). GATlab.jl allows us to make these groupings of methods explicit via GATs (generalized algebraic theories), which play the role of interfaces:

@theory ThCategory begin
  # Syntactic sugar
  @op begin
    (→) := Hom
    (⋅) := compose
  end
  
  # Types 
  Ob::TYPE
  Hom(dom::Ob, codom::Ob)::TYPE
  
  # Operations
  id(A::Ob)::(A → A)
  compose(f::(A → B), g::(B → C))::(A → C) ⊣ [A::Ob, B::Ob, C::Ob]
  
  # Laws that the operations must satisfy
  (f ⋅ g) ⋅ h == f ⋅ (g ⋅ h) ⊣ [A::Ob, B::Ob, C::Ob, D::Ob,
                                f::(A → B), g::(B → C), h::(C → D)]
  f ⋅ id(B) == f ⊣ [A::Ob, B::Ob, f::(A → B)]
  id(A) ⋅ f == f ⊣ [A::Ob, B::Ob, f::(A → B)]
end

GATlab also provides an @instance macro to allow declaring a particular model for a theory:

@instance ThCategory{Ob=Int, Hom=Vector{Int}} [model::MatrixCat] begin 
  id(x::MatrixOb) = I(x.val)
  compose(f::Matrix,g::Matrix)::Matrix = f*g 
  dom(f::Matrix)::MatrixOb = first(size(f))
  codom(f::Matrix)::MatrixOb = last(size(f))) 
end

Here the @instance macro is handling lots of boilerplate; most importantly it defines the methods which have MatrixCat as its first parameter, throwing an error if any operations have not been provided. Additionally, a getindex method is generated to allow for passing in a model as the first parameter:

id[MatrixCat()](2) == id(WithModel(MatrixCat()), 1) == [1 0; 0 1]

The WithModel wrapper is owned by GATlab and helps us distinguish when a Julia value is used as a model rather than as a piece of data.

In summary, the major refactor of Catlab is a major shift away from type dispatch via intricate types and towards using explicit interfaces and models. Although Julia doesn’t provide a built-in notion of interface, with the help of Julia’s macro system, we can create an ergonomic interface system via a library.

Wrapped models

GATlab allows us to declare that some Julia type M is a model of some theory T. Once we do this, we can write code that takes in both raw data and models which guide how to process that data:

""" Expects `model` to be an instance of `ThCategory` """
function compose_three(model, x, y, z)
  compose[model](compose[model](x,y), z)
end

We could make our assumptions more explicit (and get better errors than MethodNotFound) if we do the following:

function compose_three(model, x::H, y::H, z::H) where {H}
  implements(model, ThCategory, [Union{}, H]) || error(
    "Model $model doesn't implement ThCategory with homs of type $H")
  
  compose[model](compose[model](x,y), z)
end

implements is provided by GATlab.¹ However, we can do better with smart constructors - for example:

struct Category{Ob,Hom}
  model::Any 
  function Category(model)
    implements(model, ThCategory) || error("Bad model $model")
    new{O,H}(model)
  end
end

compose(c::Category, f, g) = compose[c.model](f, g)
# etc, for other methods

Now we can write a well-typed function which will not have any runtime errors:

compose_three(model::Category{O,H}, x::H, y::H, z::H) where {O,H} =
  compose(model, compose(model, x,y), z)

Trying to use a Julia value that isn’t a model of ThCategory will be caught earlier, whenever we tried to wrap it in the Category smart constructor. GATlab can automatically generate two wrapper types for any GAT (a version which has type parameters and one which has no type parameters).

The Catlab refactor uses these smart constructors when possible, but there is one scenario in which the former ‘risky’ strategy is used: a Julia value can be a model of multiple theories. What if our function needs to take in such a model with the intent of using it for T₁,T₂, and T₃? Until we have a wrapper for the union of these theories it’s more convenient to just pass in the ‘raw’ model and use it as a model of various theories:

function example(model, a, b, c)
  T₁.op1[model](a) * T₂.op2[model](b) - T₃.op3[model](c)
end

The best way to address this is to glue the theories together T = T₁+T₂+T₃ (formally a pushout, which allows one to coherently do “multiple-inheritance” of interfaces) and make a wrapper type for theory T. As our theory morphism² infrastructure becomes more robust, we can rely less on the risky workaround and use this as the preferred solution.

GATs with fixed Julia types

A model of a theory assigns a Julia type for each type constructor of the theory (e.g. {Ob = Int, Hom = Matrix}). Sometimes we know at the time we’re writing our theory that we have a particular Julia type in mind for a type constructor. GATlab provides the syntax MyTypeCon::TYPE{MyJuliaType} within a @theory declaration to allow one to make explicit that all models of the theory should send the type constructor MyTypeCon to the julia type MyJuliaType.

For example, Catlab has a DiscreteDiagram type which wraps a vector of objects in some category. Any model which implements the below interface is a means of taking a discrete diagram into a AbstractColimit and applying the universal property of that colimit to a cocone (i.e. multi-cospan) to obtain a hom from the apex of the colimit into the apex of the cocone.

@theory ThCategoryUnbiasedCoproducts <: ThCategoryColimitBase begin
  DiscDiag::TYPE{DiscreteDiagram}

  colimit(d::DiscDiag)::Colimit
  universal(Σ::Colimit, d::DiscDiag, csp::MCospan)::(ob(Σ) → apex(csp))
end

# Note: `ThCategoryColimitBase <: ThCategory` fixes 
#       `Colimit` to the Julia type `AbstractColimit` and
#       `MCospan` to the Julia type `Multicospan`

Without asserting various types of this theory should be sent to specific Julia types, the semantics of what colimit means would only be constrained by documentation (it could be some arbitrary function between arbitrary types). As GATlab develops, a more expressive language for expressing theories could eventually allow for encoding richer constraints into the GAT itself (e.g. support for variadic arguments), and then we could rely less on fixing particular Julia types.

Putting it all together: handling sets in Catlab

To help solidify the abstract topics above, let’s compare how old and new Catlab handle the concept of a set. In old Catlab, we have SetOb as an abstract type. Subtypes of SetOb are expected to have certain methods defined for them, though this isn’t made explicit anywhere!

abstract type SetOb{T} end

Base.eltype(::Type{<:SetOb{T}}) where T = T

""" A Julia data type regarded as a set. """
struct TypeSet{T} <: SetOb{T} end

Base.in(elem,::TypeSet{T}) where T = isa(elem,T)

""" A bool-valued function tests membership in the set """
struct PredicatedSet{T} <: SetOb{T}
  predicate::Any
end

function Base.in(s::PredicatedSet{T}, x::T)::Bool where {T}
  s.predicate(x)
end

Here the abstract type SetOb is the interface. Just like with AbstractVector and other abstract types in Julia’s standard library, one’s best hope is to delve into documentation to know which methods are mandatory, which are optional, and which are derived from other interfaces. Whether or not one has implemented the interface appropriately cannot be checked at the time of declaring that a type implements the interface.

From the new perspective, there was a theory (i.e. interface) that should have been made explicit.

@theory ThSet begin
  Bool′::TYPE{Bool}
  Any′::TYPE{Any}
  contains(e::Any′)::Bool′
  eltype()::Any′
end

# Wrapper type
ThSet.Meta.@wrapper SetOb <: AbsSet

We reproduce the old behavior by making two models for that theory.

struct TypeSet{T} end

@instance ThSet [model::TypeSet{T}] where T begin
  contains(i::Any)::Bool = i isa T
  eltype()::Any = T
end

struct PredicatedSet{T}
  predicate::Any
end

@instance ThSet [model::PredicatedSet{T}] where T begin
  contains(i::Any)::Bool = i isa T && model.predicate(i)
  eltype()::Any = T
end

If our model is not a zero-field struct, it might have some actual data inside of it that is relevant. In this case, we can refer to the model (which is implicitly the first argument for the functions defined within an @instance) with the name model, as was done above for model.predicate(i).

We no longer have the T element type parameter for SetOb. This was needed in old Catlab because a lot of code would dispatch on that T parameter (e.g. limits and colimits - thus implicitly presupposing a particular ThCategory model for objects of that type).

Stay tuned for future posts which will walk through key parts of the Catlab refactor!

The IJKLM model

In a blog post on the GAMS blog, a comparison was made between several open source modeling languages including JuMP, and GAMS. The initial JuMP implementation saw poor performance due to inefficient Julia code. The JuMP dev team responded with their own blog post on the JuMP website, using a fast solution based on DataFrames.jl. In this post we will see how to use tools from AlgebraicJulia to accomplish the example modeling task. The original data and code is at justine18/performance_experiment.

The model is given as:

The GAMS blog post calls subsets of Cartesian products “maps”, but we will use the standard term “relations” for subsets of n-ary products.

Data generation

First we load some packages. DataFrames for data frames, Distributions for sampling binomial random variates, JuMP to set up the model, and HiGHS for a solver. Catlab and DataMigrations are the two AlgebraicJulia packages we will use.

using DataFrames
using Distributions
using JuMP, HiGHS
using Catlab, DataMigrations
using BenchmarkTools

The first step is to generate synthetic data according to the method from the original repo. The probability of all zeros with the given model sizes is incomprehensibly small but there is a check for it anyway. Maybe a cosmic ray will pass through your processor at a bad time.

Like the original code, the sets are vectors of strings. There are 3 relations which are “sparse” subsets of the corresponding products, .

SampleBinomialVec = function(A,B,C,p=0.05)
    vec = rand(Binomial(1, p), length(A) * length(B) * length(C))
    while sum(vec) == 0
        vec = rand(Binomial(1, p), length(A) * length(B) * length(C))
    end
    return vec
end

n=100 # something large
m=20 # 20

# Sets IJKLM 
I = ["i$x" for x in 1:n]
J = ["j$x" for x in 1:m]
K = ["k$x" for x in 1:m]
L = ["l$x" for x in 1:m]
M = ["m$x" for x in 1:m]

# make IJK
IJK = DataFrame(Iterators.product(I,J,K))
rename!(IJK, [:i,:j,:k])
IJK.value = SampleBinomialVec(I,J,K)
filter!(:value => v -> v != 0, IJK)
select!(IJK, Not(:value))

# make JKL
JKL = DataFrame(Iterators.product(J,K,L))
rename!(JKL, [:j,:k,:l])
JKL.value = SampleBinomialVec(J,K,L)
filter!(:value => v -> v != 0, JKL)
select!(JKL, Not(:value))

# make KLM
KLM = DataFrame(Iterators.product(K,L,M))
rename!(KLM, [:k,:l,:m])
KLM.value = SampleBinomialVec(K,L,M)
filter!(:value => v -> v != 0, KLM)
select!(KLM, Not(:value))

The “intuitive” formulation

As given in the original GAMS blog post, this is the naive formulation that relies on nested for loops. As remarked in the JuMP blog, this is equivalent to taking two inner joins. Another way to look at it is as finding “paths” through the relations, such that they match on common elements. Each formulation will be benchmarked.

@benchmark let 
    x_list = [
        (i, j, k, l, m)
        for (i, j, k) in eachrow(IJK)
        for (jj, kk, l) in eachrow(JKL) if jj == j && kk == k
        for (kkk, ll, m) in eachrow(KLM) if kkk == k && ll == l
    ]
    model = JuMP.Model()
    set_silent(model)
    @variable(model, x[x_list] >= 0)
    @constraint(
        model,
        [i in I], 
        sum(x[k] for k in x_list if k[1] == i) >= 0
    )
end

BenchmarkTools.Trial: 13 samples with 1 evaluation per sample.
 Range (min … max):  400.831 ms … 415.654 ms  ┊ GC (min … max): 2.45% … 4.53%
 Time  (median):     410.973 ms               ┊ GC (median):    4.86%
 Time  (mean ± σ):   409.814 ms ±   3.953 ms  ┊ GC (mean ± σ):  4.43% ± 0.80%

  ▁         ▁                ▁     ▁      ▁█▁▁▁▁   ▁          ▁  
  █▁▁▁▁▁▁▁▁▁█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█▁▁▁▁▁█▁▁▁▁▁▁██████▁▁▁█▁▁▁▁▁▁▁▁▁▁█ ▁
  401 ms           Histogram: frequency by time          416 ms <

 Memory estimate: 233.84 MiB, allocs estimate: 6081245.

The DataFrames version

The JuMP blog authors used a version based on two inner joins to vastly improve computation speed.

ijklm_df = DataFrames.innerjoin(
    DataFrames.innerjoin(IJK, JKL; on = [:j, :k]),
    KLM;
    on = [:k, :l],
)

@benchmark let
    ijklm = DataFrames.innerjoin(
        DataFrames.innerjoin(IJK, JKL; on = [:j, :k]),
        KLM;
        on = [:k, :l],
    )
    model = JuMP.Model()
    set_silent(model)
    ijklm[!, :x] = @variable(model, x[1:size(ijklm, 1)] >= 0)
    for df in DataFrames.groupby(ijklm, :i)
        @constraint(model, sum(df.x) >= 0)
    end
end

BenchmarkTools.Trial: 6197 samples with 1 evaluation per sample.
 Range (min … max):  671.750 μs …   5.711 ms  ┊ GC (min … max):  0.00% … 85.60%
 Time  (median):     708.000 μs               ┊ GC (median):     0.00%
 Time  (mean ± σ):   805.644 μs ± 387.005 μs  ┊ GC (mean ± σ):  10.99% ± 15.37%

  █▇▆▄▃▂▁                                                       ▁
  ███████▇▆▅▅▅▁▃▁▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▅▆▇▇████▇▇█▇▇▇▇▇▆▇ █
  672 μs        Histogram: log(frequency) by time       2.42 ms <

 Memory estimate: 1.69 MiB, allocs estimate: 17264.

The Acsets version

Acsets (Attributed C-Sets) are a categorical data structure provided in the ACSets.jl library, and imported and extended with machinery from applied category theory in Catlab.jl. One of the advantages of using acsets and categorical machinery in general is that they have a natural graphical presentation, which in many cases is very readable and illuminating. If this is your first exposure to acsets, a gentle introduction can be found at Graphs and C-sets I: What is a graph?.

We use @present to make a schema for the acset which will store the data. Note that each “set” has turned into an object in the schema, and that the relations are also objects. There are projections (homs) from the relations into the sets which are involved in each relation.

@present IJKLMSch(FreeSchema) begin
    (I,J,K,L,M,IJK,JKL,KLM)::Ob
    IJK_I::Hom(IJK,I)
    IJK_J::Hom(IJK,J)
    IJK_K::Hom(IJK,K)
    JKL_J::Hom(JKL,J)
    JKL_K::Hom(JKL,K)
    JKL_L::Hom(JKL,L)
    KLM_K::Hom(KLM,K)
    KLM_L::Hom(KLM,L)
    KLM_M::Hom(KLM,M)
end

Catlab.to_graphviz(IJKLMSch, graph_attrs=Dict(:dpi=>"72",:ratio=>"expand",:size=>"8"))

Using @acset_type will programatically generate a data type and methods specific to the schema provided. We then use @acset to build a data instance on our schema.

@acset_type IJKLMData(IJKLMSch, index=[:IJK_I,:IJK_J,:IJK_K,:JKL_J,:JKL_K,:JKL_L,:KLM_K,:KLM_L,:KLM_M])

ijklm_acs = @acset IJKLMData begin
    I = n
    J = m
    K = m
    L = m
    M = m

    IJK = nrow(IJK)
    IJK_I = [parse(Int, i[2:end]) for i in IJK.i]
    IJK_J = [parse(Int, j[2:end]) for j in IJK.j]
    IJK_K = [parse(Int, k[2:end]) for k in IJK.k]

    JKL = nrow(JKL)
    JKL_J = [parse(Int, j[2:end]) for j in JKL.j]
    JKL_K = [parse(Int, k[2:end]) for k in JKL.k]
    JKL_L = [parse(Int, l[2:end]) for l in JKL.l]

    KLM = nrow(KLM)
    KLM_K = [parse(Int, k[2:end]) for k in KLM.k]
    KLM_L = [parse(Int, l[2:end]) for l in KLM.l]
    KLM_M = [parse(Int, m[2:end]) for m in KLM.m]
end

connected_paths_query = @relation (i=i,j=j,k=k,l=l,m=m) begin
    IJK(IJK_I=i, IJK_J=j, IJK_K=k)
    JKL(JKL_J=j, JKL_K=k, JKL_L=l)
    KLM(KLM_K=k, KLM_L=l, KLM_M=m)
end

Catlab.to_graphviz(connected_paths_query, box_labels=:name, junction_labels=:variable, graph_attrs=Dict(:dpi=>"72",:size=>"3.5",:ratio=>"expand"))

ijklm_query = query(ijklm_acs, connected_paths_query)
size(ijklm_query) == size(ijklm_df)

true

@benchmark let
    ijklm = query(ijklm_acs, connected_paths_query)
    model = JuMP.Model()
    set_silent(model)
    ijklm[!, :x] = @variable(model, x[1:size(ijklm, 1)] >= 0)
    for df in DataFrames.groupby(ijklm, :i)
        @constraint(model, sum(df.x) >= 0)
    end
end

BenchmarkTools.Trial: 4282 samples with 1 evaluation per sample.
 Range (min … max):  902.250 μs …  18.836 ms  ┊ GC (min … max):  0.00% … 92.54%
 Time  (median):     971.458 μs               ┊ GC (median):     0.00%
 Time  (mean ± σ):     1.166 ms ± 797.132 μs  ┊ GC (mean ± σ):  14.59% ± 16.74%

  ██▆▄▃▃▁                                                       ▁
  ███████▇▄▁▁▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▃▁▆▇▆▇▇█▇██▇▇█▇▇▇▆▆ █
  902 μs        Histogram: log(frequency) by time       3.92 ms <

 Memory estimate: 2.53 MiB, allocs estimate: 23908.

@present IJKLMRelSch(FreeSchema) begin
    (IJKLM,I,J,K,L,M)::Ob
    i::Hom(IJKLM,I)
    j::Hom(IJKLM,J)
    k::Hom(IJKLM,K)
    l::Hom(IJKLM,L)
    m::Hom(IJKLM,M)
end

@acset_type IJKLMRelType(IJKLMRelSch)

Catlab.to_graphviz(IJKLMRelSch, graph_attrs=Dict(:dpi=>"72",:ratio=>"expand",:size=>"3.5"))

M = @migration IJKLMRelSch IJKLMSch begin
    IJKLM => @join begin
        ijk::IJK
        jkl::JKL
        klm::KLM
        i::I
        j::J
        k::K
        l::L
        m::M
        IJK_I(ijk) == i
        IJK_J(ijk) == j
        JKL_J(jkl) == j
        IJK_K(ijk) == k
        JKL_K(jkl) == k
        KLM_K(klm) == k
        JKL_L(jkl) == l
        KLM_L(klm) == l
        KLM_M(klm) == m
    end
    I => I
    J => J
    K => K
    L => L
    M => M
    i => i
    j => j
    k => k
    l => l
    m => m
end;

F = functor(M)
to_graphviz(F.ob_map[:IJKLM],node_labels=true)

ijklm_migrate_acset = migrate(IJKLMRelType, ijklm_acs, M)
nparts(ijklm_migrate_acset, :IJKLM) == size(ijklm_query,1)

true

@benchmark let
    ijklm = migrate(IJKLMRelType, ijklm_acs, M)
    model = JuMP.Model()
    set_silent(model)
    @variable(model, x[parts(ijklm, :IJKLM)] >= 0)
    for i in parts(ijklm, :I)
        @constraint(model, sum(x[incident(ijklm, i, :i)]) >= 0)
    end
end

BenchmarkTools.Trial: 1774 samples with 1 evaluation per sample.
 Range (min … max):  2.088 ms … 33.095 ms  ┊ GC (min … max):  0.00% … 91.29%
 Time  (median):     2.424 ms              ┊ GC (median):     0.00%
 Time  (mean ± σ):   2.814 ms ±  1.381 ms  ┊ GC (mean ± σ):  13.26% ± 17.61%

  ▄█▂▄▃▄▁                                                     
  ████████▆▅▄▃▃▃▂▂▂▂▂▂▂▂▂▂▂▁▂▂▂▁▂▂▁▁▂▁▁▂▁▂▂▃▃▃▃▃▃▃▃▃▃▂▃▂▂▂▂▂ ▃
  2.09 ms        Histogram: frequency by time        6.11 ms <

 Memory estimate: 6.91 MiB, allocs estimate: 48899.

Acknowledgements

I would like to thank Kevin Carlson for his assistance regarding DataMigrations.jl.

Use

WARNING: InterTypes is alpha-quality software, and not only are there certainly bugs but also the interface to it may change radically.

The core of InterTypes is the intertype schema, which declares a collection of types that can refer to one another. An intertype schema is a file ending in .it. Currently, we use the Julia parser to parse the .it file, and we use Julia to generate code for all languages. However, we hope to in the future to produce a standalone binary that will parse the .it file and generate the code in other languages. So although .it files look like Julia, most features of Julia will not work with in an intertype schema; for instance, you cannot define functions in an intertype schema, or refer to types that are defined outside of an intertype schema.

There are 4 fundamental building blocks of InterTypes.

1. Primitive types.

• Int32/Int64/UInt32/UInt64 for integer numbers. We have 32 bit and 64 bit integers, because only 32 bit integers are safe to put in JSON numbers and 64 bit integers must be put in JSON strings.
• Bool for booleans.
• Float64 for floating point numbers.
• String for strings.
• Symbol for symbols. In languages that don’t have symbols, this is the same as String.
• Vector{T} for representing sequences (arrays and lists) of type T
• Binary for sequences of raw bytes without a numeric interpretation. In Julia, this maps to Vector{UInt8}, but we think of it as a binary blob rather than a sequence of values.
• Dict{K,V} for representing dictionaries with key type K and value type V.

2. Structs. A struct has a list of fields and each field has a name and a type. This looks like:

struct Point2D
  x::Float64
  y::Float64
end

3. Sum types, also known as “tagged unions”. A sum type has a list of variants, and each variant is a record containing fields. This looks like

@sum Op begin
  Plus
  Mul
end

@sum Term begin
  Constant(val::Float64)
  App(op::Op, arg1::Term, arg2::Term)
end

4. ACSets. ACSets are handled a little differently than they work in Julia, in order to paper over the fact that I have yet to fully figure out Python’s (and pydantic’s, which is the validation/serialization framework) support for generic types. When you declare the schema, you have to specify a concrete type for every AttrType. Then, when you declare an instance of the schema, you do not get a generic instance like you do in Julia; you get an instance with attribute types fixed to the supplied types. This looks like:

struct EdgeData
  name::Symbol
  length::UInt64
end

@schema SchGraph begin
  (E,V)::Ob
  (src, tgt)::Hom(E, V)
end

@schema SchWeightedGraph <: SchGraph begin
  Weight::AttrType(EdgeData) # note that we provide a type here
  weight::Attr(E, Weight)
end

@abstract_acset_type AbstractGraph

@acset_type EDWeightedGraph(SchWeightedGraph,
                            generic=WeightedGraph, index=[:src, :tgt]) <: AbstractGraph

This is equivalent to the Julia code

struct EdgeData
  name::Symbol
  length::UInt64
end

@schema SchGraph begin
  (E,V)::Ob
  (src, tgt)::Hom(E, V)
end

@schema SchWeightedGraph <: SchGraph begin
  Weight::AttrType # note that there is no type here
  weight::Attr(E, Weight)
end

@abstract_acset_type AbstractGraph

@acset_type WeightedGraph(SchWeightedGraph, index=[:src, :tgt]) <: AbstractGraph

const EDWeightedGraph = WeightedGraph{EdgeData}

However in the Python code, no data structure with the name WeightedGraph is produced; only EDWeightedGraph. This is because the Python and Julia ACSets code were written pre-intertype, so their handling of attrtypes weren’t fully compatible, and we had to get something working; hopefully in the future Python and Julia will be more congruous. This is a good first issue for someone familiar with types in Python/pydantic!

To use an intertype schema, one “declares an intertype module” like so:

@intertypes "weightedgraph.it" module weightedgraph end

Then weightedgraph is a module that contains an export for each type defined in weightedgraph.it. It also contains a Meta variable, which stores the parsed intertype definition. This can then be used to write out generated python code, via

generate_python_module(weightedgraph, ".")

which writes a python file called weightedgraph.py in the current directory. This python file imports both acsets and intertypes, so in order to use it one must have the py-acsets library installed, and also a copy of intertypes.py, which can be produced with

write("intertypes.py", InterTypes.INTERTYPE_PYTHON_MODULE)

In a similar manner, a JSONSchema definition for the json produced by intertypes can be produced with

generate_jsonschema_module(weightedgraph, ".")

which writes a JSONSchema file called weightedgraph_schema.json in the current directory. This is a file which has a JSONSchema def for each type in the intertype definition file.

Intertype modules can refer to one another. For instance, we could write another file called twoweightedgraphs.it with contents of:

struct TwoWeightedGraphs
  g1::weightedgraph.EDWeightedGraph
  g2::weightedgraph.EDWeightedGraph
end

and then import it like:

@intertypes "twoweightedgraphs.it" module twoweightedgraphs
  import ..weightedgraph
end

In fact, weightedgraph.it and twoweightedgraphs.it could be in completely different packages; as long as the first package exports the weightedgraph Julia module this will work fine.

For more examples of how to use intertypes, it would probably be best to refer to the test file.

Future Work

There are a lot of directions I’m excited to take intertypes in.

First of all, I need to write more documentation beyond this blog post.

After that, I plan to add support for Scala, TypeScript, and Rust. Scala in particular would solve a lot of problems between AlgebraicJulia and Semagrams, so I’m going to tackle that next.

Thirdly, I’d like to think about integrating GATlab with InterType, so that scientific models with algebraic expressions in them can be first-class.

Longer down the road, I want to investigate combinatorial data structures beyond acsets, as laid out in array systems and combinatorial data structures via finite existential types, and also think about structured version control for intertypes in line with chit.

But finally, I want to use intertypes to make the vision at the beginning a reality, a vision where scientific models can be passed around between programming languages and stored in databases. This is beyond a technical vision; this is a social vision; I hope to reshape how people think about scientific models. If you are interested in this, please reach out on the category theory zulip, julia zulip, localcharts, or github issues.

Background

Scientists and engineers are often interested in representing the state of the world, . We might decide to encode this as the set of possible instances of a class,¹ or as the set of terms of an algebraic data type,² or as possible databases on a schema (i.e.  -sets). We are also often interested in encoding the transition , a relationship between one state of the world and the next one. If we can communicate this relationship to a computer, then we can execute simulations to see how hypothetical states of the world evolve over time. The question we explore in this post is: what is a good syntax for representing these kinds of functions? Some virtues that we will care about:

• It should be easy for an engineer to construct such functions from simpler ones.
• It should be easy to implement the simulator in a clean, elegant way that does not have complicated edge cases to handle.
• The syntax should be general, such that we can use the same code to perform, e.g., chemistry, robotics, or epidemiology simulations.
  
• It should be natural to generalize the output of the simulation (e.g. many possible outcomes, , or a probability distribution of outcomes, ) without changing much code.
• The structure of the representation should be transparent and introspectable:
  • We can write programs to check whether properties of interest hold (e.g.  will the program terminate on all inputs?).
  • Most importantly, if our representation of the world is fundamentally changed (suppose the world is better modeled by , rather than ), we can automatically convert our -simulator to a -simulator, given some high-level description of the relationship between and .

It is difficult to obtain many of these properties when one’s syntax for is an arbitrary datatype and one’s syntax for the relationship is just an arbitrary function in your programming language. However, we propose that the syntax of directed wiring diagrams organizing rewrite rules makes these properties more tractable. Although this post will focus on engineering, we can use category theory to describe in more detail what it really means to be a good syntax and show how we can interpret our directed wiring diagrams as agent-based models.

Theoretical underpinning

Conclusion

The virtues of this approach largely come from the fact that neither code nor arbitrary functions are in principle required to specify our dynamical system . Rather than arbitrary functions (which are hard to manipulate and reason about) being the input, we automatically generate our simulator program from static, graph-like data. While we happen do this in Julia, this could in principle be done in any language because our understanding of a graph rewriting program is mathematical, rather than dependent on implementation details. In collaborations involving multiple teams, it can be helpful that the data of these programs can be serialized in a language-agnostic way.

I have also personally found it immensely useful to be able to apply functorial data migration (see Spivak (2012)), e.g. swapping sheep and wolves, to allow high level reuse of programs in different contexts, which can be done cleanly and rigorously when one’s model is expressed via combinatorial data rather than low-level code.

Although there was not space to describe how all of the virtues listed in the introduction are facilitated by this formalism, I hope you’re intrigued by the possibility of structuring your model of the world’s dynamics in this formalism. Furthermore, I hope this case study in applied category theory encourages you to look into other kinds of scientific or engineering tasks can be made more scalable and maintainable through these kinds of abstractions.⁵

What’s a varacset?

Varacsets, short for “variable-equipped acsets”, allow for a supply of distinguishable variables from attribute types, which can be mapped to constants under acset morphisms. This should leave our rewrite rule looking something like this (with position variables omitted for brevity):

By allowing a set of distinguishable variables, which can explicitly be equal or not equal to each other, rather than merely extending the attribute type to include a wildcard element, , we can model a parallelogram with the leftmost acset, rather than an arbitrary quadrilateral.

Although we can visualize these varacsets as undirected graphs, varacsets on any schema can be viewed as a set of tables in its database representation:

What’s the category of varacsets?

Although the objects of acsets are the same as relational databases, they are much more powerful because we understand them as a category and can perform categorical constructions. Thus it’s important to understand how varacsets are a category such that we can find homomorphisms and compute (co)limits.

Defining the category

Let’s figure out what the category of varacsets looks like more precisely. Given a schema we start with a typing map which gives the values of each attribute type. Our full varacset should augment this data with combinatorial data over and a supply of variables over plus the actual attribute functions. Furthermore, we want to end up in a category where the morphisms fix the constants of each attribute type but move variables freely. This defines a category well enough, but its nature isn’t very clear.

Why a different approach from acsets is needed

Acsets as a slice category of -

In the original acsets paper, the authors proved that the category of acsets with attribute types determined by is equivalent to the slice category of over a certain functor closely related to . This characterization is very helpful in seeing that the category of acsets with fixed typing is friendly (indeed, a topos), but it’s not computationally usable, because the functor (a certain right Kan extension) is generally something badly infinite. But the most interesting computations we can do in AlgebraicJulia, such as acset homomorphism search, depend on looking at acsets whose values over are finite sets. In any case, this trick can’t be readily imported to our situation, because the analog of would depend on the variables present in each particular acset and not only on the schema.

Flipping the slice

While the collaginess of sure makes us want to think of being over in some sense, this is largely an illusion. What’s much more straightforward to formalize is a view of as under a relative of namely, the functor which adds empty values over to extend to all of

Indeed, the coslice category is awfully close to the category of acsets. Specifically, if you restrict to the full subcategory of the coslice spanned by maps from which are invertible over then this is equivalent to the category of acsets as defined above. Indeed, maps in have to leave the image of , i.e. our attribute values, put, but are just any old natural transformations on the rest of the functor, i.e. our combinatorial data.

For varacsets, we don’t want a coslice object which is iso over though. Instead, since we want to be able to add variables to our attribute types, we’d better relax at least to a mono. And that’s really all you have to do! The key observation is that variables in the attribute types behave precisely like combinatorial data: we can permute them around however we want without changing the meaning of an acset. This is basically the category we have implemented in AlgebraicJulia today: the full subcategory of on monomorphisms.

Final definition

The nicest definition of a category of varacsets with attribute types given by though, is simply the entire coslice category without the monicity restriction. One can imagine applications of the case where the coslice morphism is non-monic; for instance, such a varacset on the weighted graph schema would allow us to mix ordinary weighted graphs, with edges weighted in with “angled graphs”, with edges weighted in the circle, In this case, the component of the coslice structure map at the weights object would be the canonical projection from the line to the circle.

Is this good? Maybe! In any case, the full coslice category has much better mathematical properties than the mono-coslice category. We will show in the next section precautions we can take if we wish to maintain the monicity restriction in practice.

Conclusion

Varacsets, originally born out of practical engineering demands for rewriting with attributes, are put on much more stable footing by working out the above theoretical considerations. Just as acsets were not implemented as a slice category, varacsets demonstrate that the right mathematical model doesn’t have to be isomorphic to your implementation: understanding varacsets as a coslice (despite implementing them as a database) is helpful for informing us which operations make sense or do not make sense to perform on varacsets.

Although we focused on rewriting rules in this post, there are lots of other ways to apply attribute variables, e.g. when modeling systems in which some attribute data is unknown. This allows us to -migrate data with attributes (via a left Kan extension), as variables give us a universal way to assign attribute values to new data. We’re excited to push varacsets in other directions like this in the future!

Part 1: Open dynamical systems

We begin this post by talking about open dynamical systems. Open dynamical systems have been studied extensively within applied category theory (see Myers (2022)), and additionally have been a part of AlgebraicJulia for a while, with AlgebraicDynamics, accompanying blog post.

In this post, I sketch out an approach to doing open dynamical systems symbolically. This means that the vector fields for open dynamical systems are given by symbolic expressions, rather than arbitrary Julia functions.

This has the following advantages.

1. Expressions can be serialized and stored in a database.
2. Expressions can be compared for equality modulo the laws of a theory.
3. The execution of expressions can be optimized in different ways, or translated into other formats.
4. Expressions can have metadata attached.
5. Expressions can be input from non-Julia programs.
6. Expressions can be displayed in a nice format to the user.

In my previous blog post, I lay out the mathematics behind symbolic representation of functions between spaces. Here I now apply that theory to the specific case of open dynamical systems.

We start out by reviewing open dynamical systems.

In this section we use the word “space” and don’t define what a space is. This is because in a certain sense, we are agnostic as to the exact definition of space. All we really care is that the space supports some notion of derivative, as we are doing continuous-time dynamical systems. In order of increasing generality, a space could mean:

• for some
• open subsets of
• a manifold
• a ring
• an object of any tangent bundle category

Pick whichever level of generality you are comfortable with, and mentally replace every time I say “space” with that choice. I’ll generally give examples with ; if you know about the more general types of spaces then you should know enough to generalize what I am saying.

The important thing is that any space supports a notion of tangent space at a point , denoted by , and tangent bundle denoted by . The tangent bundle consists of all of the tangent spaces put together, i.e. as sets

If , then and .

A vector field on a space consists of a section of the tangent bundle , i.e. a function such that for all . This gives a tangent vector at each point; you can visualize this by searching “vector field” in google images.

Finally, I will behave like a physicist in that I will not overburden myself with saying precisely how differentiable all my functions are. If a function needs to be differentiable, then you can assume that it is.

With these preliminaries out of the way, we can start talking about dynamical systems.

We often refer to as the “dynamics” of the system. Applied mathematicians and physicists might be more used to seeing such a system written using the equation

However, as a mathematical object, the “data” of this equation is simply the function .

In the real world, systems are rarely closed; other parts of the world have influence on the system. Classically, we might capture this with the equation

where is some other variable. However, this only captures part of “openness”; this system might also affect other systems, or we may only observe some part of a system. So we also have an “output” equation

Our system might affect other systems through .

We now state this more formally.

Part 2: Composition of dynamical systems

In this section, we learn about how to compose dynamical systems with a construction from category theory called lenses. If you have learned about lenses before from functional programming, you may have some preconceived notion that lens are a way of accessing nested fields in a data structure. However, here we are using lens in a very different way; it might be useful to just think about “lens” as a new word. The two uses of lenses are formally the same, but have a different feel.

Lenses are morphisms in a certain category, so before we can define lenses we have to define the objects in that category.

We think about an arena as a generalized specification of the inputs/outputs of a system. At each output , there are allowed inputs . We write an arena as . In a special case, the “output” of a system is its state, and the “input” is the direction that you tell it to go in, i.e. a tangent vector.