Promoted Example Tutorials¶

This page lists the maintained examples that best cover the current ZeroProofML SCM workflows. Use it as the shortest docs-backed path from SCM basics to training, export, and strict deployment checks.

Covered workflows:

• SCM onboarding
• coverage-aware training
• deployment bundle export/runtime
• flattened strict inference for composed rational pipelines

1. SCM onboarding¶

Use examples/01_quickstart.py, examples/02_rational_layer.py, and examples/03_projective_mode.py as a single short sequence.

Run:

python examples/01_quickstart.py
python examples/02_rational_layer.py
python examples/03_projective_mode.py

What to look for:

• examples/01_quickstart.py shows bottom propagation for the core SCM ops.
• examples/02_rational_layer.py moves from scalar SCM values to a trainable rational layer.
• examples/03_projective_mode.py trains a model whose public forward contract is exactly (P, Q), then applies strict inference at evaluation. Its summary labels every denominator: qualified_mse is computed only over qualified_samples; bottom, gap, fault, and semantic-bottom counts are reported separately.

Keep these docs open while you run the scripts:

• 00_getting_started.md
• 02_projective_learning.md
• 03_gradient_policies.md

2. Coverage-aware training¶

Use examples/05_coverage_control.py when you want the smallest maintained training example that makes bottom-rate control explicit.

Run:

python examples/05_coverage_control.py

What to look for:

• coverage_loss(...) penalises the gap between target coverage and achieved non-bottom rate.
• The example masks bottom outputs before the MSE term so singular samples do not silently contaminate the finite regression path.
• The final printout gives a quick sanity check for target versus achieved coverage.

Related guides:

• 05_training_guide.md
• 13_adaptive_loss_guide.md
• 14_adaptive_loss_summary.md

3. Strict deployment bundle¶

Use examples/06_export_bundle.py together with examples/cpp/minimal_bundle_consumer.cpp for the maintained deployment tutorial path.

Run the Python export:

python examples/06_export_bundle.py

Then build the C++ consumer against your local ONNX Runtime install:

c++ -std=c++17 examples/cpp/minimal_bundle_consumer.cpp \
  -I/path/to/onnxruntime/include \
  -I/path/to/nlohmann \
  -L/path/to/onnxruntime/lib \
  -lonnxruntime \
  -o minimal_bundle_consumer
./minimal_bundle_consumer export_bundle_demo

What to look for:

• The exported bundle keeps the stable strict output order: decoded, bottom_mask, gap_mask.
• metadata.json pins the strict-inference contract, batch semantics, and schema versions.
• The C++ wrapper validates contained paths, model size, SHA-256, and the same schema-v2 output contract before running ONNX Runtime. It reports checksum-validated versus legacy-unverified status; legacy three-output bundles are inspectable only and must be migrated before execution.

Related guides:

• 06_inference_deployment.md
• 35_deployment_bundles_guide.md

4. Flatten once, check once¶

Use examples/fru_strict_check_demo.py for the maintained composed-rational tutorial path.

Run:

python examples/fru_strict_check_demo.py

What to look for:

• Multiple rational stages are flattened into one final P/Q pair.
• Denominator provenance records which intermediate stages contributed strict factors.
• The stagewise bottom cases and the final strict_inference(...) result agree, so the example shows how to defer the authoritative strict check to the end of the pipeline.

v0.6.1 caveats for the FRU path: the flatten step is operational only, not a proof/certificate. evaluate_fru_expression(...) defaults to operational compatibility mode and emits RuntimeWarning for floating coefficients; proof/checker callers must pass strict=True, which refuses those inputs with FloatingCoefficientRefusal. FRUExpression.flatten() refuses expansion above FLATTEN_MAX_WORK = 100_000 with FRUResourceRefusal. Pass integer coefficients to stay on the strict path until the exact-rational subprofile lands.

Related guides:

• theory/01_fracterm_flattening.md
• 08_api_reference.md
• 23_experimental_provenance_guide.md

Reference-only supported examples¶

The remaining supported examples stay important, but they are better used as focused reference scripts than as first tutorials:

• examples/04_2r_arm.py
• examples/autodiff_demo.py
• examples/bridge_demo.py
• examples/optimization_demo.py (reports both coverage and bottom rate, whose values sum to one)

5. End-to-end deployment workflows¶

For larger deployment paths that chain multiple maintained surfaces together, use the in-tree deployment examples:

• examples/deployment/README.md
• examples/deployment/01_bundle_export_runtime.md
• examples/deployment/02_robotics_fallback_routing.md
• examples/deployment/03_benchmark_report_generation.md
• examples/deployment/04_ros2_node_launch.md

These examples connect the promoted bundle-export tutorial to the maintained reference deployment, benchmark report, and ROS 2 launch paths documented in:

• 06_inference_deployment.md
• 36_ros2_integration_guide.md
• 37_visualization_reporting_guide.md

For the full maintained-vs-archival map, see 38_examples_inventory.md.