API REFERENCE/omnibias-core

omnibias.core.proof.discovery

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.proof.discovery

Module contract & mathematical conventions

Finite discovery loop: statement → family → proposer → exact checker → verdict.

This is **not** a second prove/disprove engine. ~omnibias.core.proof.ProofMachine still adjudicates. This module is the missing *proposer* layer over a named finite family. The checker is exact; a proposer only emits candidates.

A hit certifies the **finite obligation** in that family. A miss on an incomplete family is BLOCKED (search_incomplete), never a proof of the parent. Exhaustive miss is claimed only when the proposer iterator ended *and* (if the family reports cardinality) every member was evaluated. budget == 0 is always search_incomplete.

Statement.existential selects the verdict on a hit or an exhausted miss:

• existential + hit → PROVED (witness)
• existential + exhausted complete miss → BLOCKED (empty solution set in the box)
• universal + hit → DISPROVED (counterexample)
• universal + exhausted complete miss → PROVED of that finite universal

coordinate_newton is a discrete finite-difference walk, not CubicNewton. onehot_anneal is a 1-flip anneal on a discrete box, not omnibias-qubo.

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 →

External type aliases

These public names refer to external types. Their implementations and inherited members belong to the originating library.

Public name	External definition
omnibias.core.proof.discovery.Candidate	collections.abc.Hashable

CLASS

Characterization

omnibias.core.proof.CharacterizationSource ↗

class Characterization

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.

Box-scoped uniqueness. Never a parent-theorem claim.

Parameters

Name	Type & default	Contract
unique_in_familydataclass field	boolRequired	See the operation contract and implementation below.
family_completedataclass field	boolRequired	See the operation contract and implementation below.
exhausteddataclass field	boolRequired	See the operation contract and implementation below.
solution_countdataclass field	int | NoneDefault: None	See the operation contract and implementation below.
annihilatordataclass field	str | NoneDefault: None	See the operation contract and implementation below.
notedataclass field	strDefault: _BOX_SCOPED_NOTE	See the operation contract and implementation below.

Executed regression · as dict carries honesty

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_as_dict_carries_honesty() -> None:
    family = _toy()
    payload = run_discovery(family.statement, family, "score_guided", budget=8).as_dict()
    assert payload["kind"] == "finite_discovery"
    assert payload["replay_ok"] is True
    assert payload["characterization"]["note"].startswith("uniqueness is span/box-scoped")

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_as_dict_carries_honesty" -q

Fields & methods

unique_in_familyfield

unique_in_family: bool

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

View source ↗

family_completefield

family_complete: bool

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

View source ↗

exhaustedfield

exhausted: bool

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

View source ↗

solution_countfield

solution_count: int | None = None

Declared int | None field on Characterization. Default expression: None.

View source ↗

annihilatorfield

annihilator: str | None = None

Declared str | None field on Characterization. Default expression: None.

View source ↗

notefield

note: str = _BOX_SCOPED_NOTE

Declared str field on Characterization. Default expression: _BOX_SCOPED_NOTE.

View source ↗

as_dictmethod

as_dict(self) -> dict[str, Any]

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

Returns: dict[str, Any]

Executed regression · as dict carries honesty

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_as_dict_carries_honesty() -> None:
    family = _toy()
    payload = run_discovery(family.statement, family, "score_guided", budget=8).as_dict()
    assert payload["kind"] == "finite_discovery"
    assert payload["replay_ok"] is True
    assert payload["characterization"]["note"].startswith("uniqueness is span/box-scoped")

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_as_dict_carries_honesty" -q

Method implementation

    def as_dict(self) -> dict[str, Any]:
        return {
            "unique_in_family": self.unique_in_family,
            "family_complete": self.family_complete,
            "exhausted": self.exhausted,
            "solution_count": self.solution_count,
            "annihilator": self.annihilator,
            "note": self.note,
        }

View source ↗

Read the implementation

class Characterization:
    """Box-scoped uniqueness. Never a parent-theorem claim."""

    unique_in_family: bool
    family_complete: bool
    exhausted: bool
    solution_count: int | None = None
    annihilator: str | None = None
    note: str = _BOX_SCOPED_NOTE

    def as_dict(self) -> dict[str, Any]:
        return {
            "unique_in_family": self.unique_in_family,
            "family_complete": self.family_complete,
            "exhausted": self.exhausted,
            "solution_count": self.solution_count,
            "annihilator": self.annihilator,
            "note": self.note,
        }

Other public import paths

• omnibias.core.proof.Characterization
• omnibias.core.proof.discovery.Characterization

CLASS

CoordinateNewton

omnibias.core.proof.CoordinateNewtonSource ↗

class CoordinateNewton

Finite-difference step on integer coordinates, then snap.

Not omnibias.torch.optim.CubicNewton and not a closed-form Hessian.

Executed regression · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_optional_proposers_also_hit" -q

Fields & methods

proposemethod

propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]

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

Parameters

Name	Type & default	Contract
familypositional-or-keyword	FiniteFamilyRequired	See the operation contract and implementation below.
budgetpositional-or-keyword	intRequired	See the operation contract and implementation below.

Returns: Iterator[Candidate]

Executed regression · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_optional_proposers_also_hit" -q

Method implementation

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        current = family.origin()
        seen: set[Candidate] = set()
        yielded = 0
        while yielded < budget:
            if current not in seen:
                seen.add(current)
                yield current
                yielded += 1
                if yielded >= budget:
                    return
            nxt = _newton_step(family, current)
            if nxt is None or nxt == current or nxt in seen:
                nxt = _best_unseen_neighbor(family, current, seen)
            if nxt is None:
                return
            current = nxt

