twpasolver.modes_rwa module#

modes_rwa module.

Mode Management and Rotating Wave Approximation Analysis#

Tools for managing complex mode relationships in TWPA analysis, enabling simulation of extended coupled mode equation (CME) systems with arbitrary numbers of modes beyond basic pump-signal-idler configuration.

Key Components#

ModeArray: Organizes related modes with automatic frequency propagation, parameter interpolation, and dependency graph management.

RWAAnalyzer: Identifies valid 3-wave and 4-wave mixing terms that satisfy the Rotating Wave Approximation for any given set of mode relationships.

ModeArrayFactory: Factory methods for creating standard and custom mode configurations including pump harmonics, frequency conversion terms, and harmonics.

ParameterInterpolator: Interpolation of mode parameters (kappa, gamma, alpha) from base TWPA circuit data across frequency ranges.

Capabilities#

RWA Term Selection:

  • Automatic discovery of valid 3WM and 4WM mixing processes

  • Coefficient calculation including factorial corrections for repeated modes

  • Caching of RWA terms for performance

Mode Relationships:

  • Support for arbitrary frequency relationships between modes

  • Forward and backward propagating modes

  • Pump harmonics (p, p2, p3, …)

  • Frequency conversion terms (p+s, p+i, …)

  • Signal/idler harmonics (s2, i2, …)

Symbolic Frequency Propagation:

  • O(n) frequency updates using pre-computed symbolic expressions

  • Automatic identification of independent vs. dependent modes

  • Topological sorting of mode dependencies

  • Visualization of the mode relations with a graph

Parameter Management:

  • Easy interpolation of mode parameters from base circuit data

  • Automatic handling of mode directions for wavenumber calculation

Examples

See Tutorial 4 (Tutorials) for complete examples covering:

  • Basic 3WM mode array creation and visualization

  • Extended mode arrays with pump harmonics and frequency conversion

  • Custom mode configurations for specific processes

  • RWA term analysis and CME integration

The tutorial demonstrates the progression from simple mode relationships to complex multi-mode systems used in realistic TWPA simulations.

Performance Notes#

  • Symbolic frequency propagation enables O(n) scaling, useful when iterating over arrays.

  • RWA term caching eliminates redundant calculations during CME solving

  • Numba-compatible data structures for integration with fast CME solvers

  • Efficient interpolation supports faster parameter sweeps

class twpasolver.modes_rwa.ParameterInterpolator(frequencies: ndarray, kappas: ndarray, gammas: ndarray, alphas: ndarray, kind: str = 'cubic')[source]#

Bases: object

Interpolates kappa, gamma, and alpha values based on frequency.

Always returns real kappa and alpha, complex gamma.

get_parameters(frequency: float | ndarray) → Tuple[float | ndarray, complex | ndarray, float | ndarray][source]#

Get interpolated kappa, gamma, and alpha for a given frequency or array of frequencies.

Parameters:

frequency – Frequency point(s) for interpolation, can be a single value or array

Returns:

Tuple of (kappa, gamma, alpha) at the requested frequency/frequencies kappa and alpha are real, gamma is complex

class twpasolver.modes_rwa.Mode(label: str, direction: int = 1, frequency: float | None = None, k: float | None = None, gamma: float | complex | None = 0.0, alpha: float | None = 0.0)[source]#

Bases: object

Represents a single mode with its physical properties.

Parameters:

  • label – Mode identifier (e.g., ‘p’ for pump)

  • frequency – Mode frequency

  • direction – 1 for forward, -1 for backward

  • gamma – Reflection coefficient

  • k – Wavenumber (calculated from frequency)

  • alpha – Attenuation constant

label: str#
direction: int = 1#
frequency: float | None = None#
k: float | None = None#
gamma: float | complex | None = 0.0#
alpha: float | None = 0.0#
class twpasolver.modes_rwa.RWAAnalyzer(modes: List[str], relations: List[List[str]])[source]#

Bases: object

Analyzer class for a set of coupled modes.

property relations#

Getter for mode relations.

update_relations(relations: List[List[str]])[source]#

Update mode relations.

find_rwa_terms(power: int = 3) → List[Tuple[Any, ...]][source]#

Find all valid RWA terms of given power.

Parameters:

power – Order of the interaction (default: 3 for three-wave mixing)

