ZeroProofML

What is ZeroProofML?

ZeroProofML is a Python library for Signed Common Meadow (SCM) arithmetic and PyTorch rational models. It lets scientific and ML code represent division by zero as an explicit bottom element ⊥ with masks, instead of letting NaN/Inf payloads silently drive later computations.

Documentation · PyPI · Changelog · Examples · Architecture · Assurance · Security · License

Status

Alpha; not safety-deployment or experiment-qualified.

v0.6.x is gauge-dependent: rejection scores based on |Q| are not invariant across every call site. Treat deployment safety scores as gauge-dependent. See CHANGELOG.md [0.6.1] for the current containment surface and limitations.

Install

python -m pip install zeroproofml
python -m pip install "zeroproofml[torch]"

# ONNX bundle export and runtime
python -m pip install "zeroproofml[deployment]"
# `onnx` remains a compatibility alias for the deployment extra.
python -m pip install "zeroproofml[onnx]"

# scientific benchmark harness
python -m pip install "zeroproofml[benchmarks]"

# optional experimental plotting/logging utilities
python -m pip install "zeroproofml[viz]"

# optional interactive training-log reports
python -m pip install "zeroproofml[interactive]"

# compatibility backend aggregate / every public optional feature
python -m pip install "zeroproofml[all]"
python -m pip install "zeroproofml[full]"

The core package has no required runtime dependencies. Use the torch extra for PyTorch layers, training, strict inference wrappers, and export workflows; the v0.6.x compatibility floor is torch>=1.12. Use benchmarks for the shipped DOSE / RF / IK benchmark harness, viz for experimental reporting helpers, and interactive when report regeneration should also write Plotly HTML.

Quick Start

The base package is enough to see the SCM boundary:

from zeroproofml.scm import scm_div, scm_real

print(scm_div(scm_real(1.0), scm_real(2.0)))
singular = scm_div(scm_real(1.0), scm_real(0.0))
print(singular)
print(singular.is_bottom)

SCMValue(0.5)
SCMValue(⊥)
True

For PyTorch strict inference, install zeroproofml[torch]:

import torch

from zeroproofml.inference import InferenceConfig, SCMInferenceWrapper


class Reciprocal(torch.nn.Module):
    def forward(self, x):
        return torch.ones_like(x), x


model = SCMInferenceWrapper(
    Reciprocal(),
    config=InferenceConfig(tau_infer=1e-6, tau_train=1e-4),
)
model.eval()

decoded, bottom_mask, gap_mask = model(torch.tensor([[-1.0], [0.0], [2.0]]))
print(decoded.squeeze().tolist())
print(bottom_mask.squeeze().tolist())
print(gap_mask.squeeze().tolist())

[-1.0, nan, 0.5]
[False, True, False]
[False, False, False]

The decoded NaN is only a payload sentinel. Consumers should branch on bottom_mask, fault_mask, semantic_bottom_mask, and bottom_provenance instead of interpreting decoded non-finite values as data.

Why ZeroProofML?

• Totalized arithmetic: singular scalar operations become explicit ⊥ values instead of unclassified IEEE carrier values.
• Projective training path: rational heads can learn ⟨N,D⟩ tuples while strict inference decides when denominators are too small to accept.
• Mask-first inference: bottom_mask, gap_mask, fault_mask, and semantic-bottom masks give downstream code an auditable rejection surface.
• Scientific and robotics use cases: useful for rational approximations, inverse kinematics, projective geometry, singular potentials, and censored target streams.
• Compatibility path: the legacy implementation namespace remains importable while public examples and docs use zeroproofml.*.

Requirements and Compatibility