View source ↗

Read the implementation

class CoordinateNewton:
    """Finite-difference step on integer coordinates, then snap.

    Not :class:`omnibias.torch.optim.CubicNewton` and not a closed-form Hessian.
    """

    name = "coordinate_newton"

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        current = family.origin()
        seen: set[Candidate] = set()
        yielded = 0
        while yielded < budget:
            if current not in seen:
                seen.add(current)
                yield current
                yielded += 1
                if yielded >= budget:
                    return
            nxt = _newton_step(family, current)
            if nxt is None or nxt == current or nxt in seen:
                nxt = _best_unseen_neighbor(family, current, seen)
            if nxt is None:
                return
            current = nxt

Other public import paths

• omnibias.core.proof.CoordinateNewton
• omnibias.core.proof.discovery.CoordinateNewton

CLASS

DiscoveredEquation

omnibias.core.proof.DiscoveredEquationSource ↗

class DiscoveredEquation

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.

An equation-valued witness. Coefficients are JSON-able fraction strings.

Parameters

Name	Type & default	Contract
kinddataclass field	EquationKindRequired	See the operation contract and implementation below.
prettydataclass field	strRequired	See the operation contract and implementation below.
coefficientsdataclass field	tuple[str, ...]Default: ()	See the operation contract and implementation below.

Fields & methods

kindfield

kind: EquationKind

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

View source ↗

prettyfield

pretty: str

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

View source ↗

coefficientsfield

coefficients: tuple[str, ...] = ()

Declared tuple[str, ...] field on DiscoveredEquation. Default expression: ().

View source ↗

as_dictmethod

as_dict(self) -> dict[str, Any]

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

Returns: dict[str, Any]

Method implementation

    def as_dict(self) -> dict[str, Any]:
        return {
            "kind": self.kind,
            "pretty": self.pretty,
            "coefficients": list(self.coefficients),
        }

View source ↗

Read the implementation

class DiscoveredEquation:
    """An equation-valued witness. Coefficients are JSON-able fraction strings."""

    kind: EquationKind
    pretty: str
    coefficients: tuple[str, ...] = ()

    def as_dict(self) -> dict[str, Any]:
        return {
            "kind": self.kind,
            "pretty": self.pretty,
            "coefficients": list(self.coefficients),
        }

Other public import paths

• omnibias.core.proof.DiscoveredEquation
• omnibias.core.proof.discovery.DiscoveredEquation

CLASS

DiscoveryResult

omnibias.core.proof.DiscoveryResultSource ↗

class DiscoveryResult

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 run_discovery (finite obligation only).

Parameters

Name	Type & default	Contract
statusdataclass field	DiscoveryStatusRequired	See the operation contract and implementation below.
statementdataclass field	StatementRequired	See the operation contract and implementation below.
familydataclass field	strRequired	See the operation contract and implementation below.
proposerdataclass field	strRequired	See the operation contract and implementation below.
budgetdataclass field	intRequired	See the operation contract and implementation below.
evaluateddataclass field	intRequired	See the operation contract and implementation below.
candidatedataclass field	Candidate | NoneRequired	See the operation contract and implementation below.
checkdataclass field	ExactCheck | NoneRequired	See the operation contract and implementation below.
detaildataclass field	strRequired	See the operation contract and implementation below.
search_incompletedataclass field	boolDefault: False	See the operation contract and implementation below.
characterizationdataclass field	Characterization | NoneDefault: None	See the operation contract and implementation below.
equationdataclass field	DiscoveredEquation | NoneDefault: None	See the operation contract and implementation below.
solutionsdataclass field	tuple[Candidate, ...]Default: ()	See the operation contract and implementation below.

Executed regression · as dict carries honesty

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_as_dict_carries_honesty() -> None:
    family = _toy()
    payload = run_discovery(family.statement, family, "score_guided", budget=8).as_dict()
    assert payload["kind"] == "finite_discovery"
    assert payload["replay_ok"] is True
    assert payload["characterization"]["note"].startswith("uniqueness is span/box-scoped")

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_as_dict_carries_honesty" -q

Fields & methods

statusfield

status: DiscoveryStatus

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

View source ↗

statementfield

statement: Statement

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

View source ↗

familyfield

family: str

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

View source ↗

proposerfield

proposer: str

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

View source ↗

budgetfield

budget: int

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

View source ↗

evaluatedfield

evaluated: int

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

View source ↗

candidatefield

candidate: Candidate | None

Declared Candidate | None field on DiscoveryResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

checkfield

check: ExactCheck | None

Declared ExactCheck | None field on DiscoveryResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

detailfield

detail: str

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

View source ↗

search_incompletefield

search_incomplete: bool = False

Declared bool field on DiscoveryResult. Default expression: False.

View source ↗

characterizationfield

characterization: Characterization | None = None

Declared Characterization | None field on DiscoveryResult. Default expression: None.

View source ↗

equationfield

equation: DiscoveredEquation | None = None

Declared DiscoveredEquation | None field on DiscoveryResult. Default expression: None.

View source ↗

solutionsfield

solutions: tuple[Candidate, ...] = ()

Declared tuple[Candidate, ...] field on DiscoveryResult. Default expression: ().

View source ↗

as_dictmethod

as_dict(self) -> dict[str, Any]

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

Returns: dict[str, Any]

