quchip.chip.port_network

Composable, instantaneous SLH field boundaries.

Classes

ComponentPort(input, output)	A component port pairing incoming and outgoing field connections.
FieldExposure
FieldSide
FieldTerminal(component, name, direction, ...)	One directional terminal owned by a PortNetwork.
IncludedNetwork(prefix, _host, _interfaces)	Access one prefixed copy of a template network inside a host.
NetworkPort(label, _input_key, _output_key)	A named external network port with incoming and outgoing fields.
PortNetwork(*[, scattering, label])	Compose Markovian ports with instantaneous scalar scattering.
SLHComponent(label, input_names, ...[, ...])	Boundary component with scalar scattering and named terminals.

class quchip.chip.port_network.PortNetwork(*, scattering=None, label=None)

Bases: object

Compose Markovian ports with instantaneous scalar scattering.

The network acts on fields at one reference frequency. Scattering matrices are dimensionless and must be unitary. Explicit hidden channels or reference components represent loss and noise. The network reduces feedback loops algebraically, so this class does not model propagation retardation.

Parameters:

• scattering (array-like or mapping, optional) – Authored instantaneous scattering matrix or labeled entries.

• label (str, optional) – Network label.

classmethod from_ports(ports, *, scattering=None, label=None)

Build a network containing ports in declaration order.

Parameters:

• ports (sequence of Port) – Quantum coupling channels to add. Each port can belong to only one network, so pass a copy to use it in another.

• scattering (array-like or mapping, optional) – Initial external scattering specification.

• label (str, optional) – Network label.

Returns:

Network with the supplied ports and no internal components.

Return type:

PortNetwork

property ports: tuple[Port, ...]

Return network-owned quantum coupling ports in declaration order.

property components: tuple[SLHComponent, ...]

Return all graph components in declaration order.

property external_ports: tuple[NetworkPort, ...]

Return the external network ports in channel order.

property exposures: tuple[NetworkPort, ...]

Deprecated alias for external_ports.

exposure(exposure)

Deprecated alias for external_port().

Parameters:

exposure (str or NetworkPort) – External reference plane.

external_port(exposure)

Return one external network port by object or label.

Parameters:

exposure (str or NetworkPort) – External reference plane.

property S: Any

Return the composed instantaneous scalar scattering matrix.

property parameters: Mapping[str, Any]

Return bindable scalar parameters of the network and retained responses.

Paths are scattering.<output>.<input>, component.<label>.<name> and response.<mode>.<name>. A retained mode response has freq in GHz, a dimensionless weight and internal_rate in 1/ns. The internal_rate already includes the weight.

set_parameter_value(name, value)

Set one network-owned scalar on an isolated structural copy.

Parameters:

• name (str) – Path below scattering, component or response.

• value (Any) – Replacement scalar in the parameter’s units. parameters gives the units of retained mode responses.

port(label, *, target, rate=None, external_quality_factor=None, operator=None, phase=0.0)

Create and add one quantum coupling port.

Parameters:

• label (str) – Unique port label.

• target (Any | Sequence[Any]) – See Port.

• rate (Any) – See Port.

• external_quality_factor (Any) – See Port.

• operator (Any) – See Port.

• phase (Any) – See Port.

Returns:

The network-owned port, whose input, output and side terminals can be connected immediately.

Return type:

Port

component(label, *, scattering, terminals=None)

Add a scalar scattering component with named terminals.

Parameters:

• label (str) – Unique component label.

• scattering (square array-like) – Dimensionless scattering matrix. Rows are outputs and columns are inputs, and concrete matrices must be unitary.

• terminals (sequence of str, optional) – Names for both input and output terminals. Defaults to ("signal",) for one channel and numeric names otherwise.

Returns:

Component handle used with connect(), cascade(), or link().

Return type:

SLHComponent

through(label)

Add a one-channel identity through component.

Parameters:

label (str) – Component label.

phase_shift(label, *, phase)

Add a one-channel phase shift.

Parameters:

• label (str) – Component label.

• phase (float or array-like) – Phase in radians.

beam_splitter(label, *, eta=0.5)

Add a directional two-input/two-output splitter.

