input [x] -> [V^T unitary MZI mesh] -> [Sigma attenuators] -> [U unitary MZI mesh] -> detector [y]

What the project validates

An optical circuit does not execute electronic instructions one multiply at a time. Instead, the multiplications and sums for each output element are mapped to complex amplitude encoding, interference, per-channel scaling, and coherent readout. The project closes four parts of that chain:

1. Compilation: any real matrix can be decomposed by SVD into two orthogonal transforms and non-negative scaling, then compiled into two MZI meshes and one VOA bank.
2. Propagation: after encoding an input vector as coherent complex amplitudes, ideal propagation satisfies E = (M @ x) / gain; the same relation holds for batched inputs.
3. Readout: coherent detection with a local oscillator recovers signed outputs that agree with M @ x to floating-point precision.
4. Sensitivity: static phase-control offsets, per-sample phase jitter, insertion loss, VOA setting error, and equivalent readout noise can be injected and measured independently.

This establishes feasibility inside the mathematical mapping, software implementation, and simplified linear optical circuit model. It does not by itself establish the energy, latency, precision, scale, or manufacturability of a physical chip.

Animation

The left panel shows the executing code with the active line highlighted. The right panel shows what that line does inside the optical circuit. Color encodes phase (red at 0 degrees, cyan at 180 degrees), while bar height encodes amplitude.

python -m pip install "photonic-mzi[viz]"
python -m photonic_mzi

The animation has nine stages:

Stage 2: matrix elimination and MZI parameter programming	Stage 4: interference and energy conservation in one MZI
Stage 1: M = U · Sigma · V^T	Stage 8: NumPy, ideal photonic, and simplified non-ideal results

Installation

python -m pip install "photonic-mzi[viz]"

For the NumPy-only compute kernel without the animation:

python -m pip install photonic-mzi

To develop from a source checkout, editable installs require pip 21.3 or later because this is a pyproject.toml-only package using PEP 660:

python -m pip install --upgrade pip && pip install -e ".[dev]"

You can also run directly from the checkout:

PYTHONPATH=src python -m photonic_mzi

Usage

import numpy as np
from photonic_mzi import PhotonicMatrixProcessor

M = np.random.randn(8, 5)  # rectangular matrices are supported
opu = PhotonicMatrixProcessor(M, seed=42)

x = np.random.randn(5)
y = opu.read_coherent(x)  # agrees with M @ x to about 1e-15
Y = opu.read_coherent(np.random.randn(5, 256))  # batched inputs

E = opu.optical_field(x)  # pre-detection field: (M @ x) / opu.gain when ideal
print(opu.report())

Add the simplified non-ideality model:

from photonic_mzi import NoiseModel

noise = NoiseModel(
    fab_theta=0.02,       # static phase-control offset; calibratable in the ideal model
    drift_theta=0.005,    # independent per-sample phase jitter
    mzi_loss_db=0.2,      # insertion loss per MZI
    voa_rel_err=0.01,
    detector_snr_db=40,   # post-detection equivalent relative AWGN
)
opu = PhotonicMatrixProcessor(M, noise=noise, seed=7)
opu.read_coherent(x, ideal=False)
opu.calibrate()
opu.read_coherent(x, ideal=False)

The two readout methods represent different detection schemes:

Examples

python examples/01_hello_photonic.py
python examples/02_noise_and_calibration.py
python examples/03_neural_layer.py

The third example uses a synthetic, well-separated classification problem. Its accuracy under a selected noise model must not be generalized to other models, datasets, or time-correlated thermal drift.

Tests and benchmark

pytest -m "not slow"
python benchmarks/bench_decomposition.py

The fast suite contains 128 tests; the full suite contains 133 tests, including all-frame glyph checks and GIF export. Coverage includes degenerate and structured matrices, random dense and rectangular matrices, batching, energy conservation, noise semantics, detection boundaries, calibration boundaries, and input validation.

Known limitations

• The implementation uses a triangular Reck mesh, not a rectangular Clements mesh. Both use N(N-1)/2 MZIs, but Clements has lower optical depth and is usually more tolerant of uniform loss.
• fab_* models additive phase-control offsets, not beam-splitter fabrication errors that may restrict the reachable splitting ratio.
• drift_* is independent per-input phase jitter; it does not model temporal or spatial correlation or thermal crosstalk.
• detector_snr_db is post-detection equivalent AWGN; there is no detailed shot-noise, local-oscillator, responsivity, TIA, or bandwidth model.
• mode_mzi_count() is a topology proxy, not end-to-end path tracing.
• Forward propagation still loops over MZIs in Python; devices in one mesh layer could be vectorized.
• Input modulators, laser power, DAC/ADC, system energy and latency, wavelength dependence, polarization, nonlinearities, and device crosstalk are not modeled.

See Model and validation notes for the full scope.

References

• Reck et al., Experimental realization of any discrete unitary operator, PRL 73, 58 (1994)
• Clements et al., Optimal design for universal multiport interferometers, Optica 3, 1460 (2016)
• Shen et al., Deep learning with coherent nanophotonic circuits, Nature Photonics 11, 441 (2017)

License

MIT