pybbq 2026.4.3

Python thermo-electromagnetic modelling tool for simulating transients in superconductors

pyBBQ — Python Bus-Bar Quench model

Python thermo-electromagnetic modelling tool to simulate transients in superconductors. 1.5D, homogenised, ODE-solver-based.

Installation

Prerequisites

pyBBQ is compatible with Python 3.10, 3.11, 3.12, and 3.13. To check whether Python is installed and which version you have, open a terminal and run:

python --version

If Python is not installed or the version is too old, download and install it from python.org. During installation on Windows, make sure to tick "Add Python to PATH".

How to open a terminal

• Windows: Press Win + R, type cmd, and press Enter. Alternatively, search for Command Prompt or PowerShell in the Start menu.
• macOS: Open Finder → Applications → Utilities → Terminal, or press Cmd + Space and type Terminal.
• Linux: Press Ctrl + Alt + T or search for Terminal in your application menu.

From PyPI

Once Python is installed, run the following command in your terminal to install pyBBQ:

pip install pybbq

If you have multiple Python versions installed, you may need to use pip3 instead of pip:

pip3 install pybbq

To verify the installation was successful, run:

pybbq --help

Usage

Once installed, pybbq can be run in two ways with a YAML input file:

Option 1 — via Python module:

python -m pybbq.pybbq your_input.yaml

Option 2 — via script:

pybbq your_input.yaml

Results

Results are written to the following directory relative to where pybbq is run:

output/results/<sim_name>/

Where <sim_name> is the value of sim_name in solver_settings. If sim_name is not set, the current date (YYYY-MM-DD) is used as the folder name.

The output folder contains:

File	Description
main.csv	Time, current, voltage, hot-spot temperature per time step
temperature.csv	Temperature profile along the conductor per time step
voltage.csv	Voltage profile along the conductor per time step
NZPV.csv	Normal-zone propagation velocity per time step
summary.csv	Scalar summary results (hot-spot T, MIIT, etc.)
center_points.csv	Section centre positions along the conductor
main_results.png	Main results figure
NZPV.png	Normal-zone propagation velocity figure
MIIT.png	MIIT curve figure
T_vs_MIIT.png	Temperature vs MIIT figure
logfile	Simulation log

A copy of the input YAML is also saved to the output folder for reproducibility.

Input file

The input file is a YAML file with the following structure. Optional parameters are commented out.

# --- Geometry ---
geometry_options:
  'strands': 1                       # Number of strands in a multistrand cable. Use 1 for a single strand.
  'sections': 500                    # Number of computational sections along the conductor.
  'busbar_length': 0.7               # Total conductor length [m].
  'spacing': 'linspace'              # Section spacing: 'linspace' (uniform) or 'geomspace' (finer at the left/heater end).
  'shape': 'rectangular'             # Cross-sectional shape: 'rectangular' or 'round'.
  'width': 0.0038                    # Conductor width [m]. Used for rectangular shape and for cooling/insulation area.
  'height': 0.0013                   # Conductor height [m]. Used for rectangular shape and for cooling/insulation area.
# 'strand_dmt': 0.001               # Strand diameter [m]. Used instead of width/height for round shape.
# 'cross_sectional_area': 6.8       # Total cross-sectional area including voids [mm2]. If omitted, derived from conductor_area.
  'insulation_material': 'kapton'    # Insulation material surrounding the conductor. [OPTIONAL, default: 'kapton']
  'insulation_layers': 0             # Number of computational insulation layers. Set to 0 to disable insulation. [OPTIONAL, default: 0]
  'insulation_thickness': 0.00015   # Total insulation thickness [m]. [OPTIONAL, default: 0.0]

