API REFERENCE/omnibias-core

omnibias.core.composed_curvature

0.5.0rc1Release candidatePython >=3.10Apache-2.0

Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.

import omnibias.core.composed_curvature

Module contract & mathematical conventions

Composed-curvature joint Newton algebra (theory 08-02).

The order-2 chain rule (f circ g)'' = f''(g) (g')^2 + f'(g) g'' is the exact coupling between consecutive layers. A Newton step on the joint block (W_{ell-1}, W_ell) can leave a critical point that is a minimum of the current-layer slice and a saddle of the pair.

This module is backend-free: tanh derivatives come from omnibias.core.polynomials.tanh_polynomial_coeffs (the same tower the backends evaluate), and the small dense eigen / Newton solve is shared so torch and jax take the same subspace step on the same floats. Tensor HVPs live in omnibias.{torch,jax}.optim_composed.

Jets come from the founding bias collapse (delta -> 0). No temperature collapse appears. Escape is from a *slice* critical point, not a global min of a deep nest, with explicit local scope.

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

Module source ↗Source revision 9a2d73df0573Running reference examples →

CLASS

ComposedCurvatureConfig

omnibias.core.ComposedCurvatureConfigSource ↗

class ComposedCurvatureConfig

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.

Subspace budget and Newton / escape knobs (theory 08-02).

Parameters

Name	Type & default	Contract
n_directionsdataclass field	intDefault: 4	See the operation contract and implementation below.
include_residual_hessdataclass field	boolDefault: True	See the operation contract and implementation below.
escape_toldataclass field	floatDefault: 0.0	See the operation contract and implementation below.
dampingdataclass field	floatDefault: 1e-06	See the operation contract and implementation below.
allow_fulldataclass field	boolDefault: False	See the operation contract and implementation below.

Executed regression · escape picks negative mode

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_escape_picks_negative_mode() -> None:
    # Slice PD, joint saddle: H_vv = 1, mixed = 2, H_ww = 1 => det = -3.
    h_slice = ((1.0,),)
    h_joint = ((1.0, 2.0), (2.0, 1.0))
    step = select_composed_step(h_slice, h_joint, (0.0, 0.0))
    assert step.lambda_min_slice >= 0.0
    assert step.lambda_min_joint < 0.0
    assert step.escaped
    nrm = math.sqrt(sum(c * c for c in step.coeffs))
    assert nrm == pytest.approx(1.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_escape_picks_negative_mode" -q

Fields & methods

n_directionsfield

n_directions: int = 4

Declared int field on ComposedCurvatureConfig. Default expression: 4.

View source ↗

include_residual_hessfield

include_residual_hess: bool = True

Declared bool field on ComposedCurvatureConfig. Default expression: True.

View source ↗

escape_tolfield

escape_tol: float = 0.0

Declared float field on ComposedCurvatureConfig. Default expression: 0.0.

View source ↗

dampingfield

damping: float = 1e-06

Declared float field on ComposedCurvatureConfig. Default expression: 1e-06.

View source ↗

allow_fullfield

allow_full: bool = False

Declared bool field on ComposedCurvatureConfig. Default expression: False.

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.n_directions < 1, raises ValueError(f'n_directions must be >= 1, got {self.n_directions}').
• When self.escape_tol < 0.0 or not math.isfinite(self.escape_tol), raises ValueError(f'escape_tol must be a finite number >= 0, got {self.escape_tol}').
• When self.damping < 0.0 or not math.isfinite(self.damping), raises ValueError(f'damping must be a finite number >= 0, got {self.damping}').

Executed regression · escape picks negative mode

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_escape_picks_negative_mode() -> None:
    # Slice PD, joint saddle: H_vv = 1, mixed = 2, H_ww = 1 => det = -3.
    h_slice = ((1.0,),)
    h_joint = ((1.0, 2.0), (2.0, 1.0))
    step = select_composed_step(h_slice, h_joint, (0.0, 0.0))
    assert step.lambda_min_slice >= 0.0
    assert step.lambda_min_joint < 0.0
    assert step.escaped
    nrm = math.sqrt(sum(c * c for c in step.coeffs))
    assert nrm == pytest.approx(1.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_escape_picks_negative_mode" -q

Method implementation

    def __post_init__(self) -> None:
        if self.n_directions < 1:
            raise ValueError(f"n_directions must be >= 1, got {self.n_directions}")
        if self.escape_tol < 0.0 or not math.isfinite(self.escape_tol):
            raise ValueError(
                f"escape_tol must be a finite number >= 0, got {self.escape_tol}"
            )
        if self.damping < 0.0 or not math.isfinite(self.damping):
            raise ValueError(f"damping must be a finite number >= 0, got {self.damping}")

View source ↗

Read the implementation

class ComposedCurvatureConfig:
    """Subspace budget and Newton / escape knobs (theory 08-02)."""

    n_directions: int = 4
    include_residual_hess: bool = True
    escape_tol: float = 0.0
    damping: float = 1e-6
    allow_full: bool = False

    def __post_init__(self) -> None:
        if self.n_directions < 1:
            raise ValueError(f"n_directions must be >= 1, got {self.n_directions}")
        if self.escape_tol < 0.0 or not math.isfinite(self.escape_tol):
            raise ValueError(
                f"escape_tol must be a finite number >= 0, got {self.escape_tol}"
            )
        if self.damping < 0.0 or not math.isfinite(self.damping):
            raise ValueError(f"damping must be a finite number >= 0, got {self.damping}")

Other public import paths

• omnibias.core.ComposedCurvatureConfig
• omnibias.core.composed_curvature.ComposedCurvatureConfig

CLASS

ComposedCurvatureReport

omnibias.core.ComposedCurvatureReportSource ↗

class ComposedCurvatureReport

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.

Diagnostics of one joint / escape step.

Parameters

Name	Type & default	Contract
lambda_min_slicedataclass field	floatRequired	See the operation contract and implementation below.
lambda_min_jointdataclass field	floatRequired	See the operation contract and implementation below.
escapeddataclass field	boolRequired	See the operation contract and implementation below.
step_normdataclass field	floatRequired	See the operation contract and implementation below.

Fields & methods

lambda_min_slicefield

lambda_min_slice: float

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

View source ↗

lambda_min_jointfield

lambda_min_joint: float

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

View source ↗

escapedfield

escaped: bool

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

View source ↗

step_normfield

step_norm: float

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

View source ↗

Read the implementation

class ComposedCurvatureReport:
    """Diagnostics of one joint / escape step."""

    lambda_min_slice: float
    lambda_min_joint: float
    escaped: bool
    step_norm: float

Other public import paths

• omnibias.core.ComposedCurvatureReport
• omnibias.core.composed_curvature.ComposedCurvatureReport

CLASS

SubspaceStep

omnibias.core.composed_curvature.SubspaceStepSource ↗

class SubspaceStep

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.

Newton or negative-curvature coefficients in the k-direction basis.

Parameters

Name	Type & default	Contract
coeffsdataclass field	tuple[float, ...]Required	See the operation contract and implementation below.
lambda_min_slicedataclass field	floatRequired	See the operation contract and implementation below.
lambda_min_jointdataclass field	floatRequired	See the operation contract and implementation below.
escapeddataclass field	boolRequired	See the operation contract and implementation below.

Fields & methods

coeffsfield

coeffs: tuple[float, ...]

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

View source ↗

lambda_min_slicefield

lambda_min_slice: float

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

View source ↗

lambda_min_jointfield

lambda_min_joint: float

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

View source ↗

escapedfield

escaped: bool

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

View source ↗

Read the implementation

class SubspaceStep:
    """Newton or negative-curvature coefficients in the ``k``-direction basis."""

    coeffs: tuple[float, ...]
    lambda_min_slice: float
    lambda_min_joint: float
    escaped: bool

FUNCTION

chain_rule_mse_blocks

omnibias.core.chain_rule_mse_blocksSource ↗

chain_rule_mse_blocks(h: float, h_w: float, h_ww: float, v: float) -> tuple[float, float, float]

Hessian blocks of L = 1/2 (v h - 1)^2 from the order-2 chain rule.

Spec §5 writes (v h - 1)^2; the half is the PINN convention 1/2 ||r||^2 and does not change eigenvalue *signs*. Returns (H_ww, H_wv, H_vv).

Parameters

Name	Type & default	Contract
hpositional-or-keyword	floatRequired	See the operation contract and implementation below.
h_wpositional-or-keyword	floatRequired	See the operation contract and implementation below.
h_wwpositional-or-keyword	floatRequired	See the operation contract and implementation below.
vpositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnstuple[float, float, float]

Executed regression · g1 scalar nest matches high precision fd

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_g1_scalar_nest_matches_high_precision_fd() -> None:
    w, v, x = 0.2, 0.1, 1.0
    h_ww, h_wv, h_vv = scalar_nest_hessian(w, v, x)

    def loss(ww: float, vv: float) -> float:
        h = math.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def loss_c(ww: complex, vv: complex) -> complex:
        h = cmath.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def fourth_ww(h: float) -> float:
        return (
            -loss(w + 2 * h, v)
            + 16.0 * loss(w + h, v)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w - h, v)
            - loss(w - 2 * h, v)
        ) / (12.0 * h * h)

    def fourth_vv(h: float) -> float:
        return (
            -loss(w, v + 2 * h)
            + 16.0 * loss(w, v + h)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w, v - h)
            - loss(w, v - 2 * h)
        ) / (12.0 * h * h)

    h_fd = 0.01
    fd_ww = (16.0 * fourth_ww(h_fd / 2.0) - fourth_ww(h_fd)) / 15.0
    fd_vv = (16.0 * fourth_vv(h_fd / 2.0) - fourth_vv(h_fd)) / 15.0
    step = 1e-8

    def dldw(ww: float, vv: float) -> float:
        return loss_c(ww + 1j * step, vv).imag / step

    def fourth_mixed(h: float) -> float:
        return (dldw(w, v + h) - dldw(w, v - h)) / (2.0 * h)

    fd_wv = (16.0 * fourth_mixed(h_fd / 2.0) - fourth_mixed(h_fd)) / 15.0
    assert _rel(h_ww, fd_ww) <= 1e-10
    assert _rel(h_vv, fd_vv) <= 1e-10
    assert _rel(h_wv, fd_wv) <= 1e-10

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_g1_scalar_nest_matches_high_precision_fd" -q

Read the implementation

def chain_rule_mse_blocks(
    h: float,
    h_w: float,
    h_ww: float,
    v: float,
) -> tuple[float, float, float]:
    r"""Hessian blocks of ``L = 1/2 (v h - 1)^2`` from the order-2 chain rule.

    Spec §5 writes ``(v h - 1)^2``; the half is the PINN convention
    ``1/2 ||r||^2`` and does not change eigenvalue *signs*. Returns
    ``(H_ww, H_wv, H_vv)``.
    """
    residual = v * h - 1.0
    h_vv = h * h
    h_wv = h_w * (v * h + residual)
    h_ww = (v * h_w) ** 2 + residual * v * h_ww
    return (h_ww, h_wv, h_vv)

Other public import paths

• omnibias.core.chain_rule_mse_blocks
• omnibias.core.composed_curvature.chain_rule_mse_blocks

FUNCTION

eigh_symmetric

omnibias.core.eigh_symmetricSource ↗

eigh_symmetric(matrix: Sequence[Sequence[float]], *, tol: float=_JACOBI_TOL, max_sweeps: int=_JACOBI_SWEEPS) -> tuple[tuple[float, ...], Matrix]

Jacobi eigen-decomposition of a small symmetric matrix.

Returns eigenvalues (ascending) and a matching column-orthonormal eigenvector matrix V (V[i][j] is row i, column j).

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	Sequence[Sequence[float]]Required	See the operation contract and implementation below.
tolkeyword-only	floatDefault: _JACOBI_TOL	See the operation contract and implementation below.
max_sweepskeyword-only	intDefault: _JACOBI_SWEEPS	See the operation contract and implementation below.

Returnstuple[tuple[float, ...], Matrix]

Executed regression · escape picks negative mode

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_escape_picks_negative_mode() -> None:
    # Slice PD, joint saddle: H_vv = 1, mixed = 2, H_ww = 1 => det = -3.
    h_slice = ((1.0,),)
    h_joint = ((1.0, 2.0), (2.0, 1.0))
    step = select_composed_step(h_slice, h_joint, (0.0, 0.0))
    assert step.lambda_min_slice >= 0.0
    assert step.lambda_min_joint < 0.0
    assert step.escaped
    nrm = math.sqrt(sum(c * c for c in step.coeffs))
    assert nrm == pytest.approx(1.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_escape_picks_negative_mode" -q

Regression example · eigh 2x2 matches closed form

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_eigh_2x2_matches_closed_form() -> None:
    h = ((2.0, 1.0), (1.0, 2.0))
    evals, vecs = eigh_symmetric(h)
    assert evals[0] == pytest.approx(1.0)
    assert evals[1] == pytest.approx(3.0)
    # Reconstruct H = V diag V^T.
    recon = [[0.0, 0.0], [0.0, 0.0]]
    for i in range(2):
        for j in range(2):
            recon[i][j] = (
                evals[0] * vecs[i][0] * vecs[j][0]
                + evals[1] * vecs[i][1] * vecs[j][1]
            )
    assert recon[0][0] == pytest.approx(2.0)
    assert recon[0][1] == pytest.approx(1.0)

python -m pytest packages/omnibias-core/tests/test_composed_curvature.py -k test_eigh_2x2_matches_closed_form -q

Read the implementation

def eigh_symmetric(
    matrix: Sequence[Sequence[float]],
    *,
    tol: float = _JACOBI_TOL,
    max_sweeps: int = _JACOBI_SWEEPS,
) -> tuple[tuple[float, ...], Matrix]:
    """Jacobi eigen-decomposition of a small symmetric matrix.

    Returns eigenvalues (ascending) and a matching column-orthonormal
    eigenvector matrix ``V`` (``V[i][j]`` is row ``i``, column ``j``).
    """
    h = symmetrize(matrix)
    n = len(h)
    if n == 0:
        return (), ()
    a = [list(row) for row in h]
    v = [[1.0 if i == j else 0.0 for j in range(n)] for i in range(n)]
    scale = max((abs(a[i][j]) for i in range(n) for j in range(n)), default=1.0)
    thresh = tol * (1.0 + scale)
    for _ in range(max_sweeps):
        p, q, off = 0, 1, 0.0
        for i in range(n):
            for j in range(i + 1, n):
                mag = abs(a[i][j])
                if mag > off:
                    off = mag
                    p, q = i, j
        if off <= thresh:
            break
        app = a[p][p]
        aqq = a[q][q]
        apq = a[p][q]
        theta = 0.5 * (aqq - app) / apq
        t = math.copysign(1.0, theta) / (abs(theta) + math.sqrt(1.0 + theta * theta))
        c = 1.0 / math.sqrt(1.0 + t * t)
        s = t * c
        tau_cs = s / (1.0 + c)
        for k in range(n):
            if k == p or k == q:
                continue
            akp = a[k][p]
            akq = a[k][q]
            a[k][p] = akp - s * (akq + tau_cs * akp)
            a[p][k] = a[k][p]
            a[k][q] = akq + s * (akp - tau_cs * akq)
            a[q][k] = a[k][q]
        a[p][p] = app - t * apq
        a[q][q] = aqq + t * apq
        a[p][q] = 0.0
        a[q][p] = 0.0
        for k in range(n):
            vkp = v[k][p]
            vkq = v[k][q]
            v[k][p] = c * vkp - s * vkq
            v[k][q] = s * vkp + c * vkq
    evals = [a[i][i] for i in range(n)]
    order = sorted(range(n), key=lambda i: evals[i])
    sorted_evals = tuple(evals[i] for i in order)
    sorted_vecs = tuple(tuple(v[row][order[col]] for col in range(n)) for row in range(n))
    return sorted_evals, sorted_vecs

Related APIsomnibias.core.symmetrize↗

Other public import paths

• omnibias.core.eigh_symmetric
• omnibias.core.composed_curvature.eigh_symmetric

FUNCTION

eval_tanh_derivative

omnibias.core.eval_tanh_derivativeSource ↗

eval_tanh_derivative(z: float, n: int) -> float

tanh^(n)(z) from the shared Legendre-style coefficients.

Parameters

Name	Type & default	Contract
zpositional-or-keyword	floatRequired	See the operation contract and implementation below.
npositional-or-keyword	intRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g1 worked tanh example

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_g1_worked_tanh_example() -> None:
    pack = ScaledPack(order=2, mean=0.0, alpha=1.0, base="tanh")
    got = rescale_pack(pack, 2.0).value(0.2)
    ref = 4.0 * eval_tanh_derivative(0.4, 2)
    assert abs(got - ref) <= 4.0 * math.ulp(ref)

python -m pytest "packages/omnibias-core/tests/test_scale.py::test_g1_worked_tanh_example" -q

Regression example · tanh first two derivatives match closed form

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_tanh_first_two_derivatives_match_closed_form() -> None:
    z = 0.2
    t = math.tanh(z)
    sech2 = 1.0 - t * t
    assert eval_tanh_derivative(z, 0) == pytest.approx(t)
    assert eval_tanh_derivative(z, 1) == pytest.approx(sech2)
    assert eval_tanh_derivative(z, 2) == pytest.approx(-2.0 * t * sech2)

python -m pytest packages/omnibias-core/tests/test_composed_curvature.py -k test_tanh_first_two_derivatives_match_closed_form -q

Read the implementation

def eval_tanh_derivative(z: float, n: int) -> float:
    """``tanh^(n)(z)`` from the shared Legendre-style coefficients."""
    t = math.tanh(z)
    return _horner(tanh_polynomial_coeffs(n), t)

Related APIsomnibias.core.tanh_polynomial_coeffs↗

Other public import paths

• omnibias.core.eval_tanh_derivative
• omnibias.core.composed_curvature.eval_tanh_derivative

FUNCTION

reject_full_parameter_jacobian

omnibias.core.reject_full_parameter_jacobianSource ↗

reject_full_parameter_jacobian(n_directions: int, n_params: int, allow_full: bool) -> None

G4: refuse a full-parameter Jacobian unless allow_full is set.

Parameters

Name	Type & default	Contract
n_directionspositional-or-keyword	intRequired	See the operation contract and implementation below.
n_paramspositional-or-keyword	intRequired	See the operation contract and implementation below.
allow_fullpositional-or-keyword	boolRequired	See the operation contract and implementation below.

ReturnsNone

Explicit validation & failure cases

• When n_directions < 1, raises ValueError(f'n_directions must be >= 1, got {n_directions}').
• When n_params < 2, raises ValueError(f'composed curvature needs at least two parameters (prev + curr), got n_params={n_params}').
• When n_directions >= n_params and (not allow_full), raises ValueError(f'n_directions={n_directions} >= n_params={n_params}; pass allow_full=True to opt into a full-block Jacobian (the API rejects silent P x P materialisation)').

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

Executed regression · g4 rejects full parameter jacobian

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_g4_rejects_full_parameter_jacobian() -> None:
    with pytest.raises(ValueError, match="allow_full"):
        reject_full_parameter_jacobian(2, 2, allow_full=False)
    reject_full_parameter_jacobian(2, 2, allow_full=True)
    reject_full_parameter_jacobian(1, 4, allow_full=False)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_g4_rejects_full_parameter_jacobian" -q

Read the implementation

def reject_full_parameter_jacobian(
    n_directions: int,
    n_params: int,
    allow_full: bool,
) -> None:
    """G4: refuse a full-parameter Jacobian unless ``allow_full`` is set."""
    if n_directions < 1:
        raise ValueError(f"n_directions must be >= 1, got {n_directions}")
    if n_params < 2:
        raise ValueError(
            f"composed curvature needs at least two parameters (prev + curr), "
            f"got n_params={n_params}"
        )
    if n_directions >= n_params and not allow_full:
        raise ValueError(
            f"n_directions={n_directions} >= n_params={n_params}; "
            "pass allow_full=True to opt into a full-block Jacobian "
            "(the API rejects silent P x P materialisation)"
        )

Other public import paths

• omnibias.core.reject_full_parameter_jacobian
• omnibias.core.composed_curvature.reject_full_parameter_jacobian

FUNCTION

scalar_nest_hessian

omnibias.core.scalar_nest_hessianSource ↗

scalar_nest_hessian(w: float, v: float, x: float=1.0) -> tuple[float, float, float]

Closed-form Hessian of the spec §5 scalar nest at (w, v).

g(w) = tanh(w x), L = 1/2 (v g - 1)^2. Derivatives of tanh use eval_tanh_derivative.

Parameters

Name	Type & default	Contract
wpositional-or-keyword	floatRequired	See the operation contract and implementation below.
vpositional-or-keyword	floatRequired	See the operation contract and implementation below.
xpositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.

Returnstuple[float, float, float]

Executed regression · g1 scalar nest matches high precision fd

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_g1_scalar_nest_matches_high_precision_fd() -> None:
    w, v, x = 0.2, 0.1, 1.0
    h_ww, h_wv, h_vv = scalar_nest_hessian(w, v, x)

    def loss(ww: float, vv: float) -> float:
        h = math.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def loss_c(ww: complex, vv: complex) -> complex:
        h = cmath.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def fourth_ww(h: float) -> float:
        return (
            -loss(w + 2 * h, v)
            + 16.0 * loss(w + h, v)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w - h, v)
            - loss(w - 2 * h, v)
        ) / (12.0 * h * h)

    def fourth_vv(h: float) -> float:
        return (
            -loss(w, v + 2 * h)
            + 16.0 * loss(w, v + h)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w, v - h)
            - loss(w, v - 2 * h)
        ) / (12.0 * h * h)

    h_fd = 0.01
    fd_ww = (16.0 * fourth_ww(h_fd / 2.0) - fourth_ww(h_fd)) / 15.0
    fd_vv = (16.0 * fourth_vv(h_fd / 2.0) - fourth_vv(h_fd)) / 15.0
    step = 1e-8

    def dldw(ww: float, vv: float) -> float:
        return loss_c(ww + 1j * step, vv).imag / step

    def fourth_mixed(h: float) -> float:
        return (dldw(w, v + h) - dldw(w, v - h)) / (2.0 * h)

    fd_wv = (16.0 * fourth_mixed(h_fd / 2.0) - fourth_mixed(h_fd)) / 15.0
    assert _rel(h_ww, fd_ww) <= 1e-10
    assert _rel(h_vv, fd_vv) <= 1e-10
    assert _rel(h_wv, fd_wv) <= 1e-10

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_g1_scalar_nest_matches_high_precision_fd" -q

