API REFERENCE/omnibias-core

omnibias.core.verified.complex_rootfind

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_rootfind

Module contract & mathematical conventions

Parametric complex interval Newton on rectangular enclosures.

For a family g(z, p) whose parameter p ranges over a fixed box, the interval-Newton operator

N(X) = m - g(m,P) / \partial_z g(X,P)

proves one root for every parameter and uniqueness in X when N(X) lies strictly inside X and the derivative enclosure excludes zero. Callers remain responsible for supplying sound complex enclosures of the function and derivative on the declared parameter box.

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 →

CONSTANT

ComplexFn

omnibias.core.verified.ComplexFnSource ↗

ComplexFn = Callable[[ComplexInterval], ComplexInterval]

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

ComplexFn = Callable[[ComplexInterval], ComplexInterval]

Other public import paths

• omnibias.core.verified.ComplexFn
• omnibias.core.verified.complex_rootfind.ComplexFn

CLASS

ComplexNewtonResult

omnibias.core.verified.ComplexNewtonResultSource ↗

class ComplexNewtonResult

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.

Outcome of a rectangular parametric complex interval-Newton proof.

Parameters

Name	Type & default	Contract
statusdataclass field	ComplexNewtonStatusRequired	See the operation contract and implementation below.
enclosuredataclass field	ComplexIntervalRequired	See the operation contract and implementation below.
iterationsdataclass field	intRequired	See the operation contract and implementation below.
unique_for_every_parameterdataclass field	boolRequired	See the operation contract and implementation below.

Fields & methods

statusfield

status: ComplexNewtonStatus

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

View source ↗

enclosurefield

enclosure: ComplexInterval

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

View source ↗

iterationsfield

iterations: int

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

View source ↗

unique_for_every_parameterfield

unique_for_every_parameter: bool

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

View source ↗

Read the implementation

class ComplexNewtonResult:
    """Outcome of a rectangular parametric complex interval-Newton proof."""

    status: ComplexNewtonStatus
    enclosure: ComplexInterval
    iterations: int
    unique_for_every_parameter: bool

Other public import paths

• omnibias.core.verified.ComplexNewtonResult
• omnibias.core.verified.complex_rootfind.ComplexNewtonResult

CONSTANT

ComplexNewtonStatus

omnibias.core.verified.ComplexNewtonStatusSource ↗

ComplexNewtonStatus = Literal['unique_root', 'derivative_contains_zero', 'no_root', 'max_iter']

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

ComplexNewtonStatus = Literal[
    "unique_root",
    "derivative_contains_zero",
    "no_root",
    "max_iter",
]

Other public import paths

• omnibias.core.verified.ComplexNewtonStatus
• omnibias.core.verified.complex_rootfind.ComplexNewtonStatus

FUNCTION

parametric_complex_interval_newton

omnibias.core.verified.parametric_complex_interval_newtonSource ↗

parametric_complex_interval_newton(function: ComplexFn, derivative: ComplexFn, domain: ComplexInterval, *, max_iter: int=20, tol: float=1e-13) -> ComplexNewtonResult

Prove a unique complex root branch over an implicit parameter box.

function and derivative may close over interval parameters. A unique_root result then applies separately to every parameter in that box, not merely to one representative value.

Parameters

Name	Type & default	Contract
functionpositional-or-keyword	ComplexFnRequired	See the operation contract and implementation below.
derivativepositional-or-keyword	ComplexFnRequired	See the operation contract and implementation below.
domainpositional-or-keyword	ComplexIntervalRequired	See the operation contract and implementation below.
max_iterkeyword-only	intDefault: 20	See the operation contract and implementation below.
tolkeyword-only	floatDefault: 1e-13	See the operation contract and implementation below.

ReturnsComplexNewtonResult

Explicit validation & failure cases

• When type(max_iter) is not int or max_iter < 1, raises ValueError('max_iter must be a positive integer').
• When not 0.0 < tol < float('inf'), raises ValueError('tol must be finite and positive').

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

Executed regression · parametric linear root branch is certified

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_parametric_linear_root_branch_is_certified() -> None:
    parameter = ComplexInterval(Interval(0.9, 1.1), Interval(-0.1, 0.1))
    domain = ComplexInterval(Interval(0.5, 1.5), Interval(-0.5, 0.5))
    result = parametric_complex_interval_newton(
        lambda value: value - parameter,
        lambda _value: ComplexInterval.one(),
        domain,
    )
    assert result.status == "unique_root"
    assert result.unique_for_every_parameter
    for truth in _samples(parameter, seed=18001):
        assert result.enclosure.contains(truth)

python -m pytest "packages/omnibias-core/tests/verified/test_complex_rootfind.py::test_parametric_linear_root_branch_is_certified" -q

Regression example · parametric square root branch contains dense and random truth

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_parametric_square_root_branch_contains_dense_and_random_truth() -> None:
    parameter = ComplexInterval(Interval(3.99, 4.01), Interval(-0.01, 0.01))
    domain = ComplexInterval(Interval(1.9, 2.1), Interval(-0.1, 0.1))
    result = parametric_complex_interval_newton(
        lambda value: value * value - parameter,
        lambda value: 2 * value,
        domain,
    )
    assert result.status == "unique_root"
    assert result.unique_for_every_parameter
    for value in _samples(parameter, seed=18002):
        assert result.enclosure.contains(cmath.sqrt(value))
        assert not result.enclosure.contains(-cmath.sqrt(value))

python -m pytest packages/omnibias-core/tests/verified/test_complex_rootfind.py -k test_parametric_square_root_branch_contains_dense_and_random_truth -q

Read the implementation

def parametric_complex_interval_newton(
    function: ComplexFn,
    derivative: ComplexFn,
    domain: ComplexInterval,
    *,
    max_iter: int = 20,
    tol: float = 1e-13,
) -> ComplexNewtonResult:
    """Prove a unique complex root branch over an implicit parameter box.

    ``function`` and ``derivative`` may close over interval parameters.  A
    ``unique_root`` result then applies separately to every parameter in that
    box, not merely to one representative value.
    """
    if type(max_iter) is not int or max_iter < 1:
        raise ValueError("max_iter must be a positive integer")
    if not 0.0 < tol < float("inf"):
        raise ValueError("tol must be finite and positive")
    current = domain
    unique = False
    for iteration in range(1, max_iter + 1):
        midpoint = complex(current.re.mid, current.im.mid)
        midpoint_box = ComplexInterval.point(midpoint)
        derivative_box = derivative(current)
        if derivative_box.modulus().lo <= 0.0:
            return ComplexNewtonResult(
                "derivative_contains_zero",
                current,
                iteration,
                False,
            )
        try:
            newton = midpoint_box - function(midpoint_box) / derivative_box
        except ZeroDivisionError:
            return ComplexNewtonResult(
                "derivative_contains_zero",
                current,
                iteration,
                False,
            )
        if _interior(newton, current):
            unique = True
        narrowed = _intersection(current, newton)
        if narrowed is None:
            return ComplexNewtonResult("no_root", newton, iteration, False)
        current = narrowed
        if unique and _width(current) <= tol:
            return ComplexNewtonResult("unique_root", current, iteration, True)
    return ComplexNewtonResult(
        "unique_root" if unique else "max_iter",
        current,
        max_iter,
        unique,
    )

Related APIsomnibias.core.verified.ComplexNewtonResult↗

Other public import paths

• omnibias.core.verified.parametric_complex_interval_newton
• omnibias.core.verified.complex_rootfind.parametric_complex_interval_newton

← Package overviewRunnable learning examples →