stresspy 0.0.1__tar.gz

stresspy-0.0.1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: stresspy
+Version: 0.0.1
+Summary: Geometric stress criterion modeling and tangent space decomposition
+License: CC BY-NC 4.0
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+
+# StressPy: Geometric Stress Criterion (GSC)
+
+`stresspy` is a reference Python implementation of the deterministic numerical core of the **Geometric Stress Criterion (GSC)**. It decomposes model–data discrepancies into components that are locally accessible (tangent) and inaccessible (normal) through parameter variation.
+
+---
+
+## 1. Mathematical Background
+
+At a specified parameter point $\hat{\theta}$, let $r = y - f(\hat{\theta})$ be the model–data discrepancy and $J = \left.\frac{\partial f}{\partial x}\right\vert{}_{\hat{\theta}}$ be the Jacobian with respect to parameter coordinates $x$.
+
+After applying an observation-space whitening transformation $L$:
+$$r_W = Lr, \qquad J_W = LJ$$
+
+If $U_r$ contains the retained left singular vectors of $J_W$, the orthogonal components are:
+$$r_{\parallel,W} = U_r U_r^\top r_W, \qquad r_{\perp,W} = r_W - r_{\parallel,W}$$
+
+The reported stresses and normal fraction are:
+$$S_{\mathrm{total}} = \Vert{}r_W\Vert{}_2^2, \quad S_{\parallel} = \Vert{}r_{\parallel,W}\Vert{}_2^2, \quad S_{\perp} = \Vert{}r_{\perp,W}\Vert{}_2^2, \quad F_{\perp} = \frac{S_{\perp}}{S_{\mathrm{total}}}$$
+
+The minimum-norm local repair vector $\Delta x$ satisfies:
+$$\Delta x = V_r \Sigma_r^{-1} U_r^\top r_W$$
+
+Under the local linear approximation, $r - J \Delta x = r_\perp$.
+
+---
+
+## 2. Installation
+
+```bash
+pip install stresspy

stresspy-0.0.1/README.md

@@ -0,0 +1,30 @@
+# StressPy: Geometric Stress Criterion (GSC)
+
+`stresspy` is a reference Python implementation of the deterministic numerical core of the **Geometric Stress Criterion (GSC)**. It decomposes model–data discrepancies into components that are locally accessible (tangent) and inaccessible (normal) through parameter variation.
+
+---
+
+## 1. Mathematical Background
+
+At a specified parameter point $\hat{\theta}$, let $r = y - f(\hat{\theta})$ be the model–data discrepancy and $J = \left.\frac{\partial f}{\partial x}\right\vert{}_{\hat{\theta}}$ be the Jacobian with respect to parameter coordinates $x$.
+
+After applying an observation-space whitening transformation $L$:
+$$r_W = Lr, \qquad J_W = LJ$$
+
+If $U_r$ contains the retained left singular vectors of $J_W$, the orthogonal components are:
+$$r_{\parallel,W} = U_r U_r^\top r_W, \qquad r_{\perp,W} = r_W - r_{\parallel,W}$$
+
+The reported stresses and normal fraction are:
+$$S_{\mathrm{total}} = \Vert{}r_W\Vert{}_2^2, \quad S_{\parallel} = \Vert{}r_{\parallel,W}\Vert{}_2^2, \quad S_{\perp} = \Vert{}r_{\perp,W}\Vert{}_2^2, \quad F_{\perp} = \frac{S_{\perp}}{S_{\mathrm{total}}}$$
+
+The minimum-norm local repair vector $\Delta x$ satisfies:
+$$\Delta x = V_r \Sigma_r^{-1} U_r^\top r_W$$
+
+Under the local linear approximation, $r - J \Delta x = r_\perp$.
+
+---
+
+## 2. Installation
+
+```bash
+pip install stresspy