Returns:

List of tuples (mode_idx, combination, mode_name, rhs_terms, coefficient)

print_rwa_terms(terms: List[Tuple[Any, ...]]) → None[source]#

Pretty print the RWA terms with their coefficients.

class twpasolver.modes_rwa.ModeArray(modes: List[Mode], relations: List[List[str]], interpolator: ParameterInterpolator)[source]#

Bases: object

Class representing a list of modes and frequency relations between them.

update_frequencies(new_frequencies: Dict[str, float]) → None[source]#

Update mode frequencies using optimized symbolic propagation.

Parameters:

new_frequencies – Dictionary mapping mode labels to new frequencies

update_base_data(interpolator: ParameterInterpolator) → None[source]#

Update the base data interpolator and refresh all mode parameters.

Parameters:

interpolator – New ParameterInterpolator instance

process_frequency_array(mode_label: str, frequencies: ndarray) → Dict[str, Dict[str, ndarray]][source]#

Process an array of frequencies for a single mode, propagating to all related modes.

Uses symbolic expressions for optimal performance.

Parameters:

  • mode_label – Label of the mode to update with array of frequencies

  • frequencies – Array of frequencies to process

Returns:

Dictionary with mode parameters for all related modes

plot_mode_relations(figsize: Tuple[float, float] = (12, 8), node_size: int = 3000, font_size: int = 12, show_frequencies: bool = False, show_directions: bool = True, layout: str = 'hierarchical') → None[source]#

Plot the relationships between modes as a directed graph.

Parameters:

  • figsize – Figure size (width, height)

  • node_size – Size of mode nodes

  • font_size – Font size for labels

  • show_frequencies – Whether to show current frequencies on nodes

  • show_directions – Whether to show mode propagation directions

  • layout – Graph layout algorithm (‘spring’, ‘circular’, ‘hierarchical’)

get_mode(label: str) → Mode[source]#

Get mode by label.

get_rwa_terms(power: int = 3) → List[Tuple[Any, ...]][source]#

Get RWA terms for the specified mixing order with caching.

Parameters:

power – Order of the interaction (2 for 3WM, 3 for 4WM)

Returns:

List of RWA terms

print_modes()[source]#

Print current state of all modes.

print_symbolic_expressions()[source]#

Print the symbolic expressions for all modes.

class twpasolver.modes_rwa.ModeArrayFactory[source]#

Bases: object

Factory for creating standard ModeArray configurations.

static create_basic_3wm(base_data: Dict[str, Any], forward_modes: bool = True) → ModeArray[source]#

Create a basic 3WM ModeArray with pump, signal, and idler modes.

Parameters:

  • base_data – Dictionary containing ‘freqs’, ‘k’, ‘gammas’, and ‘alpha’ arrays

  • forward_modes – Whether to create forward (True) or backward (False) propagating modes

Returns:

Configured for basic 3WM operation

Return type:

ModeArray

static create_extended_3wm(base_data: Dict[str, Any], n_pump_harmonics: int = 1, n_frequency_conversion: int = 1, n_signal_harmonics: int = 1, n_sidebands: int = 1, forward_modes: bool = True) → ModeArray[source]#

Create an extended 3WM ModeArray with pump harmonics and conversion terms.

Parameters:

  • base_data – Dictionary containing ‘freqs’, ‘k’, ‘gammas’, and ‘alpha’ arrays

  • n_pump_harmonics – Number of pump harmonics to include

  • n_frequency_conversion – Number of frequency conversion terms

  • n_signal_harmonics – Number of signal and idler harmonics

  • forward_modes – Whether to create forward (True) or backward (False) propagating modes

Returns:

Configured for extended 3WM operation with harmonics

Return type:

ModeArray

static create_custom(base_data: Dict[str, Any], mode_labels: List[str], mode_directions: List[int], relations: List[List[str]]) → ModeArray[source]#

Create a custom ModeArray with user-defined modes and relations.

Parameters:

  • base_data – Dictionary containing ‘freqs’, ‘k’, ‘gammas’, and ‘alpha’ arrays

  • mode_labels – List of mode labels

  • mode_directions – List of mode directions (1 for forward, -1 for backward)

  • relations – List of relations between modes

Returns:

Custom configured ModeArray

Return type:

ModeArray