Library Reference

The DiagrammaticEquations module exports data structures which represent diagrammatic equations and functions which manipulate them.

DECQuantities in DiagrammaticEquations must be subtypes of Number to integrate with SymbolicUtils. An intermediary type, Quantity, makes it clearer that terms in the theory are "symbolic quantities" which behave like numbers. In the context of SymbolicUtils, a Number is any type that you can do arithmetic operations on.

Rule{T}

Rules are AbstractOperators which contain type signatures that may be used for type inference or function resolution.

UserOperator{T}

UserOperators are AbstractOperators which store unary or binary operators to be checked against Rules.

function Decapode(e::DecaExpr)

Takes a DecaExpr and returns a Decapode ACSet.

function SummationDecapode(e::DecaExpr)

Takes a DecaExpr and returns a SummationDecapode ACSet.

function oapply(relation::RelationDiagram, podes::Vector{D}) where {D<:OpenSummationDecapode}

Compose a list of Decapodes as specified by the given relation diagram.

The Decapodes must be given in the same order as they were specified in the relation.

State variables (such as the (C,V) given in the head of the following @relation) do not affect the result of a composition.

Examples

julia> compose_diff_adv = @relation (C,V) begin
  diffusion(C, ϕ₁)
  advection(C, ϕ₂, V)
  superposition(ϕ₁, ϕ₂, ϕ, C)
end;

julia> oapply(compose_diff_adv, [(Diffusion, [:C, :ϕ]),
  (Advection, [:C, :ϕ, :V]), (Superposition, [:ϕ₁, :ϕ₂, :ϕ, :C])]);

Open(d::SummationDecapode{T,U,V}, names::AbstractVector{Symbol}) where {T,U,V}

creates an OpenSummationDecapode based on named variables rather than variable indices. See AlgebraicPetri.jl's Open for the analogous verion for LabelledReactionNetworks.

function average_rewrite(d::SummationDecapode)

Compute each quantitity in the given Decapode by the average of all computation paths leading to that node.

function check_operator(user::AbstractOperator, rule::Rule; check_name::Bool = false, ignore_nonapplicable_types::Bool = false)

Return the number of differences in types between a given user operator and a rule operator. If the rule does not apply to this operator, or they differ by a non-inferable type, the type difference is Inf.

The ignore_nonapplicable_types flags apply to the user operator.

function collate(equations, boundaries, uwd, symbols; restrictions::Vector{Symbol})

Create a collage of two Decapodes that simulates with boundary conditions.

Passing a list of symbols into restrictions specifies a list of boundary variables that will be restricted.

function contract_operators(d::SummationDecapode; white_list::Set{Symbol} = Set{Symbol}(), black_list::Set{Symbol} = Set{Symbol}())

Find chains of Op1s in the given Decapode, and replace them with a single Op1 with a vector of function names. After this process, all Vars that are not a part of any computation are removed. If a white list is provided, only chain those operators. If a black list is provided, do not chain those operators.

function default_composition_diagram(podes::Vector{D}, names::Vector{Symbol}) where {D<:SummationDecapode}

Given a list of Decapodes and their names, return a composition diagram which assumes that variables sharing the same name ought to be composed.

No Literals are exposed. Use unique_lits! after composing.

Throw an error if any individual Decapode already contains a repeated name (except for Literals).

If only_states_terminals is true, only expose state and terminal variables. Defaults to false.

Note that composing immediately with oapply will fail if types do not match (e.g. (:infer, :Form0) or (:Form0, :Form1)).

dot_rename!(d::AbstractNamedDecapode)

Rename tangent variables by their depending variable appended with a dot. e.g. If D == ∂ₜ(C), then rename D to Ċ.

If a tangent variable updates multiple vars, choose one arbitrarily. e.g. If D == ∂ₜ(C) and D == ∂ₜ(B), then rename D to either Ċ or B ̇.

function expand_operators(d::AbstractNamedDecapode)

If any unary operator is a composition, expand it out using intermediate variables.

function expand_operators(d::SummationDecapode)

Find operations that are compositions, and expand them with intermediate variables.

function fill_names!(d::AbstractNamedDecapode; lead_symbol::Symbol = Symbol("•"))

Provide a variable name to all the variables that don't have names.

filterfor_ec_types(types::AbstractVector{Symbol})

Return any form or vector-field type symbols.

function find_chains(d::SummationDecapode; white_list::Set{Symbol} = Set{Symbol}(), black_list::Set{Symbol} = Set{Symbol}())

Find chains of Op1s in the given Decapode. A chain ends when the target of the last Op1 is part of an Op2 or sum, or is a target of multiple Op1s. If a white list is provided, only chain those operators. If a black list is provided, do not chain those operators.

find_dep_and_order(d::AbstractNamedDecapode)

