API REFERENCE/omnibias-core

omnibias.core.verified.complex_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.complex_ode

Module contract & mathematical conventions

Validated real-time integration of complexified analytic ODEs.

This module is the rectangular-complex counterpart of omnibias.core.verified.ode. It encloses

Y'(t) = F(Y(t)), \qquad t \in [t_0,t_1] \subset \mathbb R,

uniformly for every complex initial value in a supplied rectangle. Taylor coefficients, the Picard a-priori tube, and the Lagrange remainder all use outward-rounded ~omnibias.core.verified.complex_interval.ComplexInterval arithmetic.

The result is a fixed-real-time complex flow enclosure. It does **not** by itself certify a parameter-dependent first-hit time, a holomorphic return map, or differential-polynomial closure. Those require a complex implicit-event argument and separate format bounds.

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

ComplexTaylorSeries

omnibias.core.verified.ComplexTaylorSeriesSource ↗

class ComplexTaylorSeries

A truncated power series with rectangular complex coefficients.

Parameters

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

Executed regression · complex harmonic flow contains exact solution

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_complex_harmonic_flow_contains_exact_solution() -> None:
    first, second = integrate_complex_ivp(
        _harmonic,
        [1 + 0.1j, -0.2 + 0.3j],
        0.0,
        0.75,
        order=14,
        n_steps=8,
    )
    c = cmath.cos(0.75)
    s = cmath.sin(0.75)
    assert first.contains((1 + 0.1j) * c + (-0.2 + 0.3j) * s)
    assert second.contains(-(1 + 0.1j) * s + (-0.2 + 0.3j) * c)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_harmonic_flow_contains_exact_solution" -q

Regression example · complex 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_complex_taylor_series_algebra() -> None:
    first = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 + 1j),
            ComplexInterval.point(2 - 1j),
            ComplexInterval.zero(),
        ]
    )
    second = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 - 1j),
            ComplexInterval.one(),
            ComplexInterval.zero(),
        ]
    )
    product = first * second
    assert product.coeffs[0].contains((1 + 1j) * (1 - 1j))
    assert product.coeffs[1].contains((1 + 1j) + (2 - 1j) * (1 - 1j))
    assert (2 - first).coeffs[0].contains(1 - 1j)

python -m pytest packages/omnibias-core/tests/verified/test_complex_ode.py -k test_complex_taylor_series_algebra -q

Fields & methods

__init__method

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

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

Parameters

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

Returns: None

Validation & failure cases

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

Executed regression · complex harmonic flow contains exact solution

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_complex_harmonic_flow_contains_exact_solution() -> None:
    first, second = integrate_complex_ivp(
        _harmonic,
        [1 + 0.1j, -0.2 + 0.3j],
        0.0,
        0.75,
        order=14,
        n_steps=8,
    )
    c = cmath.cos(0.75)
    s = cmath.sin(0.75)
    assert first.contains((1 + 0.1j) * c + (-0.2 + 0.3j) * s)
    assert second.contains(-(1 + 0.1j) * s + (-0.2 + 0.3j) * c)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_harmonic_flow_contains_exact_solution" -q

Method implementation

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

View source ↗

constantmethod

constant(cls, value: ComplexLike | Fraction, order: int) -> ComplexTaylorSeries

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

Parameters

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

Returns: ComplexTaylorSeries

Validation & failure cases

• When type(order) is not int or order < 0, raises ValueError('order must be a nonnegative integer').

Method implementation

    def constant(
        cls,
        value: ComplexLike | Fraction,
        order: int,
    ) -> ComplexTaylorSeries:
        """Series ``[value, 0, ..., 0]`` of length ``order + 1``."""
        if type(order) is not int or order < 0:
            raise ValueError("order must be a nonnegative integer")
        c0 = ComplexInterval.from_value(value)
        zero = ComplexInterval.zero()
        return cls([c0, *([zero] * order)])

