docs: remove references to deleted examples

Author: rezaquant

docs/api/optimizers/mera.md

@@ -118,8 +118,9 @@ optimizer = builder.fermion_parametric_optimizer(
 )
 ```
 
-For a complete native Torch example, see
-`examples/FermiHubbardQMera/fermion_qmera_energy.py`.
+For a larger native Torch workflow, use the corresponding examples maintained
+in the separate `pepsy_examples` repository; the package API is demonstrated
+by the builder flow above.
 
 ```{eval-rst}
 .. automodule:: pepsy.optimizers.mera

docs/examples.md

@@ -20,25 +20,12 @@ It demonstrates:
 - [How-To: Choose Parameters](howto/choose_parameters.md)
 - [How-To: Tune Sweep Solvers](howto/solver_tuning.md)
 
-## Runnable scripts
-
-- `examples/QMeraEnergy/qmera_energy.py` builds a small schedule-first qMERA,
-  evaluates local ZZ energy from rebuilt and compiled lightcones, and can run a
-  short optional Torch Adam optimization with `--steps`.
-- `examples/FermiHubbardUnified/fermion_workflow.py` uses one
-  `pepsy.Fermion` object to build site-native Hubbard terms and an MPS gate
-  stream, then adapts the same model to qMERA's explicit two-mode layout.
-- `examples/FermiHubbardQMera/fermion_qmera_energy.py` builds native Symmray
-  Hubbard `LocalTerm` objects and optionally optimizes their qMERA energy with
-  Torch Adam using `--steps`.
-- `examples/SimpleUpdateGen/long_range_peps.py` demonstrates a long-range PEPS
-  simple-update term: raw `quimb.SimpleUpdateGen` fails on the non-adjacent
-  endpoints, while `pepsy.SimpleUpdateGen` routes the gate through SWAPs and
-  reports the resulting max bond, gauge count, and cluster energy.
-- `examples/RelayBP/simple_update_relay_comparison.py` compares exact
-  contraction with plain D1BP, simple-update-initialized D1BP, and
-  simple-update-initialized Relay-BP on a small loopy factor network.
-- `examples/RelayBP/odd_cycle_stress.py` provides deterministic positive
-  odd-cycle cases where polarized parallel D1BP stalls and Relay-BP converges.
+## Extended examples
+
+The package repository keeps only the lightweight example notebook under
+`examples/`. Larger runnable workflows and experiment scripts are maintained
+in the separate `pepsy_examples` repository. The tests in this repository keep
+the deleted Relay-BP examples' numerical coverage without depending on local
+example files.
 
 For a cleaner, docs-first narrative, start from [tutorials](tutorials/index.md).

docs/tutorials/bp_simple_update_relay.md

@@ -6,13 +6,11 @@ Relay-BP adds per-source-node memory over several warm-started legs to make
 finding a fixed point more robust. It does not, by itself, make a loopy BP
 contraction exact; use an exact small network to measure approximation error.
 
-The runnable example below uses a 3×3 classical Ising factor network. It
-compares all three paths against the exact contraction and records the absolute
-message convergence and relative contraction error:
-
-```{literalinclude} ../../examples/RelayBP/simple_update_relay_comparison.py
-:language: python
-```
+The comparison is covered directly by the BP regression tests and uses only
+the public `gauge_all`, `one_norm_bp`, and
+`run_d1bp_from_simple_update_gauges` APIs. The package repository intentionally
+does not carry a separate runnable script for this workflow; extended example
+scripts belong in the separate `pepsy_examples` repository.
 
 The flow is:
 
@@ -30,15 +28,12 @@ easy fixed point; the reported residual separately verifies convergence.
 
 ## Relay stress cases
 
-The following runnable exact-reference stress cases begin from deliberately
-polarized messages on a near-deterministic odd cycle. Parallel D1BP stalls,
-whereas Relay's per-source memory reaches a strict residual fixed point. The
-reported exact-reference error is intentionally separate: convergence does not
-turn a strongly loopy BP approximation into an exact contraction.
-
-```{literalinclude} ../../examples/RelayBP/odd_cycle_stress.py
-:language: python
-```
+The regression suite also covers exact-reference stress cases beginning from
+deliberately polarized messages on a near-deterministic odd cycle. Parallel
+D1BP stalls, whereas Relay's per-source memory reaches a strict residual fixed
+point. The reported exact-reference error is intentionally separate:
+convergence does not turn a strongly loopy BP approximation into an exact
+contraction.
 
 For the reverse direction, use
 `simple_update_core_and_gauges_from_messages(result.bp)`. For strictly

tests/test_bp_cluster.py

@@ -9,8 +9,6 @@
 
 import numpy as np
 import pytest
-from pathlib import Path
-import runpy
 
 qtn = pytest.importorskip("quimb.tensor")
 pytest.importorskip("quimb.tensor.belief_propagation")
@@ -698,13 +696,59 @@ def test_relay_bp_runs_from_real_quimb_su_and_can_return_to_su():
 
 def test_exact_su_and_relay_d1bp_comparison_example():
     """The documented comparison tracks convergence and loopy-BP error."""
