CONSTANT

DEGENERACY_ABS_FLOOR

omnibias.curvature.information.DEGENERACY_ABS_FLOORSource ↗

DEGENERACY_ABS_FLOOR = 0.01

Absolute Fisher floor used only by the *damped* natural step when the collapse report says the coordinate is near-degenerate. Distinct from the tighter pinv cutoff (linear algebra) and from the founding delta.

Regression example · two bias near collapse is degenerate

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_near_collapse_is_degenerate() -> None:
    report = collapse_degeneracy(two_bias_family(), np.array([1e-4]))
    assert report.exponent == pytest.approx(2.0, abs=0.05)
    assert report.eigenvalue < 1e-9
    assert report.recommendation == "reparameterize by order"
    assert report.damping == DEGENERACY_ABS_FLOOR

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_two_bias_near_collapse_is_degenerate -q

Read the implementation

DEGENERACY_ABS_FLOOR = 1e-2

CLASS

DegeneracyReport

omnibias.curvature.information.DegeneracyReportSource ↗

class DegeneracyReport

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

Collapse-direction diagnosis for a pack-parameter metric.

damping is the extra Tikhonov used by damped_natural_step. The pseudo-inverse (fisher_pinv) uses the tighter PINV_RCOND_RULE.

Parameters

Name	Type & default	Contract
`eigenvalue`dataclass field	`float`Required	See the operation contract and implementation below.
`exponent`dataclass field	`float`Required	See the operation contract and implementation below.
`condition_number`dataclass field	`float`Required	See the operation contract and implementation below.
`recommendation`dataclass field	`str`Required	See the operation contract and implementation below.
`damping`dataclass field	`float`Required	See the operation contract and implementation below.
`path`dataclass field	`str`Default: PATH_CLOSED	See the operation contract and implementation below.
`direction`dataclass field	`str`Default: 'spread'	See the operation contract and implementation below.

Fields & methods

eigenvaluefield

eigenvalue: float

Declared float field on DegeneracyReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

exponentfield

exponent: float

Declared float field on DegeneracyReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

condition_numberfield

condition_number: float

Declared float field on DegeneracyReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

recommendationfield

recommendation: str

Declared str field on DegeneracyReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

dampingfield

damping: float

Declared float field on DegeneracyReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

pathfield

path: str = PATH_CLOSED

Declared str field on DegeneracyReport. Default expression: PATH_CLOSED.

View source ↗

directionfield

direction: str = 'spread'

Declared str field on DegeneracyReport. Default expression: 'spread'.

View source ↗

Read the implementation

class DegeneracyReport:
    """Collapse-direction diagnosis for a pack-parameter metric.

    ``damping`` is the extra Tikhonov used by
    :func:`damped_natural_step`. The pseudo-inverse
    (:func:`fisher_pinv`) uses the tighter :data:`PINV_RCOND_RULE`.
    """

    eigenvalue: float
    exponent: float
    condition_number: float
    recommendation: str
    damping: float
    path: str = PATH_CLOSED
    direction: str = "spread"

CLASS

FisherEvaluation

omnibias.curvature.information.FisherEvaluationSource ↗

class FisherEvaluation

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

Metric matrix plus the path that produced the expectation.

Parameters

Name	Type & default	Contract
`metric`dataclass field	`FloatArray`Required	See the operation contract and implementation below.
`path`dataclass field	`str`Required	See the operation contract and implementation below.

Fields & methods

metricfield

metric: FloatArray

Declared FloatArray field on FisherEvaluation. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

pathfield

path: str

Declared str field on FisherEvaluation. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

Read the implementation

class FisherEvaluation:
    """Metric matrix plus the path that produced the expectation."""

    metric: FloatArray
    path: str

CLASS

NotADensityError

omnibias.curvature.information.NotADensityErrorSource ↗

class NotADensityError(ValueError)

Fisher was asked for a pack that is not a probability density.

Regression example · k ge 3 finite difference is not a density

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_k_ge_3_finite_difference_is_not_a_density() -> None:
    family = finite_difference_family(n_biases=3)
    with pytest.raises(NotADensityError, match="inapplicable"):
        fisher_metric(family, np.array([0.2]))

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_k_ge_3_finite_difference_is_not_a_density -q

Regression example · non sigmoid activation is refused

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_non_sigmoid_activation_is_refused() -> None:
    with pytest.raises(NotADensityError, match="logistic"):
        from omnibias.curvature.information import PackFamily

        PackFamily(kind="logistic_location", activation="tanh")

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_non_sigmoid_activation_is_refused -q

Read the implementation

class NotADensityError(ValueError):
    """Fisher was asked for a pack that is not a probability density."""

CONSTANT

PATH_CLOSED

omnibias.curvature.information.PATH_CLOSEDSource ↗

PATH_CLOSED = 'closed_form_integrand'

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

PATH_CLOSED = "closed_form_integrand"

CONSTANT

PATH_MC

omnibias.curvature.information.PATH_MCSource ↗

PATH_MC = 'monte_carlo'

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

PATH_MC = "monte_carlo"

CONSTANT

PINV_RCOND_RULE

omnibias.curvature.information.PINV_RCOND_RULESource ↗

PINV_RCOND_RULE = 'max(n_params) * eps(dtype), matching numpy.linalg.pinv'

numpy.linalg.pinv rule: max(n, m) * eps(dtype). Documented threshold.

Regression example · pinv uses numpy rcond rule

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_pinv_uses_numpy_rcond_rule() -> None:
    g = np.diag([1.0, 1e-20])
    rc = pinv_rcond(g)
    assert rc == pytest.approx(2.0 * np.finfo(g.dtype).eps)
    pin = fisher_pinv(g)
    assert pin[0, 0] == pytest.approx(1.0)
    assert pin[1, 1] == pytest.approx(0.0)
    assert "numpy.linalg.pinv" in PINV_RCOND_RULE

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_pinv_uses_numpy_rcond_rule -q

Read the implementation

PINV_RCOND_RULE = "max(n_params) * eps(dtype), matching numpy.linalg.pinv"

CLASS

PackFamily

omnibias.curvature.information.PackFamilySource ↗

class PackFamily

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

A parametric family of 1-D logistic pack densities.

Parameters

kind two_bias_logistic (theta = (delta,)), two_bias_located (theta = (mu, delta)), logistic_location (theta = (mu,), unit logistic), logistic_mixture (two components; see unpack), or finite_difference (refused for n_components >= 3). n_components Mixture size or finite-difference bias count. activation Must be sigmoid: only the logistic mixture is a density with a closed-form score in this leftover close-out.

Parameters

Name	Type & default	Contract
`kind`dataclass field	`str`Required	`two_bias_logistic` (`theta = (delta,)`), `two_bias_located` (`theta = (mu, delta)`), `logistic_location` (`theta = (mu,)`, unit logistic), `logistic_mixture` (two components; see `unpack`), or `finite_difference` (refused for `n_components >= 3`).
`n_components`dataclass field	`int`Default: 1	Mixture size or finite-difference bias count.
`activation`dataclass field	`str`Default: 'sigmoid'	Must be `sigmoid`: only the logistic mixture is a density with a closed-form score in this leftover close-out.

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Regression example · non sigmoid activation is refused

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_non_sigmoid_activation_is_refused() -> None:
    with pytest.raises(NotADensityError, match="logistic"):
        from omnibias.curvature.information import PackFamily

        PackFamily(kind="logistic_location", activation="tanh")

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_non_sigmoid_activation_is_refused -q