eta is the power from input k to output k. With t = sqrt(eta) and r = sqrt(1 - eta), the scattering matrix is [[t, r], [-r, t]]. This component has no component ports. Use input_terminal(), output_terminal(), or cascade().

Parameters:

• label (str) – Component label.

• eta (float or array-like, default=0.5) – Power transmission in [0, 1].

hybrid90(label)

Add a directional two-input/two-output ideal 90-degree hybrid.

The scattering matrix is [[1, 1j], [1j, 1]] / sqrt(2). This component has no component ports. Use input_terminal(), output_terminal(), or cascade().

Parameters:

label (str) – Unique component label.

permutation(label, *, order)

Add an output permutation.

Parameters:

• label (str) – Unique component label.

• order (sequence of int) – Input column selected by each output row.

attenuator(label, *, eta=None, loss_db=None, thermal_occupation=None)

Add a reciprocal two-sided attenuator with power transmission eta.

Each direction has amplitude transmission sqrt(eta) and couples to one of two hidden loss channels with amplitude sqrt(1-eta). They default to vacuum. thermal_occupation gives both loads a mean thermal population in quanta, constant across the modeled band. Specify either power transmission eta or positive loss_db.

Parameters:

• label (str) – Unique component label.

• eta (scalar or None, default=None) – Power transmission in the interval [0, 1].

• loss_db (scalar or None, default=None) – Positive power loss in dB, mutually exclusive with eta.

• thermal_occupation (scalar or None, default=None) – Mean occupation of each hidden load in quanta. None means vacuum.

delay(label, *, duration)

Add a two-sided reference section with duration duration ns.

The section shifts fields at exposure planes but does not introduce retardation or memory into the Markovian dynamics.

Place it with link() or connect() like any other component. The compiler peels adjacent runs from each exposure leg, so the section never enters Markovian S, L, or H. Every reference section must belong to an exposed run or an acyclic downstream output graph. Its duration is tracked at network.component.<label>.duration.

Parameters:

• label (str) – Component label.

• duration (float or array-like) – Reference-plane delay in ns.

filter(label, *, transfer, thermal_occupation=None, **parameters)

Add a two-sided passive filter reference section.

transfer(frequency, **parameters) must accept scalar or array frequencies in GHz and return a broadcast-compatible complex value without concretizing traced inputs. Each keyword parameter is tracked at network.component.<label>.<name>.

Place the section with link() or connect(). The compiler peels it from an adjacent exposure leg, so it never enters the Markovian S, L, or H. The section reshapes the propagating field but leaves every collapse operator unchanged, including the radiative (Purcell) decay of coupled devices. Model a Purcell filter as a Resonator between the readout mode and the port instead (see the Purcell filtering guide). Continuous-wave APIs evaluate the transfer at each frequency. Transient APIs use its narrowband value at the applicable carrier. Concrete evaluations with |H| > 1 raise. You cannot serialize networks that contain filters with to_dict(). Chip.clone() and Chip.with_params() preserve the callable.

Declare thermal_occupation in quanta, constant across the modeled band, for a matched absorptive realization that emits (1-|H|²)n. A scalar transfer alone does not distinguish absorption from reflection. Colored thermal emission cannot feed a quantum coupling through a reference section. Use a dynamical filter/bath model for that case.

Parameters:

• label (str) – Unique component label.

• transfer (callable) – Passive complex amplitude transfer versus frequency in GHz.

• thermal_occupation (scalar or None, default=None) – Mean matched-load occupation in quanta. None means vacuum.

• **parameters (Any) – Named transfer-function parameters tracked by the network.

mode_reflection(label, *, freq, external_rate, internal_rate=0.0, reference_freq=None)

Add a two-sided reference section that reflects like a damped linear mode.

Each pass multiplies the field by H(f), with H(f)² = ((κ_i − κ_e)/2 − iΩ) / ((κ_e + κ_i)/2 − iΩ) and Ω = 2π(f − freq), the reflection of a mode coupled to the line at rate κ_e with internal loss κ_i. On a reflection line the incident field passes once inbound and once outbound, so the plane acquires that reflection. H is the continuous square root whose real part is nonnegative at reference_freq. When reference_freq is None, H is the root that tends to one far below freq. The branch fixes the phase of fields that cross only one leg, such as emission from the devices behind the section.

