API REFERENCE/omnibias-core

omnibias.core.verified.ode

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.verified.ode

Module contract & mathematical conventions

Verified initial-value ODE integration -- the rigorous *flow* / shooting engine.

A self-similar blow-up profile is the solution of a boundary-value problem; the *rate* is fixed by a scalar connection condition g(c) = 0 evaluated on that solution (see omnibias.core.verified.rootfind). To feed the rate selector a *genuine* connection functional we must integrate the profile ODE **rigorously** -- not float64 RK -- from the regular origin out to the matching point.

This module provides a validated Taylor-series integrator for autonomous systems Y'(t) = F(Y(t)) (a non-autonomous field is handled by appending a clock state x' = 1). One step t -> t + h at order p is the textbook Lohner scheme:

1. **Taylor coefficients** U_0..U_p of the solution at the step start, via the recurrence (k+1) U_{k+1} = [F(Y(.))]_k -- the k-th Taylor coefficient of F composed with the partial series -- evaluated by interval *automatic Taylor arithmetic* (TaylorSeries). 2. **A-priori enclosure** [Z] of the whole step: a box with Y0 + [0,h] F([Z]) subset [Z] (Picard / Banach), so the true solution provably stays in [Z] for t in [0, h]. 3. **Validated remainder**: Y(h) in sum_{k<=p} U_k h^k + U_{p+1}([Z]) h^{p+1}, where U_{p+1}([Z]) is the order-p+1 coefficient recomputed with the expansion point ranging over [Z] (Taylor's theorem, Lagrange form, derivative enclosed over the step).

Everything is an outward-rounded Interval, so the returned end enclosure is a theorem-grade bound on the flow. Wrapping is controlled only by step size / order here (no QR Lohner), which is ample for scalar / low-dimensional shooting.

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

TaylorSeries

omnibias.core.verified.TaylorSeriesSource ↗

class TaylorSeries

A truncated power series with Interval coefficients.

Supports the algebra needed to express polynomial / rational vector fields: +, -, * (series*series convolution and series*scalar). All operands in a product are kept at a common length; the product is truncated to it.

Parameters

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

Executed regression · exponential flow encloses e

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_exponential_flow_encloses_e() -> None:
    (y,) = integrate_ivp(_exp, [1.0], 0.0, 1.0, order=16, n_steps=8)
    assert y.contains(math.e)
    assert y.width < 1e-12

python -m pytest "packages/omnibias-core/tests/verified/test_ode.py::test_exponential_flow_encloses_e" -q

Regression example · taylor series algebra

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_taylor_series_algebra() -> None:
    a = TaylorSeries([Interval.point(1.0), Interval.point(2.0), Interval.point(3.0)])
    b = TaylorSeries([Interval.point(1.0), Interval.point(1.0), Interval.point(0.0)])
    prod = a * b  # (1 + 2t + 3t^2)(1 + t) = 1 + 3t + 5t^2 (truncated)
    assert prod.coeffs[0].contains(1.0)
    assert prod.coeffs[1].contains(3.0)
    assert prod.coeffs[2].contains(5.0)
    scaled = a * 2.0
    assert scaled.coeffs[1].contains(4.0)

python -m pytest packages/omnibias-core/tests/verified/test_ode.py -k test_taylor_series_algebra -q

Fields & methods

__init__method

__init__(self, coeffs: Sequence[Interval]) -> None

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

Parameters

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

Returns: None

Validation & failure cases

• When not coeffs, raises ValueError('TaylorSeries needs at least one coefficient').

Executed regression · exponential flow encloses e

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_exponential_flow_encloses_e() -> None:
    (y,) = integrate_ivp(_exp, [1.0], 0.0, 1.0, order=16, n_steps=8)
    assert y.contains(math.e)
    assert y.width < 1e-12

python -m pytest "packages/omnibias-core/tests/verified/test_ode.py::test_exponential_flow_encloses_e" -q

Method implementation

    def __init__(self, coeffs: Sequence[Interval]) -> None:
        if not coeffs:
            raise ValueError("TaylorSeries needs at least one coefficient")
        self.coeffs: tuple[Interval, ...] = tuple(coeffs)

View source ↗

constantmethod

constant(cls, value: IntervalLike, order: int) -> TaylorSeries

Series [value, 0, ..., 0] of length order + 1.

Parameters

Name	Type & default	Contract
valuepositional-or-keyword	IntervalLikeRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.

Returns: TaylorSeries

Executed regression · g3 horizon extension

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_g3_horizon_extension() -> None:
    rows = horizon_report()
    assert len(rows) == 10
    assert all("ratio" in row for row in rows)
    wins = sum(1 for row in rows if row["win"])
    assert wins == 10, rows

python -m pytest "packages/omnibias-core/tests/verified/test_jet_flow.py::test_g3_horizon_extension" -q

Method implementation

    def constant(cls, value: IntervalLike, order: int) -> TaylorSeries:
        """Series ``[value, 0, ..., 0]`` of length ``order + 1``."""
        c0 = Interval.from_value(value)
        zero = Interval.point(0.0)
        return cls([c0, *([zero] * order)])

View source ↗

orderproperty

order(self) -> int

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

Returns: int

Executed regression · g3 horizon extension

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_g3_horizon_extension() -> None:
    rows = horizon_report()
    assert len(rows) == 10
    assert all("ratio" in row for row in rows)
    wins = sum(1 for row in rows if row["win"])
    assert wins == 10, rows

python -m pytest "packages/omnibias-core/tests/verified/test_jet_flow.py::test_g3_horizon_extension" -q

Method implementation

    def order(self) -> int:
        return len(self.coeffs) - 1

View source ↗

__len__method

__len__(self) -> int

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

Returns: int

Method implementation

    def __len__(self) -> int:
        return len(self.coeffs)

View source ↗

__add__method

__add__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	TaylorSeries | IntervalLikeRequired	See the operation contract and implementation below.

Returns: TaylorSeries

Executed regression · g3 horizon extension

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_g3_horizon_extension() -> None:
    rows = horizon_report()
    assert len(rows) == 10
    assert all("ratio" in row for row in rows)
    wins = sum(1 for row in rows if row["win"])
    assert wins == 10, rows

python -m pytest "packages/omnibias-core/tests/verified/test_jet_flow.py::test_g3_horizon_extension" -q

Method implementation

    def __add__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return TaylorSeries([self.coeffs[i] + other.coeffs[i] for i in range(n)])
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] + Interval.from_value(other)
        return TaylorSeries(shifted)

