pycauset 0.6.2.dev14__tar.gz → 0.6.2.dev16__tar.gz

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/.gitignore

@@ -131,3 +131,16 @@ tools/test_release_locally.sh
 /.pycauset_stability/
 /tmp_verification_phase3_4/
 build_*/
+
+# --- Local rebuild/scratch artifacts ---
+third_party/
+*.log
+*.release_bak
+/cpp_diff.txt
+/disasm_pyd.txt
+/import_dump.txt
+/avxoff.log
+/openblas_build.log
+/pin.log
+/pin2.log
+/pin7.log

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/CMakeLists.txt

@@ -486,8 +486,11 @@ if(ENABLE_CUDA)
     check_language(CUDA)
 
     if(CMAKE_CUDA_COMPILER)
-        # Target the native architecture of the build machine (supports Pascal 6.1 on CUDA 12)
-        set(CMAKE_CUDA_ARCHITECTURES "native")
+        # Default to the build machine's GPU ("native"), but allow distribution
+        # builds (CI) to override with a list of target compute capabilities
+        # (e.g. "61;70;75;80;86;89") so the wheel runs on a range of GPUs and
+        # does not require a GPU on the builder.
+        set(CMAKE_CUDA_ARCHITECTURES "native" CACHE STRING "CUDA compute capabilities to target")
         enable_language(CUDA)
         find_package(CUDAToolkit REQUIRED)
         
@@ -509,6 +512,7 @@ if(ENABLE_CUDA)
             CUDA::cublas 
             CUDA::cusolver
             pycauset_core
+            Eigen3::Eigen
         )
         
         # Set properties
@@ -516,6 +520,11 @@ if(ENABLE_CUDA)
             WINDOWS_EXPORT_ALL_SYMBOLS ON
             CUDA_SEPARABLE_COMPILATION ON
         )
+
+        # Eigen's C++11 math detection mis-fires under nvcc's host compilation
+        # (EIGEN_USING_STD(arg) falls back to `using ::arg`, which does not exist),
+        # so force the std::arg path.
+        target_compile_definitions(pycauset_cuda PRIVATE EIGEN_HAS_CXX11_MATH=1)
         
         # Suppress specific NVCC warnings
         # 611: overloaded virtual function is only partially overridden
@@ -533,7 +542,7 @@ if(ENABLE_CUDA)
         # Only meaningful if CUDA is enabled. This module provides discovery functions.
         python_add_library(_pycauset_cuda MODULE src/bindings/bind_cuda.cpp)
         target_include_directories(_pycauset_cuda PRIVATE include)
-        target_link_libraries(_pycauset_cuda PRIVATE pycauset_cuda pybind11::module pycauset_core)
+        target_link_libraries(_pycauset_cuda PRIVATE pycauset_cuda pybind11::module pycauset_core CUDA::cudart)
         set_target_properties(_pycauset_cuda PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS ON)
         install(TARGETS _pycauset_cuda DESTINATION pycauset)
 

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pycauset
-Version: 0.6.2.dev14
+Version: 0.6.2.dev16
 Summary: High-performance Causal Set matrix operations using memory-mapped files
 Author: Bror Hjemgaard
 License: MIT
@@ -25,6 +25,10 @@ Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: psutil; extra == "dev"
+Provides-Extra: gpu
+Requires-Dist: nvidia-cuda-runtime-cu12>=12.6; extra == "gpu"
+Requires-Dist: nvidia-cublas-cu12>=12.6; extra == "gpu"
+Requires-Dist: nvidia-cusolver-cu12>=12.6; extra == "gpu"
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -110,7 +114,7 @@ PyCauset has an optimized C++ core with Python bindings, which is built specific
 
 ## Performance
 
-PyCauset's dense kernels use the same OpenBLAS/LAPACK backend as NumPy, so the goal is parity rather than a large speedup, with a goal of all PyCauset operatiosn being at least 0.90x the speed of NumPy for in-memory operations, (see [BENCHMARKS.md](BENCHMARKS.md)).
+PyCauset's dense kernels use the same OpenBLAS/LAPACK backend as NumPy, so the goal is parity rather than a large speedup, with a goal of all PyCauset operations being at least 0.90x the speed of NumPy for in-memory operations, (see [BENCHMARKS.md](BENCHMARKS.md)).
 However, the biggest reason to use PyCauset is that it memory-maps past RAM, where NumPy raises MemoryError.
 
 ## Gallery