Like filter(), the section stays outside the Markovian S, L, and H and leaves every collapse operator unchanged. Continuous-wave APIs evaluate H at each frequency. Transient APIs use its value at the applicable carrier. The internal-loss bath is vacuum. eliminate() inserts this section when it removes a mode whose port is alone on its plane. A shared line gets mode_transmission(). Every parameter is tracked at network.component.<label>.<name> and serializes.

Parameters:

• label (str) – Unique component label.

• freq (float or array-like) – Mode frequency in GHz.

• external_rate (float or array-like) – Coupling rate κ_e to this line, in 1/ns.

• internal_rate (float or array-like, default=0.0) – Internal loss rate κ_i in 1/ns.

• reference_freq (float or array-like or None, default=None) – Frequency in GHz that selects the square-root branch.

mode_transmission(label, *, freq, external_rate, internal_rate=0.0)

Add a one-pass reference section for a damped linear mode.

Side 1 to side 2 multiplies the field by S_r(f) = ((κ_i - κ_e)/2 - iΩ) / ((κ_e + κ_i)/2 - iΩ), with Ω = 2π(f - freq). Reverse propagation is transparent. With zero external coupling, the section is transparent at every frequency. The section acts on one leg and stays outside the Markovian S, L, and H. Its internal-loss bath is vacuum. Continuous-wave APIs evaluate the transfer at each frequency. Transient APIs use its value at the applicable carrier. quchip tracks every parameter at network.component.<label>.<name>, and the section serializes.

Parameters:

• label (str) – Unique component label.

• freq (float or array-like) – Mode frequency in GHz.

• external_rate (float or array-like) – Coupling rate κ_e to this line, in 1/ns.

• internal_rate (float or array-like, default=0.0) – Internal loss rate κ_i in 1/ns.

Returns:

Two-sided component with forward transfer and transparent reverse propagation.

Return type:

SLHComponent

amplifier(label, *, added_noise, gain=None, gain_db=None)

Add a phase-preserving amplifier reference section to an output line.

gain is power gain G. added_noise is input-referred symmetrized noise in quanta and must be at least (1 - 1/G) / 2. Forward propagation from side 1 to side 2 multiplies field amplitudes by sqrt(G). Reverse propagation is transparent.

Place side 1 toward the chip and side 2 toward the exposed output plane. The compiler rejects a section that would amplify an incident field into the chip or put the output plane on side 1. Both parameters are tracked at network.component.<label>.<name> and remain sweepable and differentiable. Acyclic downstream splitters keep its shared output noise. The section remains outside Markovian S, L, and H and serializes normally.

gain_db can replace linear gain. Added quanta are constant across the modeled band and exclude the input’s own noise.

Parameters:

• label (str) – Component label.

• added_noise (float or array-like) – Input-referred symmetrized added noise in quanta.

• gain (float or array-like, optional) – Power gain, specified linearly or in dB. Supply at most one.

• gain_db (float or array-like, optional) – Power gain, specified linearly or in dB. Supply at most one.

circulator(label, *, ports=3)

Add an ideal circulator routing side k to side k + 1.

The highest-numbered side routes back to side 1.

Parameters:

• label (str) – Unique component label.

• ports (int, default=3) – Number of physical sides, which must be at least three.

isolator(label, *, thermal_occupation=None)

Add an ideal isolator routing side 1 to side 2.

The reverse field is dumped into hidden.<label>.load, whose thermal population travels back toward side 1. thermal_occupation is in quanta, constant across the modeled band, and defaults to vacuum.

Parameters:

• label (str) – Unique component label.

• thermal_occupation (scalar or None, default=None) – Mean hidden-load occupation in quanta. None means vacuum.

termination(label, *, thermal_occupation=None)

Add a matched one-sided load with an optional thermal input state.

thermal_occupation is the mean thermal population in quanta, constant across the modeled band, and defaults to vacuum.

Parameters:

• label (str) – Unique component label.

• thermal_occupation (scalar or None, default=None) – Mean load occupation in quanta. None means vacuum.

connect(output, input)

Connect one component output to one component input.

