Chimera Control API

The scpn_quantum_control.chimera_control package is the public BL-60 facade for finite synthetic chimera generation, nested coherence observables, analytic hierarchy targets, unapplied phase proposals, topology-constraint composition, and deterministic evidence custody.

All arrays returned by BL-60 custody objects are copied and read-only. The API is local and simulator-only: it performs no provider submission, QPU or hardware execution, external actuation, deployment, or biological inference.

For a task-oriented walkthrough and measured evidence, read Chimera and Multiscale Synchronisation Control.

Hierarchy and target contracts

scpn_quantum_control.chimera_control.schema

Immutable hierarchy and target contracts for synthetic chimera control.

SyntheticRegime

Bases: str, Enum

Named finite synthetic regimes served by the two-population generator.

CHIMERA_TRANSIENT uses the Abrams–Mirollo–Strogatz–Wiley strong- intra/weak-inter population configuration. SYNCHRONISED_CONTROL is a deterministic contrast with stronger inter-population coupling. The names describe generator configurations, not certified dynamical attractors.

HierarchyLevel dataclass

One named partition of oscillator indices.

Parameters

name Stable non-empty identifier used by targets and evidence records. communities Disjoint non-empty oscillator-index groups. Coverage and index bounds are validated by :class:MultiscaleHierarchy because they depend on the hierarchy's node count.

MultiscaleHierarchy dataclass

A complete fine-to-coarse nested partition hierarchy.

Parameters

node_count Number of oscillators. Every level must partition exactly range(node_count). levels Levels ordered from fine to coarse. Every community in a finer level must be wholly contained in exactly one community at the next level.

Raises

ValueError If names repeat, a level omits or adds a node, an index is negative, or adjacent levels are not nested partitions.

level_names property

Return fine-to-coarse level names.

level(name)

Return the level called name or raise KeyError.

The lookup is exact and case-sensitive so evidence records cannot silently bind a target to a different scale.

HierarchyTarget dataclass

Order-parameter targets and weight for one hierarchy level.

Parameters

level_name Exact :class:HierarchyLevel name. order_parameters One desired Kuramoto coherence magnitude in [0, 1] per community. weight Non-negative multiplier used by the composed objective.

ChimeraControlSpecification dataclass

Validated hierarchy and differentiable order-parameter targets.

Every target name must resolve to exactly one hierarchy level and must supply one value per community. A level may be omitted deliberately, but a level cannot have two competing target rows.

two_population_hierarchy(population_size)

Build the canonical two-population and whole-ensemble hierarchy.

Parameters

population_size Oscillators in each population; must be at least two.

Returns

MultiscaleHierarchy A population level with two equally sized communities followed by an ensemble level containing every oscillator.

Synthetic generator

scpn_quantum_control.chimera_control.synthetic

Exact finite-N two-population Kuramoto-Sakaguchi trajectory generation.

The generator integrates

.. math::

\dot\theta_j = \sum_{k\ne j} K_{jk} \sin(\theta_k-\theta_j-\alpha)

with the production :func:oscillatools.accel.sakaguchi_force and classical RK4. The chimera configuration follows Abrams, Mirollo, Strogatz, and Wiley, PRL 101, 084103 (2008), DOI 10.1103/PhysRevLett.101.084103. A finite-N run is labelled a transient configuration, never a proof of an infinite-population attractor.

SyntheticChimeraConfig dataclass

Configuration for an exact two-population synthetic trajectory.

Parameters

regime Explicit synthetic regime label. population_size Oscillators per population; the total node count is twice this value. dt Positive RK4 integration step. steps Number of RK4 steps; output includes the initial state. settle_steps Initial samples excluded from diagnostics. beta beta = pi/2 - alpha; alpha is the Sakaguchi phase lag. intra_coupling, inter_coupling Population-normalised coupling strengths before division by population_size. seed NumPy generator seed for the publication-style initial condition.

frustration property

Return Sakaguchi phase lag alpha = pi/2 - beta.

for_regime(regime, *, population_size=64, seed=20260702) classmethod

Return the frozen reference configuration for regime.

The chimera row uses mu=0.75, nu=0.25 and 1200 steps. The synchronised contrast uses mu=0.6, nu=0.4 and 700 steps. Both use dt=0.05, beta=0.1, and 200 settle steps.

SyntheticChimeraRun dataclass

Immutable trajectory, coupling, hierarchy, and settled diagnostics.

phases has shape (steps + 1, 2 * population_size) and times has shape (steps + 1,). diagnostics is evaluated over phases[settle_steps:] at the population scale. Arrays are copied and read-only; content_digest binds configuration and numerical custody.

settled_phases property

Return a read-only view of the post-settle trajectory.

build_two_population_coupling(config)

Return the symmetric population-normalised block coupling matrix.

Off-diagonal within-population entries are intra_coupling / N and between-population entries are inter_coupling / N. The diagonal is exactly zero because self-coupling is excluded by the force definition.

generate_two_population_chimera(config=None)

Generate one deterministic finite-N two-population trajectory.

Parameters

config Validated generator configuration. None selects the reference chimera-transient configuration.

Returns

SyntheticChimeraRun Immutable full trajectory, settled population diagnostics, hierarchy, block coupling, source label, and SHA-256 custody digest.

Notes

The first population starts near coherence and the second uniformly on the circle. Natural frequencies are identical and zero. A generated row is a finite synthetic regression fixture, not a physical or biological model.

Multiscale observables

scpn_quantum_control.chimera_control.observables

Hierarchy-aware order parameters composed from oscillatools diagnostics.

LevelOrderParameterSummary dataclass

Order-parameter diagnostics for one hierarchy level.

Attributes

