Synchronisation witness API

Modules:

• scpn_quantum_control.phase.synchronisation_witness
• scpn_quantum_control.benchmarks.sync_witness_evidence

Importing either module performs no provider call or filesystem write.

Numerical functions

• harmonic_order_parameter(phases, *, harmonic=1) -> float returns a Daido order-parameter magnitude.
• geodesic_phase_distance_matrix(phases) -> numpy.ndarray returns pairwise circular arc distances.
• vietoris_rips_persistence(distance, *, max_dimension=1) -> dict returns birth/death pairs for dimensions zero and, when requested, one.
• betti_curve(persistence_pairs, thresholds) -> numpy.ndarray counts classes alive at each threshold.
• phase_cloud_synchronisation_witness(...) -> SyncWitnessRecord combines the numerical measures and checks caller-supplied regime bounds.

All array inputs are validated for shape and finite values. Thresholds must be non-negative and strictly increasing. Distance matrices must be square, symmetric, non-negative, and zero-diagonal.

Evidence records

SyncWitnessCase stores a deterministic input and its acceptance bounds. SyncWitnessRecord stores the computed order parameters, uncertainty, Betti curves, persistence diagrams, component count, dominant loop lifetime, and verdict. SyncWitnessBoundaryRow records a deliberately unsupported route. SyncWitnessSuiteResult aggregates records and exposes passed, records_for_regime(), and to_dict().

default_sync_witness_cases() returns the three reference regimes. run_sync_witness_suite(cases=None) evaluates either those defaults or a non-empty caller-supplied sequence.

Artefact writer

sync_witness_evidence_payload() returns the JSON-oriented evidence object. render_sync_witness_evidence_markdown() renders its record table and, when present, its boundary table. write_sync_witness_evidence_artifact() writes matching .json and .md destinations and returns SyncWitnessEvidenceArtifact metadata.

Full autodoc

Order-parameter and persistent-homology synchronisation witnesses.

Provides bounded synchronisation witnesses over synthetic phase clouds: harmonic Kuramoto order parameters, exact Vietoris--Rips persistent homology (Betti curves and persistence diagrams in dimensions 0 and 1) over geodesic phase distances, bootstrap uncertainty on the order parameter, and deterministic synchronised, desynchronised, and clustered reference regimes. The persistence computation is the standard reduction of the boundary matrix over GF(2) and is exact for the small phase clouds used here; it is not an accelerated timing kernel, hardware phase tomography, or high-dimensional manifold inference.

SYNC_WITNESS_EVIDENCE_CLASS = 'functional_non_isolated' module-attribute

Evidence class for local synthetic synchronisation-witness runs.

SYNC_WITNESS_CLAIM_BOUNDARY = 'bounded synthetic phase-cloud synchronisation witnesses (harmonic Kuramoto order parameters and exact Vietoris-Rips persistent homology in dimensions 0 and 1 over geodesic phase distances) with known reference regimes; not hardware phase tomography, provider execution, isolated timing, or high-dimensional manifold inference' module-attribute

Claim boundary attached to synchronisation-witness records.

SyncWitnessCase dataclass

Deterministic synchronisation-witness reference case.

Parameters

case_id : str Stable identifier used in evidence artefacts. regime : str Reference regime: "synchronised", "desynchronised", or "clustered". phases : numpy.ndarray Base phase cloud in radians. thresholds : numpy.ndarray Strictly increasing filtration thresholds for the Betti curves. reference_scale : float Filtration scale at which the persistent component count is read. noise_std : float Standard deviation of the bootstrap phase perturbation. n_bootstrap : int Number of bootstrap perturbations used for the order-parameter uncertainty. 0 disables the bootstrap. seed : int Seed for the deterministic bootstrap perturbation. min_order_parameter : float Lower bound the first-harmonic order parameter must satisfy. max_order_parameter : float Upper bound the first-harmonic order parameter must satisfy. expected_components : int Expected persistent component count at reference_scale. min_dominant_h1 : float Lower bound on the dominant H1 persistence lifetime. max_dominant_h1 : float Upper bound on the dominant H1 persistence lifetime.

__post_init__()

Validate and detach mutable arrays from the caller.

to_dict()

Return a JSON-ready case description.

SyncWitnessRecord dataclass

Known-regime synchronisation-witness certificate.

__post_init__()

Validate the certificate and detach its array fields.

to_dict()

Return JSON-ready synchronisation-witness evidence.

SyncWitnessBoundaryRow dataclass

Fail-closed boundary for non-covered synchronisation-witness routes.

__post_init__()

Reject incomplete or falsely closed boundary declarations.

to_dict()