View source ↗

__neg__method

__neg__(self) -> TaylorSeries

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

Returns: TaylorSeries

Executed regression · harmonic energy is conserved rigorously

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_harmonic_energy_is_conserved_rigorously() -> None:
    # cos^2 + sin^2 = 1 must be enclosed for the whole orbit.
    y1, y2 = integrate_ivp(_harmonic, [1.0, 0.0], 0.0, 2.0, order=16, n_steps=16)
    energy = y1 * y1 + y2 * y2
    assert energy.contains(1.0)

python -m pytest "packages/omnibias-core/tests/verified/test_ode.py::test_harmonic_energy_is_conserved_rigorously" -q

Method implementation

    def __neg__(self) -> TaylorSeries:
        return TaylorSeries([-c for c in self.coeffs])

View source ↗

__sub__method

__sub__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	TaylorSeries | IntervalLikeRequired	See the operation contract and implementation below.

Returns: TaylorSeries

Executed regression · g3 horizon extension

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_g3_horizon_extension() -> None:
    rows = horizon_report()
    assert len(rows) == 10
    assert all("ratio" in row for row in rows)
    wins = sum(1 for row in rows if row["win"])
    assert wins == 10, rows

python -m pytest "packages/omnibias-core/tests/verified/test_jet_flow.py::test_g3_horizon_extension" -q

Method implementation

    def __sub__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return TaylorSeries([self.coeffs[i] - other.coeffs[i] for i in range(n)])
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] - Interval.from_value(other)
        return TaylorSeries(shifted)

