API REFERENCE/omnibias-core

omnibias.core.verified.dfinite_continuation

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.dfinite_continuation

Module contract & mathematical conventions

Validated complex continuation for a scalar D-finite equation.

The core package cannot import the extension-tier Ore algebra, so an operator is supplied as its serial form: coeffs[i] is the ascending rational polynomial multiplying D^i. The order-r equation is converted to its companion system and then realified:

M=A+iB \longmapsto \begin{bmatrix}A&-B\\B&A\end{bmatrix}.

On each path segment, an interval matrix encloses the companion matrix at every point. The Peano--Baker series of the time-varying linear system is then enclosed by interval_matrix_exp: each ordered product of possibly different matrices from the box is contained in the corresponding interval-matrix power. This avoids the floating QR assumption documented by the generic Lohner implementation.

A path box that may meet a zero of the leading coefficient is refused. The result is a finite-path enclosure, not a global monodromy or zero-count claim.

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

DFiniteContinuation

omnibias.core.verified.DFiniteContinuationSource ↗

class DFiniteContinuation

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.

Validated finite-path enclosure of a D-finite solution jet.

Parameters

Name	Type & default	Contract
initial_hdataclass field	complexRequired	See the operation contract and implementation below.
targetdataclass field	ComplexIntervalRequired	See the operation contract and implementation below.
jetdataclass field	tuple[ComplexInterval, ...]Required	See the operation contract and implementation below.
path_boxesdataclass field	tuple[ComplexInterval, ...]Required	See the operation contract and implementation below.
n_stepsdataclass field	intRequired	See the operation contract and implementation below.
orderdataclass field	intRequired	See the operation contract and implementation below.

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Fields & methods

initial_hfield

initial_h: complex

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

View source ↗

targetfield

target: ComplexInterval

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

View source ↗

jetfield

jet: tuple[ComplexInterval, ...]

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

View source ↗

path_boxesfield

path_boxes: tuple[ComplexInterval, ...]

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

View source ↗

n_stepsfield

n_steps: int

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

View source ↗

orderfield

order: int

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

View source ↗

valueproperty

value(self) -> ComplexInterval

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

Returns: ComplexInterval

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Method implementation

    def value(self) -> ComplexInterval:
        return self.jet[0]

View source ↗

Read the implementation

class DFiniteContinuation:
    """Validated finite-path enclosure of a D-finite solution jet."""

    initial_h: complex
    target: ComplexInterval
    jet: tuple[ComplexInterval, ...]
    path_boxes: tuple[ComplexInterval, ...]
    n_steps: int
    order: int

    @property
    def value(self) -> ComplexInterval:
        return self.jet[0]

Other public import paths

• omnibias.core.verified.DFiniteContinuation
• omnibias.core.verified.dfinite_continuation.DFiniteContinuation

CONSTANT

SerializedOperator

omnibias.core.verified.SerializedOperatorSource ↗

SerializedOperator = tuple[tuple[Fraction, ...], ...]

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

SerializedOperator = tuple[tuple[Fraction, ...], ...]

Other public import paths

• omnibias.core.verified.SerializedOperator
• omnibias.core.verified.dfinite_continuation.SerializedOperator

FUNCTION

companion_matrix

omnibias.core.verified.companion_matrixSource ↗

companion_matrix(coeffs: Sequence[Sequence[Rational]], z: ComplexInterval) -> tuple[tuple[ComplexInterval, ...], ...]

Complex interval companion matrix for sum_i c_i(z) f^(i)=0.

Parameters

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

Returnstuple[tuple[ComplexInterval, ...], ...]

Explicit validation & failure cases

• When lead.modulus().lo <= 0.0, raises ZeroDivisionError('continuation path may meet a zero of the leading coefficient').

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

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Read the implementation

