headwater 0.1.0__py3-none-any.whl

headwater/__init__.py

@@ -0,0 +1,107 @@
+from typing import TYPE_CHECKING
+
+from headwater._lazy import lazy_exports
+
+if TYPE_CHECKING:
+    __version__: str
+    from headwater.model import HeadwaterError, InvalidDataError
+    from headwater.query import (
+        Background,
+        Contribution,
+        Database,
+        Emitter,
+        ManyScores,
+        Match,
+        MonteCarlo,
+        MonteCarloProvenance,
+        NotCharacterised,
+        ParameterSensitivity,
+        Place,
+        Provenance,
+        Range,
+        Result,
+        Sensitivity,
+        Study,
+        Where,
+        load,
+        monte_carlo,
+        open,
+        score_many,
+    )
+
+_exported, _dir = lazy_exports(
+    globals(),
+    {
+        "headwater.model": ["HeadwaterError", "InvalidDataError"],
+        # From the module itself: once `headwater.query.monte_carlo` is imported, the attribute
+        # `monte_carlo` of `headwater.query` is that module, not the function.
+        "headwater.query.monte_carlo": [
+            "MonteCarlo",
+            "MonteCarloProvenance",
+            "Range",
+            "monte_carlo",
+        ],
+        "headwater.query": [
+            "Background",
+            "Emitter",
+            "Contribution",
+            "Database",
+            "Sensitivity",
+            "Match",
+            "NotCharacterised",
+            "ParameterSensitivity",
+            "Place",
+            "Provenance",
+            "Result",
+            "ManyScores",
+            "Study",
+            "Where",
+            "load",
+            "open",
+            "score_many",
+        ],
+    },
+)
+
+
+def __getattr__(name: str) -> object:
+    """The lazy exports, and `__version__`, read once from the installed metadata: pyproject.toml
+    is the one place that writes the version. `import headwater` loads no `importlib.metadata`."""
+    if name == "__version__":
+        from importlib.metadata import version
+
+        globals()["__version__"] = found = version("headwater")
+        return found
+    return _exported(name)
+
+
+def __dir__() -> list[str]:
+    return sorted({*_dir(), "__version__"})
+
+
+__all__ = [
+    "Background",
+    "Emitter",
+    "Contribution",
+    "Database",
+    "HeadwaterError",
+    "InvalidDataError",
+    "Sensitivity",
+    "Match",
+    "MonteCarlo",
+    "MonteCarloProvenance",
+    "NotCharacterised",
+    "ParameterSensitivity",
+    "Place",
+    "Provenance",
+    "Range",
+    "Result",
+    "ManyScores",
+    "Study",
+    "Where",
+    "__version__",
+    "load",
+    "monte_carlo",
+    "open",
+    "score_many",
+]

headwater/_lazy.py

@@ -0,0 +1,33 @@
+"""Lazy exports for a package's `__init__`: `from headwater import open` loads `headwater.query`
+only when `open` is first asked for, so importing the package, or a light submodule such as the
+command line, loads no numpy, scipy or pyarrow."""
+
+import importlib
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+
+def lazy_exports(
+    namespace: dict[str, Any], modules: Mapping[str, Sequence[str]]
+) -> tuple[Callable[[str], object], Callable[[], list[str]]]:
+    """The `__getattr__` and `__dir__` of a package, given its `globals()`.
+
+    `modules` maps a module to the names the package exports from it. Write the same imports under
+    `if TYPE_CHECKING:` in the package, so editors and pyright see the names, and set
+    `__getattr__, __dir__ = lazy_exports(globals(), {...})`.
+    """
+    package = namespace["__name__"]
+    defined_in = {name: module for module, names in modules.items() for name in names}
+
+    def __getattr__(name: str) -> object:
+        module = defined_in.get(name)
+        if module is None:
+            raise AttributeError(f"module {package!r} has no attribute {name!r}")
+        value = getattr(importlib.import_module(module), name)
+        namespace[name] = value
+        return value
+
+    def __dir__() -> list[str]:
+        return sorted({*namespace, *defined_in})
+
+    return __getattr__, __dir__

headwater/calc/__init__.py