Read the implementation

def scalar_nest_hessian(
    w: float,
    v: float,
    x: float = 1.0,
) -> tuple[float, float, float]:
    """Closed-form Hessian of the spec §5 scalar nest at ``(w, v)``.

    ``g(w) = tanh(w x)``, ``L = 1/2 (v g - 1)^2``. Derivatives of ``tanh``
    use :func:`eval_tanh_derivative`.
    """
    z = w * x
    h = eval_tanh_derivative(z, 0)
    h_w = x * eval_tanh_derivative(z, 1)
    h_ww = (x * x) * eval_tanh_derivative(z, 2)
    return chain_rule_mse_blocks(h, h_w, h_ww, v)

Related APIsomnibias.core.chain_rule_mse_blocks↗omnibias.core.eval_tanh_derivative↗

Other public import paths

• omnibias.core.scalar_nest_hessian
• omnibias.core.composed_curvature.scalar_nest_hessian

FUNCTION

select_composed_step

omnibias.core.select_composed_stepSource ↗

select_composed_step(h_slice: Sequence[Sequence[float]], h_joint: Sequence[Sequence[float]], g_joint: Sequence[float], config: ComposedCurvatureConfig | None=None) -> SubspaceStep

Damped joint Newton, or a unit negative-curvature direction if escaped.

