pybbq 2026.3.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

From PyPI

pip install pybbq

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_perimiter': 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]