# Catlab API

`Catlab.GAT`

— Module.Generalized algebraic theories (GATs) in Julia.

GATs generalize (multisorted) algebraic theories by incorporating a fragment of dependent type theory. They allow type and term constructors to be partially defined. GATs provide a convenient formal syntax for categorical structures.

At present, this module only supports defining the *signature* of a GAT. In the future we may allow *axioms* to be expressed as well. Regardless, we will persist in calling this module "GAT". Signatures are defined using the `@signature`

macro.

There are several useful things to do with a GAT signature:

- Define
*instances*of the signature (models of the theory) in Julia code using the`@instance`

macro - Define
*syntax*systems using the`@syntax`

macro (see`Syntax`

module) - Define models of the theory by finite
*presentation*using a syntax system and the`@present`

macro (see`Present`

module)

References:

- (Cartmell, 1986, "Generalized algebraic theories and contextual categoies")
- (Pitts, 1995, "Categorical logic", Sec 6: "Dependent types")

`Catlab.GAT.invoke_term`

— Method.Invoke a term constructor by name on an instance.

This method provides reflection for GAT signatures. In everyday use the generic method for the constructor should be called directly, not through this function.

Cf. Julia's builtin `invoke()`

function.

`Catlab.GAT.@instance`

— Macro.Define an *instance* of a generalized algebraic theory (GAT).

These are perfectly analagous to instances of a type class in Haskell. See also the Typeclass.jl library for Julia.

`Catlab.GAT.@signature`

— Macro.Define a signature of a generalized algebraic theory (GAT).

Three kinds of things can go in the signature body:

- Type constructors, indicated by the special type
`TYPE`

, e.g.`Hom(X::Ob,Y::Ob)::TYPE`

- Term constructors, e.g.,
`id(X::Ob)::Hom(X,X)`

- Julia functions operating on the term constructors to provide additional functionality

A signature can extend existing signatures (at present only one).

`Catlab.GAT.Signature`

— Type.Signature for a generalized algebraic theory (GAT).

`Catlab.GAT.Stub`

— Type.Base type for method stubs in GAT signature.

`Catlab.GAT.TermConstructor`

— Type.Term constructor in a GAT.

`Catlab.GAT.TypeConstructor`

— Type.Type constructor in a GAT.

`Catlab.GAT.Typeclass`

— Type.Typeclass = GAT signature + Julia-specific content.

`Catlab.GAT.accessors`

— Method.Julia functions for type parameter accessors.

`Catlab.GAT.add_type_dispatch`

— Method.Add a type-valued first argument to a Julia function signature.

We need this to avoid ambiguity in method dispatch when a term constructor has no arguments (e.g., `munit()`

) or more generally has no arguments that are types in the signature (e.g., object generators in a category).

The fundamental reason why these cases must be treated specially is that Julia does not (yet?) support dispatching on return type.

`Catlab.GAT.constructors`

— Method.Julia functions for term constructors of GAT.

`Catlab.GAT.equations`

— Method.Implicit equations defined by context, allowing for implicit variables.

`Catlab.GAT.equations`

— Method.Implicit equations for term constructor.

`Catlab.GAT.equations`

— Method.Implicit equations defined by a context.

This function allows a generalized algebraic theory (GAT) to be expressed as an essentially algebraic theory, i.e., as partial functions whose domains are defined by equations.

References:

- (Cartmell, 1986, Sec 6: "Essentially algebraic theories and categories with finite limits")
- (Freyd, 1972, "Aspects of topoi")

`Catlab.GAT.expand_in_context`

— Method.Expand context variables that occur implicitly in an expression.

Reference: (Cartmell, 1986, Sec 10: 'Informal syntax').

`Catlab.GAT.expand_term_type`

— Method.Expand context variables that occur implicitly in the type expression of a term constructor.

`Catlab.GAT.gen_abstract_type`

— Method.Generate abstract type definition from a GAT type constructor.

`Catlab.GAT.get_type`

— Method.Get type constructor by name.

Unlike term constructors, type constructors cannot be overloaded, so there is at most one type constructor with a given name.

`Catlab.GAT.interface`

— Method.Complete set of Julia functions for a type class.

`Catlab.GAT.parse_constructor`

— Method.Parse type or term constructor in a GAT.

`Catlab.GAT.parse_context`

— Method.Parse context for term or type in a GAT.