@@ -137,9 +141,28 @@ cd pycauset
 pip install .
 ```
 
+### GPU acceleration (optional)
+
+PyCauset ships **CPU-only by default** to keep the install small. The GPU backend is a
+one-command opt-in:
+
+```bash
+pip install "pycauset[gpu]"
+```
+
+That pulls the CUDA runtime (~500 MB) and enables the `pycauset_cuda` backend. Requirements:
+
+- NVIDIA GPU, Compute Capability 6.0+ (Pascal or newer)
+- Linux or Windows (macOS has no NVIDIA CUDA)
+
+If you run on a machine with an NVIDIA GPU but haven't installed the GPU backend, PyCauset
+prints a one-line reminder at import telling you the exact command (silence it with
+`PYCAUSET_GPU_HINT=0`). CPU remains the correct, fully-supported default — the GPU backend
+is used automatically only when the cost model predicts it will be faster.
+
 ## Status
 
-Pre-alpha. Release 1 (the Foundation Release) builds the numerical core: matrices, storage, linear algebra, GPU. Release 2 (the Physics Release) adds the physics suite: arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum. The current plan is tracked in the documentation.
+Pre-alpha. Release 1 (v0.6.1, the Foundation Release) shipped the numerical core — matrices, storage, and linear algebra — CPU-only (GPU parity is deferred). Release 2 (the Physics Release) adds the physics suite — arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum — and folds in the deferred optimization program. The current plan is tracked in the documentation.
 
 ## Documentation
 

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/README.md

@@ -81,7 +81,7 @@ PyCauset has an optimized C++ core with Python bindings, which is built specific
 
 ## Performance
 
-PyCauset's dense kernels use the same OpenBLAS/LAPACK backend as NumPy, so the goal is parity rather than a large speedup, with a goal of all PyCauset operatiosn being at least 0.90x the speed of NumPy for in-memory operations, (see [BENCHMARKS.md](BENCHMARKS.md)).
+PyCauset's dense kernels use the same OpenBLAS/LAPACK backend as NumPy, so the goal is parity rather than a large speedup, with a goal of all PyCauset operations being at least 0.90x the speed of NumPy for in-memory operations, (see [BENCHMARKS.md](BENCHMARKS.md)).
 However, the biggest reason to use PyCauset is that it memory-maps past RAM, where NumPy raises MemoryError.
 
 ## Gallery
@@ -108,9 +108,28 @@ cd pycauset
 pip install .
 ```
 
+### GPU acceleration (optional)
+
+PyCauset ships **CPU-only by default** to keep the install small. The GPU backend is a
+one-command opt-in:
+
+```bash
+pip install "pycauset[gpu]"
+```
+
+That pulls the CUDA runtime (~500 MB) and enables the `pycauset_cuda` backend. Requirements:
+
+- NVIDIA GPU, Compute Capability 6.0+ (Pascal or newer)
+- Linux or Windows (macOS has no NVIDIA CUDA)
+
+If you run on a machine with an NVIDIA GPU but haven't installed the GPU backend, PyCauset
+prints a one-line reminder at import telling you the exact command (silence it with
+`PYCAUSET_GPU_HINT=0`). CPU remains the correct, fully-supported default — the GPU backend
+is used automatically only when the cost model predicts it will be faster.
+
 ## Status
 
-Pre-alpha. Release 1 (the Foundation Release) builds the numerical core: matrices, storage, linear algebra, GPU. Release 2 (the Physics Release) adds the physics suite: arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum. The current plan is tracked in the documentation.
+Pre-alpha. Release 1 (v0.6.1, the Foundation Release) shipped the numerical core — matrices, storage, and linear algebra — CPU-only (GPU parity is deferred). Release 2 (the Physics Release) adds the physics suite — arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum — and folds in the deferred optimization program. The current plan is tracked in the documentation.
 
 ## Documentation
 

pycauset-0.6.2.dev16/benchmarks/large_n_check.py