-    example_path = (
-        Path(__file__).resolve().parents[1]
-        / "examples"
-        / "RelayBP"
-        / "simple_update_relay_comparison.py"
-    )
-    comparison = runpy.run_path(str(example_path))["run_comparison"]()
+    from pepsy.bp import one_norm_bp
+
+    tn = qtn.TN2D_classical_ising_partition_function(3, 3, beta=0.2)
+    exact = float(tn.contract(optimize="auto-hq"))
+    core = tn.copy()
+    gauges = {}
+    core.gauge_all_simple_(gauges=gauges, max_iterations=100, tol=1e-12)
+    rebuilt = core.copy()
+    rebuilt.gauge_simple_insert(gauges)
+    su_representation_error = abs(float(rebuilt.contract()) - exact) / abs(exact)
+
+    runs = {
+        "plain_d1bp": one_norm_bp(
+            tn,
+            method="d1bp",
+            max_iterations=1000,
+            tol=1e-10,
+        ),
+        "su_initialized_d1bp": run_d1bp_from_simple_update_gauges(
+            core,
+            gauges,
+            run_opts={"max_iterations": 1000, "tol": 1e-10},
+        ),
+        "su_initialized_relay_d1bp": run_d1bp_from_simple_update_gauges(
+            core,
+            gauges,
+            use_relay=True,
+            run_opts={"max_iterations": 1000, "tol": 1e-10},
+            relay_opts={
+                "num_relays": 3,
+                "memory_first_leg": False,
+                "gamma_range": (0.1, 0.2),
+                "seed": 0,
+            },
+        ),
+    }
+    records = {}
+    for name, result in runs.items():
+        estimate = float(result.contract())
+        records[name] = {
+            "converged": result.converged,
+            "quimb_converged": result.quimb_converged,
+            "iterations": result.iterations,
+            "num_legs": result.num_legs_run,
+            "max_mdiff": result.max_mdiff,
+            "estimate": estimate,
+            "relative_error": abs(estimate - exact) / abs(exact),
+        }
+    comparison = {
+        "exact": exact,
+        "simple_update_representation_error": su_representation_error,
+        "runs": records,
+    }
 
     assert comparison["simple_update_representation_error"] < 1e-12
     runs = comparison["runs"]

tests/test_bp_relay.py

@@ -5,10 +5,10 @@
 import numpy as np
 import pepsy as py
 import pytest
-from pathlib import Path
-import runpy
+import warnings
 
 qtn = pytest.importorskip("quimb.tensor")
+from quimb.tensor.belief_propagation import D1BP  # noqa: E402
 
 from pepsy.bp import RelayBPResult, one_norm_bp, relay_bp  # noqa: E402
 from pepsy.bp.relay import _relay_message_sources  # noqa: E402
@@ -43,6 +43,26 @@ def _peps_2x2():
     return qtn.PEPS.rand(Lx=2, Ly=2, bond_dim=2, seed=10)
 
 
+def _odd_antiferromagnetic_cycle(epsilon):
+    """Return a positive triangle whose edge factors nearly flip a bit."""
+    factor = np.array([[epsilon, 1.0], [1.0, epsilon]])
+    return qtn.TensorNetwork(
+        [
+            qtn.Tensor(factor, inds=("ab", "ca")),
+            qtn.Tensor(factor, inds=("ab", "bc")),
+            qtn.Tensor(factor, inds=("bc", "ca")),
+        ]
+    )
+
+
+def _polarized_messages(tn):
+    """Choose a deterministic non-fixed initial message for every edge end."""
+    return {
+        key: np.array([1.0, 0.0])
+        for key in D1BP(tn, update="parallel").messages
+    }
+
+
 def test_one_norm_bp_close_to_exact_on_small_grid():
     tn = _ising_tn(3, 0.2)
     exact = float(tn.contract())
@@ -232,13 +252,48 @@ def test_parallel_update_runs():
 
 def test_relay_d1bp_odd_cycle_stress_cases_converge_strictly():
     """Relay damps deterministic parallel D1BP stalls on odd parity cycles."""
-    example_path = (
-        Path(__file__).resolve().parents[1]
-        / "examples"
-        / "RelayBP"
-        / "odd_cycle_stress.py"
-    )
-    records = runpy.run_path(str(example_path))["run_stress_cases"]()
+    records = []
+    for epsilon in (1e-3, 1e-2):
+        tn = _odd_antiferromagnetic_cycle(epsilon)
+        exact = float(tn.contract())
+        initial = _polarized_messages(tn)
+        common = {
+            "method": "d1bp",
+            "init_messages": initial,
+            "update": "parallel",
+            "diis": False,
+            "max_iterations": 100,
+            "tol": 1e-10,
+        }
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="Belief propagation did not converge.*",
+                category=UserWarning,
+            )
+            plain = one_norm_bp(tn, **common)
+        relay = relay_bp(
+            tn,
+            **common,
+            num_relays=5,
+            memory_first_leg=True,
+            gamma_range=(0.2, 0.8),
+            seed=0,
+        )
+        relay_estimate = float(relay.contract())
+        records.append(
+            {
+                "epsilon": epsilon,
+                "exact": exact,
+                "plain_converged": plain.converged,
+                "plain_max_mdiff": plain.max_mdiff,
+                "relay_converged": relay.converged,
+                "relay_iterations": relay.iterations,
+                "relay_num_legs": relay.num_legs_run,
+                "relay_max_mdiff": relay.max_mdiff,
+                "relay_relative_error": abs(relay_estimate - exact) / abs(exact),
+            }
+        )
 
     assert len(records) == 2
     for record in records: