Skip to content

Core concepts

There is no common nomenclature for the problem griddler solves, so we make up our own. There are 2 core concepts in griddler: the Spec and the Experiment.

A Spec is a set of parameter name-value pairs. Typically, a Spec corresponds to the variables and other configuration required to specify and run a single simulation. One Spec can be updated by another one, creating a new Spec with values from the updating Spec.

An Experiment is a set of Specs. An Experiment might include replicate simulations with different random seeds, simple grids of parameter values (hence, "griddler"), or more complex combinations of parameters. Experiments support two operations:

  • The union of two Experiments, which is just the union of the their constituent Specs, is another Experiment.
  • The product of two Experiments, similar to a Cartesian product, is another Experiment formed by taking each Spec in one Experiment and updating it with each Spec in the other Experiment.

Experiments, combined with unions and products, are sufficient to produce all sorts of simulations!

Implementation

In the griddler package, Specs are just dictionaries, which have the update (or |) operation. Experiments are objects of the Experiment class. Each Experiment holds a set of Specs, supports .union() (or |) and .product() (or *).

See the API reference for more details.

Theory

Specs

Specifically, a Spec is a set of name-value pairs, i.e., two-element sequences. Specs have a single, binary operation update \(\uparrow\) that adds the parameters in the right input to the left input, preferring the right value when the same name is present in both Specs. For two Specs \(S\) and \(T\),

\[ \begin{align*} S \uparrow T = &\{ (n, v) : (n, v) \in S \text{ and } n \in \pi(S) \backslash \pi(T) \} \\ &\cup \{ (n, v) : (n, v) \in T \text{ and } n \notin \pi(S) \backslash \pi(T) \} \\ \end{align*} \]

where \(\pi(\cdot)\) is the set of names in a Spec (i.e., the first projection map) and \(\backslash\) is set difference.

(The update operation is similar to null coalescence, which prefers the left value.)

Specs and the update operation \(\uparrow\) form a monoid because there is an identity element (i.e., the empty set \(\varnothing\)) and the operation is associative. Note that Specs are not commutative: the order of the inputs matters.

Experiments

An Experiment is a set of Specs, equipped with two operations: union \(\cap\), which is just the union of the constituent sets of Specs, and product \(\otimes\), analogous to Cartesian product. For two experiments \(X\) and \(Y\), define \(X \otimes Y = \{S \uparrow T : S \in X, T \in Y\}\).

Experiments and their two operations form a semiring. Union \(\cap\) is a commutative monoid whose identity element is the empty Experiment \(\varnothing\) (i.e., a set of no Specs at all). Product \(\otimes\) is a non-commutative monoid with identity element \(\{ \varnothing \}\) (i.e., an Experiment consisting of a single empty Spec). Note that the union identity \(\varnothing\) is an absorbing element under the product operation: \(X \otimes \varnothing = \varnothing \otimes X = \varnothing\) for any Experiment \(X\).