twpasolver.analysis module#

analysis module.

TWPA Analysis and Simulation#

Main analysis module for simulating TWPA nonlinear behavior through coupled mode equations (CMEs). Provides automated analysis workflows with support for extended mode systems, parameter sweeps, and multiple gain models.

The module centers around TWPAnalysis, which integrates circuit modeling, mode management, and CME solving into a unified analysis framework.

Key Components#

Analysis Engine: - TWPAnalysis: Main analysis class with automated workflows - Analyzer: Base class for structured analysis with data management

Gain Models: - GainModel: Enumeration of available CME models with different accuracy/speed tradeoffs

Decorators: - analysis_function(): Automatic result caching and data management

Usage Patterns#

Basic Analysis Workflow:

Initialize TWPAnalysis with TWPA model and frequency range
Run base analysis (response, phase matching)
Compute gain with appropriate model complexity
Perform parameter sweeps or bandwidth analysis
Visualize results with built-in plotting methods

Extended Mode Analysis:

Create custom mode arrays using ModeArrayFactory
Add to analysis instance with descriptive names
Run gain analysis specifying mode array configuration
Compare results across different mode configurations

All analysis functions automatically cache results and support parameter sweeps through the parameter_sweep() method.

See also

twpasolver.modes_rwa: Advanced mode relationship management
twpasolver.cmes: High-performance CME solvers
twpasolver.models: Circuit component and TWPA models

class twpasolver.analysis.GainModel(value)[source]#

Bases: str, Enum

Available CME models for gain analysis.

Parameters:

MINIMAL_3WM (str) – Basic pump-signal-idler model. Fastest computation but limited accuracy. Suitable for quick design estimates and parameter space exploration.
GENERAL_IDEAL (str) – Extended mode system without losses or reflections. Moderate computation time with improved accuracy over basic model. Includes pump harmonics and frequency conversion terms.
GENERAL_LOSS_ONLY (str) – Extended mode system with device losses but no reflections. Similar computation time to ideal case with better accuracy for lossy devices.
GENERAL (str) – Full extended mode system with losses and reflections. Highest accuracy but slowest computation (~10x general_ideal model). Use for quantitative predictions matching experimental data.

MINIMAL_3WM = 'minimal_3wm'#

GENERAL_IDEAL = 'general_ideal'#

GENERAL_LOSS_ONLY = 'general_loss_only'#

GENERAL = 'general'#

twpasolver.analysis.prepare_relations_coefficients(terms_3wm, terms_4wm, epsilon, xi)[source]#

Prepare relation terms and coefficients for 3-wave and 4-wave mixing.

Parameters:

terms_3wm (list) – List of 3-wave mixing terms, each containing mode indices and coefficient
terms_4wm (list) – List of 4-wave mixing terms, each containing mode indices and coefficient
epsilon (float) – Scaling factor for 3-wave mixing coefficients
xi (float) – Scaling factor for 4-wave mixing coefficients

Returns:

relations_3wm (List of mode indices for 3-wave mixing)
relations_4wm (List of mode indices for 4-wave mixing)
coeffs_3wm (numpy array of scaled coefficients for 3-wave mixing)
coeffs_4wm (numpy array of scaled coefficients for 4-wave mixing)

twpasolver.analysis.analysis_function(func)[source]#

Decorate analysis methods providing automatic result caching and management.

Wraps analysis functions to automatically: - Update base TWPA data before analysis - Cache results in the analysis instance’s data dictionary - Handle save/load operations with custom naming - Provide consistent logging and error handling

The decorated function must return a dictionary to be compatible with caching.

Parameters:

func (callable) – Analysis function to decorate. Must be a method of an Analyzer subclass and return a dictionary of results.

Returns:

wrapper (callable) – Wrapped function with automatic data management capabilities.
Function Signature
——————
The wrapper adds the following parameters to any decorated function
save (bool, default True) – Whether to cache results in the analysis data dictionary
save_name (str, optional) – Custom name for cached results. If None, uses function name

pydantic model twpasolver.analysis.Analyzer[source]#

Bases: BaseModel, ABC

Base class for structured analysis.