stresspy-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stresspy"
+version = "0.0.1"
+description = "Geometric stress criterion modeling and tangent space decomposition"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "CC BY-NC 4.0" }
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+
+# Add any dependencies your core code needs, e.g. "numpy", "scipy"
+dependencies = [
+    "numpy",
+    "scipy",
+    "pandas",
+    
+]

stresspy-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stresspy-0.0.1/src/stresspy/__init__.py

@@ -0,0 +1 @@
+from .core import *

stresspy-0.0.1/src/stresspy/core.py

@@ -0,0 +1,374 @@
+"""StressPy core routines for the Geometric Stress Criterion (GSC).
+
+This module implements the deterministic local tangent--normal decomposition.
+It deliberately does not fit models, construct Jacobians, prepare biological
+replicates, or perform bootstrap calibration. Those operations belong in
+separate modules built around this small, testable numerical kernel.
+
+Conventions
+-----------
+The discrepancy is defined as ``residual = observed - predicted``. If ``J``
+is the Jacobian of the predictions with respect to the chosen parameter
+coordinates, the minimum-norm local repair ``delta`` satisfies
+``J @ delta = tangent_component`` in the selected observation-space metric.
+Consequently, under the linear approximation, ``residual - J @ delta`` is the
+normal component.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Any, Optional, Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+FloatArray = NDArray[np.float64]
+
+
+@dataclass(frozen=True)
+class GSCResult:
+    """Result of a local GSC tangent--normal decomposition.
+
+    Stress values and the ``weighted_*`` vectors are expressed in whitened
+    observation coordinates. The unprefixed component vectors are mapped back
+    to the original observation coordinates; they are orthogonal under the
+    selected metric, not necessarily under the ordinary Euclidean metric.
+
+    The repair vector is minimum-norm in the parameter coordinates used to
+    construct the supplied Jacobian. Its magnitude is coordinate dependent.
+    """
+
+    n_observations: int
+    n_parameters: int
+    rank: int
+    rank_threshold: float
+    singular_values: FloatArray
+    total_stress: float
+    tangent_stress: float
+    normal_stress: float
+    normal_fraction: float
+    residual: FloatArray
+    tangent_component: FloatArray
+    normal_component: FloatArray
+    weighted_residual: FloatArray
+    weighted_tangent_component: FloatArray
+    weighted_normal_component: FloatArray
+    repair_vector: FloatArray
+    repair_norm: float
+    condition_number: float
+    tangent_basis: FloatArray
+    parameter_basis: FloatArray
+
+    @property
+    def normal_fraction_pct(self) -> float:
+        """Normal fraction expressed as a percentage."""
+
+        return 100.0 * self.normal_fraction
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a shallow dictionary representation of the result."""
+
+        result = {item.name: getattr(self, item.name) for item in fields(self)}
+        result["normal_fraction_pct"] = self.normal_fraction_pct
+        return result
+
+
+def _as_vector(name: str, values: ArrayLike) -> FloatArray:
+    array = np.asarray(values, dtype=float)
+    if array.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional; got shape {array.shape}.")
+    if array.size == 0:
+        raise ValueError(f"{name} must not be empty.")
+    if not np.all(np.isfinite(array)):
+        raise ValueError(f"{name} must contain only finite values.")
+    return array
+
+
+def _as_jacobian(values: ArrayLike, n_observations: int) -> FloatArray:
+    jacobian = np.asarray(values, dtype=float)
+    if jacobian.ndim != 2:
+        raise ValueError(
+            f"jacobian must be two-dimensional; got shape {jacobian.shape}."
+        )
+    if jacobian.shape[0] != n_observations:
+        raise ValueError(
+            "jacobian row count must equal the number of observations; "
+            f"got {jacobian.shape[0]} and {n_observations}."
+        )
+    if jacobian.shape[1] == 0:
+        raise ValueError("jacobian must contain at least one parameter column.")
+    if not np.all(np.isfinite(jacobian)):
+        raise ValueError("jacobian must contain only finite values.")
+    return jacobian
+
+
+def _build_whitener(
+    n: int,
+    *,
+    sigma: Optional[ArrayLike],
+    covariance: Optional[ArrayLike],
+    whitener: Optional[ArrayLike],
+) -> tuple[FloatArray, FloatArray]:
+    supplied = sum(item is not None for item in (sigma, covariance, whitener))
+    if supplied > 1:
+        raise ValueError("Supply at most one of sigma, covariance, or whitener.")
+
+    if sigma is not None:
+        scale = _as_vector("sigma", sigma)
+        if scale.size != n:
+            raise ValueError(f"sigma must have length {n}; got {scale.size}.")
+        if np.any(scale <= 0.0):
+            raise ValueError("sigma values must all be strictly positive.")
+        return np.diag(1.0 / scale), np.diag(scale)
+
+    if covariance is not None:
+        cov = np.asarray(covariance, dtype=float)
+        if cov.shape != (n, n):
+            raise ValueError(f"covariance must have shape {(n, n)}; got {cov.shape}.")
+        if not np.all(np.isfinite(cov)):
+            raise ValueError("covariance must contain only finite values.")
+        if not np.allclose(cov, cov.T, rtol=1e-10, atol=1e-12):
+            raise ValueError("covariance must be symmetric.")
+        try:
+            chol = np.linalg.cholesky(cov)
+        except np.linalg.LinAlgError as exc:
+            raise ValueError("covariance must be positive definite.") from exc
+        whitening = np.linalg.solve(chol, np.eye(n))
+        return whitening, chol
+
+    if whitener is not None:
+        whitening = np.asarray(whitener, dtype=float)
+        if whitening.shape != (n, n):
+            raise ValueError(f"whitener must have shape {(n, n)}; got {whitening.shape}.")
+        if not np.all(np.isfinite(whitening)):
+            raise ValueError("whitener must contain only finite values.")
+        try:
+            unwhitening = np.linalg.inv(whitening)
+        except np.linalg.LinAlgError as exc:
+            raise ValueError("whitener must be nonsingular.") from exc
+        return whitening, unwhitening
+
+    identity = np.eye(n)
+    return identity, identity
+
+
+def decompose(
+    observed: ArrayLike,
+    predicted: ArrayLike,
+    jacobian: ArrayLike,
+    *,
+    sigma: Optional[ArrayLike] = None,
+    covariance: Optional[ArrayLike] = None,
+    whitener: Optional[ArrayLike] = None,
+    rank_rtol: Optional[float] = None,
+    rank_atol: float = 0.0,
+) -> GSCResult:
+    """Decompose model--data discrepancy into tangent and normal components.
+
+    ``jacobian`` must be evaluated at the parameter point associated with
+    ``predicted`` and use the same parameter coordinates in which the repair
+    vector is to be reported.
+
+    Supply at most one of ``sigma``, ``covariance``, or ``whitener``. A
+    singular value is retained when
+    ``s > max(rank_atol, rank_rtol * s_max)``. If ``rank_rtol`` is omitted,
+    ``max(jacobian.shape) * machine_epsilon`` is used.
+    """
+
+    y = _as_vector("observed", observed)
+    y_hat = _as_vector("predicted", predicted)
+    if y_hat.size != y.size:
+        raise ValueError(
+            f"observed and predicted must have equal length; got {y.size} and {y_hat.size}."
+        )
+    J = _as_jacobian(jacobian, y.size)
+
+    if rank_rtol is not None and (not np.isfinite(rank_rtol) or rank_rtol < 0.0):
+        raise ValueError("rank_rtol must be finite and non-negative.")
+    if not np.isfinite(rank_atol) or rank_atol < 0.0:
+        raise ValueError("rank_atol must be finite and non-negative.")
+
+    L, L_inv = _build_whitener(
+        y.size, sigma=sigma, covariance=covariance, whitener=whitener
+    )
+    residual = y - y_hat
+    residual_w = L @ residual
+    jacobian_w = L @ J
+
+    U, singular_values, Vt = np.linalg.svd(jacobian_w, full_matrices=False)
+    s_max = float(singular_values[0]) if singular_values.size else 0.0
+    if rank_rtol is None:
+        rank_rtol = max(jacobian_w.shape) * np.finfo(float).eps
+    threshold = max(float(rank_atol), float(rank_rtol) * s_max)
+    rank = int(np.count_nonzero(singular_values > threshold))
+
+    U_r = U[:, :rank]
+    s_r = singular_values[:rank]
+    V_r = Vt[:rank, :].T
+
+    if rank:
+        tangent_w = U_r @ (U_r.T @ residual_w)
+        repair = V_r @ ((U_r.T @ residual_w) / s_r)
+        condition_number = float(s_r[0] / s_r[-1])
+    else:
+        tangent_w = np.zeros_like(residual_w)
+        repair = np.zeros(J.shape[1], dtype=float)
+        condition_number = float("inf")
+
+    normal_w = residual_w - tangent_w
+    tangent = L_inv @ tangent_w
+    normal = L_inv @ normal_w
+
+    total_stress = float(residual_w @ residual_w)
+    tangent_stress = float(tangent_w @ tangent_w)
+    normal_stress = float(normal_w @ normal_w)
+    normal_fraction = (
+        normal_stress / total_stress if total_stress > 0.0 else float("nan")
+    )
+
+    return GSCResult(
+        n_observations=y.size,
+        n_parameters=J.shape[1],
+        rank=rank,
+        rank_threshold=threshold,
+        singular_values=singular_values,
+        total_stress=total_stress,
+        tangent_stress=tangent_stress,
+        normal_stress=normal_stress,
+        normal_fraction=normal_fraction,
+        residual=residual,
+        tangent_component=tangent,
+        normal_component=normal,
+        weighted_residual=residual_w,
+        weighted_tangent_component=tangent_w,
+        weighted_normal_component=normal_w,
+        repair_vector=repair,
+        repair_norm=float(np.linalg.norm(repair)),
+        condition_number=condition_number,
+        tangent_basis=U_r,
+        parameter_basis=V_r,
+    )
+
+
+def decompose_blocks(
+    observed_blocks: Sequence[ArrayLike],
+    predicted_blocks: Sequence[ArrayLike],
+    jacobian_blocks: Sequence[ArrayLike],
+    *,
+    sigma_blocks: Optional[Sequence[ArrayLike]] = None,
+    rank_rtol: Optional[float] = None,
+    rank_atol: float = 0.0,
+) -> GSCResult:
+    """Stack independent blocks and perform one joint GSC interrogation.
+
+    This convenience function supports diagonal weighting only. Use
+    :func:`decompose` with a full covariance matrix when errors are correlated
+    across blocks.
+    """
+
+    if len(observed_blocks) == 0:
+        raise ValueError("At least one observation block is required.")
+    if not (
+        len(observed_blocks) == len(predicted_blocks) == len(jacobian_blocks)
+    ):
+        raise ValueError(
+            "observed_blocks, predicted_blocks, and jacobian_blocks must have equal length."
+        )
+    if sigma_blocks is not None and len(sigma_blocks) != len(observed_blocks):
+        raise ValueError("sigma_blocks must have the same number of blocks as observed_blocks.")
+
+    observed = np.concatenate(
+        [_as_vector("observation block", item) for item in observed_blocks]
+    )
+    predicted = np.concatenate(
+        [_as_vector("prediction block", item) for item in predicted_blocks]
+    )
+    jacobian = np.vstack([np.asarray(item, dtype=float) for item in jacobian_blocks])
+    sigma = None
+    if sigma_blocks is not None:
+        sigma = np.concatenate(
+            [_as_vector("sigma block", item) for item in sigma_blocks]
+        )
+
+    return decompose(
+        observed,
+        predicted,
+        jacobian,
+        sigma=sigma,
+        rank_rtol=rank_rtol,
+        rank_atol=rank_atol,
+    )
+
+
+def floor_sigma(
+    sigma: ArrayLike,
+    *,
+    quantile: float = 0.10,
+    floor: Optional[float] = None,
+) -> tuple[FloatArray, float]:
+    """Apply an explicit lower floor to valid positive standard deviations.
+
+    This is optional preprocessing, not part of the GSC definition. If
+    ``floor`` is omitted it is calculated from the requested quantile.
+    """
+
+    scale = _as_vector("sigma", sigma)
+    if np.any(scale <= 0.0):
+        raise ValueError("sigma values must all be strictly positive before flooring.")
+    if not np.isfinite(quantile) or not 0.0 <= quantile <= 1.0:
+        raise ValueError("quantile must be finite and lie between 0 and 1.")
+    if floor is None:
+        floor_value = float(np.quantile(scale, quantile))
+    else:
+        floor_value = float(floor)
+        if not np.isfinite(floor_value) or floor_value <= 0.0:
+            raise ValueError("floor must be finite and strictly positive.")
+    return np.maximum(scale, floor_value), floor_value
+
+
+def jacobian_to_log_coordinates(
+    jacobian: ArrayLike,
+    parameters: ArrayLike,
+    *,
+    log_mask: Optional[ArrayLike] = None,
+) -> FloatArray:
+    """Convert a raw-parameter Jacobian to mixed identity/log coordinates.
+
+    For a log-transformed parameter, ``x_j = log(theta_j)``, the corresponding
+    Jacobian column is multiplied by ``theta_j``. Columns not selected by
+    ``log_mask`` are unchanged. If ``log_mask`` is omitted, every parameter is
+    treated as log-transformed.
+    """
+
+    raw = np.asarray(jacobian, dtype=float)
+    if raw.ndim != 2:
+        raise ValueError(f"jacobian must be two-dimensional; got shape {raw.shape}.")
+    J = _as_jacobian(raw, raw.shape[0])
+    theta = _as_vector("parameters", parameters)
+    if J.shape[1] != theta.size:
+        raise ValueError(
+            f"jacobian has {J.shape[1]} columns but parameters has length {theta.size}."
+        )
+    if log_mask is None:
+        mask = np.ones(theta.size, dtype=bool)
+    else:
+        mask = np.asarray(log_mask, dtype=bool)
+        if mask.shape != theta.shape:
+            raise ValueError(f"log_mask must have shape {theta.shape}; got {mask.shape}.")
+    if np.any(theta[mask] <= 0.0):
+        raise ValueError("Parameters selected for log transformation must be positive.")
+
+    column_scale = np.ones(theta.size, dtype=float)
+    column_scale[mask] = theta[mask]
+    return J * column_scale[None, :]
+
+
+__all__ = [
+    "GSCResult",
+    "decompose",
+    "decompose_blocks",
+    "floor_sigma",
+    "jacobian_to_log_coordinates",
+]