Parameters:

• output (FieldTerminal) – Unused directional terminals from this network.

• input (FieldTerminal) – Unused directional terminals from this network.

link(*items)

Link consecutive component ports in both directions.

When a two-sided component is passed directly, the chain enters side 1 and leaves side 2. Pass component.port(k) to select a side explicitly.

Parameters:

*items (Port, SLHComponent, or ComponentPort) – At least two two-sided endpoints.

cascade(*items)

Connect each item’s output to the next item’s input in sequence.

Parameters:

*items (Port, SLHComponent, or FieldTerminal) – At least two compatible endpoints.

expose(label, *, at=None, input=None, output=None)

Name and return an external network port.

Pass at= to expose one component port. Use input= and output= for separate input and output connections. Ports and components then select their sole or signal terminal unless explicit terminals are passed.

Parameters:

• label (str) – Unique external reference-plane label.

• at (Port, SLHComponent, ComponentPort, or None, default=None) – Physical side to expose for both directions.

• input (FieldTerminal, Port, SLHComponent, or None, default=None) – Separate incoming and outgoing connection points.

• output (FieldTerminal, Port, SLHComponent, or None, default=None) – Separate incoming and outgoing connection points.

validate_for(chip)

Validate every quantum port target against a chip.

Parameters:

chip (Chip) – Chip whose device labels must contain every port target.

fingerprint()

Return a conservative structural cache signature.

resolve(base, *, _compiled=None, _generated=None)

Compose this boundary onto an input-free SLH value.

Parameters:

base (ResolvedSLH) – Resolved quantum-port channels to compose with the network.

to_dict()

Serialize the network graph, quantum ports and retained mode responses.

classmethod from_dict(data)

Reconstruct a network produced by to_dict().

Parameters:

data (mapping) – Serialized network payload.

copy()

Return an independent structural copy with label-based port targets.

restrict(ports)

Return an independent sub-network of field-graph components reachable from ports.

Every reachable component is copied with its connections, exposures, tracked parameters, and filter callables. Authored boundary scattering is limited to the kept planes. A reachable subgraph that also touches an unselected port raises, because cutting it would change the SLH dynamics.

Parameters:

ports (sequence of str or Port) – Quantum coupling ports whose field subgraphs are kept.

Returns:

An independent network with label-based port targets.

Return type:

PortNetwork

Raises:

• KeyError – A selected port is not part of this network.

• ValueError – A reachable subgraph also touches an unselected port, boundary scattering couples kept and dropped planes, or the kept ports hold only part of a retained mode response.

include(template, *, prefix)

Copy a reusable network template into this network under prefix.

Components and connections are copied with labels prefix/label. Tracked parameters therefore use paths such as network.component.prefix/label.name. Filter callables are kept. The template remains unchanged, so you can include it again under another prefix.

The template’s exposures become interfaces rather than host planes. Exposures made with expose(..., at=...) are available through side(name). Asymmetric exposures use input(name) and output(name). Wire the returned interfaces with link(), cascade(), or expose().

Parameters:

• template (PortNetwork) – A network without quantum ports or authored boundary scattering.

• prefix (str) – A label prefix for the copied components, unique in this network.

Returns:

Accessors for the copied components and interfaces.

Return type:

IncludedNetwork

Raises:

ValueError – The template owns ports or boundary scattering, or prefix is already in use.

physics_notes()

Return the boundary convention and approximation scope.

dynamical_supports(chip, *, _compiled=None)

Return device groups coupled by cascade-generated Hamiltonian terms.

Static scattering alone is excluded, because a unitary mixer changes field coordinates but leaves the summed Lindbladian invariant. Each downstream/upstream coupling pair generated by SLH series composition contributes the union of its two quantum-port supports.

Parameters:

chip (Chip) – Chip used to resolve port target supports.

fed_ports(chip, exposure, *, _compiled=None)

Return (port, coefficient) pairs reached from exposure.

Each coefficient combines the scattering entry from the exposure to a channel with that port’s weight in the channel. A coherent input β therefore reaches the port coupling as c = coefficient · β.

Parameters:

• chip (Chip) – Chip used to resolve the network boundary.

• exposure (str) – External input reference-plane label.