Show JSON schema

{
   "title": "Analyzer",
   "description": "Base class for structured analysis.",
   "type": "object",
   "properties": {
      "data_file": {
         "title": "Data File",
         "type": "string"
      },
      "data": {
         "additionalProperties": true,
         "title": "Data",
         "type": "object"
      }
   }
}

Fields:

data (dict[str, typing.Any])
data_file (str)

field data_file: str [Optional]#

field data: dict[str, Any] [Optional]#

abstract update_base_data() → None[source]#: Check and update base data of the class if necessary.

save_data(writer: str = 'hdf5') → None[source]#: Save data to file.

load_data(filename: str, writer='hdf5') → None[source]#: Load data from file.

parameter_sweep(function: str, target: str, values: list, *args, **kwargs) → dict[str, list[Any]][source]#

Run an analysis function multiple times for different values of a parameter.

Parameters:

function (str) – Name of the analysis function to be executed multiple times.
target (str) – Name of the argument of the analysis function changed in the sweep.
values (list) – list of values for the sweep.

Returns:

A dictionary containing:

The list of sweeped values.
The return dictionary of the analysis function, with all items organized in lists with an additional dimension.

Return type:

dict

pydantic model twpasolver.analysis.TWPAnalysis[source]#

Bases: Analyzer, Frequencies

TWPA Analysis Engine with Extended Coupled Mode Equations.

Main interface for simulating TWPA nonlinear behavior. Solves coupled mode equations (CMEs) with support for arbitrary numbers of modes and automatic mode relationship management.

Parameters:

twpa (TWPA or str) – TWPA model instance or path to JSON file
f_list (list of float, optional) – Explicit list of frequencies for analysis
f_arange (tuple of float, optional) – Frequency range as (start, stop, step) for numpy.arange
unit ({'Hz', 'kHz', 'MHz', 'GHz', 'THz'}, default 'GHz') – Frequency unit for the analysis
data_file (str, optional) – Name for data file storage (auto-generated if not provided)

Examples

See the Tutorials section for complete examples:

Tutorial 3: Basic 3WM gain analysis and parameter sweeps
Tutorial 4: Extended CME models with pump harmonics and custom modes

The tutorials cover everything from basic gain calculations to complex multi-mode simulations with losses and reflections.

Notes

The analysis automatically extracts TWPA parameters (kappa, gamma, alpha) from the circuit model and uses them to interpolate mode properties across frequency.

For extended CME models: - Use general_ideal or general_loss_only for rapid design iterations - Use general for highest accuracy including device imperfections

All analysis results are automatically cached in the data attribute and can be saved/loaded using the save_data() and load_data() methods.

Show JSON schema