The driver applies the subspace coefficients through Q and may then pick the *length* with spec 03-12. A negative-curvature quadratic has no interior minimum; the coefficients here are a unit descent eigenvector, not an unbounded Newton step.

Parameters

Name	Type & default	Contract
h_slicepositional-or-keyword	Sequence[Sequence[float]]Required	See the operation contract and implementation below.
h_jointpositional-or-keyword	Sequence[Sequence[float]]Required	See the operation contract and implementation below.
g_jointpositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
configpositional-or-keyword	ComposedCurvatureConfig | NoneDefault: None	See the operation contract and implementation below.

ReturnsSubspaceStep

Explicit validation & failure cases

• When not slice_evals or not joint_evals, raises ValueError('H_slice and H_joint must be non-empty').
• When len(g_joint) != len(joint_evals), raises ValueError(f'g_joint length {len(g_joint)} != joint size {len(joint_evals)}').

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

Executed regression · escape picks negative mode

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_escape_picks_negative_mode() -> None:
    # Slice PD, joint saddle: H_vv = 1, mixed = 2, H_ww = 1 => det = -3.
    h_slice = ((1.0,),)
    h_joint = ((1.0, 2.0), (2.0, 1.0))
    step = select_composed_step(h_slice, h_joint, (0.0, 0.0))
    assert step.lambda_min_slice >= 0.0
    assert step.lambda_min_joint < 0.0
    assert step.escaped
    nrm = math.sqrt(sum(c * c for c in step.coeffs))
    assert nrm == pytest.approx(1.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_escape_picks_negative_mode" -q

Regression example · g1 scalar nest matches high precision fd

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_g1_scalar_nest_matches_high_precision_fd() -> None:
    w, v, x = 0.2, 0.1, 1.0
    h_ww, h_wv, h_vv = scalar_nest_hessian(w, v, x)

    def loss(ww: float, vv: float) -> float:
        h = math.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def loss_c(ww: complex, vv: complex) -> complex:
        h = cmath.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def fourth_ww(h: float) -> float:
        return (
            -loss(w + 2 * h, v)
            + 16.0 * loss(w + h, v)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w - h, v)
            - loss(w - 2 * h, v)
        ) / (12.0 * h * h)

    def fourth_vv(h: float) -> float:
        return (
            -loss(w, v + 2 * h)
            + 16.0 * loss(w, v + h)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w, v - h)
            - loss(w, v - 2 * h)
        ) / (12.0 * h * h)

    h_fd = 0.01
    fd_ww = (16.0 * fourth_ww(h_fd / 2.0) - fourth_ww(h_fd)) / 15.0
    fd_vv = (16.0 * fourth_vv(h_fd / 2.0) - fourth_vv(h_fd)) / 15.0
    step = 1e-8

    def dldw(ww: float, vv: float) -> float:
        return loss_c(ww + 1j * step, vv).imag / step

    def fourth_mixed(h: float) -> float:
        return (dldw(w, v + h) - dldw(w, v - h)) / (2.0 * h)

    fd_wv = (16.0 * fourth_mixed(h_fd / 2.0) - fourth_mixed(h_fd)) / 15.0
    assert _rel(h_ww, fd_ww) <= 1e-10
    assert _rel(h_vv, fd_vv) <= 1e-10
    assert _rel(h_wv, fd_wv) <= 1e-10