View source ↗

orderproperty

order(self) -> int

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

Returns: int

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: ComplexTaylorSeries | ComplexLike | Fraction) -> ComplexTaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	ComplexTaylorSeries | ComplexLike | FractionRequired	See the operation contract and implementation below.

Returns: ComplexTaylorSeries

Executed regression · complex taylor series algebra

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_complex_taylor_series_algebra() -> None:
    first = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 + 1j),
            ComplexInterval.point(2 - 1j),
            ComplexInterval.zero(),
        ]
    )
    second = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 - 1j),
            ComplexInterval.one(),
            ComplexInterval.zero(),
        ]
    )
    product = first * second
    assert product.coeffs[0].contains((1 + 1j) * (1 - 1j))
    assert product.coeffs[1].contains((1 + 1j) + (2 - 1j) * (1 - 1j))
    assert (2 - first).coeffs[0].contains(1 - 1j)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_taylor_series_algebra" -q

Method implementation

    def __add__(
        self,
        other: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return ComplexTaylorSeries(
                [self.coeffs[index] + other.coeffs[index] for index in range(n)]
            )
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] + ComplexInterval.from_value(other)
        return ComplexTaylorSeries(shifted)

View source ↗

__neg__method

__neg__(self) -> ComplexTaylorSeries

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

Returns: ComplexTaylorSeries

Executed regression · complex harmonic flow contains exact solution

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_complex_harmonic_flow_contains_exact_solution() -> None:
    first, second = integrate_complex_ivp(
        _harmonic,
        [1 + 0.1j, -0.2 + 0.3j],
        0.0,
        0.75,
        order=14,
        n_steps=8,
    )
    c = cmath.cos(0.75)
    s = cmath.sin(0.75)
    assert first.contains((1 + 0.1j) * c + (-0.2 + 0.3j) * s)
    assert second.contains(-(1 + 0.1j) * s + (-0.2 + 0.3j) * c)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_harmonic_flow_contains_exact_solution" -q

Method implementation

    def __neg__(self) -> ComplexTaylorSeries:
        return ComplexTaylorSeries([-coefficient for coefficient in self.coeffs])

View source ↗

__sub__method

__sub__(self, other: ComplexTaylorSeries | ComplexLike | Fraction) -> ComplexTaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	ComplexTaylorSeries | ComplexLike | FractionRequired	See the operation contract and implementation below.

Returns: ComplexTaylorSeries

Method implementation

    def __sub__(
        self,
        other: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return ComplexTaylorSeries(
                [self.coeffs[index] - other.coeffs[index] for index in range(n)]
            )
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] - ComplexInterval.from_value(other)
        return ComplexTaylorSeries(shifted)

View source ↗

__rsub__method

__rsub__(self, other: ComplexLike | Fraction) -> ComplexTaylorSeries

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

Parameters

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

Returns: ComplexTaylorSeries

Executed regression · complex taylor series algebra

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_complex_taylor_series_algebra() -> None:
    first = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 + 1j),
            ComplexInterval.point(2 - 1j),
            ComplexInterval.zero(),
        ]
    )
    second = ComplexTaylorSeries(
        [
            ComplexInterval.point(1 - 1j),
            ComplexInterval.one(),
            ComplexInterval.zero(),
        ]
    )
    product = first * second
    assert product.coeffs[0].contains((1 + 1j) * (1 - 1j))
    assert product.coeffs[1].contains((1 + 1j) + (2 - 1j) * (1 - 1j))
    assert (2 - first).coeffs[0].contains(1 - 1j)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_taylor_series_algebra" -q