Executed regression · as dict carries honesty

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_as_dict_carries_honesty() -> None:
    family = _toy()
    payload = run_discovery(family.statement, family, "score_guided", budget=8).as_dict()
    assert payload["kind"] == "finite_discovery"
    assert payload["replay_ok"] is True
    assert payload["characterization"]["note"].startswith("uniqueness is span/box-scoped")

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_as_dict_carries_honesty" -q

Method implementation

    def as_dict(self) -> dict[str, Any]:
        payload = dict(self.check.payload) if self.check is not None else {}
        honesty = payload.get("honesty", {})
        equation = self.equation.as_dict() if self.equation is not None else None
        characterization = (
            self.characterization.as_dict() if self.characterization is not None else None
        )
        return {
            "kind": "finite_discovery",
            "status": self.status,
            "statement": self.statement.name,
            "obligation": self.statement.obligation,
            "parent": self.statement.parent,
            "parent_status": self.statement.parent_status,
            "existential": self.statement.existential,
            "family": self.family,
            "proposer": self.proposer,
            "budget": self.budget,
            "evaluated": self.evaluated,
            "candidate": _candidate_json(self.candidate),
            "solutions": [_candidate_json(item) for item in self.solutions],
            "search_incomplete": self.search_incomplete,
            "replay_ok": self.status in ("PROVED", "DISPROVED"),
            "detail": self.detail,
            "honesty": dict(honesty) if isinstance(honesty, Mapping) else {},
            "payload": payload,
            "equation": equation,
            "characterization": characterization,
        }

View source ↗

Read the implementation

class DiscoveryResult:
    """Outcome of :func:`run_discovery` (finite obligation only)."""

    status: DiscoveryStatus
    statement: Statement
    family: str
    proposer: str
    budget: int
    evaluated: int
    candidate: Candidate | None
    check: ExactCheck | None
    detail: str
    search_incomplete: bool = False
    characterization: Characterization | None = None
    equation: DiscoveredEquation | None = None
    solutions: tuple[Candidate, ...] = ()

    def as_dict(self) -> dict[str, Any]:
        payload = dict(self.check.payload) if self.check is not None else {}
        honesty = payload.get("honesty", {})
        equation = self.equation.as_dict() if self.equation is not None else None
        characterization = (
            self.characterization.as_dict() if self.characterization is not None else None
        )
        return {
            "kind": "finite_discovery",
            "status": self.status,
            "statement": self.statement.name,
            "obligation": self.statement.obligation,
            "parent": self.statement.parent,
            "parent_status": self.statement.parent_status,
            "existential": self.statement.existential,
            "family": self.family,
            "proposer": self.proposer,
            "budget": self.budget,
            "evaluated": self.evaluated,
            "candidate": _candidate_json(self.candidate),
            "solutions": [_candidate_json(item) for item in self.solutions],
            "search_incomplete": self.search_incomplete,
            "replay_ok": self.status in ("PROVED", "DISPROVED"),
            "detail": self.detail,
            "honesty": dict(honesty) if isinstance(honesty, Mapping) else {},
            "payload": payload,
            "equation": equation,
            "characterization": characterization,
        }

Other public import paths

• omnibias.core.proof.DiscoveryResult
• omnibias.core.proof.discovery.DiscoveryResult

CONSTANT

DiscoveryStatus

omnibias.core.proof.discovery.DiscoveryStatusSource ↗

DiscoveryStatus = Literal['PROVED', 'DISPROVED', 'BLOCKED']

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

DiscoveryStatus = Literal["PROVED", "DISPROVED", "BLOCKED"]

CONSTANT

EquationKind

omnibias.core.proof.discovery.EquationKindSource ↗

EquationKind = Literal['recurrence', 'ore', 'polynomial_identity', 'pde_span', 'map_witness', 'graph_witness', 'conservation', 'sos_template', 'forbidden_minor']

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

EquationKind = Literal[
    "recurrence",
    "ore",
    "polynomial_identity",
    "pde_span",
    "map_witness",
    "graph_witness",
    "conservation",
    "sos_template",
    "forbidden_minor",
]

CLASS

ExactCheck

omnibias.core.proof.ExactCheckSource ↗

class ExactCheck

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.

Result of an exact family checker. payload must carry honesty.

Parameters

Name	Type & default	Contract
okdataclass field	boolRequired	See the operation contract and implementation below.
payloaddataclass field	dict[str, Any]Required	See the operation contract and implementation below.

Regression example · rank two exact by token count

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_rank_two_exact_by_token_count() -> None:
    fat = ClassHit(
        sort="ore",
        check=ExactCheck(ok=True, payload={"tier": "exact"}),
        tier="exact",
        tokens=5,
        degree=0,
    )
    thin = ClassHit(
        sort="jet_monomial",
        check=ExactCheck(ok=True, payload={"tier": "exact"}),
        tier="exact",
        tokens=2,
        degree=4,
    )
    ranked = rank_class_hits([fat, thin])
    assert ranked[0].sort == "jet_monomial"
    assert ranked[0].tokens == 2

python -m pytest packages/omnibias-core/tests/test_observe.py -k test_rank_two_exact_by_token_count -q

Regression example · rank exact beats empirical

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_rank_exact_beats_empirical() -> None:
    exact = ClassHit(
        sort="jet_monomial",
        check=ExactCheck(ok=True, payload={"tier": "exact", "honesty": {}}),
        tier="exact",
        tokens=3,
        degree=2,
    )
    empirical = ClassHit(
        sort="pde_operator",
        check=ExactCheck(ok=False, payload={"mode": "empirical"}),
        tier="empirical",
        tokens=1,
        degree=0,
        rmse="0.001",
    )
    ranked = rank_class_hits([empirical, exact])
    assert ranked[0].sort == "jet_monomial"
    assert all(hit.tier != "empirical" for hit in ranked)

