Authoring Primitives

Authoring Requirements for HS\(^3\) Primitive Specifications¶

Primitive specifications define the mathematical semantics of new HS\(^3\) primitives. Their purpose is to enable independent implementations to interpret serialized models consistently and without ambiguity.

Intended audience¶

Primitive specifications should be understandable to three audiences simultaneously:

Software implementers, who should be able to implement import, export, and evaluation directly from the specification.
Domain experts, who should recognize how concepts from existing software correspond to the HS\(^3\) representation.
Statisticians, who should be able to infer the mathematical properties of the primitive directly from its specification and serialized representation.

The mathematical definition is normative. Implementation-specific terminology may be used where it improves understanding, but should complement rather than replace the mathematical semantics.

Design principles¶

A primitive specifies what a model computes, not how a particular implementation computes it.

Specifications shall therefore define primitives in mathematical terms whenever practical. Implementation-specific concepts may be included only where they are necessary to faithfully represent existing software.

A primitive that introduces functionality which cannot already be represented using existing HS\(^3\) primitives will generally be appropriate, provided its semantics are well defined.

A primitive that only specializes an existing abstraction should provide clear additional value, such as a substantially more compact representation of a common use case, access to significantly more efficient or numerically robust evaluation strategies, or improved interoperability through the explicit representation of a widely recognized abstraction.

Relationship to the HS\(^3\) language¶

Primitive specifications extend the vocabulary of HS\(^3\) but do not redefine the language itself.

Primitive specifications may introduce new functions, distributions, or regular members of any other existing top-level HS\(^3\) category (see Section Top-level components). They shall not introduce new language constructs. In particular, a primitive shall not change its semantic role based on configuration or context, create or transform other serialized objects, or introduce control-flow, parser directives, or other metaprogramming facilities. Such proposals constitute extensions of the HS\(^3\) language and require separate specification and review.

Required specification¶

Every primitive specification shall define:

its mathematical semantics, or an equivalent algorithmic definition;
the meaning of every serialized field, including the relationship between serialized objects and the mathematical quantities they represent;
any normative default values;
sufficient examples to remove ambiguity.

Primitive specifications should define the normative semantics of a primitive independently of any particular implementation. Whenever practical, this should be done by specifying the mathematical object represented by the primitive. Where no sufficiently precise mathematical characterization exists, or where the algorithm itself defines the abstraction, a normative algorithmic specification may be used instead.

The amount of explanatory material should be proportional to the complexity of the primitive. Simple primitives may require little more than their mathematical definition and serialization. More complex primitives should include whatever additional explanation is necessary to enable independent conforming implementations. Informative mappings to existing software are encouraged but never replace the normative definition.

Serialization¶

Every serialized field shall have a well-defined mathematical meaning.

Serialized objects should expose mathematical structure wherever practical. Mathematical concepts such as coefficients, tensors, domains, or observables should be preferred over implementation-specific concepts such as object handles or memory layouts.

Implementation-specific state may be serialized where necessary, but should remain self-contained, inspectable, schema-validatable, and editable whenever practical. References to external binary objects should be avoided unless no practical alternative exists.

Defaults and miscellaneous information¶

Evaluation shall be completely determined by the serialized object together with any normative defaults defined by the primitive.

Optional fields that affect evaluation shall have unique specification-defined default values. Such defaults shall not depend on implementations, external libraries, software versions, or backend-specific conventions.

Information that has no effect on mathematical evaluation shall be stored in misc. Conforming evaluators shall produce equivalent results regardless of the contents of misc, although implementations may use it for diagnostics, visualization, optimization, or internal representation.

Existing implementations¶

Where a primitive represents functionality already established in an existing framework or scientific domain, its semantics should remain recognizable to domain experts while preserving implementation-independent mathematical meaning.

Primitive specifications should minimize the conceptual distance between established domain abstractions and their HS\(^3\) representation. Generalization is appropriate where it improves interoperability or removes accidental implementation details. It should be avoided where it obscures established abstractions or complicates import, export, or implementation without providing corresponding semantic benefit.

Alternative implementations¶

An enum-like field may select between alternative methods when those methods operate on the same serialized state and the meaning of all other fields remains unchanged. The selected method may alter how that state is interpreted or evaluated, but shall not determine which disjoint set of fields is applicable.

If different enum values require substantially different configuration data, parameterizations, or validity conditions, they should generally be represented as separate primitives rather than as variants of a single primitive.

Implementations need to support only a subset of the methods defined by a primitive specification. An implementation that does not support the requested method shall not silently substitute another method. It shall either reject the object or explicitly report the use of a semantically valid fallback.

Conformance¶

A primitive specification is complete if independent implementations can reproduce equivalent mathematical behaviour from the specification alone, together with the documentation of any explicitly referenced external libraries.

Normative text defines behaviour. Informative text may provide motivation, examples, implementation guidance, historical context, or mappings to existing software, but does not contribute to the formal definition of the primitive.

Editorial Guideline¶

As a practical guideline, contributors should continuously ask:

Could an independent, faithful implementation of this primitive be written without ambiguity from this specification alone, together with the documentation of any explicitly referenced external libraries?

If the answer is no, the specification is likely missing semantic or algorithmic information.