Fields & methods

kindfield

kind: str

two_bias_logistic (theta = (delta,)), two_bias_located (theta = (mu, delta)), logistic_location (theta = (mu,), unit logistic), logistic_mixture (two components; see unpack), or finite_difference (refused for n_components >= 3).

View source ↗

n_componentsfield

n_components: int = 1

Mixture size or finite-difference bias count.

View source ↗

activationfield

activation: str = 'sigmoid'

Must be sigmoid: only the logistic mixture is a density with a closed-form score in this leftover close-out.

View source ↗

__post_init__method

__post_init__(self) -> None

See the class contract above and the exact method implementation below.

Returns: None

Validation & failure cases

When self.kind not in _KINDS, raises ValueError(f'unknown PackFamily.kind {self.kind!r}').
When self.activation != 'sigmoid', raises NotADensityError(f'pack Fisher is implemented for logistic/sigmoid densities only, got {self.activation!r}').
When self.n_components < 1, raises ValueError(f'n_components must be >= 1, got {self.n_components}').
When self.kind == 'logistic_mixture' and self.n_components != 2, raises ValueError(f'logistic_mixture is the two-component D8 suite; got n_components={self.n_components}').

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Method implementation

    def __post_init__(self) -> None:
        if self.kind not in _KINDS:
            raise ValueError(f"unknown PackFamily.kind {self.kind!r}")
        if self.activation != "sigmoid":
            raise NotADensityError(
                "pack Fisher is implemented for logistic/sigmoid densities "
                f"only, got {self.activation!r}"
            )
        if self.n_components < 1:
            raise ValueError(f"n_components must be >= 1, got {self.n_components}")
        if self.kind == "logistic_mixture" and self.n_components != 2:
            raise ValueError(
                "logistic_mixture is the two-component D8 suite; "
                f"got n_components={self.n_components}"
            )

View source ↗

n_paramsproperty

n_params(self) -> int

See the class contract above and the exact method implementation below.

Returns: int

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Method implementation

    def n_params(self) -> int:
        if self.kind in {"two_bias_logistic", "logistic_location", "finite_difference"}:
            return 1
        if self.kind == "two_bias_located":
            return 2
        if self.kind == "logistic_mixture":
            return 5
        raise ValueError(f"n_params undefined for kind {self.kind!r}")

View source ↗

unpackmethod

unpack(self, theta: Any) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Return (locations, scales, weights) for mixture-like kinds.

Parameters

Name	Type & default	Contract
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

Returns: tuple[np.ndarray, np.ndarray, np.ndarray]

Executed regression · metric is symmetric pspd

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_metric_is_symmetric_pspd() -> None:
    family = logistic_mixture_family()
    for theta in randomized_mixture_suite(n=4, seed=1):
        g = fisher_metric(family, theta, nodes=64)
        assert np.max(np.abs(g - g.T)) <= 1e-14
        eig = np.linalg.eigvalsh(0.5 * (g + g.T))
        assert float(np.min(eig)) >= 1e-3

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_metric_is_symmetric_pspd" -q