python -m pytest packages/omnibias-core/tests/test_composed_curvature.py -k test_g1_scalar_nest_matches_high_precision_fd -q

Read the implementation

def select_composed_step(
    h_slice: Sequence[Sequence[float]],
    h_joint: Sequence[Sequence[float]],
    g_joint: Sequence[float],
    config: ComposedCurvatureConfig | None = None,
) -> SubspaceStep:
    """Damped joint Newton, or a unit negative-curvature direction if escaped.

    The driver applies the subspace coefficients through ``Q`` and may
    then pick the *length* with spec 03-12. A negative-curvature
    quadratic has no interior minimum; the coefficients here are a unit
    descent eigenvector, not an unbounded Newton step.
    """
    cfg = config if config is not None else ComposedCurvatureConfig()
    slice_evals, _ = eigh_symmetric(h_slice)
    joint_evals, joint_vecs = eigh_symmetric(h_joint)
    if not slice_evals or not joint_evals:
        raise ValueError("H_slice and H_joint must be non-empty")
    if len(g_joint) != len(joint_evals):
        raise ValueError(
            f"g_joint length {len(g_joint)} != joint size {len(joint_evals)}"
        )
    lam_s = float(slice_evals[0])
    lam_j = float(joint_evals[0])
    slice_pd = lam_s >= -_SLICE_PD_FLOOR
    escaped = bool(slice_pd and lam_j < -cfg.escape_tol)
    k = len(joint_evals)
    if escaped:
        vec = [float(joint_vecs[i][0]) for i in range(k)]
        dot = sum(vec[i] * float(g_joint[i]) for i in range(k))
        if dot > 0.0:
            vec = [-x for x in vec]
        nrm = math.sqrt(sum(x * x for x in vec))
        coeffs = tuple(x / nrm for x in vec) if nrm > 0.0 else tuple(0.0 for _ in vec)
    else:
        neg_g = tuple(-float(g) for g in g_joint)
        coeffs = solve_dense(h_joint, neg_g, damping=cfg.damping)
    return SubspaceStep(
        coeffs=coeffs,
        lambda_min_slice=lam_s,
        lambda_min_joint=lam_j,
        escaped=escaped,
    )