@@ -0,0 +1,57 @@
+"""Large-N correctness and timing check.
+
+Runs causal-set operations at large N and verifies correctness on a random
+sample of entries (direct O(N) reference) plus a structural invariant (the
+square of a strictly upper triangular matrix is strictly upper triangular).
+
+Run with:
+
+    .venv\\Scripts\\python.exe benchmarks\\large_n_check.py
+"""
+
+import random
+import sys
+import time
+
+import pycauset as pc
+
+
+def check(n, *, seed=2024, samples=40):
+    t0 = time.perf_counter()
+    C = pc.CausalSet(n, spacetime=pc.MinkowskiDiamond(3), seed=seed).C
+    t_build = time.perf_counter() - t0
+
+    t0 = time.perf_counter()
+    C2 = C @ C
+    t_square = time.perf_counter() - t0
+
+    rng = random.Random(seed)
+    sample_ok = True
+    for _ in range(samples):
+        i = rng.randrange(n)
+        j = rng.randrange(i + 1, n)  # strictly upper triangle
+        s = 0
+        for k in range(i + 1, j):
+            s += (1 if C.get(i, k) else 0) * (1 if C.get(k, j) else 0)
+        if C2.get(i, j) != s:
+            sample_ok = False
+            print(f"  MISMATCH at ({i},{j}): got {C2.get(i, j)}, want {s}")
+            break
+
+    diag_ok = all(C2.get(i, i) == 0 for i in range(min(n, 64)))
+
+    print(f"N={n:>6}  build={t_build:8.3f}s  C@C={t_square:8.3f}s  "
+          f"sample_ok={sample_ok}  diag_ok={diag_ok}")
+
+
+def main():
+    if len(sys.argv) > 1:
+        ns = [int(x) for x in sys.argv[1:]]
+    else:
+        ns = [2000, 5000, 10000]
+    for n in ns:
+        check(n)
+
+
+if __name__ == "__main__":
+    main()

pycauset-0.6.2.dev16/benchmarks/r2_continuum_limit.py