Method implementation

    def __rsub__(
        self,
        other: ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        return (-self).__add__(other)

View source ↗

__mul__method

__mul__(self, other: ComplexTaylorSeries | ComplexLike | Fraction) -> ComplexTaylorSeries

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

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	ComplexTaylorSeries | ComplexLike | FractionRequired	See the operation contract and implementation below.

Returns: ComplexTaylorSeries

Executed regression · complex riccati encloses dense and random initial values

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_complex_riccati_encloses_dense_and_random_initial_values() -> None:
    initial = ComplexInterval(Interval(0.45, 0.55), Interval(-0.05, 0.05))
    final_time = 0.25
    (result,) = integrate_complex_ivp(
        _riccati,
        [initial],
        0.0,
        final_time,
        order=16,
        n_steps=12,
    )
    for value in _complex_rectangle_samples(initial, seed=17002):
        truth = value / (1.0 - final_time * value)
        assert result.contains(truth)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_riccati_encloses_dense_and_random_initial_values" -q

Method implementation

    def __mul__(
        self,
        other: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            out: list[ComplexInterval] = []
            for degree in range(n):
                coefficient = ComplexInterval.zero()
                for left_degree in range(degree + 1):
                    coefficient = (
                        coefficient
                        + self.coeffs[left_degree]
                        * other.coeffs[degree - left_degree]
                    )
                out.append(coefficient)
            return ComplexTaylorSeries(out)
        scalar = ComplexInterval.from_value(other)
        return ComplexTaylorSeries(
            [coefficient * scalar for coefficient 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"ComplexTaylorSeries({list(self.coeffs)!r})"

View source ↗

coeffsattribute

coeffs: tuple[ComplexInterval, ...] = 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 ComplexTaylorSeries:
    """A truncated power series with rectangular complex coefficients."""

    __slots__ = ("coeffs",)

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

    @classmethod
    def constant(
        cls,
        value: ComplexLike | Fraction,
        order: int,
    ) -> ComplexTaylorSeries:
        """Series ``[value, 0, ..., 0]`` of length ``order + 1``."""
        if type(order) is not int or order < 0:
            raise ValueError("order must be a nonnegative integer")
        c0 = ComplexInterval.from_value(value)
        zero = ComplexInterval.zero()
        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: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return ComplexTaylorSeries(
                [self.coeffs[index] + other.coeffs[index] for index in range(n)]
            )
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] + ComplexInterval.from_value(other)
        return ComplexTaylorSeries(shifted)

    __radd__ = __add__

    def __neg__(self) -> ComplexTaylorSeries:
        return ComplexTaylorSeries([-coefficient for coefficient in self.coeffs])

    def __sub__(
        self,
        other: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            return ComplexTaylorSeries(
                [self.coeffs[index] - other.coeffs[index] for index in range(n)]
            )
        shifted = list(self.coeffs)
        shifted[0] = shifted[0] - ComplexInterval.from_value(other)
        return ComplexTaylorSeries(shifted)

    def __rsub__(
        self,
        other: ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        return (-self).__add__(other)

    def __mul__(
        self,
        other: ComplexTaylorSeries | ComplexLike | Fraction,
    ) -> ComplexTaylorSeries:
        if isinstance(other, ComplexTaylorSeries):
            n = min(len(self.coeffs), len(other.coeffs))
            out: list[ComplexInterval] = []
            for degree in range(n):
                coefficient = ComplexInterval.zero()
                for left_degree in range(degree + 1):
                    coefficient = (
                        coefficient
                        + self.coeffs[left_degree]
                        * other.coeffs[degree - left_degree]
                    )
                out.append(coefficient)
            return ComplexTaylorSeries(out)
        scalar = ComplexInterval.from_value(other)
        return ComplexTaylorSeries(
            [coefficient * scalar for coefficient in self.coeffs]
        )

    __rmul__ = __mul__

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

Other public import paths

• omnibias.core.verified.ComplexTaylorSeries
• omnibias.core.verified.complex_ode.ComplexTaylorSeries

CONSTANT

ComplexVectorField

omnibias.core.verified.ComplexVectorFieldSource ↗

ComplexVectorField = Callable[[list['ComplexTaylorSeries']], list['ComplexTaylorSeries']]

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

ComplexVectorField = Callable[
    [list["ComplexTaylorSeries"]],
    list["ComplexTaylorSeries"],
]

Other public import paths

• omnibias.core.verified.ComplexVectorField
• omnibias.core.verified.complex_ode.ComplexVectorField

FUNCTION

integrate_complex_ivp

omnibias.core.verified.integrate_complex_ivpSource ↗

integrate_complex_ivp(field: ComplexVectorField, y0: Sequence[ComplexLike | Fraction], t0: float, t1: float, *, order: int=14, n_steps: int=8) -> list[ComplexInterval]

Enclose a complexified ODE flow for every supplied initial value.

Time remains real. Complex rectangles in y0 may therefore encode a complex neighborhood of state or frozen parameter coordinates.

Parameters

Name	Type & default	Contract
fieldpositional-or-keyword	ComplexVectorFieldRequired	See the operation contract and implementation below.
y0positional-or-keyword	Sequence[ComplexLike | Fraction]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[ComplexInterval]

Explicit validation & failure cases

• When t1 < t0, raises ValueError('integrate_complex_ivp requires t1 >= t0').
• When type(n_steps) is not int or n_steps < 1, raises ValueError('n_steps must be a positive integer').
• When type(order) is not int or order < 1, raises ValueError('order must be a positive integer').

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

Executed regression · complex harmonic flow contains exact solution

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_complex_harmonic_flow_contains_exact_solution() -> None:
    first, second = integrate_complex_ivp(
        _harmonic,
        [1 + 0.1j, -0.2 + 0.3j],
        0.0,
        0.75,
        order=14,
        n_steps=8,
    )
    c = cmath.cos(0.75)
    s = cmath.sin(0.75)
    assert first.contains((1 + 0.1j) * c + (-0.2 + 0.3j) * s)
    assert second.contains(-(1 + 0.1j) * s + (-0.2 + 0.3j) * c)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_ode.py::test_complex_harmonic_flow_contains_exact_solution" -q

Regression example · complex exponential encloses dense and random initial values

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_complex_exponential_encloses_dense_and_random_initial_values() -> None:
    initial = ComplexInterval(Interval(0.99, 1.01), Interval(-0.01, 0.01))
    (result,) = integrate_complex_ivp(
        _exponential,
        [initial],
        0.0,
        0.5,
        order=14,
        n_steps=8,
    )
    multiplier = cmath.exp(0.5)
    for value in _complex_rectangle_samples(initial, seed=17001):
        assert result.contains(value * multiplier)

python -m pytest packages/omnibias-core/tests/verified/test_complex_ode.py -k test_complex_exponential_encloses_dense_and_random_initial_values -q

Read the implementation

def integrate_complex_ivp(
    field: ComplexVectorField,
    y0: Sequence[ComplexLike | Fraction],
    t0: float,
    t1: float,
    *,
    order: int = 14,
    n_steps: int = 8,
) -> list[ComplexInterval]:
    """Enclose a complexified ODE flow for every supplied initial value.

    Time remains real.  Complex rectangles in ``y0`` may therefore encode a
    complex neighborhood of state or frozen parameter coordinates.
    """
    if t1 < t0:
        raise ValueError("integrate_complex_ivp requires t1 >= t0")
    if type(n_steps) is not int or n_steps < 1:
        raise ValueError("n_steps must be a positive integer")
    if type(order) is not int or order < 1:
        raise ValueError("order must be a positive integer")
    state = [ComplexInterval.from_value(value) for value in y0]
    if t1 == t0:
        return state
    step_size = (t1 - t0) / n_steps
    for _ in range(n_steps):
        state = _step(field, state, step_size, order)
    return state

Other public import paths

• omnibias.core.verified.integrate_complex_ivp
• omnibias.core.verified.complex_ode.integrate_complex_ivp

← Package overviewRunnable learning examples →