Related APIsomnibias.core.ComposedCurvatureConfig↗omnibias.core.composed_curvature.SubspaceStep↗omnibias.core.eigh_symmetric↗omnibias.core.solve_dense↗

Other public import paths

• omnibias.core.select_composed_step
• omnibias.core.composed_curvature.select_composed_step

FUNCTION

solve_dense

omnibias.core.solve_denseSource ↗

solve_dense(matrix: Sequence[Sequence[float]], rhs: Sequence[float], *, damping: float=0.0) -> Vector

Gaussian elimination with partial pivoting on (H + damping I) x = b.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	Sequence[Sequence[float]]Required	See the operation contract and implementation below.
rhspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
dampingkeyword-only	floatDefault: 0.0	See the operation contract and implementation below.

ReturnsVector

Explicit validation & failure cases

• When len(matrix) != n or any((len(row) != n for row in matrix)), raises ValueError('matrix and rhs length must match a square system').

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

Executed regression · solve dense recovers identity system

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_solve_dense_recovers_identity_system() -> None:
    x = solve_dense(((2.0, 0.0), (0.0, 3.0)), (4.0, 9.0), damping=0.0)
    assert x[0] == pytest.approx(2.0)
    assert x[1] == pytest.approx(3.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_solve_dense_recovers_identity_system" -q

Regression example · g1 scalar nest matches high precision fd

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_g1_scalar_nest_matches_high_precision_fd() -> None:
    w, v, x = 0.2, 0.1, 1.0
    h_ww, h_wv, h_vv = scalar_nest_hessian(w, v, x)

    def loss(ww: float, vv: float) -> float:
        h = math.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def loss_c(ww: complex, vv: complex) -> complex:
        h = cmath.tanh(ww * x)
        r = vv * h - 1.0
        return 0.5 * r * r

    def fourth_ww(h: float) -> float:
        return (
            -loss(w + 2 * h, v)
            + 16.0 * loss(w + h, v)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w - h, v)
            - loss(w - 2 * h, v)
        ) / (12.0 * h * h)

    def fourth_vv(h: float) -> float:
        return (
            -loss(w, v + 2 * h)
            + 16.0 * loss(w, v + h)
            - 30.0 * loss(w, v)
            + 16.0 * loss(w, v - h)
            - loss(w, v - 2 * h)
        ) / (12.0 * h * h)

    h_fd = 0.01
    fd_ww = (16.0 * fourth_ww(h_fd / 2.0) - fourth_ww(h_fd)) / 15.0
    fd_vv = (16.0 * fourth_vv(h_fd / 2.0) - fourth_vv(h_fd)) / 15.0
    step = 1e-8

    def dldw(ww: float, vv: float) -> float:
        return loss_c(ww + 1j * step, vv).imag / step

    def fourth_mixed(h: float) -> float:
        return (dldw(w, v + h) - dldw(w, v - h)) / (2.0 * h)

    fd_wv = (16.0 * fourth_mixed(h_fd / 2.0) - fourth_mixed(h_fd)) / 15.0
    assert _rel(h_ww, fd_ww) <= 1e-10
    assert _rel(h_vv, fd_vv) <= 1e-10
    assert _rel(h_wv, fd_wv) <= 1e-10