stresspy-0.0.1/src/stresspy.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: stresspy
+Version: 0.0.1
+Summary: Geometric stress criterion modeling and tangent space decomposition
+License: CC BY-NC 4.0
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+
+# StressPy: Geometric Stress Criterion (GSC)
+
+`stresspy` is a reference Python implementation of the deterministic numerical core of the **Geometric Stress Criterion (GSC)**. It decomposes model–data discrepancies into components that are locally accessible (tangent) and inaccessible (normal) through parameter variation.
+
+---
+
+## 1. Mathematical Background
+
+At a specified parameter point $\hat{\theta}$, let $r = y - f(\hat{\theta})$ be the model–data discrepancy and $J = \left.\frac{\partial f}{\partial x}\right\vert{}_{\hat{\theta}}$ be the Jacobian with respect to parameter coordinates $x$.
+
+After applying an observation-space whitening transformation $L$:
+$$r_W = Lr, \qquad J_W = LJ$$
+
+If $U_r$ contains the retained left singular vectors of $J_W$, the orthogonal components are:
+$$r_{\parallel,W} = U_r U_r^\top r_W, \qquad r_{\perp,W} = r_W - r_{\parallel,W}$$
+
+The reported stresses and normal fraction are:
+$$S_{\mathrm{total}} = \Vert{}r_W\Vert{}_2^2, \quad S_{\parallel} = \Vert{}r_{\parallel,W}\Vert{}_2^2, \quad S_{\perp} = \Vert{}r_{\perp,W}\Vert{}_2^2, \quad F_{\perp} = \frac{S_{\perp}}{S_{\mathrm{total}}}$$
+
+The minimum-norm local repair vector $\Delta x$ satisfies:
+$$\Delta x = V_r \Sigma_r^{-1} U_r^\top r_W$$
+
+Under the local linear approximation, $r - J \Delta x = r_\perp$.
+
+---
+
+## 2. Installation
+
+```bash
+pip install stresspy

stresspy-0.0.1/src/stresspy.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/stresspy/__init__.py
+src/stresspy/core.py
+src/stresspy.egg-info/PKG-INFO
+src/stresspy.egg-info/SOURCES.txt
+src/stresspy.egg-info/dependency_links.txt
+src/stresspy.egg-info/requires.txt
+src/stresspy.egg-info/top_level.txt
+tests/test_core.py

stresspy-0.0.1/src/stresspy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stresspy-0.0.1/src/stresspy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+scipy
+pandas

stresspy-0.0.1/src/stresspy.egg-info/top_level.txt

@@ -0,0 +1 @@
+stresspy

stresspy-0.0.1/tests/test_core.py

@@ -0,0 +1,113 @@
+import numpy as np
+import pytest
+from stresspy import (
+    decompose,
+    decompose_blocks,
+    floor_sigma,
+    jacobian_to_log_coordinates,
+)
+
+@pytest.fixture
+def basic_setup():
+    J = np.array([[1.0, 0.0], [1.0, 1.0], [0.0, 1.0]])
+    predicted = np.array([1.0, 2.0, 1.0])
+    observed = np.array([1.1, 1.9, 0.9])
+    sigma = np.array([0.1, 0.1, 0.1])
+    return observed, predicted, J, sigma
+
+# 1. Stress additive identity: total = tangent + normal
+def test_stress_addition(basic_setup):
+    y, y_hat, J, sigma = basic_setup
+    res = decompose(y, y_hat, J, sigma=sigma)
+    np.testing.assert_allclose(res.total_stress, res.tangent_stress + res.normal_stress)
+
+# 2. Local linear repair residual identity: (r - J @ repair) == normal_component
+def test_linear_repair_identity(basic_setup):
+    y, y_hat, J, sigma = basic_setup
+    res = decompose(y, y_hat, J, sigma=sigma)
+    residual = y - y_hat
+    np.testing.assert_allclose(residual - J @ res.repair_vector, res.normal_component, atol=1e-12)
+
+# 3. Pure tangent residual yields zero normal stress
+def test_pure_tangent_residual(basic_setup):
+    _, y_hat, J, sigma = basic_setup
+    dx_true = np.array([0.2, -0.1])
+    y_tangent = y_hat + J @ dx_true
+    res = decompose(y_tangent, y_hat, J, sigma=sigma)
+    np.testing.assert_allclose(res.normal_stress, 0.0, atol=1e-12)
+
+# 4. Pure normal residual yields zero tangent stress and zero repair
+def test_pure_normal_residual():
+    J = np.array([[1.0], [0.0]])
+    y_hat = np.array([0.0, 0.0])
+    y_normal = np.array([0.0, 2.0])  # Orthogonal to column space of J
+    res = decompose(y_normal, y_hat, J)
+    np.testing.assert_allclose(res.tangent_stress, 0.0, atol=1e-12)
+    np.testing.assert_allclose(res.repair_vector, np.array([0.0]), atol=1e-12)
+
+# 5. Diagonal covariance and equivalent sigma weighting agree
+def test_sigma_vs_covariance_equivalence(basic_setup):
+    y, y_hat, J, sigma = basic_setup
+    res_sigma = decompose(y, y_hat, J, sigma=sigma)
+    
+    cov = np.diag(sigma**2)
+    res_cov = decompose(y, y_hat, J, covariance=cov)
+    
+    np.testing.assert_allclose(res_sigma.total_stress, res_cov.total_stress)
+    np.testing.assert_allclose(res_sigma.normal_fraction_pct, res_cov.normal_fraction_pct)
+
+# 6. Rank-deficient and zero Jacobians handled cleanly
+def test_zero_jacobian(basic_setup):
+    y, y_hat, _, sigma = basic_setup
+    J_zero = np.zeros((3, 2))
+    res = decompose(y, y_hat, J_zero, sigma=sigma)
+    assert res.rank == 0
+    np.testing.assert_allclose(res.normal_stress, res.total_stress)
+    np.testing.assert_allclose(res.repair_vector, np.zeros(2))
+
+# 7. Permuting observations leaves scalar stress results unchanged
+def test_observation_permutation(basic_setup):
+    y, y_hat, J, sigma = basic_setup
+    perm = [2, 0, 1]
+    
+    res_orig = decompose(y, y_hat, J, sigma=sigma)
+    res_perm = decompose(y[perm], y_hat[perm], J[perm], sigma=sigma[perm])
+    
+    np.testing.assert_allclose(res_orig.total_stress, res_perm.total_stress)
+    np.testing.assert_allclose(res_orig.normal_fraction_pct, res_perm.normal_fraction_pct)
+    np.testing.assert_allclose(res_orig.repair_vector, res_perm.repair_vector)
+
+# 8. Joint block analysis agrees with explicit array stacking
+def test_joint_block_stacking(basic_setup):
+    y1, f1, J1, s1 = basic_setup
+    y2, f2, J2, s2 = y1 * 0.5, f1 * 0.5, J1 * 0.5, s1 * 0.5
+    
+    joint_res = decompose_blocks(
+        observed_blocks=[y1, y2],
+        predicted_blocks=[f1, f2],
+        jacobian_blocks=[J1, J2],
+        sigma_blocks=[s1, s2]
+    )
+    
+    y_stack = np.hstack([y1, y2])
+    f_stack = np.hstack([f1, f2])
+    J_stack = np.vstack([J1, J2])
+    s_stack = np.hstack([s1, s2])
+    stack_res = decompose(y_stack, f_stack, J_stack, sigma=s_stack)
+    
+    np.testing.assert_allclose(joint_res.total_stress, stack_res.total_stress)
+    np.testing.assert_allclose(joint_res.repair_vector, stack_res.repair_vector)
+
+# 9. Log-coordinate transformation spans same tangent space when un-truncated
+def test_log_coordinate_span(basic_setup):
+    y, y_hat, J_raw, sigma = basic_setup
+    p_hat = np.array([2.0, 0.5])
+    log_mask = np.array([True, True])
+    
+    J_log = jacobian_to_log_coordinates(J_raw, parameters=p_hat, log_mask=log_mask)
+    
+    res_raw = decompose(y, y_hat, J_raw, sigma=sigma)
+    res_log = decompose(y, y_hat, J_log, sigma=sigma)
+    
+    np.testing.assert_allclose(res_raw.normal_stress, res_log.normal_stress)
+    np.testing.assert_allclose(res_raw.normal_fraction_pct, res_log.normal_fraction_pct)