Find the order of each tangent variable in the Decapode, and the index of the variable that it is dependent on. Returns a tuple of (dep, order), both of which respecting the order in which incident(d, :∂ₜ, :op1) returns Vars.

function find_tgts_of_many_ops(d::SummationDecapode)

Searches SummationDecapode, d, for all Vars which have two or more distinct operations leading into the same variable.

function get_valid_op1s(deca_source::SummationDecapode, varID)

Searches SummationDecapode, deca_source, at the request varID and returns all op1s which are allowed to be averaged. Returns an array of indices of valid op1 sources.

Namely this is meant to exclude ∂ₜ from being included in an average.

infer_resolve!(d::SummationDecapode, operators::AbstractVector{Rule{Symbol}})

Runs type inference, overload resolution and type checking in that order.

function infer_state_names(d)

Find names of variables which have a time derivative or are not the source of a computation. See also: infer_states.

function infer_states(d::SummationDecapode)

Find variables which have a time derivative or are not the source of a computation. See also: infer_terminals.

function infer_terminal_names(d)

Find names of variables which have no children. See also: infer_terminals.

function infer_terminals(d::SummationDecapode)

Find variables which have no children. See also: infer_states.

function infer_types!(d::SummationDecapode, op1_rules::Vector{NamedTuple{(:src_type, :tgt_type, :replacement_type, :op), NTuple{4, Symbol}}})

Infer types of Vars given rules wherein one type is known and the other not.

is_expanded(d::AbstractNamedDecapode)

Check that no unary operator is a composition of unary operators.

function is_tgt_of_many_ops(d::SummationDecapode, var)

Return true if there are two or more distinct operations leading into Var var (not counting ∂ₜ).

function remove_neighborless_vars!(d::SummationDecapode)

Remove all Vars from the given Decapode that are not part of any computation.

function replace_all_op1s!(d::SummationDecapode, LHS::Union{Symbol, SummationDecapode}, RHS::Union{Symbol, SummationDecapode})

Given a Decapode, d, replace all instances of the left-hand-side unary operator with those of the right-hand-side.

Return true if any replacements were made, otherwise false.

See also: replace_op1!, replace_all_op2s!

function replace_all_op2s!(d::SummationDecapode, LHS::Union{Symbol, SummationDecapode}, RHS::Union{Symbol, SummationDecapode}, proj1::Int, proj2::Int)

Given a Decapode, d, replace all instances of the left-hand-side binary operator with those of the right-hand-side.

proj1 and proj2 are the indices of the intended proj1 and proj2 in RHS.

Return true if any replacements were made, otherwise false.

See also: replace_op2!, replace_all_op1s!

function replace_all_op2s!(d::SummationDecapode, LHS::Union{Symbol, SummationDecapode}, RHS::Union{Symbol, SummationDecapode})

Given a Decapode, d, replace all instances of the left-hand-side binary operator with those of the right-hand-side.

Search for distinguished variables "p1" and "p2" to serve as the proj1 and proj2 from RHS.

Return true if any replacements were made, otherwise false.

See also: replace_op2!, replace_all_op1s!

function replace_op1!(d::SummationDecapode, LHS::SummationDecapode, RHS::SummationDecapode)

Given a Decapode, d, replace at most one instance of the left-hand-side unary operator with those of the right-hand-side.

Return the index of the replaced unary operator, 0 if no match was found. See also: replace_op2!, replace_all_op1s!

function replace_op1!(d::SummationDecapode, LHS::Symbol, RHS::SummationDecapode)

Given a Decapode, d, replace at most one instance of the left-hand-side unary operator with those of the right-hand-side.

Return the index of the replaced operator, 0 if no match was found.

See also: replace_all_op1s!

function replace_op1!(d::SummationDecapode, LHS::Symbol, RHS::Symbol)

Given a Decapode, d, replace at most one instance of the left-hand-side unary operator with that of the right-hand-side.

Return the index of the replaced unary operator, 0 if no match was found. See also: replace_op2!, replace_all_op1s!

function replace_op2!(d::SummationDecapode, LHS::SummationDecapode, RHS::SummationDecapode, proj1::Int, proj2::Int)

Given a Decapode, d, replace at most one instance of the left-hand-side binary operator with those of the right-hand-side.

proj1 and proj2 are the indices of the intended proj1 and proj2 in RHS.

Return the index of the replaced binary operator, 0 if no match was found. See also: replace_op1!, replace_all_op2s!

function replace_op2!(d::SummationDecapode, LHS::Symbol, RHS::SummationDecapode, proj1::Int, proj2::Int)

Given a Decapode, d, replace at most one instance of the left-hand-side binary operator with those of the right-hand-side.

proj1 and proj2 are the indices of the intended proj1 and proj2 in RHS.

