pyproject.toml

[build-system]
requires = ["setuptools>=77.0"]
build-backend = "setuptools.build_meta"

[project]
name = "liouscope"
dynamic = ["version"]
description = "Multi-diagnostic relaxation analysis for open quantum lattice systems"
readme = "README.md"
license = "Apache-2.0"
license-files = ["LICENSE"]
requires-python = ">=3.10"
authors = [
    { name = "Coworker Research" },
]
keywords = [
    "open quantum systems",
    "lindblad",
    "liouvillian",
    "mpemba",
    "non-normal",
    "pseudospectrum",
    "relaxation",
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Science/Research",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Scientific/Engineering :: Physics",
    "Typing :: Typed",
]
dependencies = [
    "numpy>=1.24",
    "scipy>=1.10",
]

[project.optional-dependencies]
qutip = ["qutip>=4.7"]
figures = ["matplotlib>=3.7"]
# Documentation toolchain (issue #72). Mirrors docs/requirements.txt, which
# Read the Docs installs directly; this extra lets local devs run
# `pip install -e .[docs]` + `sphinx-build -W docs docs/_build/html`.
docs = [
    "sphinx>=7.3",
    "furo>=2024.1.29",
    "myst-parser>=2.0",
]
dev = [
    "pytest>=8",
    "pytest-cov>=4",
    # Pinned exactly: ruff's isort I001 heuristic (lines-after-imports before a
    # module-level constant) changed between 0.15.14 and 0.15.20, flagging a
    # byte-identical, previously-green import block. Pin so red CI reflects code
    # defects, not linter releases. Bump deliberately + reformat in a dedicated PR.
    "ruff==0.15.20",
    "mypy>=1.10",
    "hypothesis>=6.100",
    "build>=1.2",
    # jsonschema is an optional runtime extra (manifest validation degrades
    # gracefully without it), but the dev/CI env must have it so the full
    # Draft202012Validator structural-conformance path is actually exercised
    # instead of silently skipped.
    "jsonschema>=4.18",
]

[project.urls]
Homepage = "https://github.com/marcohost33-maker/Liouscope"
Repository = "https://github.com/marcohost33-maker/Liouscope"
Issues = "https://github.com/marcohost33-maker/Liouscope/issues"

[tool.setuptools]
include-package-data = true

[tool.setuptools.dynamic]
# Single source of truth for the version: src/liouscope/_version.py.
# pyproject is a *pointer* here (AGENTS.md: "numbers drift, pointers don't").
version = { attr = "liouscope._version.__version__" }

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
liouscope = ["py.typed", "MANIFEST_SCHEMA.json", "STABILITY_REPORT_SCHEMA.json"]

[tool.pytest.ini_options]
minversion = "8.0"
addopts = "-ra --strict-markers --strict-config"
testpaths = ["tests"]
log_level = "INFO"
xfail_strict = true
markers = [
    "slow: marks tests that take significant time (deselect with -m 'not slow')",
    "qutip: tests that require qutip to be installed",
]
filterwarnings = [
    # Fail-loud default: any unexpected warning (deprecations included) is an
    # error, so dependency drift surfaces in CI instead of hiding in logs.
    "error",
    # Documented library behaviour, not a defect: the power iteration reports
    # a lower bound when top resolvent singular values are clustered
    # (ResolventConvergenceWarning). Matched BY MESSAGE, not by class path:
    # a class-based filter forces pytest to import liouscope at config time,
    # i.e. before pytest-cov starts measuring, which silently craters the
    # coverage report (module-not-measured) and trips --cov-fail-under.
    "ignore:resolvent_norm power iteration did not converge:UserWarning",
    # QuTiP emits this UserWarning at import time when the optional matplotlib
    # is absent (the CI matrix installs .[dev,qutip] without the figures
    # extra). Graphics are irrelevant to the cross-checks.
    "ignore:matplotlib not found:UserWarning",
]

[tool.coverage.run]
branch = true
source = ["src/liouscope"]
omit = [
    "src/liouscope/_version.py",
    "src/liouscope/examples.py",
]

[tool.coverage.report]
# Coverage ratchet (issue #72 item 4). Measured branch coverage on the local
# baseline (Python 3.14, this commit) was 94.61%. The floor is set
# conservatively to 90 -- a ratchet up from the previous fixed gate of 80 --
# leaving headroom for cross-version variation across the 3.10-3.14 CI matrix
# (version-gated branches change which lines are reachable). Raise this floor
# in a dedicated follow-up once cross-version CI confirms a higher stable
# minimum; never lower it without a documented rationale. Note: CI passes
# --cov-fail-under=90 explicitly, which mirrors this value.
fail_under = 90
precision = 2
show_missing = true
exclude_lines = [
    "pragma: no cover",
    "raise NotImplementedError",
    "if TYPE_CHECKING:",
    "if __name__ == .__main__.:",
]

[tool.ruff]
# target-version is intentionally absent: ruff infers py310 from
# project.requires-python (single source, sp-repo-review RF002).
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "B", "UP", "C4", "SIM", "RUF"]
ignore = [
    "E741",   # ambiguous variable name (l, I, etc.) -- physics convention
    "N802",   # uppercase test function names (anchor regressions A-N)
    "N803",   # uppercase argument names (H, L matrices)
    "N806",   # uppercase locals (G, L_super, etc.)
    "N815",   # mixedCase dataclass fields (beta_D, bootstrap_B)
    "B905",   # zip strict -- 3.10+ default is correct
    "B028",   # warnings.warn stacklevel
    "RUF003", # ambiguous unicode in comments (Übersicht in spec refs)
    "RUF001", # ambiguous unicode in string literals
    "RUF013", # implicit Optional in tests
    "SIM117", # nested with statements
    "UP015",  # mode='rt' verbose
    "RUF046", # int(round()) -- explicit safety on numpy scalars
    "RUF059", # SVD unpacking discards
    "F841",   # locally unused assignment in tests
    "E501",   # long lines in error messages
    "SIM108", # explicit if/else over ternary (readability)
]

[tool.mypy]
# 3.12 (not 3.10) so mypy can parse NumPy >=2.5 stubs, which use the PEP 695
# `type` statement (only accepted when the mypy target is >=3.12). Runtime 3.10
# support stays guarded by the test matrix (3.10/3.11) and ruff's py310 target
# (inferred from requires-python). Reversible: drop to 3.10 + cap numpy<2.5 if 3.10 type semantics are
# ever required. Fixes the repo-wide mypy gate failure on the 3.12-3.14 matrix.
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
warn_unreachable = true
strict_equality = true
disallow_untyped_defs = false
enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
files = ["src/liouscope"]

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