{
   "title": "TWPAnalysis",
   "description": "TWPA Analysis Engine with Extended Coupled Mode Equations.\n\nMain interface for simulating TWPA nonlinear behavior. Solves coupled mode\nequations (CMEs) with support for arbitrary numbers of modes and automatic\nmode relationship management.\n\nParameters\n----------\ntwpa : TWPA or str\n    TWPA model instance or path to JSON file\nf_list : list of float, optional\n    Explicit list of frequencies for analysis\nf_arange : tuple of float, optional\n    Frequency range as (start, stop, step) for numpy.arange\nunit : {'Hz', 'kHz', 'MHz', 'GHz', 'THz'}, default 'GHz'\n    Frequency unit for the analysis\ndata_file : str, optional\n    Name for data file storage (auto-generated if not provided)\n\nExamples\n--------\nSee the :ref:`tutorials` section for complete examples:\n\n- Tutorial 3: Basic 3WM gain analysis and parameter sweeps\n- Tutorial 4: Extended CME models with pump harmonics and custom modes\n\nThe tutorials cover everything from basic gain calculations to complex\nmulti-mode simulations with losses and reflections.\n\nNotes\n-----\nThe analysis automatically extracts TWPA parameters (kappa, gamma, alpha) from\nthe circuit model and uses them to interpolate mode properties across frequency.\n\nFor extended CME models:\n- Use ``general_ideal`` or ``general_loss_only`` for rapid design iterations\n- Use ``general`` for highest accuracy including device imperfections\n\nAll analysis results are automatically cached in the ``data`` attribute and can\nbe saved/loaded using the ``save_data()`` and ``load_data()`` methods.",
   "type": "object",
   "properties": {
      "f_list": {
         "anyOf": [
            {
               "items": {
                  "minimum": 0,
                  "type": "number"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of frequencies",
         "title": "F List"
      },
      "f_arange": {
         "anyOf": [
            {
               "maxItems": 3,
               "minItems": 3,
               "prefixItems": [
                  {
                     "minimum": 0,
                     "type": "number"
                  },
                  {
                     "minimum": 0,
                     "type": "number"
                  },
                  {
                     "minimum": 0,
                     "type": "number"
                  }
               ],
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Tuple passed to numpy.arange to construct frequency span.",
         "title": "F Arange"
      },
      "unit": {
         "default": "GHz",
         "enum": [
            "Hz",
            "kHz",
            "MHz",
            "GHz",
            "THz"
         ],
         "title": "Unit",
         "type": "string"
      },
      "data_file": {
         "title": "Data File",
         "type": "string"
      },
      "data": {
         "additionalProperties": true,
         "title": "Data",
         "type": "object"
      },
      "twpa": {
         "$ref": "#/$defs/TWPA"
      }
   },
   "$defs": {
      "Capacitance": {
         "description": "Model of a capacitor.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "twoport_parallel": {
               "default": false,
               "description": "Insert component in parallel when transforming to twoport representation.",
               "title": "Twoport Parallel",
               "type": "boolean"
            },
            "name": {
               "const": "Capacitance",
               "default": "Capacitance",
               "title": "Name",
               "type": "string"
            },
            "C": {
               "minimum": 0,
               "title": "C",
               "type": "number"
            }
         },
         "required": [
            "C"
         ],
         "title": "Capacitance",
         "type": "object"
      },
      "Inductance": {
         "description": "Model of an inductor.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "twoport_parallel": {
               "default": false,
               "description": "Insert component in parallel when transforming to twoport representation.",
               "title": "Twoport Parallel",
               "type": "boolean"
            },
            "name": {
               "const": "Inductance",
               "default": "Inductance",
               "title": "Name",
               "type": "string"
            },
            "L": {
               "minimum": 0,
               "title": "L",
               "type": "number"
            }
         },
         "required": [
            "L"
         ],
         "title": "Inductance",
         "type": "object"
      },
      "LCLfBaseCell": {
         "description": "Base cell of twpa LC model.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "name": {
               "const": "LCLfBaseCell",
               "default": "LCLfBaseCell",
               "title": "Name",
               "type": "string"
            },
            "L": {
               "description": "Inductance of the straight line.",
               "minimum": 0,
               "title": "L",
               "type": "number"
            },
            "C": {
               "description": "Capacitance of the stub finger.",
               "minimum": 0,
               "title": "C",
               "type": "number"
            },
            "Lf": {
               "description": "Inductance of the stub finger.",
               "minimum": 0,
               "title": "Lf",
               "type": "number"
            },
            "delta": {
               "default": 0,
               "description": "Loss Tangent",
               "minimum": 0,
               "title": "Delta",
               "type": "number"
            },
            "centered": {
               "default": false,
               "title": "Centered",
               "type": "boolean"
            }
         },
         "required": [
            "L",
            "C",
            "Lf"
         ],
         "title": "LCLfBaseCell",
         "type": "object"
      },
      "LosslessTL": {
         "description": "Model for a lossless transmission line.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "name": {
               "const": "LosslessTL",
               "default": "LosslessTL",
               "title": "Name",
               "type": "string"
            },
            "l": {
               "description": "Length of the line.",
               "minimum": 0,
               "title": "L",
               "type": "number"
            },
            "L": {
               "description": "Characteristic inductance of the line.",
               "minimum": 0,
               "title": "L",
               "type": "number"
            },
            "C": {
               "description": "Characteristic capacitance of the line.",
               "minimum": 0,
               "title": "C",
               "type": "number"
            }
         },
         "required": [
            "l",
            "L",
            "C"
         ],
         "title": "LosslessTL",
         "type": "object"
      },
      "OnePortArray": {
         "description": "Container for direct compositions of OnePortModels.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "cells": {
               "description": "List of OnePortModel representing the basic cells. Nested cells are allowed.",
               "items": {
                  "discriminator": {
                     "mapping": {
                        "Capacitance": "#/$defs/Capacitance",
                        "Inductance": "#/$defs/Inductance",
                        "OnePortArray": "#/$defs/OnePortArray",
                        "Resistance": "#/$defs/Resistance",
                        "Stub": "#/$defs/Stub"
                     },
                     "propertyName": "name"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/Resistance"
                     },
                     {
                        "$ref": "#/$defs/Inductance"
                     },
                     {
                        "$ref": "#/$defs/Capacitance"
                     },
                     {
                        "$ref": "#/$defs/Stub"
                     },
                     {
                        "$ref": "#/$defs/OnePortArray"
                     }
                  ]
               },
               "title": "Cells",
               "type": "array"
            },
            "twoport_parallel": {
               "default": false,
               "description": "Insert component in parallel when transforming to twoport representation.",
               "title": "Twoport Parallel",
               "type": "boolean"
            },
            "name": {
               "const": "OnePortArray",
               "default": "OnePortArray",
               "title": "Name",
               "type": "string"
            },
            "parallel": {
               "default": false,
               "description": "Connect internal OnePortModels in parallel.",
               "title": "Parallel",
               "type": "boolean"
            }
         },
         "title": "OnePortArray",
         "type": "object"
      },
      "Resistance": {
         "description": "Model of a resistor.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "twoport_parallel": {
               "default": false,
               "description": "Insert component in parallel when transforming to twoport representation.",
               "title": "Twoport Parallel",
               "type": "boolean"
            },
            "name": {
               "const": "Resistance",
               "default": "Resistance",
               "title": "Name",
               "type": "string"
            },
            "R": {
               "minimum": 0,
               "title": "R",
               "type": "number"
            }
         },
         "required": [
            "R"
         ],
         "title": "Resistance",
         "type": "object"
      },
      "Stub": {
         "description": "Model of a stub.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "twoport_parallel": {
               "default": false,
               "description": "Insert component in parallel when transforming to twoport representation.",
               "title": "Twoport Parallel",
               "type": "boolean"
            },
            "name": {
               "const": "Stub",
               "default": "Stub",
               "title": "Name",
               "type": "string"
            },
            "L": {
               "minimum": 0,
               "title": "L",
               "type": "number"
            },
            "C": {
               "minimum": 0,
               "title": "C",
               "type": "number"
            },
            "length": {
               "minimum": 0,
               "title": "Length",
               "type": "number"
            },
            "open": {
               "default": true,
               "title": "Open",
               "type": "boolean"
            }
         },
         "required": [
            "L",
            "C",
            "length"
         ],
         "title": "Stub",
         "type": "object"
      },
      "StubBaseCell": {
         "description": "Base cell of twpa stub filter model.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "name": {
               "const": "StubBaseCell2",
               "default": "StubBaseCell2",
               "title": "Name",
               "type": "string"
            },
            "L": {
               "description": "Inductance of the straight line.",
               "minimum": 0,
               "title": "L",
               "type": "number"
            },
            "C": {
               "description": "Capacitance of the line.",
               "minimum": 0,
               "title": "C",
               "type": "number"
            },
            "Lf": {
               "description": "Inductance of the stub finger.",
               "minimum": 0,
               "title": "Lf",
               "type": "number"
            },
            "l1": {
               "description": "Length of the stub finger.",
               "minimum": 0,
               "title": "L1",
               "type": "number"
            },
            "l2": {
               "description": "Length of the straight line.",
               "minimum": 0,
               "title": "L2",
               "type": "number"
            },
            "delta": {
               "default": 0,
               "description": "Loss Tangent",
               "minimum": 0,
               "title": "Delta",
               "type": "number"
            },
            "line": {
               "default": false,
               "description": "Model line as distributed element instead of lumped inductance.",
               "title": "Line",
               "type": "boolean"
            }
         },
         "required": [
            "L",
            "C",
            "Lf",
            "l1",
            "l2"
         ],
         "title": "StubBaseCell",
         "type": "object"
      },
      "TWPA": {
         "description": "Simple model for TWPAs.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "cells": {
               "description": "List of TwoPortModels representing the basic cells. Nested lists are allowed.",
               "items": {
                  "discriminator": {
                     "mapping": {
                        "Capacitance": "#/$defs/Capacitance",
                        "Inductance": "#/$defs/Inductance",
                        "LCLfBaseCell": "#/$defs/LCLfBaseCell",
                        "LosslessTL": "#/$defs/LosslessTL",
                        "OnePortArray": "#/$defs/OnePortArray",
                        "Resistance": "#/$defs/Resistance",
                        "Stub": "#/$defs/Stub",
                        "StubBaseCell2": "#/$defs/StubBaseCell",
                        "TWPA": "#/$defs/TWPA",
                        "TwoPortArray": "#/$defs/TwoPortArray"
                     },
                     "propertyName": "name"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/LosslessTL"
                     },
                     {
                        "$ref": "#/$defs/StubBaseCell"
                     },
                     {
                        "$ref": "#/$defs/LCLfBaseCell"
                     },
                     {
                        "$ref": "#/$defs/OnePortArray"
                     },
                     {
                        "$ref": "#/$defs/TwoPortArray"
                     },
                     {
                        "$ref": "#/$defs/TWPA"
                     },
                     {
                        "$ref": "#/$defs/Resistance"
                     },
                     {
                        "$ref": "#/$defs/Capacitance"
                     },
                     {
                        "$ref": "#/$defs/Inductance"
                     },
                     {
                        "$ref": "#/$defs/Stub"
                     }
                  ]
               },
               "title": "Cells",
               "type": "array"
            },
            "name": {
               "const": "TWPA",
               "default": "TWPA",
               "title": "Name",
               "type": "string"
            },
            "Istar": {
               "default": 0.0065,
               "description": "Nonlinearity scale current parameter.",
               "minimum": 0,
               "title": "Istar",
               "type": "number"
            },
            "Idc": {
               "default": 0.001,
               "description": "Bias dc current.",
               "minimum": 0,
               "title": "Idc",
               "type": "number"
            },
            "Ip0": {
               "default": 0.0002,
               "description": "Rf pump amplitude.",
               "minimum": 0,
               "title": "Ip0",
               "type": "number"
            }
         },
         "title": "TWPA",
         "type": "object"
      },
      "TwoPortArray": {
         "description": "Generic container for arrays of TwoPortModels.",
         "properties": {
            "Z0_ref": {
               "default": 50.0,
               "description": "Reference line impedance of the two-port component.",
               "title": "Z0 Ref",
               "type": "number"
            },
            "N": {
               "default": 1,
               "description": "Number of repetitions of the model in the computed abcd matrix.",
               "minimum": 0,
               "title": "N",
               "type": "integer"
            },
            "cells": {
               "description": "List of TwoPortModels representing the basic cells. Nested lists are allowed.",
               "items": {
                  "discriminator": {
                     "mapping": {
                        "Capacitance": "#/$defs/Capacitance",
                        "Inductance": "#/$defs/Inductance",
                        "LCLfBaseCell": "#/$defs/LCLfBaseCell",
                        "LosslessTL": "#/$defs/LosslessTL",
                        "OnePortArray": "#/$defs/OnePortArray",
                        "Resistance": "#/$defs/Resistance",
                        "Stub": "#/$defs/Stub",
                        "StubBaseCell2": "#/$defs/StubBaseCell",
                        "TWPA": "#/$defs/TWPA",
                        "TwoPortArray": "#/$defs/TwoPortArray"
                     },
                     "propertyName": "name"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/LosslessTL"
                     },
                     {
                        "$ref": "#/$defs/StubBaseCell"
                     },
                     {
                        "$ref": "#/$defs/LCLfBaseCell"
                     },
                     {
                        "$ref": "#/$defs/OnePortArray"
                     },
                     {
                        "$ref": "#/$defs/TwoPortArray"
                     },
                     {
                        "$ref": "#/$defs/TWPA"
                     },
                     {
                        "$ref": "#/$defs/Resistance"
                     },
                     {
                        "$ref": "#/$defs/Capacitance"
                     },
                     {
                        "$ref": "#/$defs/Inductance"
                     },
                     {
                        "$ref": "#/$defs/Stub"
                     }
                  ]
               },
               "title": "Cells",
               "type": "array"
            },
            "name": {
               "const": "TwoPortArray",
               "default": "TwoPortArray",
               "title": "Name",
               "type": "string"
            }
         },
         "title": "TwoPortArray",
         "type": "object"
      }
   },
   "required": [
      "twpa"
   ]
}

