Documentation Standards#

This document defines the documentation standards for MADDENING. These standards support IEC 62304 SOUP traceability and are enforced by CI where possible.

Docstring Format#

Use NumPy-style docstrings for all public classes and functions:

def update(self, state, boundary_inputs, dt):
    """Advance the simulation state by one timestep.

    Parameters
    ----------
    state : dict
        Current state arrays.
    boundary_inputs : dict
        External inputs from coupled nodes.
    dt : float
        Timestep size in seconds.

    Returns
    -------
    dict
        Updated state arrays.
    """

Math in Code#

  • Docstrings: ASCII-art equations (e.g., dT/dt = alpha * d^2T/dx^2)

  • Algorithm guides: LaTeX math blocks ($$...$$)

  • Math-heavy code exception: mathematical variable names may use short names matching published formulas (e.g., tau, f_eq, dx, rho). This follows iMSTK’s convention of exempting “highly math-based code” from standard naming rules to maintain correspondence with published formulas.

Bibliography#

All academic references go in docs/bibliography.bib. This is the single centralized reference store.

In algorithm guides: cite using Pandoc-style [@Key] syntax:

  • Single citation: [@Crank1975]

  • Multiple citations: [@Crank1975; @LeVeque2007]

  • Each reference also gets a human-readable inline description

  • CI validates all cited keys exist (scripts/check_citations.py)

In code: use the Reference type in NodeMeta.references:

references=(
    Reference("Crank1975", "Analytical solutions for heat equation"),
)

Algorithm Guide Documents#

Every physics node must have a corresponding document in docs/algorithm_guide/nodes/ following the template at docs/algorithm_guide/nodes/_template.md.

Required sections:

Section

Purpose

Summary

1-2 sentences

Governing Equations

Full math formulation (LaTeX)

Discretization

How continuous equations become discrete

Implementation Mapping

Every equation term traced to code (IEC 62304 Clause 5.4)

Assumptions and Simplifications

Numbered list of every assumption

Validated Physical Regimes

Quantitative parameter bounds with evidence

Known Limitations and Failure Modes

Feeds into SOUP anomaly assessment

Stability Conditions

Analytical/empirical stability bounds

State Variables

Field, shape, units, description

Parameters

Parameter, type, default, units, description

Boundary Inputs

Field, shape, default, description

References

[@Key] citations with inline descriptions

Verification Evidence

Links to benchmarks and test files

Changelog

Version, date, change

Implementation Mapping#

The Implementation Mapping table is mandatory (IEC 62304 Clause 5.4 — detailed design traceability). It traces every term in the governing equations to a specific Python/JAX function:

| Equation Term | Implementation | Notes |
|---------------|---------------|-------|
| $\alpha \nabla^2 T$ (diffusion) | `maddening.nodes.heat.HeatNode.update` | 2nd-order central FD |
| Time integration | Forward Euler in `maddening.nodes.heat.HeatNode.update` | 1st-order explicit |

Rules:

  • Every governing equation term must appear — no silent omissions

  • Terms handled by JAX primitives must document the primitive and calling convention

  • CI validates all function names resolve to existing callables (scripts/check_impl_mapping.py)

Commit Message Convention#

Prefix

Meaning

feat:

New feature

fix:

Bug fix

refactor:

Code restructuring (no behavior change)

docs:

Documentation only

test:

Test additions or changes

perf:

Performance improvement

verify:

Verification/validation evidence

break:

Breaking change

deprecate:

Deprecation notice

security:

Security-relevant change

Commit messages should be concise (1-2 sentences) and focus on the “why” rather than the “what”.

CHANGELOG.md#

Follow Keep a Changelog with these sections:

## [Unreleased]

### Added
### Changed
### Deprecated
### Removed
### Fixed
### Verification
### Security
### Known Anomalies

The Verification, Security, and Known Anomalies sections are required for EU regulatory workflows (IEC 62304, MDCG 2019-16).

Update the changelog with every commit that adds, changes, fixes, or deprecates user-visible functionality. Empty sections can be omitted in the commit but must be present in release notes.

Anomaly Registry#

Known bugs, limitations, and failure modes go in docs/validation/known_anomalies.yaml. See CONTRIBUTING.md for the three-phase anomaly lifecycle and release gate model.

Versioning#

MADDENING follows strict Semantic Versioning:

  • MAJOR (X.0.0): Breaking API changes

  • MINOR (0.X.0): New features, backward-compatible

  • PATCH (0.0.X): Bug fixes, documentation

API stability levels:

Level

Meaning

SemVer Guarantee

stable

Breaking changes only in major versions

Full

provisional

May change in minor versions with deprecation warning

One minor version notice

experimental

May change without notice

None

deprecated

Scheduled for removal

Removed in next major