@@ -0,0 +1,76 @@
+"""Pure calculation functions on NumPy arrays and SciPy sparse matrices.
+
+Matrix indices exist only inside one calculation. No file access, no ids, no global state.
+"""
+
+from headwater.calc.errors import CalculationError, ResidualError, SingularMatrixError
+from headwater.calc.explain import (
+    Levers,
+    LineEffects,
+    Node,
+    emission_levers,
+    emission_line_levers,
+    explain,
+    levers,
+    line_levers,
+    where,
+)
+from headwater.calc.signs import Entry, Matrix, RoleEntry, matrix_entry, role_entries
+from headwater.calc.skus import sku_scores
+from headwater.calc.solve import (
+    CONDITION_LIMIT,
+    TOLERANCE,
+    Factorization,
+    Solution,
+    SolverSettings,
+    Step,
+    factorize,
+    scores,
+    supply,
+)
+from headwater.calc.study import StudySolution, solve_study
+from headwater.calc.update import (
+    LowRankUpdate,
+    low_rank_update,
+    update_column,
+    update_emissions,
+)
+from headwater.calc.weighting import weighted_scores, weighted_sum
+
+__all__ = [
+    "CONDITION_LIMIT",
+    "TOLERANCE",
+    "CalculationError",
+    "Entry",
+    "Factorization",
+    "Levers",
+    "LineEffects",
+    "LowRankUpdate",
+    "Matrix",
+    "Node",
+    "ResidualError",
+    "RoleEntry",
+    "SingularMatrixError",
+    "Solution",
+    "SolverSettings",
+    "Step",
+    "StudySolution",
+    "emission_levers",
+    "emission_line_levers",
+    "explain",
+    "factorize",
+    "levers",
+    "line_levers",
+    "low_rank_update",
+    "matrix_entry",
+    "role_entries",
+    "scores",
+    "sku_scores",
+    "solve_study",
+    "supply",
+    "update_column",
+    "update_emissions",
+    "weighted_scores",
+    "weighted_sum",
+    "where",
+]

headwater/calc/arrays.py

@@ -0,0 +1,45 @@
+"""Input checks shared by the calculation functions."""
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy import sparse
+
+from headwater.calc.errors import CalculationError
+
+type Vector = NDArray[np.float64]
+type MatrixLike = sparse.sparray | sparse.spmatrix | NDArray[np.float64]
+
+
+def as_matrix(A: MatrixLike, name: str = "matrix", *, copy: bool = True) -> sparse.csc_array:
+    """A float64 CSC copy of `A`, with duplicate entries summed and zeros removed.
+
+    With `copy=False`, a matrix already in that form is returned as it is, not copied: for a
+    caller that only reads it. `A` itself is never changed. Raises CalculationError naming the
+    columns (processes) that hold a NaN or an infinity.
+    """
+    matrix = sparse.csc_array(A, dtype=np.float64, copy=copy)
+    if matrix.ndim != 2:
+        raise ValueError(f"{name} must be 2-dimensional, got shape {matrix.shape}")
+    if copy or not matrix.has_canonical_format or not np.all(matrix.data):
+        if not copy:
+            matrix = matrix.copy()
+        matrix.sum_duplicates()
+        matrix.eliminate_zeros()
+    bad = ~np.isfinite(matrix.data)
+    if bad.any():
+        columns = np.repeat(np.arange(matrix.shape[1]), np.diff(matrix.indptr))
+        raise CalculationError(
+            f"{name} has entries that are not finite in columns", np.unique(columns[bad])
+        )
+    return matrix
+
+
+def as_vector(v: ArrayLike, n: int, name: str) -> Vector:
+    """A float64 copy of `v`, checked to be finite and of length `n`."""
+    vector = np.array(v, dtype=np.float64)
+    if vector.shape != (n,):
+        raise ValueError(f"{name} must be a vector of length {n}, got shape {vector.shape}")
+    bad = np.flatnonzero(~np.isfinite(vector))
+    if bad.size:
+        raise CalculationError(f"{name} has entries that are not finite at indices", bad)
+    return vector

headwater/calc/cancellation.py

