pyproject.toml

# SPDX-License-Identifier: AGPL-3.0-or-later
# Commercial license available
# © Concepts 1996–2026 Miroslav Šotek. All rights reserved.
# © Code 2020–2026 Miroslav Šotek. All rights reserved.
# ORCID: 0009-0009-3560-0851
# Contact: www.anulum.li | protoscience@anulum.li
# SCPN Quantum Control — Project Configuration
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "scpn-quantum-control"
version = "1.0.0"
description = "Evidence-governed Kuramoto-XY quantum-control and differentiable-computation workbench"
readme = "README.md"
license = "AGPL-3.0-or-later"
requires-python = ">=3.11"
authors = [
    { name = "Miroslav Šotek", email = "protoscience@anulum.li" },
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Scientific/Engineering :: Physics",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]
keywords = [
    "quantum computing",
    "kuramoto",
    "spiking neural networks",
    "plasma control",
    "scpn",
    "qiskit",
]
dependencies = [
    "qiskit>=2.2,<3.0",
    "qiskit-aer>=0.15,<1.0",
    "qiskit-qasm3-import>=0.6,<1.0",
    "symengine>=0.14,<1.0",
    "numpy>=1.24,<3.0",
    "scipy>=1.10,<2.0",
    "oscillatools>=0.1.0",
    "networkx>=3.0,<4.0",
    "jinja2>=3.1,<4.0",
    "requests>=2.34.2,<3.0",
    "tomli>=2.0,<3.0; python_version < '3.11'",
    "urllib3>=2.7,<3.0",
]

[project.scripts]
scpn-bench = "scpn_quantum_control.bench_cli:main"
scpn-verify-hardware-packs = "scpn_quantum_control.hardware_result_packs:main"
scpn-generate-hardware-pack-evidence = "scpn_quantum_control.hardware_result_pack_evidence:main"
scpn-provider-smoke = "scpn_quantum_control.hardware.provider_smoke:main"
scpn-biological-qec-report = "scpn_quantum_control.qec.biological_cli:main"
install-differentiable-framework-overlay = "scpn_quantum_control.differentiable_framework_overlay:main"
scpn-emit-studio-manifest = "scpn_quantum_control.studio.federation:main"
scpn-studio-run = "scpn_quantum_control.studio.executive_cli:main"

[project.optional-dependencies]
viz = ["matplotlib>=3.5,<4.0"]
studio = ["scpn-studio-platform>=0.9,<0.12"]
gpu = ["cupy-cuda12x>=13.0"]
jax = ["jax[cuda12]>=0.4.30"]
torch = ["torch>=2.2,<3.0"]
tensorflow = ["tensorflow>=2.16,<3.0"]
rust = ["scpn-quantum-engine>=0.2.0"]
dev = ["pytest>=7.0,<10.0", "pytest-cov>=4.0,<8.0", "ruff>=0.4,<1.0", "hypothesis>=6.155.2,<7.0", "pre-commit>=3.0,<5.0", "mypy>=1.0,<3.0", "bandit>=1.7,<2.0", "build>=1.0,<2.0", "hatchling>=1.27,<2.0", "tomli>=2.0,<3.0", "types-defusedxml>=0.7,<1.0"]
docs = ["mkdocs>=1.6,<2.0", "mkdocs-material>=9.0,<10.0", "pymdown-extensions>=10.0,<12.0", "mkdocstrings[python]>=0.24,<2.0"]
ibm = ["qiskit-ibm-runtime>=0.40,<1.0"]
braket = ["amazon-braket-sdk>=1.117,<2.0"]
azure = ["azure-quantum>=3.9,<4.0"]
qbraid = ["qbraid>=0.12,<1.0"]
strangeworks = ["strangeworks>=0.7,<1.0; python_version >= '3.11'"]
cirq = ["cirq-core>=1.6,<2.0"]
dwave = ["dwave-cloud-client>=0.14,<1.0", "dwave-system>=1.34,<2.0"]
ionq = ["requests>=2.34.2,<3.0"]
iqm = ["iqm-client>=34,<35"]
oqc = ["oqc-qcaas-client>=3.22,<4.0"]
pasqal = ["pulser-core>=1.8,<2.0"]
quandela = ["perceval-quandela>=1.1,<2.0"]
quantinuum = ["pytket-quantinuum>=0.59,<1.0"]
quera = ["bloqade>=0.33,<1.0"]
rigetti = ["pyquil>=4.17,<5.0"]
providers = ["qiskit-aer>=0.15,<1.0", "qiskit-ibm-runtime>=0.40,<1.0", "amazon-braket-sdk>=1.117,<2.0", "azure-quantum>=3.9,<4.0", "qbraid>=0.12,<1.0", "cirq-core>=1.6,<2.0", "pennylane>=0.40,<1.0", "requests>=2.34.2,<3.0", "oqc-qcaas-client>=3.22,<4.0", "pulser-core>=1.8,<2.0", "perceval-quandela>=1.1,<2.0", "pytket-quantinuum>=0.59,<1.0", "pyquil>=4.17,<5.0"]
tensor = ["quimb>=1.10,<2.0"]
mitigation = ["mitiq>=0.30,<2.0", "ply>=3.11,<4.0"]
topology = ["ripser>=0.6,<1.0"]
opensys = ["qutip>=5.0,<6.0"]
pennylane = ["pennylane>=0.40,<1.0"]
xvalidate = ["qutip>=5.0,<6.0", "dynamiqs>=0.3,<1.0"]
config = ["pydantic-settings>=2.0,<3"]
logging = ["structlog>=24.0,<27"]
julia = ["juliacall>=0.9,<2"]
dla-parity = ["qutip>=5.0,<6.0"]
app-eeg = ["mne>=1.6,<2.0", "edfio>=0.4,<1.0"]
app-plasma = ["h5py>=3.10,<4.0", "pandas>=2.0,<4.0"]
app-power-grid = ["pandapower>=2.14,<4.0"]
app-fep = ["pydantic>=2.0,<3.0"]
biology = ["biopython>=1.84,<2.0", "python-louvain>=0.16,<1.0", "goatools>=1.4,<2.0"]
app-benchmarks = ["scpn-quantum-control[app-eeg,app-plasma,app-power-grid,app-fep]"]
all = ["scpn-quantum-control[viz,providers,tensor,mitigation,topology,opensys,pennylane,xvalidate,config,logging,julia,dla-parity,biology]"]
accelerated = ["scpn-quantum-control[gpu,jax]"]

[project.entry-points."scpn_quantum_control.backends"]
analog_kuramoto = "scpn_quantum_control.hardware.backends:analog_kuramoto_factory"
hybrid_digital_analog = "scpn_quantum_control.hardware.backends:hybrid_digital_analog_factory"
qiskit_ibm = "scpn_quantum_control.hardware.backends:qiskit_ibm_factory"
qiskit_aer = "scpn_quantum_control.hardware.backends:qiskit_aer_factory"
cirq = "scpn_quantum_control.hardware.backends:cirq_factory"
braket = "scpn_quantum_control.hardware.backends:braket_factory"
pennylane = "scpn_quantum_control.hardware.backends:pennylane_factory"
iqm = "scpn_quantum_control.hardware.backends:iqm_factory"

[project.entry-points."scpn_quantum_control.application_plugins"]
eeg_alpha = "scpn_quantum_control.applications.app_plugins:eeg_application_plugin_factory"
friston_fep = "scpn_quantum_control.applications.app_plugins:fep_application_plugin_factory"
plasma_iter_mhd = "scpn_quantum_control.applications.app_plugins:plasma_application_plugin_factory"
power_grid_ieee5 = "scpn_quantum_control.applications.app_plugins:power_grid_application_plugin_factory"

[project.urls]
Homepage = "https://github.com/anulum/scpn-quantum-control"
Repository = "https://github.com/anulum/scpn-quantum-control"
Issues = "https://github.com/anulum/scpn-quantum-control/issues"
Changelog = "https://github.com/anulum/scpn-quantum-control/blob/main/CHANGELOG.md"
Documentation = "https://anulum.github.io/scpn-quantum-control"

[tool.hatch.build.targets.sdist]
exclude = [
    ".github/",
    ".coverage",
    ".mypy_cache/",
    ".pytest_cache/",
    ".ruff_cache/",
    ".venv*/",
    "coverage.xml",
    "dist/",
    "results/",
    "site/",
    "figures/",
    "notebooks/",
]

[tool.hatch.build.targets.wheel]
packages = ["src/scpn_quantum_control", "src/scpn"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["."]
addopts = "-m 'not slow and not hardware and not internal_corpus and not performance'"
markers = [
    "slow: marks tests as slow (run with '-m slow')",
    "hardware: requires IBM Quantum credentials",
    "internal_corpus: requires ignored internal manuscript extraction artefacts",
    "performance: wall-clock performance gate for controlled benchmark runs",
]
xfail_strict = true
filterwarnings = [
    "ignore::DeprecationWarning:qiskit",
    "ignore::DeprecationWarning:stevedore",
    "ignore:COBYLA.*Invalid MAXFUN:UserWarning:scipy",
]

[tool.ruff]
target-version = "py39"
line-length = 99

[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B", "SIM", "D", "PGH"]
ignore = [
    "E501",   # line length handled by formatter
    "SIM108", # ternary can reduce readability for physics code
    "D105",   # numpy convention: magic-method contracts are language-defined
]

[tool.ruff.lint.per-file-ignores]
"notebooks/*.py" = ["E402"]  # notebooks install deps before importing them
"notebooks/*.ipynb" = ["E402", "F821"]  # notebooks: mid-cell imports normal, cross-cell scope invisible to linter
"notebooks/**/*.ipynb" = ["E402", "F821"]  # colab notebooks same
"notebooks/kaggle_push/*.py" = ["E402", "B007"]  # kaggle scripts: iteration loops without using index
"tests/test_mps_evolution.py" = ["E402", "I001"]  # importorskip before local import
"tests/test_phase_pennylane_import.py" = ["E402", "I001"]  # importorskip before local import
"tests/test_mitiq_integration.py" = ["E402", "I001"]  # importorskip before local import
"tests/kuramoto_autodiff_witness.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_diff_kuramoto_autodiff_witness.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/kuramoto_delay_sensitivity_witness.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_diff_kuramoto_delay_sensitivity_witness.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_kyma_dynamics.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_kyma_task.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_kyma_models.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_kyma_probe.py" = ["E402", "I001"]  # importorskip(jax) before local import
"tests/test_kuramoto_visualisation.py" = ["E402", "I001"]  # importorskip(matplotlib) before local import
# Docstring (D) scope: the 2026-06-17 broadcast mandates NumPy docstrings on the
# PUBLIC API. tests/ are not public API (design exemption); scripts/ and
# examples/ adopt in a staged follow-up. The per-file entries below are the
# shrink-list ratchet: each docstring-prose closeout deletes its line.
"tests/**" = ["D"]
"scripts/**" = ["D"]
"examples/**" = ["D"]
"notebooks/**" = ["D"]
"figures/**" = ["D"]
"data/**" = ["D"]
"*.py" = ["D"]
[tool.ruff.lint.isort]
known-first-party = ["oscillatools", "scpn_quantum_control"]

[tool.ruff.lint.pydocstyle]
convention = "numpy"

[tool.mypy]
# Declared baseline per the 2026-06-17 strict-typing broadcast; CI's explicit
# `mypy --strict src/` remains as belt-and-braces enforcement of the same set.
strict = true
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
warn_unreachable = true
check_untyped_defs = true
ignore_missing_imports = false
# Every suppression must name its error code: a bare `# type: ignore` hides
# unrelated future errors on the same line. Ruff's PGH003/PGH004 enforce the
# same invariant (including in tests/, which mypy does not check — see below).
enable_error_code = ["ignore-without-code"]
# The standalone `oscillatools` distribution is a runtime dependency imported by
# the accel/kuramoto consumer modules; it is not installed during the type-check
# job (the pinned CI surface is hash-locked), so expose its source tree here for
# import resolution. Its own strict gate owns its internals (see the override
# below), and it is never added to `files`, so mypy resolves but does not re-check it.
# ``tests`` is included only for resolving shared strict-cohort helpers; the
# broad ``files`` inventory below still excludes the legacy test tree.
mypy_path = ["src", "oscillatools/src", "tests"]
# Test-typing policy (R2-M01, 2026-07-13): tests/ stays outside this broad
# `files` set because the pre-ratchet census found 6,301 errors in 388 of 968
# tracked Python test files; 5,076 were mechanical `no-untyped-def` findings. Instead,
# `tools/test_typing_policy.json` defines an additive strict cohort executed by
# `tools/audit_test_typing_policy.py` in CI and local preflight. Invalid-input
# tests keep narrow error-code suppressions where the negative call is
# intentional. The cohort ratchet grows by source-owned risk waves; it is not a
# claim that the full test tree is already strict.
files = [
    "src/scpn_quantum_control/",
]

[[tool.mypy.overrides]]
module = "numpy.*"
ignore_missing_imports = true

# scpn-studio-platform ships py.typed but its StrEnum members resolve to `str`
# under our pinned mypy, producing false "incompatible type str" arg-type errors
# at every Verb/CapabilityManifest construction. Treat the SDK as untyped so the
# studio federation surface type-checks; our own studio code stays strict.
[[tool.mypy.overrides]]
module = "scpn_studio_platform.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "scipy.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "networkx.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "jinja2.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "qiskit.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "qiskit_aer.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "qiskit_ibm_runtime.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "braket.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "azure.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "qbraid.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "matplotlib.*"
ignore_missing_imports = true

# Optional runtime dependencies imported lazily inside function bodies; absent
# in the pre-commit hook env and in CI's type-check env. A scoped override
# behaves identically whether the package is missing or installed-untyped,
# unlike inline ignores whose error codes differ between those two states.
[[tool.mypy.overrides]]
module = "cupy.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "qutip.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "community.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "pydantic.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "pydantic_settings.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "sc_neurocore.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "jax.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "ripser.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "cirq.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "mitiq.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "torch.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "tensorflow.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "sklearn.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "cotengra.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "quimb.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "pennylane.*"
ignore_missing_imports = true
follow_imports = "skip"

[[tool.mypy.overrides]]
module = "structlog.*"
ignore_missing_imports = true

# The Kuramoto toolkit now lives in the standalone `oscillatools` distribution
# (a dependency), which carries its own strict mypy gate; use its types here
# without re-reporting its internals during this project's run.
[[tool.mypy.overrides]]
module = "oscillatools.*"
follow_imports = "silent"

[tool.mutmut]
# Mutmut 2.x config. Baseline target: `analysis/koopman.py` — small
# (~250 lines), self-contained, 34 dedicated tests including the 13
# input-validation tests from commit c7d4ccd. Extend
# `paths_to_mutate` as tests harden other modules (audit item B7 in
# the internal gap audit).
#
# `runner` is a single executable command mutmut invokes per mutant.
# Keep it tight: only the tests that cover the target module.
paths_to_mutate = "src/scpn_quantum_control/analysis/koopman.py"
tests_dir = "tests/"
runner = "python -m pytest -x -q tests/test_koopman.py"

[tool.coverage.run]
source = ["src/scpn_quantum_control"]
# Collect branch arcs in every coverage.py invocation. CI preserves the
# historical 90% LINE gate through tools/audit_coverage_policy.py and keeps the
# first whole-suite branch rate in observation mode until remote evidence can
# support a separate branch threshold.
branch = true
omit = [
    # Julia tier requires juliacall + Julia runtime; not installed in
    # CI (would add ~4 min JIT boot per run). Dispatcher covers the
    # fallthrough path; the Julia-side wrapper is exercised locally
    # via the [julia] extra.
    "*/scpn_quantum_control/accel/julia/*",
    # Provider-specific HAL adapters are exercised through contract and
    # conformance tests with injected provider objects. Live SDK branches
    # require cloud credentials, account resources, or vendor runtimes and
    # are covered by provider smoke/readiness workflows instead of the
    # aggregate unit-test line gate.
    "*/scpn_quantum_control/hardware/hal_*.py",
    "*/scpn_quantum_control/hardware/provider_capability_discovery.py",
    "*/scpn_quantum_control/hardware/provider_smoke.py",
    # Hardware campaign submitters and latency probes are operational entry
    # points guarded by preregistration, approval, and result-pack tests.
    # They are not safe to force through branch coverage in ordinary CI.
    "*/scpn_quantum_control/hardware/ibm_latency_probe.py",
    "*/scpn_quantum_control/hardware/openpulse_control.py",
    "*/scpn_quantum_control/hardware/s1_feedback_ibm.py",
    # Optional accelerator and external-mitigation wrappers depend on
    # GPU/JAX/MPS/Mitiq runtime surfaces that are intentionally absent from
    # the pinned CPU-only CI lane. Dispatcher and fallback behavior remains
    # tested in the core suite.
    "*/scpn_quantum_control/phase/gpu_batch_vqe.py",
    "*/scpn_quantum_control/phase/jax_nqs.py",
    "*/scpn_quantum_control/phase/mps_evolution.py",
    # The JAX autodiff Kuramoto tier needs jax[cuda]/jax[cpu], absent from the pinned CI lane; its
    # importorskip test runs locally (GPU) or in the differentiable-frameworks overlay lane.
    "*/scpn_quantum_control/accel/jax_kuramoto.py",
    "*/scpn_quantum_control/accel/jax_kuramoto_delayed.py",
    "*/scpn_quantum_control/accel/jax_kuramoto_mpc.py",
    # The KYMA toy-composition probe needs the optional [jax] extra, absent from the pinned CI
    # lane; its importorskip(jax)-guarded tests run locally. Covered by tests/test_kyma_*.py.
    "*/scpn_quantum_control/benchmarks/kyma/*.py",
    "*/scpn_quantum_control/mitigation/mitiq_integration.py",
    # Quantum-persistent-homology hardware loops are validated by the
    # topological optimizer and hardware-topology tests. Live QPU branches
    # remain in hardware-marked campaigns.
    "*/scpn_quantum_control/analysis/quantum_persistent_homology.py",
]

[tool.coverage.report]
omit = [
    "*/scpn_quantum_control/accel/julia/*",
    "*/scpn_quantum_control/hardware/hal_*.py",
    "*/scpn_quantum_control/hardware/provider_capability_discovery.py",
    "*/scpn_quantum_control/hardware/provider_smoke.py",
    "*/scpn_quantum_control/hardware/ibm_latency_probe.py",
    "*/scpn_quantum_control/hardware/openpulse_control.py",
    "*/scpn_quantum_control/hardware/s1_feedback_ibm.py",
    "*/scpn_quantum_control/phase/gpu_batch_vqe.py",
    "*/scpn_quantum_control/phase/jax_nqs.py",
    "*/scpn_quantum_control/phase/mps_evolution.py",
    "*/scpn_quantum_control/accel/jax_kuramoto.py",
    "*/scpn_quantum_control/accel/jax_kuramoto_delayed.py",
    "*/scpn_quantum_control/accel/jax_kuramoto_mpc.py",
    # The KYMA toy-composition probe needs the optional [jax] extra, absent from the pinned CI
    # lane; its importorskip(jax)-guarded tests run locally. Covered by tests/test_kyma_*.py.
    "*/scpn_quantum_control/benchmarks/kyma/*.py",
    "*/scpn_quantum_control/mitigation/mitiq_integration.py",
    "*/scpn_quantum_control/analysis/quantum_persistent_homology.py",
    "*/scpn_quantum_control/forecasting/kuramoto_neural_operator.py",
    # The advantage study orchestrates the torch surrogate end-to-end; its test skips without the
    # optional [torch] extra, so its lines are excluded from the CPU-only line gate. The
    # host-independent arithmetic it relies on lives in neural_operator_cost_model.py, which is NOT
    # omitted and is covered to 100% in the ordinary lane.
    "*/scpn_quantum_control/forecasting/neural_operator_advantage.py",
]
exclude_lines = [
    "pragma: no cover",
    "if __name__",
    "raise NotImplementedError",
    # Protocol / abstract / overload stub bodies are never executed.
    "^\\s*\\.\\.\\.\\s*$",
]
exclude_also = ["if TYPE_CHECKING:"]