# --- Conductor Cross-Section Areas ---
# Areas of each material component in the conductor cross-section [m2].
# Key names correspond to materials available in the property library.
conductor_area:
  'cu100': 1.6013305876799997e-06    # Copper (RRR=100) area [m2].
  'ag170': 1.6023305876799997e-06    # Silver (RRR=170) area [m2].
  'hastelloy': 1.36001341232e-06     # Hastelloy substrate area [m2].
  'void': 2.236656e-06               # Void/solder/fill area [m2] (contributes to cross-section but not heat capacity).

# --- Quench Heater ---
quench_heater:
  'heating_nodes': [0, 1, 2, 3, 4]  # Indices of sections that receive heater power at t=0.
  'power': 136                       # Heater power density [W/m].
  'heating_mode': 'constant'         # Heating mode: 'constant' (heat until heat_until T), 'time' (heat for heating_time s), or 'exponential' (exponential decay with heating_time_constant).
  'heat_until': 50.0                 # Stop heating when this temperature [K] is reached. Used with heating_mode='constant'.
# 'heating_time': 0.1               # Duration of heating pulse [s]. Used with heating_mode='time'.
# 'heating_time_constant': 0.05     # Time constant for exponential heating decay [s]. Used with heating_mode='exponential'.
# 'heating_sig_c': 1000.0           # Sigmoid sharpness for the heating ramp-on. Should be 2-3 orders of magnitude larger than 1/heating_time.
# 'heating_length': 0.0002          # Length of the dedicated heater region at the start of the wire [m]. Assumes symmetry (total heated = 2x this value). [OPTIONAL]
# 'additional_heating_nodes': 3     # Number of extra sections inside the heating_length region. [OPTIONAL]

# --- Operational Parameters ---
operational_parameters:
  'current': 7000.0                  # Transport current [A].
  'current_density': 1029.411765     # Current density over total cross-section including voids [A/mm2]. If both current and current_density are given, they must agree to within 0.01 %.
  'T_initial': 4.5                   # Initial (bath) temperature [K].
  'Self_Field': 0.000685714          # Self-field coefficient [T/A]. Total self-field = Self_Field x current.
  'external_current': False          # Set to True to load a current-vs-time profile from a CSV file instead of computing the decay.
  'external_current_path': ''        # Path to the external current CSV. Only used when external_current=True.
# 'B_gradient_type': 'fit'          # Background field interpolation mode. Set to 'fit' to interpolate B along the conductor from the vectors below.
# 'Background_Bx': [0.0, 1.0]       # Background field x-component at each position in Background_positions [T].
# 'Background_By': [0.0, 0.0]       # Background field y-component at each position in Background_positions [T].
# 'Background_Bz': [0.0, 0.0]       # Background field z-component at each position in Background_positions [T].
# 'Background_positions': [0.0, 0.7] # Positions along the conductor corresponding to the Background_B* vectors [m].

# --- Materials ---
materials:
  'superconductor': 'ReBCO'          # Superconductor type. Options: 'NbTi', 'Nb3Sn', 'ReBCO', 'YBCO', 'GdBCO', 'LbCO', 'SmBCO', 'EuBCO'.
  'scaling_parameters': {'Ic_ref': 8235.0, 'T_ref': 4.5, 'B_ref': 4.8}  # Reference critical-current scaling parameters: Ic_ref [A], T_ref [K], B_ref [T].
  'fitname': 'CFUN_HTS_JcFit_SUPERPOWER_v1'  # Jc(B,T) fit function name. Must match the superconductor type. [OPTIONAL]
# 'Nb3Sn_fitname': 'summers'        # Nb3Sn-specific fit: 'summers' or 'bordini'. Required when superconductor='Nb3Sn'.
  'n_value': 30.0                    # Power-law n-value for the E-J characteristic (E proportional to (J/Jc)^n).