def companion_matrix(
    coeffs: Sequence[Sequence[Rational]], z: ComplexInterval
) -> tuple[tuple[ComplexInterval, ...], ...]:
    """Complex interval companion matrix for ``sum_i c_i(z) f^(i)=0``."""

    operator = normalize_operator(coeffs)
    order = len(operator) - 1
    values = tuple(evaluate_complex_polynomial(polynomial, z) for polynomial in operator)
    lead = values[-1]
    if lead.modulus().lo <= 0.0:
        raise ZeroDivisionError(
            "continuation path may meet a zero of the leading coefficient"
        )
    rows: list[tuple[ComplexInterval, ...]] = []
    for index in range(order - 1):
        rows.append(
            tuple(
                ComplexInterval.one() if column == index + 1 else ComplexInterval.zero()
                for column in range(order)
            )
        )
    rows.append(tuple(-values[index] / lead for index in range(order)))
    return tuple(rows)

Related APIsomnibias.core.verified.evaluate_complex_polynomial↗omnibias.core.verified.normalize_operator↗

Other public import paths

• omnibias.core.verified.companion_matrix
• omnibias.core.verified.dfinite_continuation.companion_matrix

FUNCTION

continue_dfinite

omnibias.core.verified.continue_dfiniteSource ↗

continue_dfinite(coeffs: Sequence[Sequence[Rational]], initial_h: complex | float | int, initial_jet: Sequence[ComplexLike], target: ComplexLike, *, n_steps: int=64, order: int=18) -> DFiniteContinuation

Continue a D-finite solution from a point to every point in target.

The straight homotopy h(s)=initial_h+s*(target-initial_h) is enclosed for 0 <= s <= 1. A rectangular target therefore represents a family of straight paths and the returned jet encloses all their endpoints.

Parameters

Name	Type & default	Contract
coeffspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.
initial_hpositional-or-keyword	complex | float | intRequired	See the operation contract and implementation below.
initial_jetpositional-or-keyword	Sequence[ComplexLike]Required	See the operation contract and implementation below.
targetpositional-or-keyword	ComplexLikeRequired	See the operation contract and implementation below.
n_stepskeyword-only	intDefault: 64	See the operation contract and implementation below.
orderkeyword-only	intDefault: 18	See the operation contract and implementation below.

ReturnsDFiniteContinuation

Explicit validation & failure cases

• When len(initial_jet) != differential_order, raises ValueError(f'operator order {differential_order} requires {differential_order} initial derivatives').
• 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 < 4, raises ValueError('matrix-exponential order must be an integer >= 4').

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

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Regression example · continue sine to complex point

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_continue_sine_to_complex_point() -> None:
    target = 0.2 + 0.1j
    result = continue_dfinite(
        ((1,), (), (1,)),
        0.0,
        (0.0, 1.0),
        target,
        n_steps=32,
        order=16,
    )

    assert result.value.contains(cmath.sin(target))
    assert result.jet[1].contains(cmath.cos(target))

python -m pytest packages/omnibias-core/tests/verified/test_dfinite_continuation.py -k test_continue_sine_to_complex_point -q

Read the implementation

