Restructure QuantSI into small modules, check NumPy functions, and test it against Brian2

.github/workflows/benchmarks.yaml

@@ -0,0 +1,37 @@
+name: Benchmarks
+
+on: [push, pull_request]
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Check out the repository
+      uses: actions/checkout@v7
+
+    - name: Set up PDM
+      uses: pdm-project/setup-pdm@v4
+      with:
+        python-version: 3.13
+
+    - name: Install dependencies
+      run: |
+        pdm install -G test
+
+    # Timings on shared CI runners are noisy, so we only save them as an artifact.
+    # To look into a slowdown, compare the files of two runs.
+    - name: Run benchmarks
+      run: |
+        pdm run pytest tests/benchmarks --benchmark-enable --benchmark-only --benchmark-json=benchmarks.json
+
+    - name: Check overhead against plain NumPy
+      run: |
+        pdm run pytest -m perf_guard -v
+
+    - name: Upload results
+      uses: actions/upload-artifact@v4
+      with:
+        name: benchmarks
+        path: benchmarks.json

.github/workflows/brian2.yaml

@@ -0,0 +1,44 @@
+name: Brian2
+
+on: [push, pull_request]
+
+jobs:
+  brian2:
+    name: Brian2's test suite with this QuantSI
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Check out QuantSI
+      uses: actions/checkout@v7
+      with:
+        path: QuantSI
+        fetch-depth: 0  # the version number comes from the git history
+
+    - name: Check out Brian2
+      uses: actions/checkout@v7
+      with:
+        repository: brian-team/brian2
+        path: brian2
+        fetch-depth: 0  # Brian2 also gets its version number from its git tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install Brian2 and this QuantSI
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install ./QuantSI -e "./brian2[test]"
+
+    # What the companion change in Brian2 does: brian2.units re-exports QuantSI,
+    # plus the few changes in Brian2 that QuantSI's fixes need (see the patch).
+    - name: Make brian2.units use QuantSI
+      run: |
+        python QuantSI/tools/brian2/make_facade.py brian2
+        git -C brian2 apply ../QuantSI/tools/brian2/brian2-companion.patch
+
+    - name: Run Brian2's tests (without code generation, and with the numpy target)
+      working-directory: brian2
+      run: |
+        python -c "import brian2, sys; sys.exit(0 if brian2.test('numpy', test_codegen_independent=True) else 1)"

.github/workflows/pytest-ubuntu.yaml

@@ -4,8 +4,20 @@ on: [push, pull_request]
 
 jobs:
   test:
-    name: Run tests
+    name: Python ${{ matrix.python-version }} with ${{ matrix.numpy }}
     runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The oldest versions QuantSI supports (see pyproject.toml).
+          - python-version: "3.13"
+            numpy: "numpy==2.3.*"
+          # Also test current NumPy on both Python versions.
+          - python-version: "3.13"
+            numpy: "numpy"
+          - python-version: "3.14"
+            numpy: "numpy"
 
     steps:
     - name: Check out the repository
@@ -14,21 +26,27 @@ jobs:
     - name: Set up PDM
       uses: pdm-project/setup-pdm@v4
       with:
-        python-version: 3.13
+        python-version: ${{ matrix.python-version }}
 
     - name: Install dependencies
       run: |
         pdm install -G test
+        pdm run python -m ensurepip --upgrade
+        pdm run python -m pip install "${{ matrix.numpy }}"
 
     # Update output format to enable automatic inline annotations.
     - name: Run Ruff
       run: pdm run ruff check --output-format=github .
 
+    - name: Check types
+      run: pdm run mypy
+
     - name: Run tests
       run: |
-        pdm run -v pytest --cov=QuantSI --cov-report lcov --doctest-modules
+        pdm run -v pytest --cov=QuantSI --cov-report=term-missing --cov-report=lcov --cov-fail-under=100
 
     - name: Publish coverage
+      if: matrix.python-version == '3.13' && matrix.numpy == 'numpy'
       uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e  # v2.3.7
       with:
-        format: lcov
+        format: lcov

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.11.6
+    rev: v0.16.10
     hooks:
       # Run the linter.
       - id: ruff

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: 'ubuntu-22.04'
   tools:
-    python: "3.12"
+    python: "3.13"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

README.md