python -m pytest packages/omnibias-core/tests/test_observe.py -k test_rank_exact_beats_empirical -q

Fields & methods

okfield

ok: bool

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

View source ↗

payloadfield

payload: dict[str, Any]

Declared dict[str, Any] field on ExactCheck. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

Read the implementation

class ExactCheck:
    """Result of an exact family checker. ``payload`` must carry ``honesty``."""

    ok: bool
    payload: dict[str, Any]

Other public import paths

• omnibias.core.proof.ExactCheck
• omnibias.core.proof.discovery.ExactCheck

CLASS

FiniteFamily

omnibias.core.proof.FiniteFamilySource ↗

class FiniteFamily(Protocol)

A named, bounded search space with an exact witness predicate.

Fields & methods

namefield

name: str

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

View source ↗

completefield

complete: bool

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

View source ↗

statementfield

statement: Statement

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

View source ↗

originmethod

origin(self) -> Candidate

A seed candidate (need not be a witness).

Returns: Candidate

Method implementation

    def origin(self) -> Candidate:
        """A seed candidate (need not be a witness)."""
        ...

View source ↗

neighborsmethod

neighbors(self, candidate: Candidate) -> Sequence[Candidate]

Adjacent candidates in the discrete family.

Parameters

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

Returns: Sequence[Candidate]

Method implementation

    def neighbors(self, candidate: Candidate) -> Sequence[Candidate]:
        """Adjacent candidates in the discrete family."""
        ...

View source ↗

scoremethod

score(self, candidate: Candidate) -> Fraction | int

Heuristic only. The accept gate is check.

Parameters

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

Returns: Fraction | int

Method implementation

    def score(self, candidate: Candidate) -> Fraction | int:
        """Heuristic only. The accept gate is :meth:`check`."""
        ...

View source ↗

checkmethod

check(self, candidate: Candidate) -> ExactCheck | None

Exact witness test, or None if the candidate is ill-formed.

Parameters

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

Returns: ExactCheck | None

Method implementation

    def check(self, candidate: Candidate) -> ExactCheck | None:
        """Exact witness test, or ``None`` if the candidate is ill-formed."""
        ...

View source ↗

cardinalitymethod

cardinality(self) -> int | None

Known finite size, or None if unknown. Optional on implementations.

Returns: int | None

Method implementation

    def cardinality(self) -> int | None:
        """Known finite size, or ``None`` if unknown. Optional on implementations."""
        ...

View source ↗

Read the implementation

class FiniteFamily(Protocol):
    """A named, bounded search space with an exact witness predicate."""

    name: str
    complete: bool
    statement: Statement

    def origin(self) -> Candidate:
        """A seed candidate (need not be a witness)."""
        ...

    def neighbors(self, candidate: Candidate) -> Sequence[Candidate]:
        """Adjacent candidates in the discrete family."""
        ...

    def score(self, candidate: Candidate) -> Fraction | int:
        """Heuristic only. The accept gate is :meth:`check`."""
        ...

    def check(self, candidate: Candidate) -> ExactCheck | None:
        """Exact witness test, or ``None`` if the candidate is ill-formed."""
        ...

    def cardinality(self) -> int | None:
        """Known finite size, or ``None`` if unknown. Optional on implementations."""
        ...

Other public import paths

• omnibias.core.proof.FiniteFamily
• omnibias.core.proof.discovery.FiniteFamily

CLASS

IntegerIntervalFamily

omnibias.core.proof.IntegerIntervalFamilySource ↗

class IntegerIntervalFamily

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.

Toy 1-D family used by core tests and the discovery cookbook.

Parameters

Name	Type & default	Contract
lodataclass field	intRequired	See the operation contract and implementation below.
hidataclass field	intRequired	See the operation contract and implementation below.
target_squaredataclass field	intDefault: 4	See the operation contract and implementation below.
namedataclass field	strDefault: 'integer_square'	See the operation contract and implementation below.
completedataclass field	boolDefault: True	See the operation contract and implementation below.
statementdataclass field	StatementDefault: field(default_factory=lambda: Statement(name='exists_square', obligation='some integer x in the interval with x^2 equal to the target', parent='toy', parent_status='already_true'))	See the operation contract and implementation below.

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Regression example · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_optional_proposers_also_hit -q

Fields & methods

lofield

lo: int

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

View source ↗

hifield

hi: int

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

View source ↗

target_squarefield

target_square: int = 4

Declared int field on IntegerIntervalFamily. Default expression: 4.

View source ↗

namefield

name: str = 'integer_square'

Declared str field on IntegerIntervalFamily. Default expression: 'integer_square'.

View source ↗

completefield

complete: bool = True

Declared bool field on IntegerIntervalFamily. Default expression: True.

Regression example · incomplete family miss is blocked

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_incomplete_family_miss_is_blocked() -> None:
    family = IntegerIntervalFamily(lo=-1, hi=1, target_square=4)
    family.complete = False
    family.statement = Statement(
        name="exists_square_incomplete",
        obligation="some integer x with x^2 = 4",
        parent="toy",
        parent_status="open",
    )
    result = run_discovery(family.statement, family, "score_guided", budget=8)
    assert result.status == "BLOCKED"
    assert result.search_incomplete is True
    assert result.detail == "search_incomplete"
    assert result.statement.parent_status == "open"

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_incomplete_family_miss_is_blocked -q