python -m pytest packages/omnibias-core/tests/test_composed_curvature.py -k test_g1_scalar_nest_matches_high_precision_fd -q

Read the implementation

def solve_dense(
    matrix: Sequence[Sequence[float]],
    rhs: Sequence[float],
    *,
    damping: float = 0.0,
) -> Vector:
    """Gaussian elimination with partial pivoting on ``(H + damping I) x = b``."""
    n = len(rhs)
    if len(matrix) != n or any(len(row) != n for row in matrix):
        raise ValueError("matrix and rhs length must match a square system")
    a = [
        [float(matrix[i][j]) + (damping if i == j else 0.0) for j in range(n)]
        for i in range(n)
    ]
    b = [float(x) for x in rhs]
    for k in range(n):
        pivot = k
        best = abs(a[k][k])
        for i in range(k + 1, n):
            mag = abs(a[i][k])
            if mag > best:
                best = mag
                pivot = i
        if best < _GE_PIVOT:
            a[k][k] = _GE_PIVOT if a[k][k] >= 0.0 else -_GE_PIVOT
            pivot = k
        if pivot != k:
            a[k], a[pivot] = a[pivot], a[k]
            b[k], b[pivot] = b[pivot], b[k]
        diag = a[k][k]
        for i in range(k + 1, n):
            factor = a[i][k] / diag
            for j in range(k, n):
                a[i][j] -= factor * a[k][j]
            b[i] -= factor * b[k]
    x = [0.0] * n
    for i in range(n - 1, -1, -1):
        acc = b[i]
        for j in range(i + 1, n):
            acc -= a[i][j] * x[j]
        x[i] = acc / a[i][i]
    return tuple(x)