• Python: 3.10 through 3.14, CPython.
• Core install: no mandatory third-party runtime dependencies.
• PyTorch extra: torch>=1.12; CI includes a Python 3.10 minimum-Torch lane. The extra is not platform-empty on Linux, Windows, macOS x86_64, or macOS arm64.
• Optional backends: PyTorch via zeroproofml[torch]; JAX is available as an optional backend for supported local workflows.
• deployment is the ONNX export/runtime extra; onnx is its v0.6.x compatibility alias. backends is the lean backend aggregate and all is its compatibility alias; use full for every supported public optional feature.
• Benchmarks: install zeroproofml[benchmarks] before running python -m zeroproofml.benchmarks ....
• Stability: alpha. Public APIs are versioned, but v0.7.0a1 is expected to introduce breaking semantic/status changes.
• Documentation: published docs track the latest main branch at the site root.

zeroproofml is the canonical public namespace for package/docs/install references. The legacy zeroproof import path remains supported as a compatibility namespace. That compatibility commitment holds through the roadmap's next major milestone, the M4 core 1.0-or-stay-0.x decision, and no namespace deprecation warning is planned before then unless a concrete migration plan is published. Layering rule for new code: keep SCM implementation modules under zeroproof.*, expose them through zeroproofml.* for public imports/docs, and reserve zeroproofml.*-only modules for product-level surfaces that have no legacy counterpart (for example zeroproofml.benchmarks). Import guidance lives in docs/33_namespace_guide.md.

Limitations and Non-Goals

• v0.6.x does not provide gauge-invariant deployment qualification.
• Observation, censoring, missingness, domain-invalid values, semantic bottom, and runtime faults are still being separated into the breaking v0.7.x contract.
• Full trainer run-accounting and deterministic DataLoader worker contracts remain deferred; gradient-policy contexts are isolated per task/thread in this release.
• Safety-critical deployment wording is unsupported for this release line.
• For paper-exact reproduction, pin to zeroproofml==0.4.3 or the matching release tag v0.4.3; the v0.6.x line should not reinterpret paper-era bundles under newer strict-inference schemas.

Documentation

• Getting started
• Documentation hub
• API reference
• Namespace guide
• Masks and provenance guide
• examples/README.md — maintained-vs-archival map.
• docs/38_examples_inventory.md — full examples label map.
• docs/39_examples_tutorials.md — tutorial path through maintained examples.
• examples/deployment/README.md — deployment workflow examples.
• Reproducibility

Development and Release Checks

make install
make quality
make test-fast
make test-coverage
make test-release-blockers
make docs

These targets use the locked environment and the same profile definitions as CI. Run the broader optional-backend/package matrix with make test-all. Build and validate release artifacts from a clean candidate checkout with:

make build

Scientific claim benchmark runs and performance microbenchmarks are separate. GitLab claim-benchmark:* jobs exercise the current v0.6.x scientific benchmark harness in the bounded contract mode. Paper-exact experiments are frozen to zeroproofml==0.4.3 / tag v0.4.3; do not interpret current v0.6.1 benchmark runs as paper reproduction. The benchmark_results/ JSON files belong to the performance microbenchmark suite:

python -m pip install "zeroproofml[benchmarks]"
make benchmark-contract
python -m zeroproofml.benchmarks dose --mode contract --out-root runs/dose-contract
python -m zeroproofml.report training-log runs/scm_train_metrics.jsonl
python perf/run_benchmarks.py --suite all --output benchmark_results

Support, Security, and Citation

• Report bugs through the GitLab issue tracker.
• Read the release history in CHANGELOG.md; the [0.6.1] entry lists the current containment surface, disabled paths, and known limitations.
• Read a compact per-defect summary of the v0.6.0 audit that motivated v0.6.1 in docs/16_verification_report.md under "v0.6.0 audit summary".
• See CONTRIBUTING.md for contribution and release-check expectations.
• Cite the software with CITATION.cff. The published paper artifact DOI is 10.5281/zenodo.18944465.

Acknowledgements

The theoretical foundation builds on Jan A. Bergstra and John V. Tucker's work on meadows and common meadows, algebraic structures that make division total by adding an absorptive element.

License

MIT License. See LICENSE for details.