Method implementation

    def unpack(
        self, theta: Any
    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
        """Return ``(locations, scales, weights)`` for mixture-like kinds."""
        t = _theta(self, theta)
        if self.kind == "logistic_location":
            return np.array([t[0]]), np.array([1.0]), np.array([1.0])
        if self.kind == "logistic_mixture":
            mu1, phi1, mu2, phi2, psi = (float(v) for v in t)
            c1 = 1.0 / (1.0 + math.exp(-psi))
            return (
                np.array([mu1, mu2]),
                np.array([math.exp(phi1), math.exp(phi2)]),
                np.array([c1, 1.0 - c1]),
            )
        if self.kind == "two_bias_logistic":
            return np.array([0.0]), np.array([1.0]), np.array([1.0])
        if self.kind == "two_bias_located":
            return np.array([t[0]]), np.array([1.0]), np.array([1.0])
        raise NotADensityError(_finite_difference_msg(self))

View source ↗

Read the implementation

class PackFamily:
    """A parametric family of 1-D logistic pack densities.

    Parameters
    ----------
    kind
        ``two_bias_logistic`` (``theta = (delta,)``),
        ``two_bias_located`` (``theta = (mu, delta)``),
        ``logistic_location`` (``theta = (mu,)``, unit logistic),
        ``logistic_mixture`` (two components; see :meth:`unpack`),
        or ``finite_difference`` (refused for ``n_components >= 3``).
    n_components
        Mixture size or finite-difference bias count.
    activation
        Must be ``sigmoid``: only the logistic mixture is a density
        with a closed-form score in this leftover close-out.
    """

    kind: str
    n_components: int = 1
    activation: str = "sigmoid"

    def __post_init__(self) -> None:
        if self.kind not in _KINDS:
            raise ValueError(f"unknown PackFamily.kind {self.kind!r}")
        if self.activation != "sigmoid":
            raise NotADensityError(
                "pack Fisher is implemented for logistic/sigmoid densities "
                f"only, got {self.activation!r}"
            )
        if self.n_components < 1:
            raise ValueError(f"n_components must be >= 1, got {self.n_components}")
        if self.kind == "logistic_mixture" and self.n_components != 2:
            raise ValueError(
                "logistic_mixture is the two-component D8 suite; "
                f"got n_components={self.n_components}"
            )

    @property
    def n_params(self) -> int:
        if self.kind in {"two_bias_logistic", "logistic_location", "finite_difference"}:
            return 1
        if self.kind == "two_bias_located":
            return 2
        if self.kind == "logistic_mixture":
            return 5
        raise ValueError(f"n_params undefined for kind {self.kind!r}")

    def unpack(
        self, theta: Any
    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
        """Return ``(locations, scales, weights)`` for mixture-like kinds."""
        t = _theta(self, theta)
        if self.kind == "logistic_location":
            return np.array([t[0]]), np.array([1.0]), np.array([1.0])
        if self.kind == "logistic_mixture":
            mu1, phi1, mu2, phi2, psi = (float(v) for v in t)
            c1 = 1.0 / (1.0 + math.exp(-psi))
            return (
                np.array([mu1, mu2]),
                np.array([math.exp(phi1), math.exp(phi2)]),
                np.array([c1, 1.0 - c1]),
            )
        if self.kind == "two_bias_logistic":
            return np.array([0.0]), np.array([1.0]), np.array([1.0])
        if self.kind == "two_bias_located":
            return np.array([t[0]]), np.array([1.0]), np.array([1.0])
        raise NotADensityError(_finite_difference_msg(self))

FUNCTION

collapse_degeneracy

omnibias.curvature.information.collapse_degeneracySource ↗

collapse_degeneracy(family: PackFamily, theta: Any, *, direction: str='spread') -> DegeneracyReport

Eigenvalue, local exponent, and damping along the collapse chart.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`direction`keyword-only	`str`Default: 'spread'	See the operation contract and implementation below.

ReturnsDegeneracyReport

Explicit validation & failure cases

When direction != 'spread', raises ValueError(f"only direction='spread' is implemented, got {direction!r}").

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · two bias near collapse is degenerate

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_near_collapse_is_degenerate() -> None:
    report = collapse_degeneracy(two_bias_family(), np.array([1e-4]))
    assert report.exponent == pytest.approx(2.0, abs=0.05)
    assert report.eigenvalue < 1e-9
    assert report.recommendation == "reparameterize by order"
    assert report.damping == DEGENERACY_ABS_FLOOR

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_near_collapse_is_degenerate" -q

Read the implementation

def collapse_degeneracy(
    family: PackFamily,
    theta: Any,
    *,
    direction: str = "spread",
) -> DegeneracyReport:
    """Eigenvalue, local exponent, and damping along the collapse chart."""
    if direction != "spread":
        raise ValueError(f"only direction='spread' is implemented, got {direction!r}")
    _require_density(family, theta)
    g = fisher_metric(family, theta)
    eig = np.linalg.eigvalsh(_sym(g))
    lam_min = float(np.min(eig))
    lam_max = float(np.max(np.abs(eig)))
    cond = (
        float("inf")
        if lam_min <= 0.0
        else float(lam_max / max(lam_min, 1e-300))
    )
    exponent = _spread_exponent(family, theta)
    near = bool(lam_min < DEGENERACY_ABS_FLOOR or exponent > 1.5)
    if near:
        recommendation = "reparameterize by order"
        damping = max(pinv_rcond(g) * max(lam_max, 1e-300), DEGENERACY_ABS_FLOOR)
    else:
        recommendation = "spread coordinate is identifiable"
        damping = pinv_rcond(g) * max(lam_max, 1e-300)
    return DegeneracyReport(
        eigenvalue=lam_min,
        exponent=exponent,
        condition_number=cond,
        recommendation=recommendation,
        damping=float(damping),
        path=PATH_CLOSED,
        direction=direction,
    )

FUNCTION

damped_natural_step

omnibias.curvature.information.damped_natural_stepSource ↗

damped_natural_step(family: PackFamily, theta: Any, data: Any, *, lr: float=1.0, report: DegeneracyReport | None=None) -> FloatArray

Natural step with eigenvalues floored by DegeneracyReport.

Only the collapse direction is damped. Well-conditioned coordinates keep their Fisher scaling. This is the opposite of adding damping * I to every direction.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`data`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`lr`keyword-only	`float`Default: 1.0	See the operation contract and implementation below.
`report`keyword-only	`DegeneracyReport \| None`Default: None	See the operation contract and implementation below.

ReturnsFloatArray

Read the implementation

def damped_natural_step(
    family: PackFamily,
    theta: Any,
    data: Any,
    *,
    lr: float = 1.0,
    report: DegeneracyReport | None = None,
) -> FloatArray:
    """Natural step with eigenvalues floored by :class:`DegeneracyReport`.

    Only the collapse direction is damped. Well-conditioned coordinates
    keep their Fisher scaling. This is the opposite of adding
    ``damping * I`` to every direction.
    """
    t = _theta(family, theta)
    g = _sym(fisher_metric(family, theta))
    grad = nll_gradient(family, theta, data)
    used = report if report is not None else collapse_degeneracy(family, theta)
    eig, vecs = np.linalg.eigh(g)
    floored = np.maximum(eig, float(used.damping))
    step = vecs @ ((vecs.T @ grad) / floored)
    return _project_theta(family, t - float(lr) * step)

FUNCTION

distinguishability_samples

omnibias.curvature.information.distinguishability_samplesSource ↗

distinguishability_samples(family: PackFamily, theta_a: Any, theta_b: Any, *, power: float=0.8, alpha: float=0.05, steps: int=64) -> int

Wald sample count from the Fisher distance.

N = (z_{1-alpha/2} + z_{power})^2 / d_F^2. Default alpha=0.05, power=0.8 gives the usual 7.849 / d_F^2.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta_a`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`theta_b`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`power`keyword-only	`float`Default: 0.8	See the operation contract and implementation below.
`alpha`keyword-only	`float`Default: 0.05	See the operation contract and implementation below.
`steps`keyword-only	`int`Default: 64	See the operation contract and implementation below.

Returnsint

Explicit validation & failure cases

When not 0.0 < float(power) < 1.0, raises ValueError(f'power must be in (0, 1), got {power}').
When not 0.0 < float(alpha) < 1.0, raises ValueError(f'alpha must be in (0, 1), got {alpha}').
When dist <= 0.0, raises ValueError('Fisher distance is zero; the settings are identical').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Read the implementation

def distinguishability_samples(
    family: PackFamily,
    theta_a: Any,
    theta_b: Any,
    *,
    power: float = 0.8,
    alpha: float = 0.05,
    steps: int = 64,
) -> int:
    """Wald sample count from the Fisher distance.

    ``N = (z_{1-alpha/2} + z_{power})^2 / d_F^2``. Default
    ``alpha=0.05``, ``power=0.8`` gives the usual ``7.849 / d_F^2``.
    """
    if not 0.0 < float(power) < 1.0:
        raise ValueError(f"power must be in (0, 1), got {power}")
    if not 0.0 < float(alpha) < 1.0:
        raise ValueError(f"alpha must be in (0, 1), got {alpha}")
    dist = fisher_distance(family, theta_a, theta_b, steps=steps)
    if dist <= 0.0:
        raise ValueError("Fisher distance is zero; the settings are identical")
    z_a = _normal_ppf(1.0 - float(alpha) / 2.0)
    z_p = _normal_ppf(float(power))
    return max(1, int(math.ceil((z_a + z_p) ** 2 / (dist * dist))))

FUNCTION

empirical_distinguishability_n

omnibias.curvature.information.empirical_distinguishability_nSource ↗

empirical_distinguishability_n(family: PackFamily, theta_a: Any, theta_b: Any, *, power: float=0.8, alpha: float=0.05, n_trials: int=80, seed: int=0, n_min: int=8, n_max: int=512) -> int

Smallest n whose Neyman–Pearson test reaches power.

Simple H0: theta_a vs H1: theta_b. Threshold is the 1 - alpha quantile of the log-likelihood ratio under H0.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta_a`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`theta_b`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`power`keyword-only	`float`Default: 0.8	See the operation contract and implementation below.
`alpha`keyword-only	`float`Default: 0.05	See the operation contract and implementation below.
`n_trials`keyword-only	`int`Default: 80	See the operation contract and implementation below.
`seed`keyword-only	`int`Default: 0	See the operation contract and implementation below.
`n_min`keyword-only	`int`Default: 8	See the operation contract and implementation below.
`n_max`keyword-only	`int`Default: 512	See the operation contract and implementation below.

Returnsint

Read the implementation

def empirical_distinguishability_n(
    family: PackFamily,
    theta_a: Any,
    theta_b: Any,
    *,
    power: float = 0.8,
    alpha: float = 0.05,
    n_trials: int = 80,
    seed: int = 0,
    n_min: int = 8,
    n_max: int = 512,
) -> int:
    """Smallest ``n`` whose Neyman–Pearson test reaches ``power``.

    Simple ``H0: theta_a`` vs ``H1: theta_b``. Threshold is the
    ``1 - alpha`` quantile of the log-likelihood ratio under ``H0``.
    """
    lo, hi = int(n_min), int(n_max)
    best = hi
    while lo <= hi:
        mid = (lo + hi) // 2
        pw = _likelihood_ratio_power(
            family,
            theta_a,
            theta_b,
            n=mid,
            n_trials=int(n_trials),
            seed=int(seed),
            alpha=float(alpha),
        )
        if pw >= float(power):
            best = mid
            hi = mid - 1
        else:
            lo = mid + 1
    return int(best)

FUNCTION

evaluate_fisher

omnibias.curvature.information.evaluate_fisherSource ↗

evaluate_fisher(family: PackFamily, theta: Any, *, closed_form: bool=True, nodes: int=96, n_mc: int=200000, seed: int=0) -> FisherEvaluation

Assemble G(theta). Closed-form integrand plus quadrature by default.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`closed_form`keyword-only	`bool`Default: True	See the operation contract and implementation below.
`nodes`keyword-only	`int`Default: 96	See the operation contract and implementation below.
`n_mc`keyword-only	`int`Default: 200000	See the operation contract and implementation below.
`seed`keyword-only	`int`Default: 0	See the operation contract and implementation below.

ReturnsFisherEvaluation

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Read the implementation

def evaluate_fisher(
    family: PackFamily,
    theta: Any,
    *,
    closed_form: bool = True,
    nodes: int = 96,
    n_mc: int = 200_000,
    seed: int = 0,
) -> FisherEvaluation:
    """Assemble ``G(theta)``. Closed-form integrand plus quadrature by default."""
    _require_density(family, theta)
    if closed_form:
        return FisherEvaluation(
            metric=_quadrature_metric(family, theta, nodes=nodes),
            path=PATH_CLOSED,
        )
    metric, _se = _monte_carlo_metric(family, theta, n=n_mc, seed=seed)
    return FisherEvaluation(metric=metric, path=PATH_MC)

FUNCTION

finite_difference_family

omnibias.curvature.information.finite_difference_familySource ↗

finite_difference_family(*, n_biases: int) -> PackFamily

Central finite-difference pack. Fisher applies only for n_biases == 2.

Parameters

Name	Type & default	Contract
`n_biases`keyword-only	`int`Required	See the operation contract and implementation below.

ReturnsPackFamily

Executed regression · k ge 3 finite difference is not a density

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_k_ge_3_finite_difference_is_not_a_density() -> None:
    family = finite_difference_family(n_biases=3)
    with pytest.raises(NotADensityError, match="inapplicable"):
        fisher_metric(family, np.array([0.2]))

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_k_ge_3_finite_difference_is_not_a_density" -q

Read the implementation

def finite_difference_family(*, n_biases: int) -> PackFamily:
    """Central finite-difference pack. Fisher applies only for ``n_biases == 2``."""
    return PackFamily(kind="finite_difference", n_components=int(n_biases))

FUNCTION

fisher_delta_delta

omnibias.curvature.information.fisher_delta_deltaSource ↗

fisher_delta_delta(delta: float, *, nodes: int=200) -> float

G_{delta,delta} for the two-bias logistic pack.

Parameters

Name	Type & default	Contract
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.
`nodes`keyword-only	`int`Default: 200	See the operation contract and implementation below.

Returnsfloat

Executed regression · two bias prefactor matches g2

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_prefactor_matches_g2() -> None:
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=200)
    expected = (1.0 / 720.0) * delta * delta
    assert abs(g - expected) / expected <= 1e-6

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_prefactor_matches_g2" -q

Read the implementation

def fisher_delta_delta(delta: float, *, nodes: int = 200) -> float:
    """``G_{delta,delta}`` for the two-bias logistic pack."""
    metric = fisher_metric(two_bias_family(), np.array([float(delta)]), nodes=nodes)
    return float(metric[0, 0])

FUNCTION

fisher_distance

omnibias.curvature.information.fisher_distanceSource ↗

fisher_distance(family: PackFamily, theta_a: Any, theta_b: Any, *, steps: int=64) -> float

Fisher length of the chart-straight path.

Equals the geodesic in one parameter. In several parameters it is the length of the linear interpolant (an upper bound on the geodesic). The returned matrix can be used directly by downstream geometry code.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta_a`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`theta_b`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`steps`keyword-only	`int`Default: 64	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

When steps < 1, raises ValueError(f'steps must be >= 1, got {steps}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Regression example · location distance is euclidean over sqrt i

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_location_distance_is_euclidean_over_sqrt_i() -> None:
    family = logistic_location_family()
    dist = fisher_distance(family, np.array([0.0]), np.array([math.sqrt(3.0)]))
    assert dist == pytest.approx(1.0, rel=1e-12)

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_location_distance_is_euclidean_over_sqrt_i -q

Read the implementation

def fisher_distance(
    family: PackFamily,
    theta_a: Any,
    theta_b: Any,
    *,
    steps: int = 64,
) -> float:
    """Fisher length of the chart-straight path.

    Equals the geodesic in one parameter. In several parameters it is
    the length of the linear interpolant (an upper bound on the
    geodesic). The returned matrix can be used directly by downstream geometry code.
    """
    if steps < 1:
        raise ValueError(f"steps must be >= 1, got {steps}")
    a = _theta(family, theta_a)
    b = _theta(family, theta_b)
    length = 0.0
    delta = (b - a) / float(steps)
    for i in range(steps):
        mid = a + (i + 0.5) * delta
        g = fisher_metric(family, mid)
        quad = float(delta @ g @ delta)
        length += math.sqrt(max(quad, 0.0))
    return length

FUNCTION

fisher_metric

omnibias.curvature.information.fisher_metricSource ↗

fisher_metric(family: PackFamily, theta: Any, *, closed_form: bool=True, nodes: int=96, n_mc: int=200000, seed: int=0) -> FloatArray

Closed form where the family's moments are; else Monte Carlo.

Records the path on the returned evaluation via evaluate_fisher. This leftover uses quadrature of a closed-form integrand (not a sampling-free moment formula).

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`closed_form`keyword-only	`bool`Default: True	See the operation contract and implementation below.
`nodes`keyword-only	`int`Default: 96	See the operation contract and implementation below.
`n_mc`keyword-only	`int`Default: 200000	See the operation contract and implementation below.
`seed`keyword-only	`int`Default: 0	See the operation contract and implementation below.

ReturnsFloatArray

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Regression example · logistic location fisher is one third

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_logistic_location_fisher_is_one_third() -> None:
    g = fisher_metric(logistic_location_family(), np.array([0.3]), nodes=96)
    assert float(g[0, 0]) == pytest.approx(1.0 / 3.0, rel=1e-12)

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_logistic_location_fisher_is_one_third -q

Read the implementation

def fisher_metric(
    family: PackFamily,
    theta: Any,
    *,
    closed_form: bool = True,
    nodes: int = 96,
    n_mc: int = 200_000,
    seed: int = 0,
) -> FloatArray:
    """Closed form where the family's moments are; else Monte Carlo.

    Records the path on the returned evaluation via
    :func:`evaluate_fisher`. This leftover uses quadrature of a
    closed-form integrand (not a sampling-free moment formula).
    """
    return evaluate_fisher(
        family,
        theta,
        closed_form=closed_form,
        nodes=nodes,
        n_mc=n_mc,
        seed=seed,
    ).metric

FUNCTION

fisher_metric_mc

omnibias.curvature.information.fisher_metric_mcSource ↗

fisher_metric_mc(family: PackFamily, theta: Any, *, n: int, seed: int) -> tuple[FloatArray, FloatArray]

Monte Carlo Fisher and per-entry standard errors.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`n`keyword-only	`int`Required	See the operation contract and implementation below.
`seed`keyword-only	`int`Required	See the operation contract and implementation below.

Returnstuple[FloatArray, FloatArray]

Executed regression · mixture mc agrees with quadrature

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_mixture_mc_agrees_with_quadrature() -> None:
    family = logistic_mixture_family()
    theta = randomized_mixture_suite(n=1, seed=2)[0]
    closed = fisher_metric(family, theta, nodes=64)
    mc, se = fisher_metric_mc(family, theta, n=40_000, seed=0)
    sig = np.abs(closed - mc) / np.maximum(se, 1e-18)
    assert float(np.max(sig)) <= 3.0

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_mixture_mc_agrees_with_quadrature" -q

Read the implementation

def fisher_metric_mc(
    family: PackFamily,
    theta: Any,
    *,
    n: int,
    seed: int,
) -> tuple[FloatArray, FloatArray]:
    """Monte Carlo Fisher and per-entry standard errors."""
    _require_density(family, theta)
    return _monte_carlo_metric(family, theta, n=int(n), seed=int(seed))

FUNCTION

fisher_pinv

omnibias.curvature.information.fisher_pinvSource ↗

fisher_pinv(metric: Any) -> FloatArray

Symmetric eigen-pseudoinverse at pinv_rcond.

Parameters

Name	Type & default	Contract
`metric`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

ReturnsFloatArray

Executed regression · pinv uses numpy rcond rule

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_pinv_uses_numpy_rcond_rule() -> None:
    g = np.diag([1.0, 1e-20])
    rc = pinv_rcond(g)
    assert rc == pytest.approx(2.0 * np.finfo(g.dtype).eps)
    pin = fisher_pinv(g)
    assert pin[0, 0] == pytest.approx(1.0)
    assert pin[1, 1] == pytest.approx(0.0)
    assert "numpy.linalg.pinv" in PINV_RCOND_RULE

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_pinv_uses_numpy_rcond_rule" -q

Read the implementation

def fisher_pinv(metric: Any) -> FloatArray:
    """Symmetric eigen-pseudoinverse at :func:`pinv_rcond`."""
    g = _sym(metric)
    eig, vecs = np.linalg.eigh(g)
    cutoff = pinv_rcond(g) * float(np.max(np.abs(eig)))
    inv = np.where(np.abs(eig) > cutoff, 1.0 / eig, 0.0)
    return np.asarray((vecs * inv) @ vecs.T, dtype=np.float64)

FUNCTION

honesty_payload

omnibias.curvature.information.honesty_payloadSource ↗

honesty_payload() -> dict[str, object]

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Returnsdict[str, object]

Executed regression · worked example and honesty

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_worked_example_and_honesty() -> None:
    ex = worked_example()
    assert abs(float(ex["g_over_delta2"]) - 1.0 / 720.0) / (1.0 / 720.0) < 1e-6
    assert ex["recommendation"] == "reparameterize by order"
    payload = honesty_payload()
    assert payload["bias_collapse"] is True
    assert payload["temperature_collapse"] is False
    assert payload["k_ge_3_fisher"] == "inapplicable_not_a_density"
    assert payload["theorem_prover_verified"] is False

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_worked_example_and_honesty" -q

Read the implementation

def honesty_payload() -> dict[str, object]:
    return {
        "bias_collapse": True,
        "temperature_collapse": False,
        "k_ge_3_fisher": "inapplicable_not_a_density",
        "scalar_glm_fisher_is_a_different_object": True,
        "theorem_prover_verified": False,
        "mathlib_verified": False,
        "pinv_rcond_rule": PINV_RCOND_RULE,
    }

FUNCTION

log_density

omnibias.curvature.information.log_densitySource ↗

log_density(family: PackFamily, theta: Any, data: Any) -> FloatArray

Per-observation log p_theta(x).

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`data`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

ReturnsFloatArray

Read the implementation

def log_density(family: PackFamily, theta: Any, data: Any) -> FloatArray:
    """Per-observation ``log p_theta(x)``."""
    _require_density(family, theta)
    xs = np.asarray(data, dtype=float).reshape(-1)
    p, _jac = _density_and_jac(family, theta, xs)
    return np.asarray(np.log(np.maximum(p, 1e-300)), dtype=np.float64)

FUNCTION

logistic_location_family

omnibias.curvature.information.logistic_location_familySource ↗

logistic_location_family() -> PackFamily

Unit logistic location family; Fisher is exactly 1/3.

ReturnsPackFamily

Executed regression · distinguishability wald count

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_distinguishability_wald_count" -q

Regression example · logistic location fisher is one third

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_logistic_location_fisher_is_one_third() -> None:
    g = fisher_metric(logistic_location_family(), np.array([0.3]), nodes=96)
    assert float(g[0, 0]) == pytest.approx(1.0 / 3.0, rel=1e-12)

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_logistic_location_fisher_is_one_third -q

Read the implementation

def logistic_location_family() -> PackFamily:
    """Unit logistic location family; Fisher is exactly ``1/3``."""
    return PackFamily(kind="logistic_location", n_components=1)

FUNCTION

logistic_mixture_family

omnibias.curvature.information.logistic_mixture_familySource ↗

logistic_mixture_family() -> PackFamily

Two-component logistic mixture (the G1 / D8 suite).

ReturnsPackFamily

Executed regression · metric is symmetric pspd

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_metric_is_symmetric_pspd() -> None:
    family = logistic_mixture_family()
    for theta in randomized_mixture_suite(n=4, seed=1):
        g = fisher_metric(family, theta, nodes=64)
        assert np.max(np.abs(g - g.T)) <= 1e-14
        eig = np.linalg.eigvalsh(0.5 * (g + g.T))
        assert float(np.min(eig)) >= 1e-3

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_metric_is_symmetric_pspd" -q

Regression example · mixture mc agrees with quadrature

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_mixture_mc_agrees_with_quadrature() -> None:
    family = logistic_mixture_family()
    theta = randomized_mixture_suite(n=1, seed=2)[0]
    closed = fisher_metric(family, theta, nodes=64)
    mc, se = fisher_metric_mc(family, theta, n=40_000, seed=0)
    sig = np.abs(closed - mc) / np.maximum(se, 1e-18)
    assert float(np.max(sig)) <= 3.0

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_mixture_mc_agrees_with_quadrature -q

Read the implementation

def logistic_mixture_family() -> PackFamily:
    """Two-component logistic mixture (the G1 / D8 suite)."""
    return PackFamily(kind="logistic_mixture", n_components=2)

FUNCTION

mean_nll

omnibias.curvature.information.mean_nllSource ↗

mean_nll(family: PackFamily, theta: Any, data: Any) -> float

Mean negative log-density of i.i.d. observations.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`data`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

Returnsfloat

Read the implementation

def mean_nll(family: PackFamily, theta: Any, data: Any) -> float:
    """Mean negative log-density of i.i.d. observations."""
    _require_density(family, theta)
    xs = np.asarray(data, dtype=float).reshape(-1)
    p, _jac = _density_and_jac(family, theta, xs)
    return float(-np.mean(np.log(np.maximum(p, 1e-300))))

FUNCTION

nll_gradient

omnibias.curvature.information.nll_gradientSource ↗

nll_gradient(family: PackFamily, theta: Any, data: Any) -> FloatArray

Mean -score of i.i.d. observations (NLL gradient).

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`data`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

ReturnsFloatArray

Read the implementation

def nll_gradient(family: PackFamily, theta: Any, data: Any) -> FloatArray:
    """Mean ``-score`` of i.i.d. observations (NLL gradient)."""
    _require_density(family, theta)
    xs = np.asarray(data, dtype=float).reshape(-1)
    _p, jac = _density_and_jac(family, theta, xs)
    score = jac / np.maximum(_p[:, None], 1e-300)
    return np.asarray(-np.mean(score, axis=0), dtype=np.float64)

FUNCTION

pinv_rcond

omnibias.curvature.information.pinv_rcondSource ↗

pinv_rcond(metric: Any) -> float

Documented pseudo-inverse cutoff: max(shape) * eps(dtype).

Parameters

Name	Type & default	Contract
`metric`positional-or-keyword	`Any`Required	See the operation contract and implementation below.

Returnsfloat

Executed regression · pinv uses numpy rcond rule

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_pinv_uses_numpy_rcond_rule() -> None:
    g = np.diag([1.0, 1e-20])
    rc = pinv_rcond(g)
    assert rc == pytest.approx(2.0 * np.finfo(g.dtype).eps)
    pin = fisher_pinv(g)
    assert pin[0, 0] == pytest.approx(1.0)
    assert pin[1, 1] == pytest.approx(0.0)
    assert "numpy.linalg.pinv" in PINV_RCOND_RULE

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_pinv_uses_numpy_rcond_rule" -q

Read the implementation

def pinv_rcond(metric: Any) -> float:
    """Documented pseudo-inverse cutoff: ``max(shape) * eps(dtype)``."""
    arr = np.asarray(metric)
    return float(max(arr.shape)) * float(np.finfo(arr.dtype).eps)

FUNCTION

randomized_mixture_suite

omnibias.curvature.information.randomized_mixture_suiteSource ↗

randomized_mixture_suite(*, n: int=8, seed: int=0, min_eig: float=0.001) -> list[FloatArray]

Well-separated two-component mixtures for G1 / G3.

Draws are rejected until the closed-form metric is positive definite away from collapse (lambda_min >= min_eig).

Parameters

Name	Type & default	Contract
`n`keyword-only	`int`Default: 8	See the operation contract and implementation below.
`seed`keyword-only	`int`Default: 0	See the operation contract and implementation below.
`min_eig`keyword-only	`float`Default: 0.001	See the operation contract and implementation below.

Returnslist[FloatArray]

Explicit validation & failure cases

When attempts > 200 * int(n), raises RuntimeError('could not draw a well-separated mixture suite').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · metric is symmetric pspd

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_metric_is_symmetric_pspd() -> None:
    family = logistic_mixture_family()
    for theta in randomized_mixture_suite(n=4, seed=1):
        g = fisher_metric(family, theta, nodes=64)
        assert np.max(np.abs(g - g.T)) <= 1e-14
        eig = np.linalg.eigvalsh(0.5 * (g + g.T))
        assert float(np.min(eig)) >= 1e-3

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_metric_is_symmetric_pspd" -q

Regression example · mixture mc agrees with quadrature

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_mixture_mc_agrees_with_quadrature() -> None:
    family = logistic_mixture_family()
    theta = randomized_mixture_suite(n=1, seed=2)[0]
    closed = fisher_metric(family, theta, nodes=64)
    mc, se = fisher_metric_mc(family, theta, n=40_000, seed=0)
    sig = np.abs(closed - mc) / np.maximum(se, 1e-18)
    assert float(np.max(sig)) <= 3.0

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_mixture_mc_agrees_with_quadrature -q

Read the implementation

def randomized_mixture_suite(
    *,
    n: int = 8,
    seed: int = 0,
    min_eig: float = 1e-3,
) -> list[FloatArray]:
    """Well-separated two-component mixtures for G1 / G3.

    Draws are rejected until the closed-form metric is positive definite
    away from collapse (``lambda_min >= min_eig``).
    """
    rng = np.random.default_rng(int(seed))
    family = logistic_mixture_family()
    out: list[FloatArray] = []
    attempts = 0
    while len(out) < int(n):
        attempts += 1
        if attempts > 200 * int(n):
            raise RuntimeError("could not draw a well-separated mixture suite")
        mu1 = float(rng.uniform(-2.2, -0.8))
        mu2 = float(rng.uniform(0.8, 2.2))
        phi1 = float(rng.uniform(-0.15, 0.35))
        phi2 = float(rng.uniform(-0.15, 0.35))
        psi = float(rng.uniform(-0.5, 0.5))
        theta = np.array([mu1, phi1, mu2, phi2, psi], dtype=np.float64)
        eig = np.linalg.eigvalsh(fisher_metric(family, theta, nodes=64))
        if float(np.min(eig)) >= float(min_eig):
            out.append(theta)
    return out

FUNCTION

sample_family

omnibias.curvature.information.sample_familySource ↗

sample_family(family: PackFamily, theta: Any, n: int, *, seed: int) -> FloatArray

Exact inverse-CDF samples from a logistic pack mixture / two-bias pack.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`n`positional-or-keyword	`int`Required	See the operation contract and implementation below.
`seed`keyword-only	`int`Required	See the operation contract and implementation below.

ReturnsFloatArray

Executed regression · mixture mc agrees with quadrature

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_mixture_mc_agrees_with_quadrature() -> None:
    family = logistic_mixture_family()
    theta = randomized_mixture_suite(n=1, seed=2)[0]
    closed = fisher_metric(family, theta, nodes=64)
    mc, se = fisher_metric_mc(family, theta, n=40_000, seed=0)
    sig = np.abs(closed - mc) / np.maximum(se, 1e-18)
    assert float(np.max(sig)) <= 3.0

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_mixture_mc_agrees_with_quadrature" -q

Read the implementation

def sample_family(
    family: PackFamily,
    theta: Any,
    n: int,
    *,
    seed: int,
) -> FloatArray:
    """Exact inverse-CDF samples from a logistic pack mixture / two-bias pack."""
    _require_density(family, theta)
    rng = np.random.default_rng(int(seed))
    if family.kind in {"two_bias_logistic", "two_bias_located"}:
        mu, delta = _two_bias_mu_delta(family, theta)
        u1 = np.clip(rng.random(int(n)), 1e-16, 1.0 - 1e-16)
        u2 = rng.random(int(n))
        return np.asarray(
            mu + np.log(u1 / (1.0 - u1)) + float(delta) * (u2 - 0.5),
            dtype=np.float64,
        )
    locations, scales, weights = family.unpack(theta)
    choice = rng.choice(len(weights), size=int(n), p=weights)
    u = np.clip(rng.random(int(n)), 1e-16, 1.0 - 1e-16)
    return np.asarray(
        locations[choice] + np.log(u / (1.0 - u)) / scales[choice],
        dtype=np.float64,
    )

FUNCTION

two_bias_A

omnibias.curvature.information.two_bias_ASource ↗

two_bias_A(delta: float) -> float

A = (delta/2) cosh(delta/2) - sinh(delta/2), series-stable.

Parameters

Name	Type & default	Contract
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.

Returnsfloat

Executed regression · two bias prefactor matches g2

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_prefactor_matches_g2() -> None:
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=200)
    expected = (1.0 / 720.0) * delta * delta
    assert abs(g - expected) / expected <= 1e-6

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_prefactor_matches_g2" -q

Read the implementation

def two_bias_A(delta: float) -> float:
    """``A = (delta/2) cosh(delta/2) - sinh(delta/2)``, series-stable."""
    h = 0.5 * float(delta)
    if h < 0.5:
        tot = 0.0
        for k in range(1, 25):
            tot += h ** (2 * k + 1) * (
                1.0 / math.factorial(2 * k) - 1.0 / math.factorial(2 * k + 1)
            )
        return tot
    return h * math.cosh(h) - math.sinh(h)

FUNCTION

two_bias_ddelta_u

omnibias.curvature.information.two_bias_ddelta_uSource ↗

two_bias_ddelta_u(u: Any, delta: float) -> Any

Cancellation-free d p_delta / d delta in u = exp(-x).

Parameters

Name	Type & default	Contract
`u`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.

ReturnsAny

Explicit validation & failure cases

When d <= 0.0, raises ValueError(f'delta must be positive, got {delta}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · two bias prefactor matches g2

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_prefactor_matches_g2() -> None:
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=200)
    expected = (1.0 / 720.0) * delta * delta
    assert abs(g - expected) / expected <= 1e-6

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_prefactor_matches_g2" -q

Read the implementation

def two_bias_ddelta_u(u: Any, delta: float) -> Any:
    """Cancellation-free ``d p_delta / d delta`` in ``u = exp(-x)``."""
    d = float(delta)
    if d <= 0.0:
        raise ValueError(f"delta must be positive, got {delta}")
    uu = np.asarray(u, dtype=float)
    s = math.sinh(0.5 * d)
    c = math.cosh(0.5 * d)
    denom = 1.0 + 2.0 * uu * c + uu * uu
    a = two_bias_A(d)
    return 2.0 * uu * (denom * a - d * uu * s * s) / (d * d * denom * denom)

FUNCTION

two_bias_density_naive

omnibias.curvature.information.two_bias_density_naiveSource ↗

two_bias_density_naive(x: Any, delta: float) -> Any

Definition form (sigma(x+d/2) - sigma(x-d/2)) / d.

Parameters

Name	Type & default	Contract
`x`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.

ReturnsAny

Executed regression · stable two bias matches definition

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_stable_two_bias_matches_definition() -> None:
    xs = np.linspace(-3.0, 3.0, 81)
    u = np.exp(-xs)
    assert np.max(np.abs(two_bias_density_u(u, 0.4) - two_bias_density_naive(xs, 0.4))) < 1e-12

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_stable_two_bias_matches_definition" -q

Read the implementation

def two_bias_density_naive(x: Any, delta: float) -> Any:
    """Definition form ``(sigma(x+d/2) - sigma(x-d/2)) / d``."""
    d = float(delta)
    xx = np.asarray(x, dtype=float)
    sp = 1.0 / (1.0 + np.exp(-(xx + 0.5 * d)))
    sm = 1.0 / (1.0 + np.exp(-(xx - 0.5 * d)))
    return (sp - sm) / d

FUNCTION

two_bias_density_u

omnibias.curvature.information.two_bias_density_uSource ↗

two_bias_density_u(u: Any, delta: float) -> Any

Cancellation-free p_delta in u = exp(-x).

Parameters

Name	Type & default	Contract
`u`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.

ReturnsAny

Explicit validation & failure cases

When d <= 0.0, raises ValueError(f'delta must be positive, got {delta}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · two bias prefactor matches g2

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_prefactor_matches_g2() -> None:
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=200)
    expected = (1.0 / 720.0) * delta * delta
    assert abs(g - expected) / expected <= 1e-6

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_prefactor_matches_g2" -q

Regression example · stable two bias matches definition

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_stable_two_bias_matches_definition() -> None:
    xs = np.linspace(-3.0, 3.0, 81)
    u = np.exp(-xs)
    assert np.max(np.abs(two_bias_density_u(u, 0.4) - two_bias_density_naive(xs, 0.4))) < 1e-12

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_stable_two_bias_matches_definition -q

Read the implementation

def two_bias_density_u(u: Any, delta: float) -> Any:
    """Cancellation-free ``p_delta`` in ``u = exp(-x)``."""
    d = float(delta)
    if d <= 0.0:
        raise ValueError(f"delta must be positive, got {delta}")
    uu = np.asarray(u, dtype=float)
    s = math.sinh(0.5 * d)
    c = math.cosh(0.5 * d)
    denom = 1.0 + 2.0 * uu * c + uu * uu
    return 2.0 * uu * s / (d * denom)

FUNCTION

two_bias_dx_u

omnibias.curvature.information.two_bias_dx_uSource ↗

two_bias_dx_u(u: Any, delta: float) -> Any

Cancellation-free d p_delta / d x in u = exp(-x).

Parameters

Name	Type & default	Contract
`u`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`delta`positional-or-keyword	`float`Required	See the operation contract and implementation below.

ReturnsAny

Explicit validation & failure cases

When d <= 0.0, raises ValueError(f'delta must be positive, got {delta}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · located pack translation

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_located_pack_translation() -> None:
    family = two_bias_located_family()
    g0 = fisher_metric(family, np.array([0.0, 0.8]), nodes=96)
    g1 = fisher_metric(family, np.array([1.3, 0.8]), nodes=96)
    assert g0 == pytest.approx(g1, rel=1e-9, abs=1e-12)

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_located_pack_translation" -q

Read the implementation

def two_bias_dx_u(u: Any, delta: float) -> Any:
    """Cancellation-free ``d p_delta / d x`` in ``u = exp(-x)``."""
    d = float(delta)
    if d <= 0.0:
        raise ValueError(f"delta must be positive, got {delta}")
    uu = np.asarray(u, dtype=float)
    s = math.sinh(0.5 * d)
    c = math.cosh(0.5 * d)
    denom = 1.0 + 2.0 * uu * c + uu * uu
    return -2.0 * s * uu * (1.0 - uu * uu) / (d * denom * denom)

FUNCTION

two_bias_family

omnibias.curvature.information.two_bias_familySource ↗

two_bias_family() -> PackFamily

One-parameter two-bias logistic pack p_delta.

ReturnsPackFamily

Executed regression · two bias prefactor matches g2

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_prefactor_matches_g2() -> None:
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=200)
    expected = (1.0 / 720.0) * delta * delta
    assert abs(g - expected) / expected <= 1e-6

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_two_bias_prefactor_matches_g2" -q

Regression example · two bias near collapse is degenerate

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_two_bias_near_collapse_is_degenerate() -> None:
    report = collapse_degeneracy(two_bias_family(), np.array([1e-4]))
    assert report.exponent == pytest.approx(2.0, abs=0.05)
    assert report.eigenvalue < 1e-9
    assert report.recommendation == "reparameterize by order"
    assert report.damping == DEGENERACY_ABS_FLOOR

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_two_bias_near_collapse_is_degenerate -q

Read the implementation

def two_bias_family() -> PackFamily:
    """One-parameter two-bias logistic pack ``p_delta``."""
    return PackFamily(kind="two_bias_logistic", n_components=2)

FUNCTION

two_bias_located_family

omnibias.curvature.information.two_bias_located_familySource ↗

two_bias_located_family() -> PackFamily

Location-plus-spread two-bias pack p(x; mu, delta).

ReturnsPackFamily

Executed regression · located pack translation

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_located_pack_translation() -> None:
    family = two_bias_located_family()
    g0 = fisher_metric(family, np.array([0.0, 0.8]), nodes=96)
    g1 = fisher_metric(family, np.array([1.3, 0.8]), nodes=96)
    assert g0 == pytest.approx(g1, rel=1e-9, abs=1e-12)

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_located_pack_translation" -q

Regression example · distinguishability wald count

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_distinguishability_wald_count() -> None:
    family = logistic_location_family()
    n = distinguishability_samples(family, np.array([0.0]), np.array([0.6]))
    assert n == 66

python -m pytest packages/omnibias-curvature/tests/test_information.py -k test_distinguishability_wald_count -q

Read the implementation

def two_bias_located_family() -> PackFamily:
    """Location-plus-spread two-bias pack ``p(x; mu, delta)``."""
    return PackFamily(kind="two_bias_located", n_components=2)

FUNCTION

undamped_natural_step

omnibias.curvature.information.undamped_natural_stepSource ↗

undamped_natural_step(family: PackFamily, theta: Any, data: Any, *, lr: float=1.0) -> FloatArray

theta - lr * G^{-1} grad with the tight pinv cutoff only.

Parameters

Name	Type & default	Contract
`family`positional-or-keyword	`PackFamily`Required	See the operation contract and implementation below.
`theta`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`data`positional-or-keyword	`Any`Required	See the operation contract and implementation below.
`lr`keyword-only	`float`Default: 1.0	See the operation contract and implementation below.

ReturnsFloatArray

Read the implementation

def undamped_natural_step(
    family: PackFamily,
    theta: Any,
    data: Any,
    *,
    lr: float = 1.0,
) -> FloatArray:
    """``theta - lr * G^{-1} grad`` with the tight pinv cutoff only."""
    g = fisher_metric(family, theta)
    grad = nll_gradient(family, theta, data)
    step = fisher_pinv(g) @ grad
    return _project_theta(family, _theta(family, theta) - float(lr) * step)

FUNCTION

worked_example

omnibias.curvature.information.worked_exampleSource ↗

worked_example() -> dict[str, object]

Tiny deterministic example for docs snippets.

Returnsdict[str, object]

Executed regression · worked example and honesty

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_worked_example_and_honesty() -> None:
    ex = worked_example()
    assert abs(float(ex["g_over_delta2"]) - 1.0 / 720.0) / (1.0 / 720.0) < 1e-6
    assert ex["recommendation"] == "reparameterize by order"
    payload = honesty_payload()
    assert payload["bias_collapse"] is True
    assert payload["temperature_collapse"] is False
    assert payload["k_ge_3_fisher"] == "inapplicable_not_a_density"
    assert payload["theorem_prover_verified"] is False

python -m pytest "packages/omnibias-curvature/tests/test_information.py::test_worked_example_and_honesty" -q

Read the implementation

def worked_example() -> dict[str, object]:
    """Tiny deterministic example for docs snippets."""
    family = two_bias_family()
    delta = 1e-4
    g = fisher_delta_delta(delta, nodes=96)
    report = collapse_degeneracy(family, np.array([0.1]))
    loc = logistic_location_family()
    dist = fisher_distance(loc, np.array([0.0]), np.array([math.sqrt(3.0)]))
    return {
        "g_over_delta2": g / (delta * delta),
        "predicted_prefactor": 1.0 / 720.0,
        "recommendation": report.recommendation,
        "unit_location_distance": dist,
    }

omnibias.curvature.information

DEGENERACY_ABS_FLOOR​

DegeneracyReport​

Parameters

Fields & methods

FisherEvaluation​

Parameters

Fields & methods

NotADensityError​

PATH_CLOSED​

PATH_MC​

PINV_RCOND_RULE​

PackFamily​

Parameters

Fields & methods

Parameters

collapse_degeneracy​

Parameters

damped_natural_step​

Parameters

distinguishability_samples​

Parameters

empirical_distinguishability_n​

Parameters

evaluate_fisher​

Parameters

finite_difference_family​

Parameters

fisher_delta_delta​

Parameters

fisher_distance​

Parameters

fisher_metric​

Parameters

fisher_metric_mc​

Parameters

fisher_pinv​

Parameters

honesty_payload​

log_density​

Parameters

logistic_location_family​

logistic_mixture_family​

mean_nll​

Parameters

nll_gradient​

Parameters

pinv_rcond​

Parameters

randomized_mixture_suite​

Parameters

sample_family​

Parameters

two_bias_A​

Parameters

two_bias_ddelta_u​

Parameters

two_bias_density_naive​

Parameters

two_bias_density_u​

Parameters

two_bias_dx_u​

Parameters

two_bias_family​

two_bias_located_family​

undamped_natural_step​

Parameters

worked_example​

DEGENERACY_ABS_FLOOR

DegeneracyReport

FisherEvaluation

NotADensityError

PATH_CLOSED

PATH_MC

PINV_RCOND_RULE

PackFamily

collapse_degeneracy

damped_natural_step

distinguishability_samples

empirical_distinguishability_n

evaluate_fisher

finite_difference_family

fisher_delta_delta

fisher_distance

fisher_metric

fisher_metric_mc

fisher_pinv

honesty_payload

log_density

logistic_location_family

logistic_mixture_family

mean_nll

nll_gradient

pinv_rcond

randomized_mixture_suite

sample_family

two_bias_A

two_bias_ddelta_u

two_bias_density_naive

two_bias_density_u

two_bias_dx_u

two_bias_family

two_bias_located_family

undamped_natural_step

worked_example