Metadata-Version: 2.4
Name: pybbq
Version: 2026.4.4
Summary: Python thermo-electromagnetic modelling tool for simulating transients in superconductors
Author: Tim Mulder
License: MIT
Keywords: superconductor,quench,thermo-electromagnetic,simulation,busbar
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib~=3.10.0
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: openpyxl
Requires-Dist: STEAM-materials~=2026.3.2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: coverage-badge; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings-python; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "docs"
Requires-Dist: markdown-include; extra == "docs"

# 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:

```bash
python --version
```

If Python is not installed or the version is too old, download and install it from [python.org](https://www.python.org/downloads/). 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:

```bash
pip install pybbq
```

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

```bash
pip3 install pybbq
```

To verify the installation was successful, run:

```bash
pybbq --help
```

## Usage

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

**Option 1 — via Python module:**
```bash
python -m pybbq.pybbq your_input.yaml
```

**Option 2 — via script:**
```bash
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.

```yaml
# --- 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]
```
