Centralizing Operators

[quffaro]

This PR straddles two needs, in order of decreasing effort:

1. Centralizing operator definitions in Decapodes. Operators should de-duplicated and defined in a central location as much as possible. A canon directory for operators should be defined to provide a reference for operators, and a tutorial should be provided for adding operators to Decapodes, removing the need for example pages to exhibit this feature.

2. Upstreaming operators Issue 286 in CatColab requires as many operators defined in CatColab be upstreamed as possible. This means proposing to add the flat-sharp operator to default_dec_matrix_generate

The first effort opens several technical questions:

Firstly, an operator may have different definitions. In this case flat-sharp. Because of @match, we can still override a definition of any operator by defining the same Symbol with a different function. However adding a polysemous operator to default_dec_matrix_generate biases a definition. Is this a design we want?

Secondly, the :mag and :neg operators are both included in default_dec_matrix_generate and default_dec_generate. Currently, we cannot programmatically know whether the default-generate family of functions implement a symbol unless we check that the function returns an output. I think the smallest footprint solution to multiply-defining operators would be to have default_generate be the fallback case in any default-generate method, and rely on it to handle the case when something is not implemented.

However I wonder if a pending feature for this branch--a canonical operators documentation feature a la @docapodes--could also be coupled with the default-generate methods.

Pending Development

• a canon for operators
• a tutorial page for adding operators, or added emphasis for defining bespoke operators to A Little More Complicated and Bring in the Dynamics

List of Operators

Here is a list of operators defined in the generate statements for our docs. Those that have been migrated completely to a default-method are checked off.

• CISM (mag, sharp)
• EBM Melt (mag, sharp)
• Grigoriev (mag, sharp)
• Halmo (mag, sharp)
• ice_dynamics (sharp defined differently, mag)
• klausmeier (Delta as a cycle in the DEC)
• poiseuille (partial p, partial q)

As of this commit I have verified that the docs still build locally.

[lukem12345]

Should DiagrammaticEquations repo have the template for the type system and Decapodes just provide julia definitions. I recall all operators being stored in a present macro at one point.

[jpfairbanks]

Yeah it makes sense for the symbolic parts to live in DiagEqn and the mapping of names to Julia functions to live here.

[GeorgeR227]

This should probably be rebased on PR #269 since that goes through the work of:

• Organizing operators into two separate classes (those with in-place variants and those without)
• Removing any duplicates
• Introduces many operators into the compiler DEC operator classes so that they can be automatically recognized instead of having to rely on the user's generate function.