Metadata-Version: 2.4
Name: sqzcomb
Version: 0.12.0
Summary: Squeezed light in Kerr microcombs: Lugiato-Lefever steady states, linearized quantum noise, and detected output spectra
Author-email: "Tanvir M. Mahim" <tanvir.mahim@bracu.ac.bd>
License: Apache-2.0
Project-URL: Homepage, https://tanvir-mahmud-mahim.github.io/software/
Project-URL: Repository, https://github.com/TaN-MM-Org/sqzcomb
Project-URL: Issues, https://github.com/TaN-MM-Org/sqzcomb/issues
Project-URL: Changelog, https://github.com/TaN-MM-Org/sqzcomb/releases
Keywords: squeezed light,microcomb,Kerr,Lugiato-Lefever,quantum optics,homodyne
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.10
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: interop
Requires-Dist: qutip>=4.7; extra == "interop"
Dynamic: license-file

# sqzcomb

[![PyPI](https://img.shields.io/pypi/v/sqzcomb)](https://pypi.org/project/sqzcomb/) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22015375-blue)](https://doi.org/10.5281/zenodo.22015375) [![tests](https://github.com/TaN-MM-Org/sqzcomb/actions/workflows/ci.yml/badge.svg)](https://github.com/TaN-MM-Org/sqzcomb/actions)

Quantum noise in Kerr microcombs, computed end to end: from the
classical field circulating in the ring, through the quantum
fluctuations around it, to **the noise a detector on the output fiber
would actually report**. The package exists because squeezing inside
the cavity is not the observable -- what leaves the extraction port
is -- and the coupling that maximizes one does not maximize the
other.

## Install

```
pip install sqzcomb              # numpy + scipy
pip install sqzcomb[interop]     # adds the QuTiP adapter
```

For development: clone the repository and `pip install -e .[test]`.

## Quick start, from laboratory numbers

The package computes in the standard normalized units of the
Lugiato-Lefever equation; `RingSpec` is the exact dictionary from the
numbers a lab actually has (v0.9):

```python
import sqzcomb as sc

ring = sc.RingSpec(kappa_hz=100e6, eta_esc=0.8, g0_hz=10.0,
                   lambda_pump_m=1.55e-6,
                   reference="our device, linewidth scan 2026-09")
F = sc.normalized_pump(ring, power_w=2e-3)       # pump amplitude
P_th = sc.threshold_power(ring, alpha=1.0)       # comb threshold, W
```

and `fit_noise_spectra` runs the model backward from measured data:
feed it the squeezed and antisqueezed homodyne traces (dB relative to
shot noise) and it returns the pump parameter, total detection
efficiency and cavity linewidth with uncertainties. Identifiability
is arithmetic, enforced rather than hoped for: one quadrature is a
single Lorentzian -- two shape numbers for three unknowns -- so the
fit requires both traces or an independently measured linewidth, and
refuses otherwise; an antisqueezed trace below shot noise (impossible
in this model) is refused too.

A minimal prediction in normalized units:

```python
import numpy as np
from sqzcomb import (lle_evolve, fluctuation_matrix,
                     output_quadrature_variance, squeezing_db)

psi = lle_evolve(np.full(256, 0.05 + 0j), F=1.2, alpha=0.8,
                 dispersion=(-0.02,), t_end=300.0)
M, modes = fluctuation_matrix(psi, alpha=0.8, dispersion=(-0.02,))
i0 = int(np.where(modes == 0)[0][0])
v = output_quadrature_variance(M, eta=0.5, omega=0.0,
                               mode_index=i0, n_modes=modes.size)
print(squeezing_db(v), "dB relative to vacuum")
```

Conventions, stated once and stable: time in photon lifetimes,
eta = kappa_ex / kappa, vacuum variance 1/2 (xxpp export uses
hbar = 2, vacuum exactly the identity).

## What the losses hid: source inference

The standard characterization of the 2025-2026 on-chip squeezing
literature is a measured pair -- squeezed and antisqueezed dB after
all losses -- from which the source is inferred (as in Ulanov et
al., Nat. Commun. 16, 10791 (2025), and the 18-dB TFLN inference of
Karnik et al., arXiv:2605.27607). Under the standard model (a pure
squeezed state followed by loss) the pair determines the source and
the total efficiency in CLOSED FORM, and `infer_source` ships that
algebra with its assumptions stated:

```python
from sqzcomb import infer_source

out = infer_source(sq_db=-1.71, anti_db=5.54, sigma_db=0.1)
print(out["eta"], out["sq_db_source"], out["sq_db_source_sigma"])
```

The refusals catch what the algebra can catch -- a measured
uncertainty product below vacuum (impossible after loss), a missing
antisqueezing trace, an implied efficiency outside (0, 1] -- and the
docstring says plainly that "inferred squeezing" is a model
statement: an impurer-than-assumed source makes the inferred numbers
flatter than reality.

## Adapting it to your lab

The fit closes the loop after a measurement; the `lab` tools close it
before, and calibrate the one ring number a lab rarely measures
directly:

```python
import numpy as np
import sqzcomb as sc

# Would this measurement work? Predicted error bars for a planned
# trace (both quadratures, 0.1 dB per point), before beam time:
f = np.linspace(1e6, 60e6, 40)
plan = sc.plan_noise_measurement(mu=0.5, eta=0.6, kappa_hz=20e6,
                                 f_hz=f, sigma_db=0.1)
print(plan["identifiable"], plan["sigma"])

# Which analysis frequencies matter most? Pick the best 8:
pick = sc.design_noise_frequencies(0.5, 0.6, 20e6, f, 8, sigma_db=0.1)

# Calibrate g0 from the measured comb threshold power -- an exact
# inversion of this package's own threshold identity:
ring, sigma_g0 = sc.ring_from_threshold(
    kappa_hz=20e6, eta_esc=0.8, threshold_w=2.1e-3,
    lambda_pump_m=1.55e-6, reference="threshold sweep 2026-09-17",
    sigma_kappa_hz=0.4e6, sigma_threshold_w=0.05e-3)
```

The planner catches the same degeneracy the fit refuses -- one
quadrature alone can never determine three parameters -- before the
measurement instead of after. Measured spectra travel in a plain,
checked CSV format (`save_spectra_csv` / `load_spectra_csv`) whose
round trip is exact.

## What is inside

- **The classical field**: a Lugiato-Lefever split-step solver whose
  two half-steps are each exact; homogeneous steady states checked
  against the exact cubic; and a Newton solver for localized states
  -- dissipative solitons and soliton crystals -- that refuses to
  return anything whose stationarity is not verified.
- **The quantum fluctuations**: the linearized fluctuation matrix
  around any steady state, with a stability guard that refuses
  unstable states (and marginal soliton states unless the translation
  mode is explicitly acknowledged); input-output quadrature spectra
  through an extraction port with intrinsic loss and thermal baths;
  single-mode, joint two-mode, and full covariance matrices.
- **Photonic molecules**: the two-ring coupled model and the full
  multimode comb molecule (every retained comb line coupled to an
  auxiliary ring), including the extraction mechanism the associated
  paper is about -- a ring with no extraction port of its own
  delivering deep detected squeezing through its neighbor.
- **Entanglement, as a detector would certify it**: two-mode Gaussian
  entanglement of comb lines (logarithmic negativity through the
  Simon invariants, the Duan-Simon sum with its bound) both inside
  the cavity and -- frequency-resolved, through loss and finite
  detection efficiency -- at the output.
- **Imperfect detection**: the standard beamsplitter loss model and
  additive electronic noise, as scalar maps and as the Gaussian
  channel on covariance matrices; `required_efficiency` inverts it
  into the number an experiment plans around. New in v0.10,
  local-oscillator **phase noise**: when the measurement phase
  jitters, squeezing mixes with antisqueezing, and the package
  averages that mixing exactly for Gaussian jitter (Dwyer 2013;
  Oelker 2016) -- the limit identified for integrated squeezers once
  loss is tamed (Dean et al., npj Nanophotonics (2026)).
  `max_phase_noise` inverts the law into the jitter budget a
  homodyne experiment plans around.
- **Supermodes**: `principal_quadratures` finds the deepest squeezing
  any generalized quadrature of a multimode state attains, and the
  supermode carrying it -- exactly, by linear algebra, for pure and
  mixed states alike.
- **Interop**: xxpp covariance export, Williamson spectra, and a
  QuTiP adapter that turns any quadratic QuTiP Hamiltonian into a
  drift matrix this package accepts, refusing non-quadratic ones
  rather than silently linearizing.

## How it is checked

95 tests (Python 3.9-3.14, run in CI on every push), every physics
claim anchored to a closed form, an exact identity, or two
independent code paths -- never a stored number. Highlights: vacuum
passes any passive device unchanged at every coupling, port and
frequency; the degenerate parametric oscillator spectrum to 1e-10;
the textbook 3 dB detected-squeezing ceiling at critical coupling --
and its violation by full extraction -- emerging from the machinery
rather than being asserted; exact molecule thresholds, supermode
splittings and port equivalences; the converged soliton's exact
translation zero mode and the two-pulse crystal equal to a rescaled
single soliton grid point for grid point; thermal baths pinned to
(2 n_bar + 1)/2 closed forms with h and k_B from their exact SI
definitions; entanglement formulas cross-checked against explicit
partial transposition and the closed-form two-mode squeezed vacuum;
lab-unit conversions anchored by exact round trips and by
`threshold_power` hitting the root of the package's own cubic; the
noise-spectrum fit recovering generating parameters with Monte-Carlo
scatter matching its reported uncertainties; and the phase-noise
closed form held against direct numerical integration over the
jitter distribution, its exact zero- and infinite-jitter limits, and
its exact commutation with the loss channel. The lab tools are
checked the same way: planner and fit report the same error bars
as two code paths of one matrix, the single-quadrature degeneracy
shows up as an exact rank deficiency, and the g0 calibration
round-trips through `threshold_power` to machine precision.

## Honest limits

Deliberate scope, designed out with reasons: no quantum noise beyond
the Gaussian linearization (no non-Gaussian states or above-threshold
dynamics -- unstable drift matrices are refused, never silently
averaged); no technical noise of the resonator itself
(thermorefractive and Raman noise are material physics with their own
modelling choices); and continuous-wave pumping only.

## Associated paper

> T. M. Mahim, M. M. Rahman and A. S. M. Mohsin, "Overcoming the 3 dB
> squeezing extraction limit in silicon carbide microcombs with a
> photonic molecule," Optics Express 34(18), 34822-34834 (2026),
> https://doi.org/10.1364/OE.612248 (open access); code for the paper:
> https://github.com/Tanvir-Mahmud-Mahim/sic-molecule-squeezer

This package is the general-purpose engine; the paper repository
reproduces the specific published study.

## Support and governance

Written and maintained by Tanvir Mahmud Mahim (Department of
Electrical and Electronic Engineering, BRAC University), who reviews
every change and takes the final decision on scope and releases.
Design questions are discussed in the open in issues and pull
requests, and the standing rule of
[CONTRIBUTING.md](CONTRIBUTING.md) binds the maintainer exactly as it
binds contributors: a change that touches physics arrives with a
test, and a constant arrives with its source.

Support runs through the
[issue tracker](https://github.com/TaN-MM-Org/sqzcomb/issues). Usage
questions are welcome alongside bug reports; a docstring that left a
unit or a sign convention unclear is treated as a documentation bug,
not user error. While the version is below 1.0 the API may still move
between minor versions; such changes are called out in the release
notes. The normalized-unit conventions above are stable: any change
to them would be a breaking change named in the release notes, never
a quiet renormalization.

## License

Apache-2.0. Every release is archived on Zenodo under the concept DOI
[10.5281/zenodo.22015375](https://doi.org/10.5281/zenodo.22015375),
which always resolves to the latest version.