Other public import paths

• omnibias.core.solve_dense
• omnibias.core.composed_curvature.solve_dense

FUNCTION

symmetrize

omnibias.core.symmetrizeSource ↗

symmetrize(matrix: Sequence[Sequence[float]]) -> Matrix

(H + H^T) / 2 as nested tuples.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	Sequence[Sequence[float]]Required	See the operation contract and implementation below.

ReturnsMatrix

Explicit validation & failure cases

• When any((len(row) != n for row in matrix)), raises ValueError('matrix must be square').

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

Executed regression · escape picks negative mode

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_escape_picks_negative_mode() -> None:
    # Slice PD, joint saddle: H_vv = 1, mixed = 2, H_ww = 1 => det = -3.
    h_slice = ((1.0,),)
    h_joint = ((1.0, 2.0), (2.0, 1.0))
    step = select_composed_step(h_slice, h_joint, (0.0, 0.0))
    assert step.lambda_min_slice >= 0.0
    assert step.lambda_min_joint < 0.0
    assert step.escaped
    nrm = math.sqrt(sum(c * c for c in step.coeffs))
    assert nrm == pytest.approx(1.0)

python -m pytest "packages/omnibias-core/tests/test_composed_curvature.py::test_escape_picks_negative_mode" -q

Read the implementation

def symmetrize(matrix: Sequence[Sequence[float]]) -> Matrix:
    """``(H + H^T) / 2`` as nested tuples."""
    n = len(matrix)
    if n == 0:
        return ()
    if any(len(row) != n for row in matrix):
        raise ValueError("matrix must be square")
    out: list[tuple[float, ...]] = []
    for i in range(n):
        row = []
        for j in range(n):
            row.append(0.5 * (float(matrix[i][j]) + float(matrix[j][i])))
        out.append(tuple(row))
    return tuple(out)

Other public import paths

• omnibias.core.symmetrize
• omnibias.core.composed_curvature.symmetrize

← Package overviewRunnable learning examples →