`Catlab.GAT.parse_instance_body`

— Method.Parse the body of a GAT instance definition.

`Catlab.GAT.parse_raw_expr`

— Method.Parse a raw expression in a GAT.

A "raw expression" is a just composition of function and constant symbols.

`Catlab.GAT.parse_signature_body`

— Method.Parse the body of a GAT signature declaration.

`Catlab.GAT.replace_types`

— Method.Replace names of type constructors in a GAT.

`Catlab.GAT.strip_type`

— Method.Remove type parameters from dependent type.

`Catlab.Meta`

— Module.General-purpose tools for metaprogramming in Julia.

`Catlab.Meta.append_expr!`

— Method.Append a Julia expression to a block expression.

`Catlab.Meta.concat_expr`

— Method.Concatenate two Julia expressions into a block expression.

`Catlab.Meta.generate_docstring`

— Method.Wrap Julia expression with docstring.

`Catlab.Meta.generate_function`

— Method.Generate Julia expression for function definition.

`Catlab.Meta.parse_docstring`

— Method.Parse Julia expression that is (possibly) annotated with docstring.

`Catlab.Meta.parse_function`

— Method.Parse Julia function definition into standardized form.

`Catlab.Meta.parse_function_sig`

— Method.Parse signature of Julia function.

`Catlab.Meta.replace_symbols`

— Method.Replace symbols occuring anywhere in a Julia expression.

`Catlab.Meta.replace_symbols`

— Method.Replace symbols occurring anywhere in a Julia function (except the name).

`Catlab.Meta.strip_lines`

— Method.Remove all LineNumberNodes from a Julia expression.

`Catlab.Present`

— Module.Finite presentations of a model of a generalized algebraic theory (GAT).

We support two methods for defining models of a GAT: as Julia objects using the `@instance`

macro and as syntactic objects using the `@present`

macro. Instances are useful for casting generic data structures, such as matrices, abstract tensor systems, and wiring diagrams, in categorical language. Presentations define small categories by generators and relations and are useful for applications like knowledge representation.

`Catlab.Present.add_definition!`

— Method.Add a generator defined by an equation.

`Catlab.Present.add_equation!`

— Method.Add an equation between terms to a presentation.

`Catlab.Present.add_generator!`

— Method.Add a generator to a presentation.

`Catlab.Present.add_generators!`

— Method.Add multiple generators to a presentation.

`Catlab.Present.equations`

— Method.Get all equations of a presentation.

`Catlab.Present.generator`

— Method.Retrieve a generator by name.

`Catlab.Present.generators`

— Method.Get all generators of a presentation.

`Catlab.Present.has_generator`

— Method.Does the presentation contain a generator with the given name?

`Catlab.Present.merge_presentation!`

— Method.Merge the second presentation into the first.

The first presentation is mutated and returned; the second is not.

`Catlab.Present.@present`

— Macro.Define a presentation using a convenient syntax.

`Catlab.Present.translate_definition`

— Method.Translate definition of generator in terms of other generators.

`Catlab.Present.translate_equation`

— Method.Translate declaration of equality between terms.

`Catlab.Present.translate_expr`

— Method.Translate a single statement in the presentation DSL to Julia code.

`Catlab.Present.translate_generator`

— Method.Translate declaration of a generator.

`Catlab.Present.translate_presentation`

— Method.Translate a presentation in the DSL to a block of Julia code.

`Catlab.Rewrite`

— Module.Rewriting for GAT expressions.

The current content of this module is just a stopgap until I can implement a generic term rewriting system.

`Catlab.Rewrite.anti_involute`

— Method.Simplify unary operation that is an anti-involution on a (typed) monoid.

`Catlab.Rewrite.associate`

— Method.Simplify associative binary operation.

Maintains the normal form `op(e1,e2,...)`

where `e1`

,`e2`

,... are expressions that are *not* applications of `op()`

`Catlab.Rewrite.associate_unit`

— Method.Simplify associative binary operation with unit.

Reduces a freely generated (typed) monoid to normal form.

`Catlab.Rewrite.distribute_unary`

— Method.Distribute unary operation over a binary operation.

`Catlab.Syntax`

— Module.Syntax for a generalized algebraic theory (GAT).

Unlike instances of a theory, syntactic expressions don't necessarily satisfy the equations of the theory. For example, the default syntax operations for the `Category`