Fields:

twpa (twpasolver.models.twoportarrays.TWPA)

Validators:

load_model_from_file » twpa

field twpa: TWPA [Required]#

Validated by:

load_model_from_file

validator load_model_from_file » twpa[source]#: Try loading twpa model from file if filename string is provided.

update_base_data() → None[source]#

Update data extracted from the twpa model.

This function is triggered every time an analysis function is executed after changing a parameter of the model.

get_mode_array(config: str = 'basic_3wm') → ModeArray[source]#

Get a mode array by configuration name.

Parameters:: config – Name of the mode array configuration
Returns:: The requested mode array configuration
Return type:: ModeArray

add_mode_array(name: str, mode_array: ModeArray) → None[source]#

Add a custom mode array to the analyzer.

Parameters:

name – Name to assign to the mode array
mode_array – The mode array to add

phase_matching(process: Literal['PA', 'FCU', 'FCD'] = 'PA', signal_mode: str = 's', pump_mode: str = 'p', idler_mode: str = 'i', mode_array_config: str = 'basic_3wm', pump_Ip0: float | None = None, signal_arange: Tuple[float, float, float] | None = None, pump_arange: Tuple[float, float, float] | None = None, thin: int = 20) → dict[str, Any][source]#

Analyze phase matching conditions for nonlinear processes using mode arrays.

