ConversionResult

class photonforge.spice.ConversionResult(component_name, backend_name, port_convention, output_dir, artifact_cache_dir, external_nodes, va_files, artifact_files, runnable, missing_artifacts, fits, flat_netlist, instance_names, frequencies, time_step, carrier_frequency, z0, field_impedance, subcircuit_name, subcircuit_text, subcircuit_path, _backend, _gf_45spclo_npe_support_module)

Immutable artifacts produced by convert().

Modal channel names always include a mode index, such as P0@0. Conversion generates the reusable subcircuit and model artifacts; use write_test_deck(), write_transient_deck(), write_dc_deck(), or write_wavelength_sweep_deck() to create a complete simulation deck. Every field is a read-only snapshot; external_nodes and flat_netlist are dicts that must be treated as read-only.

Parameters:

• component_name (str) – Name of the converted top-level component.

• backend_name (str) – Built-in backend used to emit the subcircuit and decks ("ngspice" or "spectre").

• port_convention (str) – Port convention used to emit the subcircuit and decks ("travelling_wave" or "gf_45spclo_npe").

• output_dir (Path) – Directory containing conversion-specific outputs.

• artifact_cache_dir (Path) – Content-addressed model artifact cache.

• external_nodes (dict[str, tuple[str, ...]]) – Mapping from each external modal channel to its SPICE node names. Values are (re, im) for "travelling_wave" and the shared one-element structured physical pin for "gf_45spclo_npe". Multi-carrier keys use a #<carrier_index> suffix, e.g. "P0@0#1".

• va_files (tuple[Path, ...]) – Generated Verilog-A source paths. Electric-field conversion adds one NPE adapter/terminator support source.

• artifact_files (tuple[Path, ...]) – Successfully compiled backend model artifacts.

• runnable (bool) – Whether every backend-required model artifact exists and is nonempty. Simulator availability is not checked.

• missing_artifacts (tuple[MissingArtifact, ...]) – Structured records for required artifacts that could not be generated.

• fits (tuple[FitRecord, ...]) – Pole-residue fit record for each unique leaf.

• flat_netlist (dict[str, Any]) – Flattened netlist used for subcircuit emission.

• instance_names (tuple[str, ...]) – Names assigned to flattened leaf instances.

• frequencies (ndarray) – Read-only absolute S-matrix sample frequencies in Hz.

• time_step (float | None) – Conversion time step in seconds, if specified or inferred.

• carrier_frequency (float | tuple[float, ...]) – Complex-envelope carrier frequency in Hz, or a tuple of N carriers when converted with a sequence carrier_frequency of more than one value. A single value, however supplied, always yields a bare float here.

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

• field_impedance (float | None) – Conversion constant between a wave amplitude and a real electric field, under "gf_45spclo_npe"; None under "travelling_wave".

• subcircuit_name (str) – Backend subcircuit identifier.

• subcircuit_text (str) – Complete generated subcircuit source.

• subcircuit_path (Path) – Path to the generated subcircuit.

• _backend (Backend)

• _gf_45spclo_npe_support_module (str | None)

Methods

write_dc_deck([path, output_channels, ...])	Write a fixed DC operating-point deck.
write_test_deck([path, drive_channel, ...])	Write a Gaussian-pulse transient test deck.
write_transient_deck([path, time_step, ...])	Write a transient deck driven by complex envelopes.
write_wavelength_sweep_deck([path, ...])	Write a GF NPE Spectre DC wavelength-sweep deck.

Attributes

component_name
backend_name
port_convention
output_dir
artifact_cache_dir
external_nodes
va_files
artifact_files
runnable
missing_artifacts
fits
flat_netlist
instance_names
frequencies
time_step
carrier_frequency
z0
field_impedance
subcircuit_name
subcircuit_text
subcircuit_path

write_dc_deck(path=None, *, inputs, output_channels=None, output_file=None, wavelength=None, allow_incomplete=False)

Write a fixed DC operating-point deck.

Constant complex incident waves are keyed by external modal channel. Travelling-wave models evaluate at their converted carrier. GF NPE models evaluate at C / wavelength; omission uses the wavelength of the first converted carrier.

Parameters:

• path (str | Path | None) – Output deck path. The suffix is replaced with the backend netlist extension.

• inputs (Mapping[str, Any]) – Mapping from modal channel names to finite complex scalar incident waves.

• output_channels (Iterable[str] | None) – Modal channels to save. None selects nondriven channels, or all channels if every channel is driven.

• output_file (str | Path | None) – Explicit backend-native output path. Unsupported for Spectre.