# --- Cooling ---
cooling:
  'c1': 500.                         # He I nucleate-boiling coefficient, onset [W/m2/K].
  'c2': 5.0e+4                       # He I nucleate-boiling coefficient, peak [W/m2/K].
  'c3': 250                          # He I nucleate-boiling coefficient, recovery [W/m2/K].
  'c4': 200                          # Transient cooling coefficient (currently unused).
  'c5': 200                          # Superfluid He II cooling coefficient: H(T) = c5 * (T1^p - T0^p) [W/m2/K^p].
  'c6': 200                          # Film-boiling cooling coefficient: H(T) = c6 * (T1 - T0) [W/m2/K].
  'p': 4.0                           # Exponent for superfluid He II heat flux law.
  'h1': 10                           # He I convective heat transfer coefficient, lower bound [W/m2/K].
  'h2': 1.0e+4                       # He I convective heat transfer coefficient, upper bound [W/m2/K].
  'Pmax': 35.0e+3                    # Maximum heat flux before transitioning to film-boiling regime [W/m2].
  'Helium_cooling': False            # Enable external (surface) helium cooling.
  'Helium_cooling_internal': False   # Enable internal helium cooling (e.g. hollow conductor).
  'cooled_perimeter': None           # Wetted perimeter used for cooling [m].

# --- Protection Settings ---
protection_settings:
  'protection': True                 # Enable quench protection (energy extraction).
  'Inductance': 0.000388             # Circuit inductance [H]. Used for exponential current decay.
  'DumpV': 100.0                     # Dump resistor voltage [V]. DumpR is derived as DumpV / current if DumpR is not set.
# 'DumpR': 0.014286                  # Dump resistance [Ohm]. Alternative to DumpV; provide one or the other.
  'Detection_Voltage': 0.01          # Quench-detection voltage threshold [V].
  'Protection_Delay': 0.01           # Delay between detection and activation of protection [s].
  'Validation_Delay': 0.0            # Additional validation time added to the detection timestamp [s]. Detection triggers at t_detect + Validation_Delay.
  'decay': 'exponential'             # Current decay mode: 'exponential' (L/R decay), 'constant' (fixed dI/dt), or 'no_load_fast' (fast L/R with tau=1 ms).
# 'decay_rate': 10.0                 # Constant current decay rate [A/s]. Only used when decay='constant'.
  'B0_dump': True                    # Ramps down background field B0 following the current decay.

# --- Solver Settings ---
solver_settings:
  'Tref': 80.                        # Reference (normal-zone) temperature [K]. Defaults: 9 K (NbTi), 15 K (Nb3Sn), 80 K (ReBCO).
  'Posref': [0.2, 0.3]               # Reference positions along the conductor to track and report [m].
  'dt': 0.00001                      # Initial ODE time step [s].
  't0': [0., 0.1]                    # Simulation time window [t_start, t_end] [s].
  'print_every': 1                   # Print status to console every N stored steps.
  'store_every': 1                   # Store solution every N ODE steps.
  'max_timestep': 0.001              # Maximum allowed time step for the adaptive stepper [s].
  'min_timestep': 0.00001            # Minimum allowed time step for the adaptive stepper [s].
  'min_step': 1.0e-9                 # Absolute minimum ODE step size [s].
  'max_step': 0.001                  # Absolute maximum ODE step size [s].
# 'atol': 1.0e-6                     # Absolute tolerance for the ODE solver. [OPTIONAL, uses default if omitted]
# 'rtol': 1.0e-3                     # Relative tolerance for the ODE solver. [OPTIONAL, uses default if omitted]
  'symmetry': true                   # Multiply the resistive voltage by 2 to account for conductor symmetry. Set to false if symmetry_factor=1 is desired.
  'sim_name': example_full           # Simulation name; used as the output directory name.
# 'open_plots': false                # Automatically open plots after the simulation completes. [OPTIONAL]
# 'time_step_rules': [[0.0, 0.01, 0.00001], [0.01, 0.1, 0.0001]]  # Fixed time-step rules: list of [t_min, t_max, dt_fixed] tuples. Overrides the adaptive stepper within each time window [s]. [OPTIONAL, default: None]