def continue_dfinite(
    coeffs: Sequence[Sequence[Rational]],
    initial_h: complex | float | int,
    initial_jet: Sequence[ComplexLike],
    target: ComplexLike,
    *,
    n_steps: int = 64,
    order: int = 18,
) -> DFiniteContinuation:
    """Continue a D-finite solution from a point to every point in ``target``.

    The straight homotopy ``h(s)=initial_h+s*(target-initial_h)`` is enclosed
    for ``0 <= s <= 1``.  A rectangular target therefore represents a family
    of straight paths and the returned jet encloses all their endpoints.
    """

    operator = normalize_operator(coeffs)
    differential_order = len(operator) - 1
    if len(initial_jet) != differential_order:
        raise ValueError(
            f"operator order {differential_order} requires {differential_order} initial derivatives"
        )
    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 < 4:
        raise ValueError("matrix-exponential order must be an integer >= 4")

    start = complex(initial_h)
    start_box = ComplexInterval.point(start)
    target_box = ComplexInterval.from_value(target)
    delta = target_box - start_box
    whole_path = start_box + delta * ComplexInterval.from_value(Interval(0.0, 1.0))
    # Refuse a path family that may cross a singular leading coefficient
    # before attempting any matrix exponential.
    companion_matrix(operator, whole_path)
    state = _realify_state(
        tuple(ComplexInterval.from_value(value) for value in initial_jet)
    )
    step_size = Interval.from_rational(Fraction(1, n_steps))
    path_boxes: list[ComplexInterval] = []

    for index in range(n_steps):
        # Rational injection inflates binary endpoints when needed, keeping
        # the path cover sound.
        s_box = Interval.hull(
            Interval.from_rational(Fraction(index, n_steps)),
            Interval.from_rational(Fraction(index + 1, n_steps)),
        )
        h_box = start_box + delta * ComplexInterval.from_value(s_box)
        path_boxes.append(h_box)
        complex_generator = _scale_complex_matrix(
            companion_matrix(operator, h_box),
            delta,
        )
        real_generator = _scale_real_matrix(
            realify_complex_matrix(complex_generator),
            step_size,
        )
        transition = interval_matrix_exp(real_generator, order=order)
        state = matvec(transition, state)

    return DFiniteContinuation(
        initial_h=start,
        target=target_box,
        jet=_complexify_state(state),
        path_boxes=tuple(path_boxes),
        n_steps=n_steps,
        order=order,
    )

Related APIsomnibias.core.verified.DFiniteContinuation↗omnibias.core.verified.companion_matrix↗omnibias.core.verified.normalize_operator↗omnibias.core.verified.realify_complex_matrix↗omnibias.core.verified.Interval↗omnibias.core.verified.matvec↗omnibias.core.verified.interval_matrix_exp↗

Other public import paths

• omnibias.core.verified.continue_dfinite
• omnibias.core.verified.dfinite_continuation.continue_dfinite

FUNCTION

continue_dfinite_path

omnibias.core.verified.continue_dfinite_pathSource ↗

continue_dfinite_path(coeffs: Sequence[Sequence[Rational]], initial_h: complex | float | int, initial_jet: Sequence[ComplexLike], waypoints: Sequence[complex | float | int], *, steps_per_segment: int=32, order: int=18) -> tuple[DFiniteContinuation, ...]

Continue successively through point waypoints, retaining every enclosure.

Parameters

Name	Type & default	Contract
coeffspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.
initial_hpositional-or-keyword	complex | float | intRequired	See the operation contract and implementation below.
initial_jetpositional-or-keyword	Sequence[ComplexLike]Required	See the operation contract and implementation below.
waypointspositional-or-keyword	Sequence[complex | float | int]Required	See the operation contract and implementation below.
steps_per_segmentkeyword-only	intDefault: 32	See the operation contract and implementation below.
orderkeyword-only	intDefault: 18	See the operation contract and implementation below.

Returnstuple[DFiniteContinuation, ...]

Read the implementation

def continue_dfinite_path(
    coeffs: Sequence[Sequence[Rational]],
    initial_h: complex | float | int,
    initial_jet: Sequence[ComplexLike],
    waypoints: Sequence[complex | float | int],
    *,
    steps_per_segment: int = 32,
    order: int = 18,
) -> tuple[DFiniteContinuation, ...]:
    """Continue successively through point waypoints, retaining every enclosure."""

    current_h = complex(initial_h)
    current_jet = tuple(ComplexInterval.from_value(value) for value in initial_jet)
    results: list[DFiniteContinuation] = []
    for waypoint in waypoints:
        result = continue_dfinite(
            coeffs,
            current_h,
            current_jet,
            complex(waypoint),
            n_steps=steps_per_segment,
            order=order,
        )
        results.append(result)
        current_h = complex(waypoint)
        current_jet = result.jet
    return tuple(results)