Return the index of the replaced operator, 0 if no match was found.

See also: replace_op1!, replace_all_op2s!

function replace_op2!(d::SummationDecapode, LHS::Symbol, RHS::Symbol)

Given a Decapode, d, replace at most one instance of the left-hand-side binary operator with that of the right-hand-side.

Return the index of the replaced binary operator, 0 if no match was found. See also: replace_op1!, replace_all_op2s!

function resolve_overloads!(d::SummationDecapode, op1_rules::Vector{NamedTuple{(:src_type, :tgt_type, :resolved_name, :op), NTuple{4, Symbol}}})

Resolve function overloads based on types of src and tgt.

safe_modifytype!(d::SummationDecapode, var_idx::Int, new_type::Symbol)

This function calls safe_modifytype to safely modify a Decapode's variable type.

safe_modifytype(org_type::Symbol, new_type::Symbol)

This function accepts an original type and a new type and determines if the original type can be safely overwritten by the new type.

function transfer_children!(d::SummationDecapode, x, y)

Transfer the children of x to y.

function transfer_parents!(d::SummationDecapode, x, y)

Transfer the parents of x to y. Also transfer TVar status from x to y.

type_check(d::SummationDecapode, type_rules::AbstractVector{Rule{Symbol}})

Takes a Decapode and a set of rules and checks to see if the operators that are in the Decapode contain a valid configuration of input/output types. If an operator in the Decapode does not contain a rule in the rule set it will be seen as valid.

In the case of a type error a DecaTypeExeception is thrown. Otherwise true is returned.

function type_check_Decapodes_composition(relation::RelationDiagram, decs::Vector{OpenSummationDecapode})

Check that the types of all Vars connected by the same junction match.

This function only throws an error on the first type mismatch found.

function unique_by!(acset, column_names::Vector{Symbol})

Given column names from the same table, remove duplicate rows.

WARNING: This function does not check if other tables index into the one given. Removal of rows is performed with prejudice.

See also: unique_by.

Examples

julia> unique_by!(parallel_arrows(Graph, 123), :E, [:src,:tgt]) == parallel_arrows(Graph, 1)
true

function unique_by(acset, column_names::Vector{Symbol})

Given column names from the same table, return a copy of the acset with duplicate rows removed. Removal of rows is performed with prejudice.

WARNING: This function does not check if other tables index into the one given. Removal of rows is performed with prejudice.

See also: unique_by!.

Examples

julia> unique_by(parallel_arrows(Graph, 123), :E, [:src,:tgt]) == parallel_arrows(Graph, 1)
true

function unique_lits!(d::SummationDecapode)

Remove repeated Literals from a Decapode.

Given a tuple of symbols ("aliases") and their canonical name (or "rep"), produces for each alias typechecking and nameof methods which call those for their rep. Example: @alias (d₀, d₁) => d

macro decapode(e)

Construct a SummationDecapode using the Decapode Domain-Specific Language.

Creates an operator foo with arguments which are types in a given Theory. This entails creating (1) a function which performs type construction and (2) a function which consumes BasicSymbolic variables and returns Terms.

@operator foo(S1, S2, ...)::Theory begin
    (body of function)
    (@rule expr1)
    ...
    (@rule exprN)
end

builds

promote_symtype(::typeof{f}, ::Type{S1}, ::Type{S2}, ...) where {S1<:DECQuantity, S2<:DECQuantity, ...}
    (body of function)
end

as well as

foo(S1, S2, ...) where {S1<:DECQuantity, ...}
    s = promote_symtype(f, S1, S2, ...)
    SymbolicUtils.Term{s}(foo, [S1, S2, ...])
end

Example:

@operator Δ(s)::DECQuantity begin
    @match s begin
        ::Scalar => error("Invalid")
        ::VField => error("Invalid")
        ::Form => ⋆(d(⋆(d(s))))
    end
    @rule ~s --> ⋆(d(⋆(d(~s))))
end

These are the default rules used to do type inference/function resolution in the 1D/2D exterior calculus.

Graphics.to_graphviz(F::AbstractDecapode; directed = true, kw...)

Visualize the given Decapode through Graphviz. Ensure that you have called using Catlab.Graphics before-hand, and have a way of visualizing SVG files in your current environment.

get_colors(d::SummationDecapode)

Given a Decapode, we infer the name of the boxes in the cospan which defines it and associate to these boxes a random unique color from a list of colors.

function recursive_delete_parents!(d::SummationDecapode, to_delete::Vector{Int64})

Delete the given nodes and their parents in the Decapode, recursively.

function unicode!(d::SummationDecapode)

Replace ASCII operators with their Unicode equivalents.

function vec_to_dec!(d::SummationDecapode)

Replace Vector Calculus operators with Discrete Exterior Calculus equivalents.