@@ -0,0 +1,85 @@
+"""The positive and negative parts of a score, and whether the score is near 0 because they cancel.
+
+Example, the carbon toy: 1 kg of fabric takes 1.5 kg of CO2 from the air, which counts -1.5,
+and its residue emits 0.4 kg of non-fossil CO2, which counts +0.4. The net biogenic score is
+-1.1, of parts +0.4 and -1.5: it does not cancel. If the residue emitted 1.5 kg, the net would
+be 0 with parts of 1.5 each: a reader who sees 0 should know it is +1.5 - 1.5.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from headwater.calc.arrays import MatrixLike, Vector, as_matrix
+
+CANCELS_BELOW = 1e-3
+"""A score cancels when it is smaller than this share of its gross, the sum of the sizes of its
+parts. The share docs/appendix/benchmarks.md checks on ecoinvent, under "Numerics on ecoinvent"."""
+
+
+@dataclass(frozen=True)
+class Cancellation:
+    """The positive and the negative part of a score: the sums of its positive and of its
+    negative terms, one term per flow and process."""
+
+    positive: float
+    negative: float
+
+    @property
+    def net(self) -> float:
+        """The score: positive + negative."""
+        return self.positive + self.negative
+
+    @property
+    def gross(self) -> float:
+        """The sum of the sizes of the parts: positive - negative."""
+        return self.positive - self.negative
+
+    @property
+    def cancels(self) -> bool:
+        """True when the parts are not 0 and the score is less than `CANCELS_BELOW` of their
+        size. A score with no parts, an exact zero, does not cancel."""
+        return self.gross > 0 and abs(self.net) < CANCELS_BELOW * self.gross
+
+    def __add__(self, other: "Cancellation") -> "Cancellation":
+        return Cancellation(self.positive + other.positive, self.negative + other.negative)
+
+
+def cancellation(B: MatrixLike, c: Vector, s: Vector) -> Cancellation:
+    """The parts of the score `c · B s`, term by term: `c[f] × B[f, p] × s[p]` for every flow f
+    and process p.
+
+    `B` has one row per elementary flow and one column per process, `c` holds the factors of one
+    indicator and `s` how much each process runs. Terms are taken per flow, not per process, so
+    a process that takes CO2 from the air and emits it again has two parts, not a net of 0.
+    """
+    plus, minus = process_parts(B, c)
+    return cancellation_of(plus, minus, s)
+
+
+def process_parts(B: MatrixLike, c: Vector) -> tuple[Vector, Vector]:
+    """For each process, the sum of its positive terms `c[f] × B[f, p]` and of its negative
+    ones, per unit it runs. They depend on `B` and `c` only, so a caller can keep them for every
+    `s`."""
+    matrix = as_matrix(B, "B", copy=False)
+    n_flows = matrix.shape[0]
+    if c.shape != (n_flows,):
+        raise ValueError(f"c must have one factor per flow of B ({n_flows} flows), got {c.shape}")
+    terms = matrix.multiply(c.reshape(-1, 1)).tocsc()
+    plus = np.asarray(terms.maximum(0).sum(axis=0), dtype=np.float64).ravel()
+    minus = np.asarray(terms.minimum(0).sum(axis=0), dtype=np.float64).ravel()
+    return plus, minus
+
+
+def cancellation_of(plus: Vector, minus: Vector, s: Vector) -> Cancellation:
+    """The parts of a score from `process_parts` and how much each process runs. A term is
+    positive when its process's term and its run have the same sign, so a process that runs
+    backwards turns its terms around."""
+    if s.shape != plus.shape:
+        raise ValueError(
+            f"s must have one entry per process ({plus.shape[0]} processes), got {s.shape}"
+        )
+    up, down = np.maximum(s, 0.0), np.minimum(s, 0.0)
+    return Cancellation(
+        positive=float(plus @ up + minus @ down), negative=float(minus @ up + plus @ down)
+    )

headwater/calc/errors.py

@@ -0,0 +1,54 @@
+"""Errors raised when a calculation cannot give a trustworthy number."""
+
+from collections.abc import Iterable
+
+from headwater.model.errors import HeadwaterError
+
+SHOWN = 20
+
+
+class CalculationError(HeadwaterError):
+    """A calculation cannot give a trustworthy number.
+
+    `indices` names the processes involved, as matrix indices of this calculation. The caller
+    maps them back to ids.
+    """
+
+    def __init__(self, message: str, indices: Iterable[int] = ()) -> None:
+        self.message = message
+        self.indices: tuple[int, ...] = tuple(int(i) for i in indices)
+        text = message
+        if self.indices:
+            shown = ", ".join(str(i) for i in self.indices[:SHOWN])
+            more = len(self.indices) - SHOWN
+            text = f"{message}: {shown}" + (f" and {more} more" if more > 0 else "")
+        super().__init__(text)
+
+    def __reduce__(self) -> tuple[type, tuple[object, ...]]:
+        return (type(self), (self.message, self.indices))
+
+    def shifted(self, offset: int) -> "CalculationError":
+        """The same error with every index moved by `offset`.
+
+        For a calculation on a block that sits below another one in a stacked system.
+        """
+        return type(self)(self.message, (i + offset for i in self.indices))
+
+
+class SingularMatrixError(CalculationError):
+    """The technosphere matrix cannot be solved."""
+
+
+class ResidualError(CalculationError):
+    """A result does not satisfy its equations within the tolerance."""
+
+    def __init__(self, message: str, indices: Iterable[int], residual: float) -> None:
+        super().__init__(f"{message} (largest {residual:.3g})", indices)
+        self.message = message
+        self.residual = residual
+
+    def __reduce__(self) -> tuple[type, tuple[object, ...]]:
+        return (type(self), (self.message, self.indices, self.residual))
+
+    def shifted(self, offset: int) -> "ResidualError":
+        return ResidualError(self.message, (i + offset for i in self.indices), self.residual)