@@ -0,0 +1,74 @@
+"""R2_QA / R2_CMVP — continuum-limit benchmark (massless 1+1, Minkowski diamond).
+
+Reproduces with::
+
+    python benchmarks/r2_continuum_limit.py
+
+For the massless 1+1 field the discrete Pauli–Jordan ``iΔ = (i/2)(C − Cᵀ)`` is
+**exact** against the continuum ``iΔ = (i/2) sgn(Δt) θ(σ)`` sampled at the causet's
+points — there is no discretization error, so this also pins the sign/scale
+convention (R2_CONV). What *does* converge is the Sorkin–Johnston Wightman
+``W = positive part of iΔ``: as the number of sprinkled points grows, its
+finite-dimensional positive spectrum approaches the continuum positive-frequency
+spectrum. This benchmark reports both:
+
+* ``max |iΔ_discrete − iΔ_continuum|`` — the convention pin (should be ~0 at every n).
+* the SJ Wightman positive spectrum (count, extremal eigenvalues, trace) vs ``n``.
+
+The analytic continuum **Wightman** (massive/Bessel + the massless log) is a
+deferred R2_CMVP item — see `documentation/project/plans/R2_ROADMAP.md`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+import pycauset as pc
+
+
+def run(n: int, seed: int = 11):
+    st = pc.MinkowskiDiamond(2)
+    c = pc.CausalSet(n=n, spacetime=st, seed=seed)
+
+    phi = pc.field("scalar", mass=0.0)
+    q_c = phi.on(c)
+    q_ct = phi.on(st)
+
+    coords = st.to_embedding(c.embedding)  # lightcone (u,v) -> physical (t,x)
+
+    iD_disc = np.asarray(q_c.pauli_jordan())
+    iD_cont = np.asarray(q_ct.at(coords, which="pauli_jordan"))
+    pin_err = float(np.max(np.abs(iD_disc - iD_cont)))
+
+    # SJ Wightman = positive-eigenvalue part of iΔ (purely imaginary spectrum).
+    w = np.asarray(q_c.wightman())
+    w_eig = np.linalg.eigvalsh(w)
+    pos = w_eig[w_eig > 1e-12]
+
+    return {
+        "n": n,
+        "pin_err": pin_err,
+        "n_pos_modes": int(pos.size),
+        "w_min_pos": float(pos.min()) if pos.size else float("nan"),
+        "w_max_pos": float(pos.max()) if pos.size else float("nan"),
+        "w_trace": float(np.real(np.trace(w))),
+    }
+
+
+def main() -> None:
+    ns = [32, 64, 128, 256, 512, 1024]
+    print(f"{'n':>6} {'|iD err|':>12} {'#W+modes':>10} {'W min+':>14} {'W max+':>14} {'tr(W)':>14}")
+    print("-" * 74)
+    for n in ns:
+        r = run(n)
+        print(
+            f"{r['n']:>6} {r['pin_err']:>12.2e} {r['n_pos_modes']:>10} "
+            f"{r['w_min_pos']:>14.6f} {r['w_max_pos']:>14.6f} {r['w_trace']:>14.6f}"
+        )
+    print("-" * 74)
+    print("|iD err| stays ~machine-epsilon at every n (the massless 1+1 convention is pinned).")
+    print("The SJ Wightman positive spectrum grows with n (continuum limit of W).")
+
+
+if __name__ == "__main__":
+    main()

pycauset-0.6.2.dev16/documentation/dev/R2_QA_AUDIT.md

@@ -0,0 +1,68 @@
+# R2_QA — public-surface audit (partial)
+
+Audit of the R2 public API surface and per-node test/doc coverage. This is the
+"in-step docs + tests" gate (R2_QA); it does not write docs/tests — it verifies.
+
+## Public surface (all resolve)
+
+- `spacetime`: `Spacetime`, `register`, `create`, `export_python`, `get_registry`,
+  `RestrictedSpacetime`, `TransformedSpacetime`, `ConformalSpacetime`,
+  `PeriodicSpacetime`, `MinkowskiDiamond/Cylinder/Box`, `DeSitter`, `AntiDeSitter`,
+  `FLRW`, `Schwarzschild`.
+- `field`: `Field`, `CorrelatedField`, `ContinuumCorrelatedField`, `ScalarField`,
+  callable `pc.field("scalar", …)`.
+- `CausalSet` methods: `validate`, `links`, `past`, `future`, `interval`, `is_chain`,
+  `is_antichain`, `longest_chain`, `layers`, `relation_fraction`,
+  `myrheim_meyer_dimension`, `plot_embedding`, `plot_hasse`, `plot_causal_matrix`.
+- `synthetic`: `chain`, `antichain`, `transitive_percolation`, `random_dag_order`,
+  `product_order`, `poset`.
+- Top-level: `pc.plot_embedding/hasse/causal_matrix`, `pc.show`.
+
+## Test coverage (187 tests across the R2 node files + regression suites, all passing)
+
+| node | test file |
+| :-- | :-- |
+| R2_SIG / R2_ABC | `test_spacetime_r2_abc.py` |
+| R2_VALIDATE / R2_EMBED | `test_causet_r2_sprinkle_validate.py` |
+| R2_MINK | `test_minkowski_r2.py` |
+| R2_FIELD / R2_KRD / R2_SJ | `test_field_r2.py` |
+| R2_CONV / R2_CMVP | `test_conv_continuum_r2.py` |
+| R2_CREATE | `test_create_r2.py` (18) |
+| R2_VIZ | `test_viz_r2.py` (11) |
+| R2_STRUCT | `test_struct_r2.py` |
+| R2_SYNTH | `test_synth_r2.py` |
+| R2_DIM | `test_dim_r2.py` |
+| R2_BATCH | `test_batch_r2.py` |
+| R2_CURVED / R2_BH | `test_curved_r2.py`, `test_bh_r2.py` |
+| R2_ENT | `test_ent_r2.py` |
+| R2_CORR | `test_state_r2.py` |
+| R2_CPU (elementwise SIMD) | `test_elementwise_r2.py` (18) + `test_operations{,_extensive}.py` |
+| R2_COEFFS | covered by `test_field.py` |
+
+Bugs discovered during the R2E work are logged in `tests/BUG_LOG.md` per the
+Testing & Bug Tracking protocol.
+
+## Delivered audit items
+
+- **Continuum-limit benchmark** — `benchmarks/r2_continuum_limit.py` (discrete `iΔ`
+  vs continuum `iΔ` convention pin + the SJ Wightman positive-spectrum growth vs `n`).
+- **Conference feature menu** — `documentation/guides/R2 Feature Menu.md`.
+- **CI correctness gate** — `.github/workflows/ci.yml` runs `pytest tests/python`
+  on the 3-OS matrix (Linux/macOS/Windows).
+
+## Remaining (not yet audited/closed)
+
+- **CI parity threshold** (R2_PERF: `benchmarks/r2_parity.py` with the `>= 0.90×`
+  bar enforced in CI — timing thresholds are intentionally not CI-gated yet).
+- **C++ R2E** (R2_CPU lazy-routing / R2_GPU / R2_STREAM / R2_EIGCACHE) — in progress.
+
+## Deferred to future releases (explicitly NOT R2 scope)
+
+Per the R2 field-theory boundary (Pauli–Jordan + retarded propagator is enough):
+
+- Massive/Bessel Green's functions and the continuum Wightman log (R2_CONV/R2_CMVP
+  ship the massless 1+1 pin only).
+- Entanglement-entropy analytic reference (R2_ENT ships two documented conventions).
+- RN/Kerr/Kerr–Newman black holes (R2_BH ships `Schwarzschild` 1+1).
+- Higher-point Wick contractions, interacting fields, fermions, gauge fields
+  (R2_FIELD/R2_CORR ship the free scalar core).

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/documentation/dev/Restructure Plan.md

@@ -33,7 +33,7 @@ See:
 
 Some additional restructure work was intentionally deferred behind an explicit approval gate. The execution record and remaining proposals live in:
 
-- [[internals/plans/completed/Restructure Plan.md|Internals: Restructure execution record]]
+- [[internals/plans/archive/Restructure Plan.md|Internals: Restructure execution record]]
 
 ## See also
 

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/documentation/dev/Storage Semantics.md

@@ -4,8 +4,8 @@ This page is the developer-facing hub for how storage works in Release 1. User-f
 
 ## Canonical references
 - [[guides/Storage and Memory]] (user workflow + container overview)
-- [[internals/plans/completed/R1_STORAGE_PLAN.md|R1_STORAGE_PLAN]] (frozen container contract)
-- [[internals/plans/completed/R1_PROPERTIES_PLAN.md|R1_PROPERTIES_PLAN]] (metadata semantics and gospel properties)
+- [[internals/plans/archive/R1_STORAGE_PLAN.md|R1_STORAGE_PLAN]] (frozen container contract)
+- [[internals/plans/archive/R1_PROPERTIES_PLAN.md|R1_PROPERTIES_PLAN]] (metadata semantics and gospel properties)
 
 ## Release 1 guarantees (storage)
 - Single-file `.pycauset` container, little-endian, with a 4096-byte header holding two slots (A/B). The valid slot with the highest generation is active; CRC mismatch or out-of-range pointers fail deterministically.

pycauset-0.6.2.dev16/documentation/docs/classes/field/index.md

@@ -0,0 +1,7 @@
+# Field
+
+* **[[docs/classes/field/pycauset.field.Field.md|Field]]**
+* **[[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]]**
+* **[[docs/classes/field/pycauset.field.ContinuumCorrelatedField.md|ContinuumCorrelatedField]]**
+* **[[docs/classes/field/pycauset.field.State.md|State]]**
+* **[[docs/classes/field/pycauset.field.ScalarField.md|ScalarField (R1 back-compat)]]**

pycauset-0.6.2.dev16/documentation/docs/classes/field/pycauset.field.ContinuumCorrelatedField.md

@@ -0,0 +1,53 @@
+# pycauset.field.ContinuumCorrelatedField
+
+```python
+class ContinuumCorrelatedField(spacetime: Spacetime, mass: float = 0.0)
+```
+
+Closed-form Green's functions on a continuum flat-Minkowski spacetime, for the R2 continuum-limit comparison. Returned by `phi.on(spacetime)`.
+
+## Description
+
+Provides the continuum `G_R`, `G_A`, and `iΔ` as callables of two points, plus `.at(coords)` sampling. Currently exact for the **massless 1+1** case (`iΔ = (i/2) sgn(Δt) θ(σ)`); massive and higher-dimensional closed forms (Bessel functions) are pending.
+
+## Methods
+
+### retarded / advanced
+
+```python
+def retarded(self, x, y) -> float
+def advanced(self, x, y) -> float
+```
+
+Continuum retarded/advanced Green's function at two points.
+
+### pauli_jordan
+
+```python
+def pauli_jordan(self, x, y) -> complex
+```
+
+Continuum Pauli–Jordan `iΔ(x, y) = i(G_R - G_A)`.
+
+### at
+
+```python
+def at(self, coords, which="pauli_jordan") -> np.ndarray
+```
+
+Samples a kernel at an `(n, d)` coordinate array, returning an `(n, n)` matrix.
+
+## Example
+
+```python
+import pycauset as pc
+
+c = pc.causet(n=100, spacetime=pc.MinkowskiDiamond(2), seed=1)
+Q_ct = pc.field("scalar", mass=0.0).on(c.spacetime)
+iD_continuum = Q_ct.at(c.spacetime.to_embedding(c.embedding), which="pauli_jordan")
+```
+
+## See also
+
+- [[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]]
+- [[guides/Field Theory.md|Field Theory guide]]

pycauset-0.6.2.dev16/documentation/docs/classes/field/pycauset.field.CorrelatedField.md

@@ -0,0 +1,96 @@
+# pycauset.field.CorrelatedField
+
+```python
+class CorrelatedField(causet: CausalSet, mass: float = 0.0)
+```
+
+A field together with its Green's functions and vacuum two-point function on a causal set. Returned by `phi.on(causet)` for a `Field`.
+
+## Parameters
+
+*   **causet** (*CausalSet*): The background causal set.
+*   **mass** (*float*): The field mass. Defaults to 0.0 (massless).
+
+## Methods
+
+### retarded
+
+```python
+def retarded(self, a=None, b=None) -> np.ndarray
+```
+
+Retarded Green's function `K_R = aC (I - baC)⁻¹` as a dense `n×n` array. `a`, `b` default to `Spacetime.scalar_coeffs(mass, density)`; pass them manually to override.
+
+### advanced
+
+```python
+def advanced(self, a=None, b=None) -> np.ndarray
+```
+
+Advanced Green's function `K_A = K_Rᵀ`.
+
+### pauli_jordan
+
+```python
+def pauli_jordan(self) -> np.ndarray
+```
+
+Pauli–Jordan function `iΔ = K_R - K_A` (a Hermitian matrix).
+
+### wightman
+
+```python
+def wightman(self) -> np.ndarray
+```
+
+Sorkin–Johnston vacuum Wightman two-point function — the positive-eigenvalue part of `iΔ`.
+
+### correlator
+
+```python
+def correlator(self) -> np.ndarray
+```
+
+Vacuum two-point function `⟨φφ⟩ = W` (free field).
+
+### state
+
+```python
+def state(self, config=None) -> State
+```
+
+Builds a [[docs/classes/field/pycauset.field.State.md|State]] (a coherent field configuration) on top of this correlated field. `config` defaults to the vacuum (zero).
+
+### entanglement_entropy
+
+```python
+def entanglement_entropy(self, region, convention="sorkin_yazdi") -> float
+```
+
+Sorkin–Yazdi entanglement entropy of a region (a subset of element indices), from the region-restricted SJ Wightman matrix.
+
+**Conventions (documented):**
+
+| `convention` | formula | requirement |
+| :-- | :-- | :-- |
+| `"sorkin_yazdi"` *(default)* | `S = tr[(W_A + I) ln(W_A + I) − W_A ln W_A]` (`0 ln 0 = 0`) | `W_A ≥ 0` — the SJ Wightman's zero-point "1/2" convention |
+| `"symplectic"` | `S = tr[(W_A + 1/2) ln(W_A + 1/2) − (W_A − 1/2) ln(W_A − 1/2)]` | `W_A ≥ 1/2` (raises `ValueError` otherwise) |
+
+The two conventions are the same formula up to the zero-point shift:
+`sorkin_yazdi(W) == symplectic(W + 1/2 I)`.
+
+## Example
+
+```python
+import pycauset as pc
+
+c = pc.causet(n=500, spacetime=pc.MinkowskiDiamond(2), seed=42)
+Q = pc.field("scalar", mass=1.0).on(c)
+W = Q.wightman()
+```
+
+## See also
+
+- [[docs/classes/field/pycauset.field.Field.md|Field]]
+- [[docs/classes/field/pycauset.field.State.md|State]]
+- [[guides/Field Theory.md|Field Theory guide]]

pycauset-0.6.2.dev16/documentation/docs/classes/field/pycauset.field.Field.md

@@ -0,0 +1,45 @@
+# pycauset.field.Field
+
+```python
+class Field(kind="scalar", *, mass=0.0, spin=0, scheme=None)
+```
+
+Set-independent field content (R2): the field's species — `kind`, `mass`, `spin`, and
+discretization `scheme` — independent of any background. You apply it to a background
+with `.on()`.
+
+## Parameters
+
+*   **kind** (*str*): The species. Only `"scalar"` is implemented; unknown kinds raise `NotImplementedError`.
+*   **mass** (*float*): The field mass. Defaults to 0.0 (massless).
+*   **spin** (*int*): Reserved for future species. Defaults to 0.
+*   **scheme**: Reserved for future discretization schemes.
+
+## Methods
+
+### on
+
+```python
+def on(self, background) -> CorrelatedField | ContinuumCorrelatedField
+```
+
+Applies the field to a background:
+
+*   `phi.on(causet)` → a [[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]] (the field + its Green's functions and vacuum two-point on that causet).
+*   `phi.on(spacetime)` → a [[docs/classes/field/pycauset.field.ContinuumCorrelatedField.md|ContinuumCorrelatedField]] (closed-form Green's functions on a continuum Minkowski spacetime).
+
+## Example
+
+```python
+import pycauset as pc
+
+phi = pc.field("scalar", mass=1.5)   # the Field, background-independent
+Q   = phi.on(causet)                 # a CorrelatedField on the causet
+```
+
+## See also
+
+- [[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]]
+- [[docs/classes/field/pycauset.field.State.md|State]]
+- [[docs/functions/pycauset.field.md|pc.field]]
+- [[guides/Field Theory.md|Field Theory guide]]

{pycauset-0.6.2.dev14 → pycauset-0.6.2.dev16}/documentation/docs/classes/field/pycauset.field.ScalarField.md

@@ -1,13 +1,18 @@
 # pycauset.field.ScalarField
 
 ```python
-class ScalarField(Field)
+class ScalarField(causet=None, mass=0.0, *, n=None, density=None, spacetime=None, seed=None, matrix=None)
 ```
 
 Represents a massive scalar field defined on a Causal Set.
 
 This class implements the generalized Retarded Propagator $K_R$ for a scalar field $\phi$ satisfying the Klein-Gordon equation on the discrete causal set structure.
 
+> **R1 back-compat.** The R2 field model is `Field → CorrelatedField → State` (see
+> [[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]]). `ScalarField`
+> is kept for back-compat and returns the R1 native matrix types (`TriangularFloatMatrix`,
+> `AntiSymmetricFloat64Matrix`).
+
 ## Constructor
 
 ```python

pycauset-0.6.2.dev16/documentation/docs/classes/field/pycauset.field.State.md

@@ -0,0 +1,60 @@
+# pycauset.field.State
+
+```python
+class State(correlated_field: CorrelatedField, config: np.ndarray)
+```
+
+A specific excitation of the vacuum — a coherent/classical field configuration over the causet, carrying the vacuum two-point function. Returned by `CorrelatedField.state(config)`.
+
+## Description
+
+For a Gaussian/coherent state with configuration `phi`:
+
+- `⟨φ⟩ = phi`
+- `⟨φφ⟩ = phi phiᵀ + W`
+- `⟨φ²⟩ = diag(W) + phi²`
+
+where `W` is the Sorkin–Johnston Wightman function.
+
+## Methods
+
+### field
+
+```python
+def field(self) -> np.ndarray
+```
+
+`⟨φ⟩` — the mean field configuration.
+
+### two_point
+
+```python
+def two_point(self) -> np.ndarray
+```
+
+`⟨φφ⟩ = phi phiᵀ + W`.
+
+### field_variance
+
+```python
+def field_variance(self) -> np.ndarray
+```
+
+`⟨φ²⟩ = diag(W) + phi²` (per-element fluctuation).
+
+## Example
+
+```python
+import numpy as np
+import pycauset as pc
+
+c = pc.causet(n=100, spacetime=pc.MinkowskiDiamond(2), seed=1)
+Q = pc.field("scalar", mass=1.0).on(c)
+state = Q.state(np.arange(c.n, dtype=float))
+vev_phi_sq = state.field_variance()
+```
+
+## See also
+
+- [[docs/classes/field/pycauset.field.CorrelatedField.md|CorrelatedField]]
+- [[guides/Field Theory.md|Field Theory guide]]