View source ↗

statementfield

statement: Statement = field(default_factory=lambda: Statement(name='exists_square', obligation='some integer x in the interval with x^2 equal to the target', parent='toy', parent_status='already_true'))

Declared Statement field on IntegerIntervalFamily. Default expression: field(default_factory=lambda: Statement(name='exists_square', obligation='some integer x in the interval with x^2 equal to the target', parent='toy', parent_status='already_true')).

Regression example · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_optional_proposers_also_hit -q

View source ↗

cardinalitymethod

cardinality(self) -> int

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

Returns: int

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def cardinality(self) -> int:
        return max(0, self.hi - self.lo + 1)

View source ↗

originmethod

origin(self) -> int

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

Returns: int

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def origin(self) -> int:
        return 0 if self.lo <= 0 <= self.hi else self.lo

View source ↗

neighborsmethod

neighbors(self, candidate: Candidate) -> Sequence[int]

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

Parameters

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

Returns: Sequence[int]

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def neighbors(self, candidate: Candidate) -> Sequence[int]:
        if not isinstance(candidate, int):
            return ()
        out: list[int] = []
        if candidate - 1 >= self.lo:
            out.append(candidate - 1)
        if candidate + 1 <= self.hi:
            out.append(candidate + 1)
        return out

View source ↗

scoremethod

score(self, candidate: Candidate) -> int

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

Parameters

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

Returns: int

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def score(self, candidate: Candidate) -> int:
        if not isinstance(candidate, int):
            return 0
        return -abs(candidate * candidate - self.target_square)

View source ↗

checkmethod

check(self, candidate: Candidate) -> ExactCheck | None

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

Parameters

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

Returns: ExactCheck | None

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def check(self, candidate: Candidate) -> ExactCheck | None:
        if not isinstance(candidate, int):
            return None
        value = candidate
        if not self.lo <= value <= self.hi:
            return None
        ok = value * value == self.target_square
        return ExactCheck(
            ok=ok,
            payload={
                "x": value,
                "honesty": {
                    "discovered_by_omnibias": ok,
                },
            },
        )

View source ↗

Read the implementation

class IntegerIntervalFamily:
    """Toy 1-D family used by core tests and the discovery cookbook."""

    lo: int
    hi: int
    target_square: int = 4
    name: str = "integer_square"
    complete: bool = True
    statement: Statement = field(
        default_factory=lambda: Statement(
            name="exists_square",
            obligation="some integer x in the interval with x^2 equal to the target",
            parent="toy",
            parent_status="already_true",
        )
    )

    def cardinality(self) -> int:
        return max(0, self.hi - self.lo + 1)

    def origin(self) -> int:
        return 0 if self.lo <= 0 <= self.hi else self.lo

    def neighbors(self, candidate: Candidate) -> Sequence[int]:
        if not isinstance(candidate, int):
            return ()
        out: list[int] = []
        if candidate - 1 >= self.lo:
            out.append(candidate - 1)
        if candidate + 1 <= self.hi:
            out.append(candidate + 1)
        return out

    def score(self, candidate: Candidate) -> int:
        if not isinstance(candidate, int):
            return 0
        return -abs(candidate * candidate - self.target_square)

    def check(self, candidate: Candidate) -> ExactCheck | None:
        if not isinstance(candidate, int):
            return None
        value = candidate
        if not self.lo <= value <= self.hi:
            return None
        ok = value * value == self.target_square
        return ExactCheck(
            ok=ok,
            payload={
                "x": value,
                "honesty": {
                    "discovered_by_omnibias": ok,
                },
            },
        )

Related APIsomnibias.core.proof.ExactCheck↗omnibias.core.proof.Statement↗

Other public import paths

• omnibias.core.proof.IntegerIntervalFamily
• omnibias.core.proof.discovery.IntegerIntervalFamily

CLASS

OneHotAnneal

omnibias.core.proof.OneHotAnnealSource ↗

class OneHotAnneal

1-flip Metropolis walk on the discrete box (QUBO-shaped; no omnibias-qubo).

Parameters

Name	Type & default	Contract
seedkeyword-only	intDefault: 0	See the operation contract and implementation below.
temperaturekeyword-only	Fraction | intDefault: 1	See the operation contract and implementation below.

Executed regression · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_optional_proposers_also_hit" -q

Fields & methods

__init__method

__init__(self, *, seed: int=0, temperature: Fraction | int=1) -> None

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

Parameters

Name	Type & default	Contract
seedkeyword-only	intDefault: 0	See the operation contract and implementation below.
temperaturekeyword-only	Fraction | intDefault: 1	See the operation contract and implementation below.

Returns: None

Executed regression · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_optional_proposers_also_hit" -q

Method implementation

    def __init__(self, *, seed: int = 0, temperature: Fraction | int = 1) -> None:
        self.seed = seed
        self.temperature = (
            temperature if isinstance(temperature, Fraction) else Fraction(temperature)
        )

View source ↗

proposemethod

propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]

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

Parameters

Name	Type & default	Contract
familypositional-or-keyword	FiniteFamilyRequired	See the operation contract and implementation below.
budgetpositional-or-keyword	intRequired	See the operation contract and implementation below.

Returns: Iterator[Candidate]

Executed regression · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_optional_proposers_also_hit" -q

Method implementation

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        rng = _LCG(self.seed)
        current = family.origin()
        seen: set[Candidate] = set()
        yielded = 0
        temp = self.temperature if self.temperature > 0 else Fraction(1)
        while yielded < budget:
            if current not in seen:
                seen.add(current)
                yield current
                yielded += 1
                if yielded >= budget:
                    return
            nbrs = [n for n in family.neighbors(current) if n not in seen] or list(
                family.neighbors(current)
            )
            if not nbrs:
                return
            nxt = nbrs[rng.next() % len(nbrs)]
            delta = _score(family, nxt) - _score(family, current)
            # Metropolis on energy = -score: accept if score improves or by chance.
            if delta >= 0 or _accept(rng, delta, temp):
                current = nxt
            elif nxt not in seen:
                current = nxt

View source ↗

seedattribute

seed: int = seed

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

View source ↗

temperatureattribute

temperature = temperature if isinstance(temperature, Fraction) else Fraction(temperature)

Public instance attribute assigned by __init__. The source assignment is temperature = temperature if isinstance(temperature, Fraction) else Fraction(temperature); it describes instance state, not a literal constructor default.

View source ↗

Read the implementation

class OneHotAnneal:
    """1-flip Metropolis walk on the discrete box (QUBO-shaped; no ``omnibias-qubo``)."""

    name = "onehot_anneal"

    def __init__(self, *, seed: int = 0, temperature: Fraction | int = 1) -> None:
        self.seed = seed
        self.temperature = (
            temperature if isinstance(temperature, Fraction) else Fraction(temperature)
        )

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        rng = _LCG(self.seed)
        current = family.origin()
        seen: set[Candidate] = set()
        yielded = 0
        temp = self.temperature if self.temperature > 0 else Fraction(1)
        while yielded < budget:
            if current not in seen:
                seen.add(current)
                yield current
                yielded += 1
                if yielded >= budget:
                    return
            nbrs = [n for n in family.neighbors(current) if n not in seen] or list(
                family.neighbors(current)
            )
            if not nbrs:
                return
            nxt = nbrs[rng.next() % len(nbrs)]
            delta = _score(family, nxt) - _score(family, current)
            # Metropolis on energy = -score: accept if score improves or by chance.
            if delta >= 0 or _accept(rng, delta, temp):
                current = nxt
            elif nxt not in seen:
                current = nxt

Other public import paths

• omnibias.core.proof.OneHotAnneal
• omnibias.core.proof.discovery.OneHotAnneal

CONSTANT

ParentStatus

omnibias.core.proof.discovery.ParentStatusSource ↗

ParentStatus = Literal['already_false', 'already_true', 'open']

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

ParentStatus = Literal["already_false", "already_true", "open"]

CLASS

Proposer

omnibias.core.proof.discovery.ProposerSource ↗

class Proposer(Protocol)

Emits at most budget candidates from a family.

Fields & methods

namefield

name: str

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

View source ↗

proposemethod

propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]

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

Parameters

Name	Type & default	Contract
familypositional-or-keyword	FiniteFamilyRequired	See the operation contract and implementation below.
budgetpositional-or-keyword	intRequired	See the operation contract and implementation below.

Returns: Iterator[Candidate]

Method implementation

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]: ...

View source ↗

Read the implementation

class Proposer(Protocol):
    """Emits at most ``budget`` candidates from a family."""

    name: str

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]: ...

CONSTANT

ProposerName

omnibias.core.proof.discovery.ProposerNameSource ↗

ProposerName = Literal['score_guided', 'coordinate_newton', 'onehot_anneal']

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

ProposerName = Literal["score_guided", "coordinate_newton", "onehot_anneal"]

CLASS

ScoreGuidedWalk

omnibias.core.proof.ScoreGuidedWalkSource ↗

class ScoreGuidedWalk

Walk neighbors in nonincreasing score order (CI default proposer).

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Fields & methods

proposemethod

propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]

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

Parameters

Name	Type & default	Contract
familypositional-or-keyword	FiniteFamilyRequired	See the operation contract and implementation below.
budgetpositional-or-keyword	intRequired	See the operation contract and implementation below.

Returns: Iterator[Candidate]

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Method implementation

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        start = family.origin()
        seen: set[Candidate] = {start}
        queue: list[tuple[Fraction, int, Candidate]] = [(-_score(family, start), 0, start)]
        tie = 1
        yielded = 0
        while queue and yielded < budget:
            queue.sort(key=lambda item: (item[0], item[1]))
            _neg, _t, current = queue.pop(0)
            yield current
            yielded += 1
            if yielded >= budget:
                return
            ranked = sorted(
                family.neighbors(current),
                key=lambda cand: _score(family, cand),
                reverse=True,
            )
            for nbr in ranked:
                if nbr in seen:
                    continue
                seen.add(nbr)
                queue.append((-_score(family, nbr), tie, nbr))
                tie += 1

View source ↗

Read the implementation

class ScoreGuidedWalk:
    """Walk neighbors in nonincreasing score order (CI default proposer)."""

    name = "score_guided"

    def propose(self, family: FiniteFamily, budget: int) -> Iterator[Candidate]:
        if budget <= 0:
            return
        start = family.origin()
        seen: set[Candidate] = {start}
        queue: list[tuple[Fraction, int, Candidate]] = [(-_score(family, start), 0, start)]
        tie = 1
        yielded = 0
        while queue and yielded < budget:
            queue.sort(key=lambda item: (item[0], item[1]))
            _neg, _t, current = queue.pop(0)
            yield current
            yielded += 1
            if yielded >= budget:
                return
            ranked = sorted(
                family.neighbors(current),
                key=lambda cand: _score(family, cand),
                reverse=True,
            )
            for nbr in ranked:
                if nbr in seen:
                    continue
                seen.add(nbr)
                queue.append((-_score(family, nbr), tie, nbr))
                tie += 1

Other public import paths

• omnibias.core.proof.ScoreGuidedWalk
• omnibias.core.proof.discovery.ScoreGuidedWalk

CLASS

Statement

omnibias.core.proof.StatementSource ↗

class Statement

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.

A finite obligation, never an implicit parent claim.

Parameters

Name	Type & default	Contract
namedataclass field	strRequired	See the operation contract and implementation below.
obligationdataclass field	strRequired	See the operation contract and implementation below.
parentdataclass field	strRequired	See the operation contract and implementation below.
parent_statusdataclass field	ParentStatusRequired	See the operation contract and implementation below.
existentialdataclass field	boolDefault: True	See the operation contract and implementation below.

Regression example · universal hit is disproved

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_universal_hit_is_disproved() -> None:
    family = _toy()
    family.statement = Statement(
        name="no_square_false",
        obligation="every integer x in the interval has x^2 not equal to the target",
        parent="toy",
        parent_status="already_false",
        existential=False,
    )
    result = run_discovery(family.statement, family, "score_guided", budget=8)
    assert result.status == "DISPROVED"
    assert result.candidate in (-2, 2)
    assert result.detail == "counterexample to universal obligation"

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_universal_hit_is_disproved -q

Regression example · incomplete family miss is blocked

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_incomplete_family_miss_is_blocked() -> None:
    family = IntegerIntervalFamily(lo=-1, hi=1, target_square=4)
    family.complete = False
    family.statement = Statement(
        name="exists_square_incomplete",
        obligation="some integer x with x^2 = 4",
        parent="toy",
        parent_status="open",
    )
    result = run_discovery(family.statement, family, "score_guided", budget=8)
    assert result.status == "BLOCKED"
    assert result.search_incomplete is True
    assert result.detail == "search_incomplete"
    assert result.statement.parent_status == "open"

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_incomplete_family_miss_is_blocked -q

Fields & methods

namefield

name: str

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

View source ↗

obligationfield

obligation: str

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

View source ↗

parentfield

parent: str

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

View source ↗

parent_statusfield

parent_status: ParentStatus

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

View source ↗

existentialfield

existential: bool = True

Declared bool field on Statement. Default expression: True.

View source ↗

Read the implementation

class Statement:
    """A finite obligation, never an implicit parent claim."""

    name: str
    obligation: str
    parent: str
    parent_status: ParentStatus
    existential: bool = True

Other public import paths

• omnibias.core.proof.Statement
• omnibias.core.proof.discovery.Statement

FUNCTION

get_proposer

omnibias.core.proof.get_proposerSource ↗

get_proposer(name: ProposerName | str, **kwargs: Any) -> Proposer

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
namepositional-or-keyword	ProposerName | strRequired	See the operation contract and implementation below.
kwargsvariadic keyword	AnyRequired	See the operation contract and implementation below.

ReturnsProposer

Executed regression · get proposer rejects unknown

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_get_proposer_rejects_unknown() -> None:
    try:
        get_proposer("cubic_newton")
    except ValueError as exc:
        assert "unknown proposer" in str(exc)
    else:
        raise AssertionError("expected ValueError")

python -m pytest "packages/omnibias-core/tests/test_discovery.py::test_get_proposer_rejects_unknown" -q

Regression example · core get proposer still rejects anneal descent

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_core_get_proposer_still_rejects_anneal_descent() -> None:
    try:
        get_proposer("anneal_descent")
    except ValueError as exc:
        assert "unknown proposer" in str(exc)
    else:
        raise AssertionError("expected ValueError")

python -m pytest packages/omnibias-discrete/tests/test_proposers.py -k test_core_get_proposer_still_rejects_anneal_descent -q

Read the implementation

def get_proposer(name: ProposerName | str, **kwargs: Any) -> Proposer:
    if name == "score_guided":
        return ScoreGuidedWalk()
    if name == "coordinate_newton":
        return CoordinateNewton()
    if name == "onehot_anneal":
        return OneHotAnneal(
            seed=int(kwargs.get("seed", 0)),
            temperature=kwargs.get("temperature", 1),
        )
    raise ValueError(f"unknown proposer {name!r}")

Related APIsomnibias.core.proof.CoordinateNewton↗omnibias.core.proof.OneHotAnneal↗omnibias.core.proof.ScoreGuidedWalk↗

Other public import paths

• omnibias.core.proof.get_proposer
• omnibias.core.proof.discovery.get_proposer

FUNCTION

run_discovery

omnibias.core.proof.run_discoverySource ↗

run_discovery(statement: Statement, family: FiniteFamily, proposer: Proposer | ProposerName | str='score_guided', *, budget: int=64, collect: bool=False) -> DiscoveryResult

Propose up to budget candidates; accept the first exact hit unless collect.

Parameters

Name	Type & default	Contract
statementpositional-or-keyword	StatementRequired	See the operation contract and implementation below.
familypositional-or-keyword	FiniteFamilyRequired	See the operation contract and implementation below.
proposerpositional-or-keyword	Proposer | ProposerName | strDefault: 'score_guided'	See the operation contract and implementation below.
budgetkeyword-only	intDefault: 64	See the operation contract and implementation below.
collectkeyword-only	boolDefault: False	See the operation contract and implementation below.

