pic-autotune-control

pic-autotune-control is a Python virtual lab for photonic integrated-circuit autotuning. It models controller-visible detector observations, bounded actuator commands, measurement budgets, drift, crosstalk, device variation, and safety guards for closed-loop reacquisition experiments.

The current package is a stateful NumPy/SciPy lab and controller harness. SAX is pinned as the planned nominal circuit substrate for E001, but a SAX adapter has not been implemented and canonical E001 evidence has not been run.

LabSession -> controller -> bounded actuator commands -> noisy observations -> TuningResult

Current Status

Area	Status
Core lab	Ideal MZI/ring/mesh transfer helpers, actuator constraints, detector noise, thermal crosstalk, hidden drift, seeded variation, faults, and safety guards are implemented.
Controller surface	Measurement budgets, structured TuningResult objects, coordinate search, random search, lock-in/dither control, inverse-Jacobian control, Kalman-integrated control, inverse-distance finite-grid control, and MPC primitives are implemented.
Public API boundary	Non-oracle controllers interact through LabSession; hidden simulator state remains separate from controller-visible observations.
Upstream substrate	SAX is pinned in UPSTREAM.md, not vendored, not a required dependency, and not yet wired into the lab.
E001	Preregistered in experiments/e001/experiment.md. Canonical measurement-budgeted SAX evidence has not been run yet.
Local smoke	./scripts/reproduce_e001.sh smoke runs two current-lab examples and checks that they converge. These are smoke checks, not benchmark evidence.
Canonical run	./scripts/reproduce_e001.sh canonical --dry-run prints the preregistered plan. Full execution is blocked until the SAX adapter, equivalence tests, and result artifact writer exist.

Question

Which controller reacquires a photonic operating point after an unobserved thermal shift using the fewest detector samples and actuator commands under model mismatch?

Method

The planned E001 comparison evaluates:

• coordinate search;
• lock-in/dither control;
• nominal differentiable optimization using the unperturbed SAX model;
• estimated inverse-Jacobian control;
• an oracle hidden-state controller as a diagnostic upper bound only;
• a treatment that updates a local model or Jacobian from detector observations.

Promotion requires improved sample efficiency in more than one mismatch regime without degrading worst-quartile final error or stability. Until E001 is run, the included controllers should be read as implemented baselines and primitives, not as validated winners.

Install

Requires Python 3.11 or newer.

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Optional plotting helpers require:

python -m pip install -e ".[plots]"

Reproduce

Run local acceptance checks:

ruff check .
python -m pytest

Run a deterministic current-lab example:

python examples/coordinate_descent_mzi.py

Run the E001 smoke path:

./scripts/reproduce_e001.sh smoke

Inspect the canonical E001 plan:

./scripts/reproduce_e001.sh canonical --dry-run

Canonical E001 execution intentionally exits until the SAX adapter, equivalence tests, and result artifact writer are implemented.

Minimal API Example

from pic_autotune_control.controllers import (
    CoordinateDescentController,
    MeasurementBudget,
)
from pic_autotune_control.experiments import create_single_mzi_power_lab

scenario = create_single_mzi_power_lab()


def bar_power_error(observation):
    return abs(observation.readings[scenario.bar_detector].value - 1.0)


controller = CoordinateDescentController(
    actuators=[scenario.actuator_name],
    detectors=list(scenario.detector_names),
    candidates=[0.0, 0.25, 0.5, 0.75, 1.0],
    objective=bar_power_error,
    samples_per_measurement=4,
)

result = controller.tune(
    scenario.lab,
    MeasurementBudget(max_measurements=80),
)

print(result.converged, result.final_score, result.actuator_state)

Implementation Map

Path	Purpose
src/pic_autotune_control/simulation/	Stateful lab API, crosstalk, drift, variation, and faults.
src/pic_autotune_control/devices/	Phase shifters, actuator constraints, detector models, and hysteresis.
src/pic_autotune_control/circuits/	Local NumPy/SciPy photonic transfer helpers used by the current smoke path.
src/pic_autotune_control/controllers/	Controller protocols, baselines, estimators, lock-in, inverse-Jacobian, finite-grid, and MPC primitives.
src/pic_autotune_control/estimation/	Kalman-style and particle-filter state-estimation helpers.
src/pic_autotune_control/identification/	Crosstalk and Jacobian identification utilities.
src/pic_autotune_control/benchmarks/	JSON-compatible aggregation and leaderboard helpers.
src/pic_autotune_control/reporting/	Markdown reports and optional PNG plotting helpers.
experiments/e001/	Preregistered measurement-budgeted reacquisition experiment and smoke/canonical configs.
docs/verification.md	Current acceptance-check surface.

Historical learning and loop modules remain compatibility surfaces. They are not part of the current PhotonLock headline.

Evidence Boundary

Current examples and tests show deterministic local lab behavior, API contracts, and smoke-path convergence. They do not establish controller superiority under SAX-backed model mismatch.

E001 has not produced canonical results yet. Promotion of controller claims requires the SAX adapter, ideal-circuit equivalence tests, fixed controller and mismatch configs, raw run records, deterministic summaries, representative traces, hidden-state versus public-observation checks, and explicit measurement/actuation cost accounting.

Limitations

See docs/limitations.md. In short:

• SAX is pinned but not integrated;
• smoke examples are not canonical benchmark evidence;
• the lab is a virtual harness, not a hardware driver or PDK-backed simulator;
• the oracle controller is a diagnostic upper bound only;
• learning and loop modules are compatibility surfaces, not the current public claim.

License

MIT. See LICENSE.