Computes phase mismatch Δβ as a function of pump and signal frequencies for different nonlinear processes. Uses ModeArray interpolation for mode parameter calculation across frequency ranges.

Parameters:

process ({'PA', 'FCU', 'FCD'}, default 'PA') –
Nonlinear process type:
- PA: Parametric amplification (signal + idler → pump)
- FCU: Frequency conversion up (signal → idler, ω_i > ω_s)
- FCD: Frequency conversion down (signal → idler, ω_i < ω_s)
signal_mode (str, default 's', 'p', 'i') – Mode labels in the mode array configuration
pump_mode (str, default 's', 'p', 'i') – Mode labels in the mode array configuration
idler_mode (str, default 's', 'p', 'i') – Mode labels in the mode array configuration
mode_array_config (str, default 'basic_3wm') – Mode array configuration name for parameter interpolation
pump_Ip0 (float, optional) – Pump current for nonlinear correction. If None, uses TWPA’s Ip0
signal_arange (tuple of float, optional) – Signal frequency range as (start, stop, step). If None, uses automatic range from start of frequency span to stopband edge
pump_arange (tuple of float, optional) – Pump frequency range as (start, stop, step). If None, uses automatic range from stopband edge to maximum frequency
thin (int, default 20) – Array thinning factor for computational efficiency

