convert

photonforge.spice.convert(component, *, carrier_frequency=None, frequencies=None, time_step=None, time_stepper=None, max_poles=32, rms_tol=1e-3, fit_failure='error', passivity='auto', z0=50.0, output_dir=None, artifact_cache_dir=None, backend='ngspice', port_convention='travelling_wave', field_impedance=None, compile_va=True, compile_timeout=_COMPILER_TIMEOUT, treat_as_leaf=None, show_progress=True)[source]

Convert a PhotonForge component into a SPICE subcircuit.

The hierarchy is flattened into modeled leaves. Each unique leaf S-matrix is sampled at absolute frequencies and fitted to candidate pole-residue models. Accepted fits are converted to Verilog-A, optionally compiled, and assembled into a backend-specific subcircuit. Generated models are stored in a content-addressed cache.

Parameters:

  • component (Component) – Top-level component to convert.

  • carrier_frequency (float | Sequence[float] | None) – Complex-envelope carrier frequency in Hz, or a non-empty sequence of N carrier frequencies for N-channel WDM (port_convention="gf_45spclo_npe" only; all carriers must agree on whether they are exactly zero, since one fit selects a single real/complex realization shared by every carrier). If omitted, infer a single carrier from time_stepper. Each resolved value must be non-negative.

  • frequencies (Any) – Strictly increasing absolute S-matrix sample frequencies in Hz. At least two values are required. If omitted, infer them from time_stepper.

  • time_step (float | None) – Delay-validation time step in seconds. If omitted, infer it from time_stepper when possible. Backends without internal absdelay() support require a value.

  • time_stepper (Any) – Time stepper or nested container used to infer missing carrier frequency, frequencies, and time step.

  • max_poles (int) – Maximum number of poles requested from each fit.

  • rms_tol (float) – Maximum accepted pole-residue RMS fitting error.

  • fit_failure (Literal['error', 'warn']) – "error" to reject fits above rms_tol, or "warn" to use the lowest-error backend-realizable fit.

  • passivity (Literal['auto', 'enforce', 'ignore']) – Passivity policy. "auto" enforces passivity only when the sampled data is passive and preserves active data; "enforce" requires a passive fit and rejects otherwise; "ignore" never requests passivity. Stability is always enforced.

  • z0 (float) – Modal channel reference impedance in ohms. Ignored under port_convention="gf_45spclo_npe".

  • output_dir (str | Path | None) – Conversion output directory. By default, create a backend-prefixed directory below the current directory.

  • artifact_cache_dir (str | Path | None) – Content-addressed artifact cache. By default, use output_dir/artifacts.

  • backend (Literal['ngspice', 'spectre']) – Built-in backend name, "ngspice" or "spectre".

  • port_convention (Literal['travelling_wave', 'gf_45spclo_npe']) – Port convention emitted by the subcircuit and decks. "travelling_wave" represents each modal channel with a real/imaginary node pair combined through port impedance (z0). "gf_45spclo_npe" instead uses GF two-mode structured optical pins with packed incoming/outgoing E-fields; currently only backend="spectre" supports it.

  • field_impedance (float | None) – Conversion constant between a PhotonForge wave amplitude and the optical E-field. Omission resolves to the GF convention 1.0 when port_convention="gf_45spclo_npe"; it must be omitted otherwise.

  • compile_va (bool) – Whether to compile Verilog-A when required by the backend. Source is retained if compilation is unavailable.

  • compile_timeout (float | None) – Per-invocation wall-clock ceiling for the Verilog-A compiler, in seconds. Raise it for large multimode or high-pole-count models, or pass None to disable the limit. A timed-out compile is reported as a missing artifact.

  • treat_as_leaf (Iterable[Any] | None) – Component names or component-like objects to fit directly instead of recursively flattening.

  • show_progress (bool) – Whether to show conversion progress and a completion summary on standard output.

Returns:

Conversion result containing the generated subcircuit, fit records, node mapping, and model artifacts.

Return type:

ConversionResult

Notes

Conversion creates output and cache directories and may execute a Verilog-A compiler. It does not invoke ngspice or Spectre. ConversionResult.runnable reports only whether backend-required model artifacts were generated.