level_name Exact hierarchy level identifier. community_order_parameters Array of shape (time, communities) with coherence magnitudes. mean_by_community Time mean of each community column. chimera_index Mean across-time population variance across communities, matching Shanahan's chimera index. It is zero for a single community. community_metastability Mean across-community population variance through time.

MultiscaleOrderParameterReport dataclass

Immutable order-parameter report over every hierarchy level.

global_order_parameter has one value per input time sample. levels preserves the hierarchy's fine-to-coarse order. content_digest binds the numerical trajectory and hierarchy definition.

level(name)

Return the report row named name or raise KeyError.

measure_multiscale_order_parameters(phases, hierarchy)

Measure global and community coherence at every hierarchy level.

Parameters

phases Finite phase trajectory of shape (time, hierarchy.node_count) in radians. hierarchy Complete fine-to-coarse nested partition definition.

Returns

MultiscaleOrderParameterReport Read-only global coherence plus per-level Shanahan chimera and community-metastability summaries.

Differentiable targets and proposals

scpn_quantum_control.chimera_control.objectives

Differentiable hierarchy targets composed from existing analytic terms.

PhaseControlProposal dataclass

One unapplied analytic-gradient phase proposal.

Attributes

original_value, proposed_value Objective values before and after the accepted backtracking step. step_size Accepted scalar gradient step; zero if no strict decrease was found. backtracks Number of halvings attempted. accepted Whether the proposal strictly reduced the objective. phase_delta, proposed_phases Read-only vectors. No external or persistent system is mutated. claim_boundary Explicit synthetic and non-actuating interpretation boundary.

build_chimera_control_objective(specification, *, min_order_parameter=1e-12)

Build one analytic cluster-order term per non-zero hierarchy target.

Parameters

specification Validated nested hierarchy and per-community target rows. min_order_parameter Positive singularity guard forwarded to the existing analytic cluster-order gradient.

Returns

ComposedPhaseObjective Weighted objective whose term names are chimera_<level_name>_target and whose gradients come from :func:cluster_synchronisation_target_term.

Raises

ValueError If the threshold is not finite and positive or every target weight is zero.

propose_phase_control_step(objective, phases, *, initial_step_size=0.25, max_backtracks=16)

Propose an unapplied backtracking analytic-gradient phase step.

The routine evaluates the supplied objective at a single phase vector, halves initial_step_size until a strict finite decrease is found, and returns the candidate without mutating phases or any external system. If the gradient is zero or no strict decrease is found, accepted is false and the returned candidate equals the input.

Parameters

objective Composed phase objective, normally from :func:build_chimera_control_objective. phases Finite one-dimensional phase vector matching the objective width. initial_step_size Finite positive first backtracking step. max_backtracks Number of candidate evaluations after the initial point; at least one.

Topology-constraint bridge

scpn_quantum_control.chimera_control.topology

Hierarchy summaries around the existing topology-constraint ledger.

HierarchyCouplingSummary dataclass

Mean off-diagonal coupling within and between communities at one level.

mean_within is None when every community is a singleton. mean_between is None for a one-community level because that scale has no between-community edge set. Means are descriptive and do not imply learned, causal, hardware-realised, or dynamically stable couplings.

TopologyProjectionReport dataclass

Immutable before/after report from TopologyConstraintLedger.project.

The ledger may report a remaining algebraic-connectivity violation because its projection routine does not manufacture connectivity. This record is a local candidate audit, not a stability, controllability, PH, DLA, hardware, or deployment certificate.

project_chimera_coupling(candidate, hierarchy, ledger)

Project and audit one hierarchy-sized coupling candidate.

Parameters

candidate Finite square matrix with order hierarchy.node_count. hierarchy Partition hierarchy used only for descriptive within/between summaries. ledger Existing SCPN topology policy that owns projection and violation semantics.

Returns

TopologyProjectionReport Read-only original/projected matrices, ledger violation magnitudes, multiscale coupling summaries, and a SHA-256 digest.

Evidence contracts

scpn_quantum_control.chimera_control.evidence

Deterministic BL-60 evidence construction, rendering, and byte custody.

ChimeraSupportRow dataclass

One BL-60 scope row with evidence and an explicit non-claim.

to_dict()

Return a JSON-ready support row.

SyntheticRegimeEvidence dataclass

Measured finite-trajectory evidence for one synthetic regime.

Population statistics contain two values in canonical population order. Objective fields describe one unapplied analytic-gradient proposal evaluated at the last settled phase vector.

to_dict()

Return JSON-ready regime metrics without rounding.

ChimeraMultiscaleEvidence dataclass

Complete deterministic BL-60 evidence payload.

The payload binds the exact synthetic configurations, two measured regime rows, finite-difference agreement, topology-ledger before/after violations, support matrix, claim boundary, and a SHA-256 content digest.

to_dict()

Return the canonical JSON-ready payload.

build_chimera_multiscale_evidence(*, population_size=64)

Build deterministic finite synthetic evidence for both frozen regimes.

population_size=64 is the committed configuration. The function runs no provider, QPU, hardware, network, optimiser service, or external action. It integrates two local trajectories, evaluates existing analytic objectives, finite-differences one gradient, and projects one local coupling candidate through the existing topology ledger.

render_chimera_multiscale_markdown(evidence)

Render the evidence payload as deterministic reviewer-facing Markdown.

write_chimera_multiscale_evidence(evidence, *, json_path, markdown_path, check=False)

Write or byte-check deterministic JSON and Markdown evidence files.

In check mode both files must already exist and match the rendered bytes exactly; a mismatch raises RuntimeError and no file is changed. In write mode parent directories are created and both UTF-8 files end with one newline.