Return a JSON-ready boundary row.

SyncWitnessSuiteResult dataclass

Result of a bounded synchronisation-witness evidence suite.

passed property

Whether every witness case satisfied its regime bounds.

__post_init__()

Require records, explicit boundaries, and evidence metadata.

records_for_regime(regime)

Return witness records for one reference regime.

to_dict()

Return JSON-ready suite evidence.

harmonic_order_parameter(phases, *, harmonic=1)

Return the magnitude of the harmonic-th Kuramoto order parameter.

Parameters

phases : array_like One-dimensional array of oscillator phases in radians. harmonic : int, optional Positive harmonic index m of the Daido order parameter |mean(exp(i * m * phases))|. harmonic=1 recovers the global Kuramoto order parameter; harmonic=2 witnesses two-cluster (anti-phase) structure.

Returns

float The order-parameter magnitude in [0, 1].

geodesic_phase_distance_matrix(phases)

Return the pairwise geodesic (arc-length) phase-distance matrix.

Parameters

phases : array_like One-dimensional array of oscillator phases in radians.

Returns

numpy.ndarray Symmetric zero-diagonal matrix of arc distances in [0, pi] between phases wrapped onto the unit circle.

vietoris_rips_persistence(distance, *, max_dimension=1)

Return exact Vietoris--Rips persistence pairs by homology dimension.

The boundary matrix over the filtered Rips complex is reduced over GF(2) with the standard lowest-one algorithm. Essential classes (never filled by a higher simplex) are reported with an infinite death. The result is exact for the small point clouds used by the synchronisation-witness suite.

Parameters

distance : array_like Symmetric zero-diagonal non-negative pairwise distance matrix. max_dimension : int, optional Highest homology dimension to certify. 0 builds edges only (H0); 1 also builds triangles so that H1 loops can be filled.

Returns

dict of int to numpy.ndarray Mapping from homology dimension to an (k, 2) array of (birth, death) pairs. Deaths may be inf for essential classes.

betti_curve(persistence_pairs, thresholds)

Return the Betti curve of one homology dimension over thresholds.

Parameters

persistence_pairs : array_like (k, 2) array of (birth, death) pairs for a single dimension. An empty array yields an all-zero curve. thresholds : array_like Strictly increasing non-negative filtration thresholds.

Returns

numpy.ndarray Integer Betti number alive at each threshold, birth <= t < death.

phase_cloud_synchronisation_witness(phases, *, thresholds, reference_scale, case_id='phase_cloud', regime='synchronised', noise_std=0.0, n_bootstrap=0, seed=0, min_order_parameter=0.0, max_order_parameter=1.0, expected_components=1, min_dominant_h1=0.0, max_dominant_h1=float(np.pi))

Compute the synchronisation witness for one phase cloud.

Parameters

phases : array_like One-dimensional array of oscillator phases in radians. thresholds : array_like Strictly increasing filtration thresholds for the Betti curves. reference_scale : float Filtration scale at which the persistent component count is read. case_id : str, optional Stable identifier used in the returned record. regime : str, optional Reference regime the witness is checked against. noise_std : float, optional Standard deviation of the bootstrap phase perturbation. n_bootstrap : int, optional Number of bootstrap perturbations for the order-parameter uncertainty. seed : int, optional Seed for the deterministic bootstrap. min_order_parameter, max_order_parameter : float, optional Inclusive bounds the first-harmonic order parameter must satisfy. expected_components : int, optional Expected persistent component count at reference_scale. min_dominant_h1, max_dominant_h1 : float, optional Inclusive bounds on the dominant H1 persistence lifetime.

Returns

SyncWitnessRecord The order-parameter and persistent-homology witness certificate.

default_sync_witness_cases()

Return deterministic synchronisation-witness reference cases.

sync_witness_boundary_rows()

Return fail-closed synchronisation-witness boundary rows.

run_sync_witness_suite(cases=None)

Run the deterministic synchronisation-witness evidence suite.

Benchmark artefacts for bounded synchronisation-witness runs.

SyncWitnessEvidenceArtifact dataclass

Metadata for written synchronisation-witness artefacts.

to_dict()

Return JSON-ready artifact metadata.

sync_witness_evidence_payload(suite=None, *, artifact_id='sync-witness-evidence-local')

Return a bounded synchronisation-witness evidence payload.

render_sync_witness_evidence_markdown(payload)

Render a synchronisation-witness payload as bounded Markdown evidence.

write_sync_witness_evidence_artifact(output_path, *, markdown_path=None, suite=None, artifact_id='sync-witness-evidence-local')

Write JSON and Markdown synchronisation-witness artefacts.