theory don't form a category because they don't satisfy the category laws, e.g.,

`compose(f, id(A)) != compose(f)`

Whether dependent types are enforced at runtime and whether expressions are automatically brought to normal form depends on the particular syntax. In general, a single theory may have many different syntaxes. The purpose of this module to make the construction of syntax simple but flexible.

`Catlab.Syntax.GATExpr`

— Type.Base type for expression in the syntax of a GAT.

We define Julia types for each *type constructor* in the theory, e.g., object, morphism, and 2-morphism in the theory of 2-categories. Of course, Julia's type system does not support dependent types, so the type parameters are incorporated in the Julia types. (They are stored as extra data in the expression instances.)

The concrete types are structurally similar to the core type `Expr`

in Julia. However, the *term constructor* is represented as a type parameter, rather than as a `head`

field. This makes dispatch using Julia's type system more convenient.

`Base.Meta.show_sexpr`

— Method.Show the syntax expression as an S-expression.

Cf. the standard library function `Meta.show_sexpr`

.

`Catlab.GAT.invoke_term`

— Method.Invoke a term constructor by name in a syntax system.

This method provides reflection for syntax systems. In everyday use the generic method for the constructor should be called directly, not through this function.

`Catlab.Syntax.functor`

— Method.Functor from GAT expression to GAT instance.

Strictly speaking, we should call these "structure-preserving functors" or, better, "model homomorphisms of GATs". But this is a category theory library, so we'll go with the simpler "functor".

A functor is completely determined by its action on the generators. There are several ways to specify this mapping:

Simply specify a Julia instance type for each doctrine type, using the required

`types`

tuple. For this to work, the generator constructors must be defined for the instance types.Explicitly map each generator term to an instance value, using the

`generators`

dictionary.

- For each doctrine type (e.g., object and morphism), specify a function mapping generator terms of that type to an instance value, using the
`terms`

dictionary.

The `terms`

dictionary can also be used for special handling of non-generator expressions. One use case for this capability is defining forgetful functors, which map non-generators to generators.

`Catlab.Syntax.parse_json_sexpr`

— Method.Deserialize expression from JSON-able S-expression.

If `symbols`

is true (the default), strings are converted to symbols.

`Catlab.Syntax.show_latex`

— Method.Show the expression in infix notation using LaTeX math.

Does *not* include `$`

or `\[begin|end]{equation}`

delimiters.

`Catlab.Syntax.show_unicode`

— Method.Show the expression in infix notation using Unicode symbols.

`Catlab.Syntax.to_json_sexpr`

— Method.Serialize expression as JSON-able S-expression.

The format is an S-expression encoded as JSON, e.g., "compose(f,g)" is represented as ["compose", f, g].

`Catlab.Syntax.@syntax`

— Macro.Define a *syntax* system for a generalized algebraic theory (GAT).

A syntax system consists of Julia types (with top type `GATExpr`

) for each type constructor in the signature, plus Julia functions for

*Generators*: creating new generator terms, e.g., objects or morphisms*Accessors*: accessing type parameters, e.g., domains and codomains*Term constructors*: applying term constructors, e.g., composition and monoidal products

Julia code for all this is generated by the macro. Any of the methods can be overriden with custom simplification logic.

`Catlab.Syntax.constructor_name`

— Method.Name of constructor that created expression.

`Catlab.Syntax.gen_term_constructor`

— Method.Generate methods for syntax term constructors.

Generate expressions for type parameters of term constructor.

Besides expanding the implicit variables, we must handle two annoying issues:

Add types for method dispatch where necessary (see

`GAT.add_type_dispatch`

) FIXME: We are currently only handling the nullary case (e.g.,`munit()`

). To handle the general case, we need to do basic type inference.Rebind the term constructors to ensure that user overrides are preferred over the default term constructors.

`Catlab.Syntax.gen_term_generator`

— Method.Generate methods for term generators.

Generators are extra term constructors created automatically for the syntax.

`Catlab.Syntax.gen_type`

— Function.Generate syntax type definitions.

`Catlab.Syntax.gen_type_accessors`

— Method.Generate accessor methods for type parameters.

`Catlab.Syntax.generator_like`

— Method.Create generator of the same type as the given expression.

`Catlab.Syntax.interface`

— Method.Complete set of Julia functions for a syntax system.