View source ↗

__rsub__method

__rsub__(self, other: IntervalLike) -> TaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	IntervalLikeRequired	See the operation contract and implementation below.

Returns: TaylorSeries

Method implementation

    def __rsub__(self, other: IntervalLike) -> TaylorSeries:
        return (-self).__add__(other)

View source ↗

__mul__method

__mul__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	TaylorSeries | IntervalLikeRequired	See the operation contract and implementation below.

Returns: TaylorSeries

Executed regression · g3 horizon extension

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_g3_horizon_extension() -> None:
    rows = horizon_report()
    assert len(rows) == 10
    assert all("ratio" in row for row in rows)
    wins = sum(1 for row in rows if row["win"])
    assert wins == 10, rows

python -m pytest "packages/omnibias-core/tests/verified/test_jet_flow.py::test_g3_horizon_extension" -q

Method implementation

    def __mul__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            out: list[Interval] = []
            for k in range(n):
                acc = Interval.point(0.0)
                for i in range(k + 1):
                    acc = acc + self.coeffs[i] * other.coeffs[k - i]
                out.append(acc)
            return TaylorSeries(out)
        scalar = Interval.from_value(other)
        return TaylorSeries([c * scalar for c in self.coeffs])

View source ↗

__repr__method

__repr__(self) -> str

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

Returns: str

Method implementation

    def __repr__(self) -> str:
        return f"TaylorSeries({list(self.coeffs)!r})"

View source ↗

coeffsattribute

coeffs: tuple[Interval, ...] = tuple(coeffs)

Public instance attribute assigned by __init__. The source assignment is coeffs = tuple(coeffs); it describes instance state, not a literal constructor default.

View source ↗

Read the implementation