• wavelength (float | None) – GF NPE operating wavelength in meters. Invalid under the travelling-wave convention.

• allow_incomplete (bool) – Write a source-only deck even when required artifacts are missing.

Returns:

Absolute path to the generated deck.

Return type:

Path

write_test_deck(path=None, *, drive_channel=None, drive_amplitude=1.0, pulse_width=5e-12, pulse_center=1e-11, t_end=5e-11, time_step=None, output_file=None, allow_incomplete=False)

Write a Gaussian-pulse transient test deck.

The real incident wave is drive_amplitude * exp(-0.5 * ((t - center) / width)**2). Under the "travelling_wave" convention it is converted to a matched source voltage using V_src = 2 * sqrt(z0) * a; under "gf_45spclo_npe" it is converted to an incident electric field using E_src = sqrt(field_impedance) * a. All nondriven channels are selected for output, or all channels when the driven channel is the only external channel.

Parameters:

• path (str | Path | None) – Output deck path. The suffix is replaced with the backend netlist extension. By default, the deck is written below output_dir.

• drive_channel (str | None) – External modal channel to drive. By default, the first channel in natural port and numeric mode order.

• drive_amplitude (float) – Peak incident-wave amplitude.

• pulse_width (float) – Gaussian standard deviation in seconds.

• pulse_center (float) – Gaussian center time in seconds.

• t_end (float) – Transient simulation stop time in seconds.

• time_step (float | None) – Transient time step in seconds. By default, use the conversion time step or pulse_width / 50.

• output_file (str | Path | None) – Explicit backend-native output path. Unsupported for backends such as Spectre that manage output directly.

• allow_incomplete (bool) – Write a source-only deck even when required artifacts are missing.

Returns:

Absolute path to the generated simulation deck.

Return type:

Path

Notes

An existing deck is overwritten atomically. The simulator creates any requested output file when the deck is run; this method does not run it.

write_transient_deck(path=None, *, inputs, time_step=None, output_channels=None, output_file=None, t_end=None, hold_last=False, allow_incomplete=False)

Write a transient deck driven by complex envelopes.

Input values are incident scattering waves keyed by external modal channel. Under the "travelling_wave" convention, real and imaginary source voltages use V_src = 2 * sqrt(z0) * a; under "gf_45spclo_npe", source electric fields use E_src = sqrt(field_impedance) * a. Shorter input arrays are padded with zeros to the longest input. One end-of-input sample is appended one step past the last input: zero by default, or the final value when hold_last is set.

Parameters:

• path (str | Path | None) – Output deck path. The suffix is replaced with the backend netlist extension. By default, the deck is written below output_dir.

• inputs (TimeSeries | Mapping[str, Any]) – photonforge.TimeSeries or dictionary from modal channel names to one-dimensional complex sample arrays.

• time_step (float | None) – Sample and transient time step in seconds. Optional when inputs is a photonforge.TimeSeries (inferred from it); required for a plain mapping.

• output_channels (Iterable[str] | None) – Modal channels to save. None selects nondriven channels, or all channels if every channel is driven. An empty iterable creates a run-only deck.

• output_file (str | Path | None) – Explicit backend-native output path. Unsupported for backends such as Spectre that manage output directly.

• t_end (float | None) – Transient stop time in seconds. By default, one time step beyond the final input sample. Must not precede the final input sample.

• hold_last (bool) – Hold the final input value after the input ends instead of returning to zero.

• allow_incomplete (bool) – Write a source-only deck even when required artifacts are missing.

Returns:

Absolute path to the generated simulation deck.

Return type:

Path

Notes

An existing deck is overwritten atomically. The simulator creates any requested output file when the deck is run; this method does not run it.

write_wavelength_sweep_deck(path=None, *, inputs, wavelength_start, wavelength_stop, wavelength_step, output_channels=None, allow_incomplete=False)

Write a GF NPE Spectre DC wavelength-sweep deck.

Parameters:

• path (str | Path | None) – Output deck path. The suffix is replaced with .scs.

• inputs (Mapping[str, Any]) – Mapping from modal channel names to finite complex scalar incident waves.

• wavelength_start (float) – First wavelength in meters.

• wavelength_stop (float) – Final wavelength in meters.

• wavelength_step (float) – Positive wavelength increment in meters.

• output_channels (Iterable[str] | None) – Modal channels to save. None selects nondriven channels, or all channels if every channel is driven.

• allow_incomplete (bool) – Write a source-only deck even when required artifacts are missing.

Returns:

Absolute path to the generated Spectre deck.

Return type:

Path