swc-runtime 0.4.1

TrueLoop Compute client with Envelope V2 assessment

swc-runtime - TrueLoop Compute client

This is the thin, standard-library client for the hosted TrueLoop runtime. The private update law remains server-side. Runtime calls keep the substrate-agnostic start → measure → step → end contract; Envelope V2 separately describes the application, substrate, hardware timing, coupling structure, and evidence boundary.

Install

python -m pip install swc-runtime

For a local/manual installation, download the reviewed client bundle, verify HASHES.sha256, and install its wheel:

python -m pip install ./swc_runtime/dist/swc_runtime-*-py3-none-any.whl

For source-only manual use, place the bundled swc/ folder beside your code.

Runtime quickstart

from swc import SWCOptimizer

opt = SWCOptimizer(license_key="EVAL-...", n=len(x0), mode="regulation", target=target)
x = opt.start(x0)
for _ in range(rounds):
    x = opt.step(measure(x), target=target)
opt.end()

The legacy jacobian= constructor argument is reserved and deprecated. The hosted runtime never consumed it, and this client no longer transmits it. Supplying it emits a nonfatal warning and does not change hosted execution or install a new controller.

Envelope V2

assess_envelope() separates applicability from performance:

• DECLINE with structural_precondition means a checkable structural condition blocks use.
• EVIDENCE with measured_evidence cites the nearest measured cell and its numbers. It is neutral, not a performance forecast.
• MARGINAL with no_structural_bar means no structural condition blocks use and no measured cell matches. Run a race.

check_envelope() remains a verdict-string compatibility method. It can now return "EVIDENCE" as the neutral value for a measured cell.

from swc import SWCOptimizer, EnvelopeProfile

opt = SWCOptimizer(license_key="EVAL-...", n=4096, mode="regulation")
profile = EnvelopeProfile(
    application="photonic.mesh.regulation",
    substrate="photonic",
    mode="regulation",
    n_controls=4096,
    n_measurements=4096,
    measurement={
        "shape": "vector", "parallel": True, "direction_rich": True,
        "action_consistent": True, "objective_observable": True,
        "semantics": "full_vector_residual", "noise_sigma": 0.02,
    },
    plant={
        "drifting": True, "drift_per_round": 0.01, "locally_monotone": True,
        "retainable_configuration": True, "target_type": "vector_setpoint",
    },
    coupling={
        "present": True, "structure": "banded", "bandwidth": 3,
        "normalized_mass": 0.3, "conditioning_known": False,
    },
    hardware={"parallel_readout": True, "physical_hardware": False},
    baseline={"type": "unknown", "tuned": False, "model_access": "none",
              "demonstrated_performance": "unknown"},
    budget={"measurements_per_round": 1, "total_measurements": 300,
            "rounds": 300},
    evidence_profile="photonic.mesh.regulation.banded.v1",
)
report = opt.assess_envelope(profile)
assert report["verdict"] == "EVIDENCE"
assert report["evidence_tier"] == "measured_evidence"
print(report["evidence"]["measured_numbers"])

Legacy Regime requests remain accepted:

from swc import Regime
verdict = opt.check_envelope(Regime(drifting=True, coupled_plant=True,
                                    have_calibration=False,
                                    per_channel_error=True))

Unknown coupling structure is MARGINAL, not an automatic decline. Absence of calibration alone never triggers DECLINE.

Pilot race

Applicability can be checked from structure. Performance is measured on your plant, never forecast. race() alternates the hosted runtime and a reference arm on the same live plant until both residual histories plateau:

def measure_for_race(configuration):
    measurement = measure(configuration)
    residual = rms_error(measurement, target)
    return {"measurement": measurement, "residual": residual}

opt = SWCOptimizer(
    license_key="EVAL-...", n=len(x0),
    mode="regulation", target=target,
)
result = opt.race(
    "integrator",
    1.25,
    measure=measure_for_race,
    x0=x0,
    plateau_window=20,
    plateau_slope=1e-3,
    plateau_patience=3,
)
print(result["decision"], result["steady_state_advantage"])
print(result["acquisitions"])

The advantage is the reference steady-state residual divided by the runtime steady-state residual. min_advantage is your economic threshold. At or above it the result is CONTINUE; below it the result is ABORT and recommends the reference. If both arms do not plateau, the result is INCONCLUSIVE and no magnitude is reported.

In regulation mode the default reference is a tuned integrator. In optimization mode it is tuned SPSA. You may pass your own object with start(x0) and step(configuration, measurement, score=None, target=None).

The reference arm consumes acquisitions. The report calls these reference_tax and includes them in the total. The race is a paid diagnosis, not a free probe. A stable early direction checkpoint can guide the pilot. If that direction later reverses, direction_reliable_early is false and the report discloses the reversal. A short fixed horizon can overstate magnitude, so it is never used for the magnitude estimate. Magnitude is reported only after convergence.

Evidence boundary

The mesh scaling evidence uses a simulated nonlinear photonic-mesh plant with the live production TrueLoop runtime. Exact registered cells are M=0.3 at n=64, 256, 512, 1024, and 4096, plus M=0.7 only at n=256, with ±3 banding, measurement noise sigma 0.02, drift sigma 0.01 radians per round, three seeds, and 300 rounds.

Physical photonic-hardware transfer remains unverified. The n=4096, M=0.7 combination was not tested. Discrete cells are not a continuous performance guarantee.

Full docs: https://trueloopcompute.com/docs/envelope