class TaylorSeries:
    """A truncated power series with :class:`Interval` coefficients.

    Supports the algebra needed to express polynomial / rational vector fields:
    ``+``, ``-``, ``*`` (series*series convolution and series*scalar).  All operands
    in a product are kept at a common length; the product is truncated to it.
    """

    __slots__ = ("coeffs",)

    def __init__(self, coeffs: Sequence[Interval]) -> None:
        if not coeffs:
            raise ValueError("TaylorSeries needs at least one coefficient")
        self.coeffs: tuple[Interval, ...] = tuple(coeffs)

    @classmethod
    def constant(cls, value: IntervalLike, order: int) -> TaylorSeries:
        """Series ``[value, 0, ..., 0]`` of length ``order + 1``."""
        c0 = Interval.from_value(value)
        zero = Interval.point(0.0)
        return cls([c0, *([zero] * order)])

    @property
    def order(self) -> int:
        return len(self.coeffs) - 1

    def __len__(self) -> int:
        return len(self.coeffs)

    def __add__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return TaylorSeries([self.coeffs[i] + other.coeffs[i] for i in range(n)])
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] + Interval.from_value(other)
        return TaylorSeries(shifted)

    __radd__ = __add__

    def __neg__(self) -> TaylorSeries:
        return TaylorSeries([-c for c in self.coeffs])

    def __sub__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return TaylorSeries([self.coeffs[i] - other.coeffs[i] for i in range(n)])
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] - Interval.from_value(other)
        return TaylorSeries(shifted)

    def __rsub__(self, other: IntervalLike) -> TaylorSeries:
        return (-self).__add__(other)

    def __mul__(self, other: TaylorSeries | IntervalLike) -> TaylorSeries:
        if isinstance(other, TaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            out: list[Interval] = []
            for k in range(n):
                acc = Interval.point(0.0)
                for i in range(k + 1):
                    acc = acc + self.coeffs[i] * other.coeffs[k - i]
                out.append(acc)
            return TaylorSeries(out)
        scalar = Interval.from_value(other)
        return TaylorSeries([c * scalar for c in self.coeffs])

    __rmul__ = __mul__

    def __repr__(self) -> str:
        return f"TaylorSeries({list(self.coeffs)!r})"

Other public import paths

• omnibias.core.verified.TaylorSeries
• omnibias.core.verified.ode.TaylorSeries

CONSTANT

VectorField

omnibias.core.verified.VectorFieldSource ↗

VectorField = Callable[[list['TaylorSeries']], list['TaylorSeries']]

An autonomous vector field acting on a list of component Taylor series.

Read the implementation

VectorField = Callable[[list["TaylorSeries"]], list["TaylorSeries"]]

Other public import paths

• omnibias.core.verified.VectorField
• omnibias.core.verified.ode.VectorField

FUNCTION

integrate_ivp

omnibias.core.verified.integrate_ivpSource ↗

integrate_ivp(field: VectorField, y0: Sequence[IntervalLike], t0: float, t1: float, *, order: int=14, n_steps: int=8) -> list[Interval]

Rigorously enclose the flow of Y' = F(Y) from t0 to t1.

field maps a list of component TaylorSeries to the list of series of F(Y) (autonomous; append a clock state x' = 1 for explicit-time fields). Returns a list of Interval enclosing Y(t1) component-wise. The enclosure is guaranteed for **every** initial condition in y0.

Parameters

Name	Type & default	Contract
fieldpositional-or-keyword	VectorFieldRequired	See the operation contract and implementation below.
y0positional-or-keyword	Sequence[IntervalLike]Required	See the operation contract and implementation below.
t0positional-or-keyword	floatRequired	See the operation contract and implementation below.
t1positional-or-keyword	floatRequired	See the operation contract and implementation below.
orderkeyword-only	intDefault: 14	See the operation contract and implementation below.
n_stepskeyword-only	intDefault: 8	See the operation contract and implementation below.

Returnslist[Interval]

Explicit validation & failure cases

• When t1 < t0, raises ValueError('integrate_ivp requires t1 >= t0').
• When n_steps < 1, raises ValueError('n_steps must be >= 1').
• When order < 1, raises ValueError('order must be >= 1').

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

Executed regression · exponential flow encloses e

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_exponential_flow_encloses_e() -> None:
    (y,) = integrate_ivp(_exp, [1.0], 0.0, 1.0, order=16, n_steps=8)
    assert y.contains(math.e)
    assert y.width < 1e-12

python -m pytest "packages/omnibias-core/tests/verified/test_ode.py::test_exponential_flow_encloses_e" -q

Regression example · rejects bad arguments

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_rejects_bad_arguments() -> None:
    with pytest.raises(ValueError):
        integrate_ivp(_exp, [1.0], 1.0, 0.0)
    with pytest.raises(ValueError):
        integrate_ivp(_exp, [1.0], 0.0, 1.0, n_steps=0)

python -m pytest packages/omnibias-core/tests/verified/test_ode.py -k test_rejects_bad_arguments -q

Read the implementation

def integrate_ivp(field: VectorField, y0: Sequence[IntervalLike], t0: float, t1: float,
                  *, order: int = 14, n_steps: int = 8) -> list[Interval]:
    r"""Rigorously enclose the flow of ``Y' = F(Y)`` from ``t0`` to ``t1``.

    ``field`` maps a list of component :class:`TaylorSeries` to the list of series of
    ``F(Y)`` (autonomous; append a clock state ``x' = 1`` for explicit-time fields).
    Returns a list of :class:`Interval` enclosing ``Y(t1)`` component-wise.  The
    enclosure is guaranteed for **every** initial condition in ``y0``.
    """
    if t1 < t0:
        raise ValueError("integrate_ivp requires t1 >= t0")
    if n_steps < 1:
        raise ValueError("n_steps must be >= 1")
    if order < 1:
        raise ValueError("order must be >= 1")
    y = [Interval.from_value(v) for v in y0]
    if t1 == t0:
        return y
    h = (t1 - t0) / n_steps
    for _ in range(n_steps):
        y = _step(field, y, h, order)
    return y

Other public import paths

• omnibias.core.verified.integrate_ivp
• omnibias.core.verified.ode.integrate_ivp

← Package overviewRunnable learning examples →