ReturnsDiscoveryResult

Explicit validation & failure cases

• When budget < 0, raises ValueError('budget must be >= 0').

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

Executed regression · register and discover toy

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_register_and_discover_toy() -> None:
    register_catalog(_toy_entry(), _toy_factory)
    kinds = {item.kind for item in list_catalog()}
    assert "integer_square_toy" in kinds
    result = discover("integer_square_toy")
    assert result.status == "PROVED"
    assert result.candidate in (-2, 2)

python -m pytest "packages/omnibias-core/tests/test_catalog.py::test_register_and_discover_toy" -q

Regression example · optional proposers also hit

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_optional_proposers_also_hit() -> None:
    family = _toy()
    for name in ("coordinate_newton", "onehot_anneal"):
        result = run_discovery(family.statement, family, name, budget=16)
        assert result.status == "PROVED", name
        assert result.candidate in (-2, 2)
        assert result.proposer == name

python -m pytest packages/omnibias-core/tests/test_discovery.py -k test_optional_proposers_also_hit -q

Read the implementation

def run_discovery(
    statement: Statement,
    family: FiniteFamily,
    proposer: Proposer | ProposerName | str = "score_guided",
    *,
    budget: int = 64,
    collect: bool = False,
) -> DiscoveryResult:
    """Propose up to ``budget`` candidates; accept the first exact hit unless ``collect``."""
    walker = get_proposer(proposer) if isinstance(proposer, str) else proposer
    evaluated = 0
    last: Candidate | None = None
    last_check: ExactCheck | None = None
    hits: list[tuple[Candidate, ExactCheck]] = []
    if budget < 0:
        raise ValueError("budget must be >= 0")
    for candidate in walker.propose(family, budget):
        evaluated += 1
        last = candidate
        checked = family.check(candidate)
        last_check = checked
        if checked is not None and checked.ok:
            hits.append((candidate, checked))
            if not collect:
                break
    stopped_for_hit = bool(hits) and not collect
    cardinality = _family_cardinality(family)
    exhausted = _proposer_exhausted(
        budget=budget,
        evaluated=evaluated,
        cardinality=cardinality,
        stopped_for_hit=stopped_for_hit,
    )
    truly_exhausted = exhausted and family.complete
    first_check = hits[0][1] if hits else last_check
    equation = _equation_from_check(hits[0][1] if hits else None)
    annihilator = _annihilator_from_check(hits[0][1] if hits else None)
    solutions = tuple(item[0] for item in hits)
    if hits:
        unique = truly_exhausted and len(hits) == 1
        characterization = Characterization(
            unique_in_family=unique,
            family_complete=family.complete,
            exhausted=truly_exhausted,
            solution_count=len(hits) if collect or truly_exhausted else None,
            annihilator=annihilator,
        )
        if statement.existential:
            return DiscoveryResult(
                status="PROVED",
                statement=statement,
                family=family.name,
                proposer=walker.name,
                budget=budget,
                evaluated=evaluated,
                candidate=hits[0][0],
                check=hits[0][1],
                detail="exact witness in family",
                search_incomplete=False,
                characterization=characterization,
                equation=equation,
                solutions=solutions,
            )
        return DiscoveryResult(
            status="DISPROVED",
            statement=statement,
            family=family.name,
            proposer=walker.name,
            budget=budget,
            evaluated=evaluated,
            candidate=hits[0][0],
            check=hits[0][1],
            detail="counterexample to universal obligation",
            search_incomplete=False,
            characterization=characterization,
            equation=equation,
            solutions=solutions,
        )
    if not truly_exhausted:
        characterization = Characterization(
            unique_in_family=False,
            family_complete=family.complete,
            exhausted=False,
            solution_count=None,
            annihilator=None,
        )
        return DiscoveryResult(
            status="BLOCKED",
            statement=statement,
            family=family.name,
            proposer=walker.name,
            budget=budget,
            evaluated=evaluated,
            candidate=last,
            check=first_check if first_check is not None and not first_check.ok else None,
            detail="search_incomplete",
            search_incomplete=True,
            characterization=characterization,
            equation=None,
            solutions=(),
        )
    characterization = Characterization(
        unique_in_family=False,
        family_complete=True,
        exhausted=True,
        solution_count=0,
        annihilator=None,
    )
    if statement.existential:
        miss_detail = getattr(family, "empty_miss_detail", None)
        if not isinstance(miss_detail, str) or not miss_detail:
            miss_detail = "no witness in enumerated family"
        return DiscoveryResult(
            status="BLOCKED",
            statement=statement,
            family=family.name,
            proposer=walker.name,
            budget=budget,
            evaluated=evaluated,
            candidate=last,
            check=None,
            detail=miss_detail,
            search_incomplete=False,
            characterization=characterization,
            equation=None,
            solutions=(),
        )
    return DiscoveryResult(
        status="PROVED",
        statement=statement,
        family=family.name,
        proposer=walker.name,
        budget=budget,
        evaluated=evaluated,
        candidate=last,
        check=None,
        detail="no counterexample in complete family",
        search_incomplete=False,
        characterization=characterization,
        equation=None,
        solutions=(),
    )

Related APIsomnibias.core.proof.Characterization↗omnibias.core.proof.DiscoveryResult↗omnibias.core.proof.get_proposer↗

Other public import paths

• omnibias.core.proof.run_discovery
• omnibias.core.proof.discovery.run_discovery

← Package overviewRunnable learning examples →