Returns:

Phase matching analysis results:

delta : ndarray - Phase mismatch matrix [n_signal, n_pump]
triplets : dict - Frequency and wavenumber triplets
pump_freqs : ndarray - Pump frequency array
signal_freqs : ndarray - Signal frequency array
mode_info : dict - Mode configuration metadata

Return type:

dict

Examples

See Tutorial 3 (Tutorials) for basic phase matching analysis and Tutorial 4 for extended mode configurations with frequency conversion.

Notes

The chi nonlinear parameter includes pump current corrections
Optimal phase matching regions appear as minima in the phase mismatch
Extended mode arrays enable analysis beyond basic pump-signal-idler

gain(signal_freqs: ndarray[Any, dtype[float64]], pump: float | None = None, Is0: float = 1e-06, Ip0: float | None = None, model: str | GainModel = GainModel.MINIMAL_3WM, mode_array_config: str = 'basic_3wm', signal_mode: str = 's', pump_mode: str = 'p', idler_mode: str = 'i', initial_amplitudes: List[float] | ndarray | None = None, thin: int = 100) → dict[str, Any][source]#

Compute the TWPA gain using coupled mode equation models.

Supports multiple CME models from basic 3-wave mixing to extended systems with arbitrary numbers of modes, losses, and reflections.