Related APIsomnibias.core.verified.continue_dfinite↗

Other public import paths

• omnibias.core.verified.continue_dfinite_path
• omnibias.core.verified.dfinite_continuation.continue_dfinite_path

FUNCTION

evaluate_complex_polynomial

omnibias.core.verified.evaluate_complex_polynomialSource ↗

evaluate_complex_polynomial(coeffs: Sequence[Rational], z: ComplexInterval) -> ComplexInterval

Horner enclosure of a rational polynomial over a complex box.

Parameters

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

ReturnsComplexInterval

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Read the implementation

def evaluate_complex_polynomial(
    coeffs: Sequence[Rational], z: ComplexInterval
) -> ComplexInterval:
    """Horner enclosure of a rational polynomial over a complex box."""

    result = ComplexInterval.zero()
    for coefficient in reversed(coeffs):
        c = ComplexInterval.from_parts(Interval.from_rational(_fraction(coefficient)))
        result = result * z + c
    return result

Other public import paths

• omnibias.core.verified.evaluate_complex_polynomial
• omnibias.core.verified.dfinite_continuation.evaluate_complex_polynomial

FUNCTION

normalize_operator

omnibias.core.verified.normalize_operatorSource ↗

normalize_operator(coeffs: Sequence[Sequence[Rational]]) -> SerializedOperator

Validate and trim a serialized differential operator over Q[h].

Parameters

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

ReturnsSerializedOperator

Explicit validation & failure cases

• When len(normalized) < 2, raises ValueError('a D-finite continuation operator must have order >= 1').

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

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Read the implementation

def normalize_operator(
    coeffs: Sequence[Sequence[Rational]],
) -> SerializedOperator:
    """Validate and trim a serialized differential operator over ``Q[h]``."""

    normalized: list[tuple[Fraction, ...]] = []
    for polynomial in coeffs:
        values = [_fraction(value) for value in polynomial]
        while values and values[-1] == 0:
            values.pop()
        normalized.append(tuple(values))
    while normalized and not normalized[-1]:
        normalized.pop()
    if len(normalized) < 2:
        raise ValueError("a D-finite continuation operator must have order >= 1")
    return tuple(normalized)

Other public import paths

• omnibias.core.verified.normalize_operator
• omnibias.core.verified.dfinite_continuation.normalize_operator

FUNCTION

realify_complex_matrix

omnibias.core.verified.realify_complex_matrixSource ↗

realify_complex_matrix(matrix: Sequence[Sequence[ComplexInterval]]) -> IntervalMatrix

Realify A+iB to the interval block matrix [[A,-B],[B,A]].

Parameters

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

ReturnsIntervalMatrix

Explicit validation & failure cases

• When size == 0 or any((len(row) != size for row in matrix)), raises ValueError('a nonempty square complex matrix is required').

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

Executed regression · continue exponential to real point

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_continue_exponential_to_real_point() -> None:
    result = continue_dfinite(
        ((-1,), (1,)),
        0.0,
        (1.0,),
        0.1,
        n_steps=16,
        order=14,
    )

    assert result.value.contains(math.exp(0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_dfinite_continuation.py::test_continue_exponential_to_real_point" -q

Read the implementation

def realify_complex_matrix(
    matrix: Sequence[Sequence[ComplexInterval]],
) -> IntervalMatrix:
    """Realify ``A+iB`` to the interval block matrix ``[[A,-B],[B,A]]``."""

    size = len(matrix)
    if size == 0 or any(len(row) != size for row in matrix):
        raise ValueError("a nonempty square complex matrix is required")
    result: IntervalMatrix = []
    for row in matrix:
        result.append([value.re for value in row] + [-value.im for value in row])
    for row in matrix:
        result.append([value.im for value in row] + [value.re for value in row])
    return result

Other public import paths

• omnibias.core.verified.realify_complex_matrix
• omnibias.core.verified.dfinite_continuation.realify_complex_matrix

← Package overviewRunnable learning examples →