Common change recipes

This page is a practical map for changes that cross several Quantas layers. Use it as a checklist, then consult the focused architecture pages for details.

Add a scientific option

An option that changes a formula, approximation, domain, tolerance, sampling resolution, or failure policy is a scientific option.

  1. Add a typed field to the passive module Options contract.

  2. Validate range, unit, allowed values, and cross-option consistency.

  3. Add focused tests for default, valid alternatives, and invalid values.

  4. Thread the option into the analysis layer; do not read Click state there.

  5. Preserve the resolved option in ResultData.options and native HDF5.

  6. Include it in reports when it affects interpretation.

  7. Expose it through the public API contract.

  8. Add the Click option and a meaningful help string.

  9. Update Implementation and Workflows, CLI reference, API reference, and the relevant tutorial when users need guidance.

  10. Compare CLI and API results with the option enabled.

Presentation-only controls such as DPI, colormap, and report precision belong to renderers or CLI rendering options, not the scientific Options dataclass.

Add a result field

  1. Define the field on the typed Result contract with shape and unit in its docstring.

  2. Calculate it in the analysis layer using full precision.

  3. Define invalid/unavailable semantics and any aligned mask.

  4. Include uncertainty or covariance when scientifically supported.

  5. Add the HDF5 dataset with unit and description attributes.

  6. Read and validate it in the payload reader.

  7. Add round-trip and malformed-shape/unit tests.

  8. Decide whether it belongs in reports, exports, plots, and interoperability.

  9. Document it in the format specification and API reference.

  10. Add a regression test for at least one meaningful state.

Do not reuse an existing field name for a quantity with a different physical normalization.

Add a CLI option

  1. Confirm that a public API option or operation already exists.

  2. Add the Click declaration in the relevant adapter.

  3. Group it with related options.

  4. Let Click perform basic type conversion and choice validation.

  5. Construct the public options/request object.

  6. Add or update the centralized descriptive help text when used by the command reference generator.

  7. Test --help, valid use, invalid use, and output-path behaviour.

A CLI-only scientific option is an architectural error because notebooks and a GUI could not request the same calculation.

Add a report quantity

  1. Read the value from the typed result; do not recalculate it in the renderer.

  2. Keep the cell value numerical.

  3. Add unit and numeric-format metadata to the ReportTable.

  4. Update plain-text and Rich snapshots only when their semantic content changes.

  5. Check redirected output for absence of ANSI sequences.

Add a plot

  1. Decide the scientific question answered by the figure.

  2. Build required arrays and masks from the typed result.

  3. Represent them with existing neutral plot contracts.

  4. Add the module plot builder and plot-selection API.

  5. Add renderer support only if a genuinely new neutral primitive is required.

  6. Add CLI selection and renderer options.

  7. Test the plot specification separately from Matplotlib output.

  8. Add one renderer smoke or image-structure test.

  9. Document scientific interpretation and convergence controls.

Do not place Matplotlib calls in a module plot package.

Add an HDF5 field or change a schema

A backward-compatible optional dataset may not require a shared envelope version change, but it still needs a module payload version or explicit reader policy when interpretation changes.

  1. Define whether the change is optional, required, or incompatible.

  2. Update the writer to emit the current layout only.

  3. Update the reader to validate and migrate supported older layouts.

  4. Never infer a missing unit or module solely from the filename.

  5. Preserve None and unavailable states explicitly.

  6. Add old-file and new-file tests.

  7. Update the format documentation.

  8. Update registry-based opening if metadata or dispatch changes.

  9. Decide whether a schema version increment is required.

See Native HDF5 persistence and schema evolution.

Add a public API symbol

  1. Add a stable wrapper or alias under quantas.api.

  2. Add it to the namespace __all__.

  3. Add a complete public docstring.

  4. Add it once to the curated API reference.

  5. Add surface and usage tests.

  6. Add a registry capability only when frontend discovery needs it.

  7. Ensure the CLI uses the public operation when applicable.

Do not promote a calculator or reader simply to avoid writing a wrapper.

Add an external-code parser

  1. Place code-specific syntax under quantas.interfaces.<code>.

  2. Define file-recognition and completion checks.

  3. Parse into explicit physical fields with units.

  4. Preserve source provenance and relevant code settings.

  5. Convert to a normalized module input through a separate adapter.

  6. Test complete, incomplete, malformed, and version-variant fixtures.

  7. Keep parser errors contextual and actionable.

See External-code interfaces and parsers.

Add a canonical citation

  1. Add one immutable Citation to quantas.references.registry.

  2. Use a stable lowercase key; store the DOI without a URL prefix.

  3. Add the record to CITATIONS.

  4. Associate the key with module/method sets when appropriate.

  5. Cite the key in the scientific page at the relevant statement.

  6. Regenerate bibliography fragments.

  7. Update report citation sets if the implemented method changed.

  8. Run citation and documentation tests.

See Citation registry.

Change a numerical default

A default change can alter scientific results for every user. Treat it as a scientific change:

  1. characterize the old default;

  2. explain the failure or limitation motivating the new value;

  3. run convergence or sensitivity studies;

  4. update Options, CLI, workflow documentation, tutorial commands, reports, and frozen examples;

  5. preserve the old value as an explicit selectable option when scientifically meaningful;

  6. record the change in release notes.

Do not change a default merely because a larger grid or higher polynomial order sounds more accurate.