Parameters:

signal_freqs (array_like) – Signal frequencies for gain calculation
pump (float, optional) – Pump frequency. If None, uses automatically determined optimal frequency
Is0 (float, default 1e-6) – Initial signal current amplitude (A) for standard 3WM model
Ip0 (float, optional) – Initial pump current amplitude (A). If None, uses TWPA’s Ip0 parameter
model ({'minimal_3wm', 'general_ideal', 'general_loss_only', 'general'}, default 'minimal_3wm') –
CME model complexity:
- minimal_3wm: Basic pump-signal-idler only (fastest)
- general_ideal: Extended modes, no losses/reflections
- general_loss_only: Extended modes with losses
- general: Full model with losses and reflections (most accurate)
mode_array_config (str, default 'basic_3wm') –
Name of mode array configuration to use. Built-in options:
- basic_3wm: Standard pump, signal, idler modes
- Custom configurations added via add_mode_array()
signal_mode (str, default 's', 'p', 'i') – Mode labels within the mode array for signal, pump, and idler
pump_mode (str, default 's', 'p', 'i') – Mode labels within the mode array for signal, pump, and idler
idler_mode (str, default 's', 'p', 'i') – Mode labels within the mode array for signal, pump, and idler
initial_amplitudes (array_like, optional) –
Initial current amplitudes for all modes. Can be:
- 1D array: Same conditions for all frequencies [n_modes]
- 2D array: Different conditions per frequency [n_freq, n_modes]
- None: Use default values (Ip0, Is0, 1e-14 for others)
thin (int, default 100) – Position array thinning factor (higher = faster, lower resolution)

Returns:

Gain analysis results containing:

model : str - CME model used
pump_freq : float - Pump frequency
signal_freqs : ndarray - Signal frequencies
x : ndarray - Position array along TWPA
I_triplets : ndarray - Current evolution [n_freq, n_modes, n_pos]
gain_db : ndarray - Gain in dB for each signal frequency
mode_info : dict - Mode configuration metadata

Return type:

dict

Examples

See Tutorial 3 (Tutorials) for basic gain analysis examples and Tutorial 4 for extended CME models.

Notes

The general model is most accurate but ~10x slower than others
Extended mode arrays capture more subtle effects and improve the accuracy of the simulation.
Results are automatically cached in analysis.data['gain']
Use plot_gain() and plot_mode_currents() for visualization

bandwidth(gain_reduction: float = 3, **gain_kwargs) → dict[str, Any][source]#

Compute informations about the compund gain bandwidth.

Parameters:

gain_reduction (float) – Difference from maximum gain used as threshold to determine the bandwidth edges.
**gain_kwargs – Additional arguments to pass to the gain function.

Returns:

A dictionary containing:

”pump_freq” (float): The pump frequency used in the gain calculation.
”bandwidth_edges” (array): The frequency edges of each gain profile section above the threshold.
”total_bw” (float): The total bandwidth.
”max_gain” (float): The maximum gain observed.
”reduced_gain” (float): The minimum gain level above the threshold.
”mean_gain” (float): The mean gain across the bandwidth range.
”bw_freqs” (array): Frequencies where gain is above the threshold.

Return type:

dict

plot_response(**kwargs) → Axes[source]#: Plot response of twpa.

plot_gain(**kwargs) → Axes[source]#: Plot gain of twpa.

plot_mode_currents(**kwargs) → Axes[source]#: Plot mean currents of modes as a function of position along the TWPA line.

plot_phase_matching(**kwargs) → Axes[source]#: Plot phase matching profile of twpa.

model_post_init(context: Any, /) → None#

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.