Developer setup

Quantas is a scientific library first. Numerical behaviour, units, shapes, and native HDF5 contracts must remain independent from the command line and from a future graphical frontend.

Development environment

Use Python 3.10 or newer in a fresh virtual environment. From the repository root:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

On Windows PowerShell, activate with:

.venv\Scripts\Activate.ps1

The dev extra installs the scientific runtime, tests, static-analysis tools, packaging tools, Sphinx, and the plotting backend. The smaller extras are useful when reproducing an end-user installation:

plot

Static Matplotlib rendering.

test

Pytest and test-only dependencies.

docs

Sphinx, numpydoc, sphinx-click, and the Read the Docs theme.

typecheck

Mypy and the supported NumPy range used for type checking.

GUI frameworks are intentionally not Quantas dependencies. A separate GUI application should install Quantas and consume quantas.api.

Verify the checkout

Before editing code, establish a clean baseline:

ruff check src tests tools
mypy
python -m compileall -q src tests tools
python tools/run_tests.py all -- -q

The complete test runner uses isolated subprocesses, disables unrelated pytest plugin autoloading, gives each stage its own Matplotlib configuration directory, and limits numerical library thread counts. A failure in a clean baseline must be understood before it is mixed with a new change.

Use focused loops while developing

Run the smallest relevant suite during implementation:

pytest --suite ha -q
pytest --suite elasticity -q
pytest --suite cli -q
pytest tests/infrastructure/test_architecture.py -q

Then run the complete staged matrix before producing a checkpoint:

python tools/run_tests.py all -- -q

Do not repeatedly run every plotting suite while changing a scalar numerical function. Conversely, do not consider a numerical change complete merely because one unit test passes.

Repository orientation

src/quantas/core

Reusable physics, mathematics, chemistry, geometry, numerical policies, and frontend-neutral events.

src/quantas/models

Passive contracts and shared active base classes.

src/quantas/interfaces

Parsers and adapters for external scientific codes.

src/quantas/modules

Complete scientific workflows, reports, plot builders, persistence adapters, and exports.

src/quantas/api

Supported application-facing namespaces.

src/quantas/renderers

Concrete table and plot presentation.

src/quantas/cli

Click option parsing, validation, dispatch, Rich presentation, and output naming.

tests

Scientific, architectural, frontend, persistence, example, and regression tests.

docs

Sphinx sources and reproducible documentation asset generators.

examples

Curated scientific inputs used by tutorials and smoke tests.

tools

Test orchestration, distribution validation, and repository checks.

A safe first contribution

For a first code contribution, choose a change that does not alter formulas or persisted schemas. Good examples are:

  • improve one public docstring and its API-reference wording;

  • add a missing validation test for an existing option;

  • add a report row using a value that is already present in the result payload;

  • improve a CLI help string without changing the option contract.

A useful workflow is:

  1. identify the authoritative contract and its existing tests;

  2. write or extend a focused test;

  3. make the smallest change;

  4. run lint, type checking, and the focused test;

  5. inspect the rendered output or report;

  6. run the relevant staged suite.

Avoid beginning with a new Click option or a new HDF5 field. Both are cross-cutting changes and are better attempted after reading Common change recipes.

Working rules

  • Use from __future__ import annotations in public modules.

  • Use modern Python 3.10 type hints and pathlib.Path.

  • Use dataclasses for passive data, not for active workflow controllers.

  • Keep real calculations and native floating HDF5 values in float64; complex values use complex128.

  • Do not add a runtime precision selector.

  • Do not print from scientific code.

  • Do not import Click, Rich, Matplotlib, or GUI objects into numerical code.

  • Add technical NumPy/Sphinx-compatible docstrings with parameters, returns, and raises sections to every public object.

  • Update tests and documentation in the same change as the code.