@@ -3,4 +3,49 @@
 [![Tests](https://github.com/brian-team/QuantSI/actions/workflows/pytest-ubuntu.yaml/badge.svg)](https://github.com/brian-team/QuantSI/actions/workflows/pytest-ubuntu.yaml)
 [![Coverage Status](https://coveralls.io/repos/github/brian-team/QuantSI/badge.svg?branch=main)](https://coveralls.io/github/brian-team/QuantSI?branch=main)
 
-Work in progress: unit system as used by the Brian2 simulator
+**Pragmatic dimensional checking for NumPy-based SI calculations.**
+
+QuantSI attaches a physical dimension to NumPy arrays and checks, operation by
+operation, that the physics makes sense. It is the unit system of the
+[Brian2](https://briansimulator.org) simulator, packaged so that it can also be
+used on its own.
+
+QuantSI requires Python 3.13 or newer and NumPy 2.3 or newer. Minimum supported
+versions follow [SPEC-0](https://scientific-python.org/specs/spec-0000/).
+
+```python
+>>> import numpy as np
+>>> from QuantSI import Mohm, mV, nA, parse_quantity
+>>> v = np.array([-70.0, -55.0]) * mV
+>>> v
+array([-70., -55.]) * mvolt
+>>> 2 * nA * 50 * Mohm
+100. * mvolt
+>>> f"{v.max() / mV:.1f} mV"
+'-55.0 mV'
+>>> v + 1 * nA
+Traceback (most recent call last):
+    ...
+DimensionMismatchError: Cannot calculate [-70. -55.] mV add 1. nA, the units do not match (units are V and A).
+>>> parse_quantity("-70 * mV")
+-70. * mvolt
+
+```
+
+## What QuantSI does
+
+- Stores every value in base SI units, with one shared `Dimension` object per
+  kind of quantity (so checking "same kind?" is a single identity check).
+- Checks arithmetic, comparisons and the supported NumPy functions, and raises
+  `DimensionMismatchError` when dimensions do not match.
+- Displays values in a sensible unit (`3. mV`), parses simple unit expressions
+  (`"3.5 * mV"`), and provides ~2000 named units generated from one rule.
+
+## What QuantSI deliberately does not do
+
+- No offset units (degrees Celsius/Fahrenheit) and no user-defined base dimensions.
+- No unit-conversion contexts, definition files or a general units language.
+- Values never remember the unit they were entered in: `3 * mV` *is* `0.003 V`.
+
+If you need any of these, have a look at [pint](https://pint.readthedocs.io) or
+[astropy.units](https://docs.astropy.org/en/stable/units/).

conftest.py

@@ -0,0 +1,77 @@
+import contextlib
+import importlib
+
+import pytest
+
+
+def pytest_collection_modifyitems(config, items):
+    """Skip the doctests of objects marked ``_do_not_run_doctests``.
+
+    Such objects (e.g. Quantity.fill, the wrappers in unitsafefunctions) reuse a
+    NumPy docstring, whose examples are about NumPy arrays. Brian2 uses the same
+    marker.
+    """
+
+    # (Deselected rather than skipped: their docstrings have no line in our files,
+    # which pytest needs to report a skip.)
+    def marked(item):
+        doctest = getattr(item, "dtest", None)
+        return doctest is not None and getattr(
+            _resolve(doctest.name), "_do_not_run_doctests", False
+        )
+
+    deselected = [item for item in items if marked(item)]
+    if deselected:
+        items[:] = [item for item in items if not marked(item)]
+        config.hook.pytest_deselected(items=deselected)
+
+
+def _resolve(dotted_name):
+    """The object called ``dotted_name`` (module path, then attributes), or None."""
+    parts = dotted_name.split(".")
+    for split in range(len(parts), 0, -1):
+        try:
+            obj = importlib.import_module(".".join(parts[:split]))
+        except ImportError:
+            continue
+        for attribute in parts[split:]:
+            obj = getattr(obj, attribute, None)
+        return obj
+    return None
+
+
+@contextlib.contextmanager
+def preserved_unit_registries():
+    """Undo, on exit, every unit registered inside the ``with`` block.
+
+    Units are registered globally, either explicitly with register_new_unit or
+    implicitly whenever units are combined (``siemens / cm**2``), and that changes
+    how quantities are displayed from then on.
+    """
+    from QuantSI.fundamentalunits import (
+        additional_unit_register,
+        standard_unit_register,
+        user_unit_register,
+    )
+
+    registries = (standard_unit_register, user_unit_register, additional_unit_register)
+    saved = [
+        (dict(r.units), {dim: dict(units) for dim, units in r.units_for_dimensions.items()})
+        for r in registries
+    ]
+    try:
+        yield
+    finally:
+        for registry, (units, by_dimension) in zip(registries, saved, strict=True):
+            registry.units.clear()
+            registry.units.update(units)
+            registry.units_for_dimensions.clear()
+            registry.units_for_dimensions.update(by_dimension)
+            registry._tables.clear()
+
+
+@pytest.fixture(autouse=True)
+def _isolated_unit_registries():
+    """No test (or doctest) can change how quantities display in another one."""
+    with preserved_unit_registries():
+        yield

docs_sphinx/QuantSI.rst

@@ -1,14 +1,6 @@
 QuantSI package
 ===============
 
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 2
-
-   QuantSI.tests
-
 Submodules
 ----------