bolts 0.2.1__py3-none-any.whl

bolts/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""BOLTS: Branching-unit and Optical-repeater power-feed Loop Transient Simulator.
+
+Stress and vulnerability of submarine power-feed systems (PFE, cable, repeaters, branching units) under geomagnetic disturbances
+(GMD / space weather), lightning and switching surges, down to loss of signal, failures and traffic loss.
+"""
+from . import api as _api
+from ._version import __version__
+from .api import (
+    Result,
+    assess,
+    build_network,
+    export_spice,
+    load_parameters,
+    load_waveform,
+    register_element,
+    register_waveform,
+    run_transient,
+)
+
+__all__ = ["__version__", *_api.__all__]

bolts/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""``python -m bolts`` is the same as the ``bolts`` command."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

bolts/_version.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""Single source of the package version (read by ``pyproject.toml``)."""
+
+__version__ = "0.2.1"

bolts/api.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""The public API: a few functions that cover a whole study. Everything here is also re-exported from ``bolts``.
+
+    >>> import bolts
+    >>> params = bolts.load_parameters()                       # shipped defaults (every value with unit, status and source)
+    >>> record = bolts.load_waveform("data/example_vind_1s.csv", params=params)
+    >>> net = bolts.build_network(params, record)
+    >>> result = bolts.run_transient(net, params)
+    >>> summary = bolts.assess(result)
+"""
+from __future__ import annotations
+
+import pathlib
+
+import numpy as np
+
+from .config.loader import load_parameters
+from .config.schema import ParameterSet
+from .mna.timestep import fixed_axis
+from .mna.transient import run_transient as _run
+from .network.builder import build_network
+from .network.graph import Network
+from .registry import register_element, register_waveform
+from .result import Result
+from .waveforms.base import Record
+from .waveforms.csv_record import read_csv_record, record_from_parameters
+
+
+def load_waveform(path=None, params: ParameterSet | None = None, **kwargs) -> Record:
+    """Read a voltage record. With ``params`` the columns, time format, window, scale and step come from its ``[forcing]`` section
+    (``path`` overrides the file); without it pass ``time_column``, ``value_column`` ... as keywords."""
+    if params is not None:
+        return record_from_parameters(params, path)
+    return read_csv_record(path, **kwargs)
+
+
+def run_transient(network: Network, params: ParameterSet, dt_s: float | None = None, t_s: np.ndarray | None = None, newton: bool | None = None) -> Result:
+    """Run a built network. The time axis is ``t_s`` if given, else the record's duration at ``dt_s`` (default: the record's own spacing,
+    or ``solver.dt_s`` without a record). The regulator is exact for any dt / tau. A network with nonlinear elements is solved by Newton iteration
+    automatically; ``newton=True`` forces that path for a linear network (a check that both paths agree)."""
+    rec = network.meta.get("record")
+    # the time axis comes from the record unless the caller gives one (needed for a network without a record)
+    if t_s is None:
+        if rec is None:
+            dt = float(dt_s or params.get("solver", "dt_s"))
+            raise ValueError(f"no record in the network: pass t_s (for example a {dt:g} s axis) or build the network with a record")
+        dt = float(dt_s or rec.dt_s)
+        t_s = fixed_axis(rec.duration_s, dt, rec.t_s[0])
+    system = network.compile()      # stamp the elements and assemble the matrices
+    res = _run(system, t_s, network.controller, str(params.get("solver", "integrator")), newton)
+    return Result(network, res, params)
+
+
+def assess(result: Result, targets=(100, 200, 250)) -> dict:
+    """Electrical, optical and traffic metrics of a run; ``targets`` are the terminal rates (Gbit/s) to evaluate."""
+    return result.assess(targets)
+
+
+def export_spice(result_or_network, path, params: ParameterSet | None = None) -> pathlib.Path:
+    """Write an ngspice netlist of the circuit, for an independent cross-check. Imported lazily: the SPICE code is optional."""
+    from .spice.netlist import write_netlist
+    return write_netlist(result_or_network, path)
+
+
+__all__ = [
+    "Result",
+    "assess",
+    "build_network",
+    "export_spice",
+    "load_parameters",
+    "load_waveform",
+    "register_element",
+    "register_waveform",
+    "run_transient",
+]

bolts/cli.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""Command line: ``bolts run | params | validate | spice | doctor``."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .api import assess, build_network, load_parameters, load_waveform, run_transient
+from .config.overrides import parse_overrides
+from .errors import BoltsError
+
+
+def _add_input_args(sp: argparse.ArgumentParser) -> None:
+    """Options shared by every command that reads a voltage record (``run`` and ``spice``)."""
+    sp.add_argument("--params", help="parameter TOML merged over the shipped defaults")
+    sp.add_argument("--set", action="append", metavar="section.key=value", help="override any parameter (repeatable)")
+    sp.add_argument("--csv", help="voltage CSV (overrides forcing.csv_path)")
+    sp.add_argument("--start", type=float, help="window start, s from the first row")
+    sp.add_argument("--end", type=float, help="window end, s from the first row (negative = end of file)")
+    sp.add_argument("--scale", type=float, help="multiply the voltages")
+    sp.add_argument("--dt", type=float, help="time step of the run, s (default: the record's spacing)")
+
+
+def _params(a) -> object:
+    """Parameters from the defaults, the optional file, ``--set`` items and the window / scale flags (flags win over ``--set``)."""
+    ov = parse_overrides(a.set)
+    for key, val in (("forcing.window_start_s", a.start), ("forcing.window_end_s", a.end), ("forcing.scale", a.scale)):
+        if val is not None:
+            ov[key] = val
+    return load_parameters(a.params, ov or None)
+
+
+def _cmd_run(a) -> int:
+    """``bolts run``: record -> network -> transient -> assessment, printed and saved."""
+    p = _params(a)
+    rec = load_waveform(a.csv, params=p)
+    net = build_network(p, rec)
+    res = run_transient(net, p, dt_s=a.dt)
+    s = assess(res)
+    print(f"{rec.label}: {s['samples']} samples at {s['dt_s']:g} s = {s['duration_s']:.0f} s; V_ind {s['v_in_min_V']:.1f} to {s['v_in_max_V']:.1f} V")
+    print(f"PFE total {s['v_pfe_min_V']:.0f} to {s['v_pfe_max_V']:.0f} V (static need {s['static_need_V']:.0f} V, limit {s['v_tot_max_V']:.0f} V); "
+          f"clamped {100 * s['frac_pfe_clamped']:.2f}% of the time")
+    print(f"repeater current change {s['di_min_mA']:.1f} to {s['di_max_mA']:+.1f} mA (margin {s['margin_mA']:.0f} mA; below it "
+          f"{100 * s['frac_time_below_margin']:.2f}% of the time); an instantaneous jump of the largest sample step would reach {s['jump_bound_mA']:.0f} mA")
+    print(f"Q margin down to {s['min_margin_dB']:.2f} dB; outage {100 * s['frac_time_outage']:.2f}% of the time; largest conductor-to-sea voltage {s['v_cs_peak_V']:.0f} V")
+    for tg in (100, 200, 250):      # one line per terminal target rate: delivered share when adaptive vs fixed-format
+        k = f"adaptive_{tg}G_mean_rate_fraction"
+        if k in s:
+            print(f"  {tg}G target: adaptive {100 * s[k]:.1f}% delivered ({s[f'adaptive_{tg}G_ses']} SES), fixed {100 * s[f'fixed_{tg}G_mean_rate_fraction']:.1f}%")
+    out = res.save(a.out, extra_manifest={"command": "run", "csv": str(a.csv or p.get('forcing', 'csv_path'))})
+    print(f"wrote series.csv, summary.json, manifest.json, node_peaks_V.csv in {out}")
+    if a.plot:
+        from .plotting.timeseries import plot_result
+        print("wrote", plot_result(res, out / "run.png"))
+    return 0
+
+
+def _cmd_params(a) -> int:
+    """``bolts params``: list parameters with their status; filter by text or by status (``--status unknown`` shows what is missing)."""
+    p = load_parameters(a.params, parse_overrides(a.set) or None)
+    rows = [q for q in p.params() if (not a.filter or a.filter in q.key) and (not a.status or q.status.value == a.status)]
+    print(f"{'key':44s} {'value':>14s} {'unit':10s} {'status':9s}")
+    for q in rows:
+        print(f"{q.key:44s} {str(q.value)[:14]:>14s} {q.unit:10s} {q.status.value:9s}")
+    print(f"\n{len(rows)} shown; counts {p.counts()}; fingerprint {p.fingerprint()}")
+    return 0
+
+
+def _cmd_validate(a) -> int:
+    """``bolts validate``: run the analytic cases; the exit code is 1 if any fails (usable in CI)."""
+    from .validation import run_all
+    bad = 0
+    for c in run_all():
+        ok = "PASS" if c.passed else "FAIL"
+        bad += not c.passed
+        print(f"{c.name:16s} error {c.error:.2e} (tolerance {c.tolerance:.1e})  {ok}  {c.detail}")
+    return 1 if bad else 0
+
+
+def _cmd_spice(a) -> int:
+    """``bolts spice``: write the netlist; with ``--run`` also run ngspice and compare every node voltage."""
+    from .spice.compare import compare_voltages
+    from .spice.netlist import write_netlist
+    from .spice.run_ngspice import ngspice_path, run_ngspice
+    p = _params(a)
+    rec = load_waveform(a.csv, params=p)
+    res = run_transient(build_network(p, rec), p, dt_s=a.dt)
+    path = write_netlist(res, a.out)
+    print("wrote", path)
+    if a.run:
+        if ngspice_path() is None:
+            print("ngspice not found on PATH; netlist written only", file=sys.stderr)
+            return 1
+        v = run_ngspice(res.transient.system, res.transient.t_s, res.transient.v_tot_V)
+        c = compare_voltages(res.transient.nodes_V, v)
+        print(f"BOLTS against ngspice: max difference {c['max_abs_V']:.3e} V ({c['max_rel']:.2e} of {c['scale_V']:.0f} V), RMS {c['rms_V']:.3e} V")
+    return 0
+
+
+def _cmd_doctor(a) -> int:
+    """``bolts doctor``: versions, optional tools found, and what is registered (first thing to run when something misbehaves)."""
+    import platform
+
+    import numpy
+    import scipy
+
+    from .registry import element_names, waveform_names
+    from .spice.run_ngspice import ngspice_path
+    print(f"bolts {__version__}  python {platform.python_version()}  numpy {numpy.__version__}  scipy {scipy.__version__}")
+    print(f"ngspice: {ngspice_path() or 'not found (optional; needed only for the SPICE cross-check)'}")
+    for mod in ("matplotlib", "pandas"):
+        try:
+            __import__(mod)
+            print(f"{mod}: available")
+        except ImportError:
+            print(f"{mod}: not installed (optional extra)")
+    p = load_parameters()
+    print(f"parameters: {p.counts()}  fingerprint {p.fingerprint()}")
+    print(f"elements: {', '.join(element_names())}")
+    print(f"waveforms: {', '.join(waveform_names()) or '(none registered yet)'}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argument parser (separate from :func:`main` so tests can inspect it)."""
+    ap = argparse.ArgumentParser(prog="bolts", description="BOLTS: Branching-unit and Optical-repeater power-feed Loop Transient Simulator.")
+    ap.add_argument("--version", action="version", version=f"bolts {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run", help="run a voltage record through the whole chain")
+    _add_input_args(r)
+    r.add_argument("--out", default="outputs/run", help="output directory")
+    r.add_argument("--plot", action="store_true", help="also write a figure (needs matplotlib)")
+    r.set_defaults(fn=_cmd_run)
+    q = sub.add_parser("params", help="list parameters with unit, status and source")
+    q.add_argument("--params")
+    q.add_argument("--set", action="append")
+    q.add_argument("--filter", help="only keys containing this text")
+    q.add_argument("--status", choices=["sourced", "assumed", "unknown", "override"])
+    q.set_defaults(fn=_cmd_params)
+    v = sub.add_parser("validate", help="run the analytic validation cases")
+    v.set_defaults(fn=_cmd_validate)
+    s = sub.add_parser("spice", help="export an ngspice netlist (and compare with ngspice)")
+    _add_input_args(s)
+    s.add_argument("--out", default="outputs/bolts.cir")
+    s.add_argument("--run", action="store_true", help="run ngspice and compare the node voltages")
+    s.set_defaults(fn=_cmd_spice)
+    d = sub.add_parser("doctor", help="check the installation")
+    d.set_defaults(fn=_cmd_doctor)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point (``bolts`` script). Returns 0 on success, 1 for failed validation, 2 for a user error such as a missing file."""
+    a = build_parser().parse_args(argv)
+    try:
+        return a.fn(a)
+    except BoltsError as e:
+        print(f"bolts: {e}", file=sys.stderr)
+        return 2
+    except FileNotFoundError as e:
+        print(f"bolts: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bolts/config/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty

bolts/config/defaults/bu.toml

@@ -0,0 +1,6 @@
+# Branching units: placeholders for v0.3. All unknown until an architecture and vendor data exist.
+[bu]
+sea_earth_resistance_ohm   = { value = "TBD", unit = "ohm", status = "unknown", source = "BU sea-earth electrode; design data" }
+relay_on_resistance_ohm    = { value = "TBD", unit = "ohm", status = "unknown", source = "power-switching relay in the closed state" }
+current_limiting_ohm       = { value = "TBD", unit = "ohm", status = "unknown", source = "resistor bank used against hot switching (Chesnoy p. 395)" }
+electrode_mass_kg          = { value = 25.0, unit = "kg", status = "sourced", source = "Chesnoy p. 395: a copper BU sea-earth electrode has a mass of about 25 kg" }

bolts/config/defaults/cable.toml

@@ -0,0 +1,18 @@
+# Cable and link. Every parameter: value, unit, status (sourced | assumed | unknown | override), source.
+[cable]
+length_km               = { value = 750.8, unit = "km", status = "assumed", source = "Point Hope to Gambell link of the pfe_design study (route chainage 5601.2 to 6352.0 km); replace for another link" }
+resistance_ohm_per_km   = { value = 1.0, unit = "ohm/km", status = "sourced", source = "Chesnoy ch.13 (printed p. 479): typical linear ohmic resistance about 1 ohm/km" }
+capacitance_uF_per_km   = { value = 0.2, unit = "uF/km", status = "assumed", source = "placeholder, conductor to sea; vendor value unknown. Provider: bolts.properties (constant now, section table in v0.2)" }
+leakage_S_per_km        = { value = 0.0, unit = "S/km", status = "assumed", source = "placeholder (G' = 0); vendor value unknown. Provider: bolts.properties" }
+inductance_mH_per_km    = { value = "TBD", unit = "mH/km", status = "unknown", source = "needed for microsecond surges (v0.2); not used by the slow GMD runs. A few tenths of a henry over 750 km is the pfe_design estimate" }
+emf_share_of_loop       = { value = 1.0, status = "assumed", source = "fraction of the record's net end-to-end voltage applied along the cable (spread evenly over every span)" }
+seabed_temperature_C      = { value = 4.0, unit = "C", status = "assumed", source = "deep-sea water temperature (about 2 to 4 C); used only by the temperature-dependent provider (bolts.properties.temperature_R), which is opt-in. Replace with the route's measured seabed temperature" }
+conductor_tempco_per_K    = { value = 0.00393, unit = "1/K", status = "assumed", source = "textbook temperature coefficient of copper resistance at 20 C; check against the cable vendor's conductor datasheet" }
+resistance_reference_temperature_C = { value = 20.0, unit = "C", status = "assumed", source = "temperature at which resistance_ohm_per_km is taken to apply when the temperature-dependent provider is used; the sourced 1 ohm/km does not state one" }
+temperature_model         = { value = "off", status = "assumed", source = "'off' keeps the constant resistance_ohm_per_km; 'copper' scales it by 1 + alpha (T - T_ref) at the seabed temperature (bolts.properties.temperature_R). Off by default so the pfe_design regression holds" }
+section_table_csv         = { value = "none", status = "assumed", source = "path to a per-section table (x_start_km, x_end_km, r_ohm_per_km, c_uF_per_km[, g_S_per_km, l_mH_per_km]) from the cable design; 'none' = uniform values above. data/example_cable_sections.csv is an illustration only" }
+depth_profile_csv         = { value = "none", status = "assumed", source = "path to the route's water depth (columns x_km, depth_m); 'none' = depth ignored. data/example_route_depth.csv is an illustration only" }
+depth_temperature_csv     = { value = "none", status = "assumed", source = "path to seabed temperature by depth (columns depth_m, temperature_C); 'none' = the constant seabed_temperature_C. data/example_depth_temperature.csv is an illustration only" }
+insulation_exponent_n     = { value = "TBD", status = "unknown", source = "exponent n of the insulation life law V^n t = constant (Chesnoy Eq. 10.1, from Dakin 1983); device-specific, unpublished. Sweep 10 to 40 in studies" }
+design_life_years         = { value = 25.0, unit = "years", status = "assumed", source = "typical design life of submerged plant; used with the nominal end voltage as the reference point of the life law. Confirm with the operator" }
+

bolts/config/defaults/earthing.toml

@@ -0,0 +1,10 @@
+[earthing]
+landing_earth_resistance_ohm      = { value = 3.0, unit = "ohm", status = "sourced", source = "Chesnoy Sec. 10.2.4 (p. 387): system earth electrodes typically below 3 ohm (upper bound used)" }
+station_vs_system_earth_V_nominal = { value = 20.0, unit = "V", status = "sourced", source = "Chesnoy Sec. 10.2.4 (p. 387): recommended nominal difference between system earth and station earth, at most 20 V (reference)" }
+station_vs_system_earth_V_lightning = { value = 90.0, unit = "V", status = "sourced", source = "Chesnoy Sec. 10.2.4 (p. 387): exceptional increase to 90 V in a lightning environment (reference)" }
+soil_resistivity_ohm_m            = { value = "TBD", unit = "ohm m", status = "unknown", source = "soil resistivity at the landing; measure with the Wenner method (bolts.earthing.soil.wenner_resistivity_ohm_m). With the four rod_* parameters it sets the landing earth resistance instead of the 3 ohm bound. Typical range 10 (wet) to 3000 ohm m (rock)" }
+rod_count                         = { value = "TBD", status = "unknown", source = "number of buried rods in a line at each landing (1 to 4; Chesnoy Eq. 10.4 tabulates lambda for 2, 3 and 4); station design" }
+rod_length_m                      = { value = "TBD", unit = "m", status = "unknown", source = "buried length b of each rod (Chesnoy Eq. 10.3); station design" }
+rod_radius_m                      = { value = "TBD", unit = "m", status = "unknown", source = "radius r of each rod; station design" }
+rod_spacing_m                     = { value = "TBD", unit = "m", status = "unknown", source = "spacing a between rods in the line (needed for n >= 2); station design" }
+

bolts/config/defaults/forcing.toml

@@ -0,0 +1,10 @@
+# Your own voltage record (net end-to-end induced voltage V_ind(t), volts; positive drives current toward increasing chainage).
+[forcing]
+csv_path        = { value = "data/example_vind_1s.csv", status = "assumed", source = "path to the voltage CSV, relative to the current directory (or absolute). The shipped file is SYNTHETIC (storm backbone (peak about -200 V), random 2.5 to 600 s pulsations, one onset impulse; scripts/make_synthetic_vind.py); replace it with your 1-second or sub-second record" }
+time_column     = { value = "t_s", status = "assumed", source = "name of the time column" }
+time_format     = { value = "seconds", status = "assumed", source = "'seconds' (any origin; the run starts at 0) or 'iso' (ISO-8601 timestamps)" }
+voltage_column  = { value = "v_ind_V", status = "assumed", source = "name of the voltage column (volts)" }
+scale           = { value = 1.0, status = "assumed", source = "multiplies every voltage in the file" }
+window_start_s  = { value = 0.0, unit = "s", status = "assumed", source = "start of the window, seconds from the first row" }
+window_end_s    = { value = -1.0, unit = "s", status = "assumed", source = "end of the window, seconds from the first row; negative means the end of the file" }
+model_dt_s      = { value = 0.0, unit = "s", status = "assumed", source = "step of the run; 0 = the file's own spacing; otherwise resampled by linear interpolation" }

bolts/config/defaults/lightning.toml

@@ -0,0 +1,5 @@
+# Lightning: placeholders for v0.2 to v0.4. Standard values must be verified from IEC 62305 and CIGRE before use.
+[lightning]
+peak_current_median_kA     = { value = "TBD", unit = "kA", status = "unknown", source = "median first-stroke peak current (log-normal statistics); verify against CIGRE / IEEE" }
+ground_flash_density_per_km2_yr = { value = "TBD", unit = "1/(km2 yr)", status = "unknown", source = "site thunderstorm statistics (keraunic level)" }
+rod_to_pfe_earth_separation_m   = { value = "TBD", unit = "m", status = "unknown", source = "Chesnoy p. 390: the influence is roughly inversely proportional to the separation of the two earths" }

bolts/config/defaults/optical.toml

@@ -0,0 +1,19 @@
+# Optical chain and terminal (ported from the pfe_design study; Chesnoy printed pages in the sources).
+[optical]
+laser_threshold_fraction   = { value = 0.2, status = "assumed", source = "pump threshold as a fraction of the nominal laser current; vendor unknown (swept 0, 0.2, 0.4 in pfe_design)" }
+noise_figure_dB            = { value = 4.5, unit = "dB", status = "sourced", source = "Chesnoy Sec. 4.4.5 (printed p. 143): noise figure 4.5 dB in the worked example" }
+output_power_per_channel_dBm = { value = -2.5, unit = "dBm", status = "assumed", source = "repeater output per channel; from the Chesnoy p. 143 example (does not reproduce with its own formula)" }
+fiber_attenuation_dB_per_km = { value = 0.2, unit = "dB/km", status = "sourced", source = "Chesnoy Sec. 5.4.2.2 (printed p. 191)" }
+extra_span_loss_dB         = { value = 0.0, unit = "dB", status = "assumed", source = "splices, connectors, repairs (repairs 3 dB deep water, 0.5 dB shallow, p. 191)" }
+osnr_constant_dB           = { value = 58.0, unit = "dB", status = "sourced", source = "Chesnoy Eq. 5.23 (printed p. 189): OSNR = P_in - 10 log10 k - NF + 58 (P_in = repeater INPUT power per wavelength)" }
+optical_bandwidth_GHz      = { value = 12.5, unit = "GHz", status = "sourced", source = "Chesnoy Sec. 3.4.6 (printed p. 88): 0.1 nm = 12.5 GHz at 1550 nm" }
+baud_rate_GBd              = { value = 25.0, unit = "GBd", status = "sourced", source = "Chesnoy Fig. 5.25 (printed p. 190): theoretical 25 GBd PDM-QPSK transponder (the ITU table implies about 44 GBd)" }
+channel_rate_Gbps          = { value = 100.0, unit = "Gbit/s", status = "assumed", source = "reference channel for the Shannon-gap calibration" }
+penalties_total_dB         = { value = 3.5, unit = "dB", status = "sourced", source = "Chesnoy Table 5.1 (p. 199): 3.5 dB of impairments of the ITU-T G.977 example (10 000 km; conservative for a short link)" }
+terminal_back_to_back_Q_dB = { value = 17.1, unit = "dB", status = "sourced", source = "Chesnoy Table 5.1 (p. 199) line 4; combined by Eq. 5.29 (p. 200)" }
+q2_limit_dB                = { value = 5.0, unit = "dB", status = "sourced", source = "Chesnoy Table 5.1 (p. 199) line 6 'Q limit compliance with ITU after FEC' = 5.0 dB (defined p. 201)" }
+bits_per_symbol_ladder     = { value = [2, 3, 4, 5, 6], status = "sourced", source = "Chesnoy Sec. 5.7.2 (printed pp. 225-227): QPSK 2, 8QAM 3, 16QAM 4, 32QAM 5, 64QAM 6 bits per symbol" }
+relock_time_s              = { value = 10.0, unit = "s", status = "assumed", source = "receiver relock after an outage; not given by Chesnoy (cycle slips corrupt symbols until the next pilot frame, p. 187); vendor. Swept 0 to 30 s in pfe_design" }
+adaptation_delay_s         = { value = 5.0, unit = "s", status = "assumed", source = "outage time before the terminal steps down a format; vendor unknown" }
+upshift_hold_s             = { value = 60.0, unit = "s", status = "assumed", source = "margin must hold this long before stepping back up" }
+switch_margin_dB           = { value = 0.5, unit = "dB", status = "assumed", source = "spare SNR required when stepping to another format" }

bolts/config/defaults/pfe.toml

@@ -0,0 +1,21 @@
+[pfe]
+feed_current_A             = { value = 1.0, unit = "A", status = "assumed", source = "inside the sourced 0.5 to 1.5 A repeater range (Chesnoy ch.12)" }
+max_voltage_kV_per_end     = { value = 2.5, unit = "kV", status = "assumed", source = "operator basis of pfe_design: 5 kV in total, 2.5 kV per end with the 50/50 split. Override for what-ifs (pfe_design also ran 0.75 kV per end = 1.5 kV total)" }
+split_fraction_end_A       = { value = 0.5, status = "sourced", source = "NEC / Chesnoy p. 392: each end normally feeds half of the system voltage, with opposite signs" }
+feed_configuration         = { value = "double_end", status = "sourced", source = "Chesnoy pp. 392-393: double-end feeding; single_end after one PFE fails" }
+feed_direction             = { value = 1, status = "assumed", source = "+1: feed current flows toward increasing chainage; an induced voltage along +chainage then assists the PFEs" }
+regulator_bandwidth_Hz     = { value = 200.0, unit = "Hz", status = "sourced", source = "Chesnoy Sec. 10.3.2 (p. 390): a PFE current controller typically operates on a control loop of around 200 Hz bandwidth (stated in a lightning discussion; no loop shape given)" }
+regulator_response_s       = { value = 0.005, unit = "s", status = "assumed", source = "tau = 1 / regulator_bandwidth_Hz = 5 ms (convention of the pfe_design study, no 2 pi); the 1/(2 pi 200 Hz) = 0.8 ms reading is a sensitivity. First-order loop, integrated exactly over each step" }
+converter_modules          = { value = "TBD", status = "unknown", source = "series converter modules per PFE (n+1 redundancy); a vendor catalogue shows 6 with 5 needed, Chesnoy p. 398: N:1 protected" }
+failover_time_s            = { value = "TBD", unit = "s", status = "unknown", source = "converter transfer time; a web claim of under 50 ms is unverified and is NOT used" }
+output_filter_L_mH         = { value = "TBD", unit = "mH", status = "unknown", source = "PFE output filter inductance (v0.2 surges); vendor" }
+output_filter_C_uF         = { value = "TBD", unit = "uF", status = "unknown", source = "PFE output filter capacitance (v0.2 surges); vendor" }
+converter_module_rating_V  = { value = "TBD", unit = "V", status = "unknown", source = "voltage rating of one series converter module (the PFE cap is about modules x rating); vendor. For studies the cap is max_voltage_kV_per_end" }
+output_slew_limit_V_per_s  = { value = "TBD", unit = "V/s", status = "unknown", source = "fastest rate at which the PFE can change its output (slow ramp-up/down, Chesnoy p. 397); vendor. Sweep 10 V/s to 1 kV/s in studies" }
+overcurrent_trip_fraction  = { value = "TBD", status = "unknown", source = "line current, as a multiple of the set current, above which the PFE shuts itself down (Chesnoy p. 397: 'a specified threshold'); vendor. Study 08 sweeps 1.2, 1.5 and 2.0" }
+overcurrent_trip_delay_s   = { value = "TBD", unit = "s", status = "unknown", source = "how long the current must stay above the trip level before the PFE shuts down; vendor. Study 08 uses 1 s" }
+trip_hold_s                = { value = "TBD", unit = "s", status = "unknown", source = "time from a trip to a restart attempt, including discharge of the cable (resistive, then short, Chesnoy p. 397); operator procedure. Study 08 uses 30 s" }
+restart_ramp_V_per_s       = { value = "TBD", unit = "V/s", status = "unknown", source = "voltage ramp-up rate of a restart; vendor. Study 08 uses 20 V/s" }
+converter_spare_modules    = { value = 1, status = "assumed", source = "N:1 protection (Chesnoy p. 397): one spare module per bank; a vendor catalogue shows 6 modules with 5 needed" }
+converter_failed_modules   = { value = 0, status = "assumed", source = "modules out of service in a what-if; 0 = healthy. Used only when converter_modules and converter_module_rating_V are given" }
+

bolts/config/defaults/repeater.toml

@@ -0,0 +1,14 @@
+[repeater]
+spacing_km                 = { value = 60.0, unit = "km", status = "assumed", source = "typical spacing; Chesnoy examples use 50 to 70 km (p. 191)" }
+voltage_drop_V             = { value = 56.0, unit = "V", status = "sourced", source = "Chesnoy ch.12 (pp. 430-431): about 56 V for an 8 amp-pair unipolar repeater (Zener stack)" }
+dynamic_resistance_ohm     = { value = 5.0, unit = "ohm", status = "assumed", source = "placeholder slope of the Zener stack; vendor value unknown (pfe_design swept 0 to 60 ohm)" }
+current_margin_fraction    = { value = 0.10, status = "sourced", source = "Chesnoy Table 10.1 (p. 385): 10% electroding margin" }
+pump_current_fraction      = { value = 0.8, status = "sourced", source = "Chesnoy Table 10.1 (p. 385): laser current 80% of the line current" }
+control_current_fraction   = { value = 0.1, status = "sourced", source = "Chesnoy Table 10.1 (p. 385): control circuit 10%" }
+zener_knee_current_A       = { value = "TBD", unit = "A", status = "unknown", source = "v0.2 piecewise Zener: current where the stack starts to conduct; vendor datasheet" }
+zener_power_rating_W       = { value = "TBD", unit = "W", status = "unknown", source = "continuous power rating of the shunt stack (damage criterion); vendor" }
+zener_surge_rating_A       = { value = "TBD", unit = "A", status = "unknown", source = "8/20 us surge rating of the clamp; the book gives only the repeater bypass (200 A long pulses, 450 A at 15 kV short pulses, p. 392)" }
+zener_temp_coeff_mV_per_K  = { value = "TBD", unit = "mV/K", status = "unknown", source = "temperature coefficient of the stack voltage (v0.5 electro-thermal Zener); vendor" }
+housing_capacitance_nF     = { value = "TBD", unit = "nF", status = "unknown", source = "repeater housing to sea, the surge path to earth (v0.2); vendor" }
+zener_below_knee_fraction = { value = "TBD", status = "unknown", source = "voltage across the repeater at zero current as a fraction of its value at the knee: 0 = the repeater circuit is resistive below the knee (the voltage falls to zero with the current), 1 = the voltage stays put (laser-diode-like). Used with zener_knee_current_A; if only the knee is given the model uses 0, the strongest effect. Study range 0 to 0.9" }
+

bolts/config/defaults/solver.toml

@@ -0,0 +1,3 @@
+[solver]
+dt_s        = { value = 0.1, unit = "s", status = "assumed", source = "time step of the transient. The regulator is integrated exactly, so any dt / tau is accepted; a jump between two samples is a ramp over dt" }
+integrator  = { value = "backward_euler", status = "assumed", source = "backward_euler (stable for the stiff ladder); trapezoid is planned" }

bolts/config/loader.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""Read parameter files (TOML) and merge them over the shipped defaults."""
+from __future__ import annotations
+
+import pathlib
+import tomllib
+from typing import Any
+
+from ..errors import ConfigError
+from .provenance import TBD, Param, Status
+from .schema import ParameterSet
+from .validate import validate
+
+DEFAULTS_DIR = pathlib.Path(__file__).with_name("defaults")
+
+
+def _parse_table(section: str, name: str, raw: Any, from_user: bool) -> Param:
+    """Turn one TOML entry into a :class:`Param`. Shipped defaults must be complete tables (value, status, source) so that nothing enters
+    the package without provenance; user files may use a bare value, which becomes an ``override``."""
+    if isinstance(raw, dict):
+        if "value" not in raw:
+            raise ConfigError(f"{section}.{name}: a table needs a 'value'")
+        status = raw.get("status", "override" if from_user else None)
+        if status is None:
+            raise ConfigError(f"{section}.{name}: missing 'status'")
+        if "source" not in raw and not from_user:
+            raise ConfigError(f"{section}.{name}: missing 'source'")
+        try:
+            st = Status(status)
+        except ValueError as e:
+            raise ConfigError(f"{section}.{name}: status {status!r} not in {[s.value for s in Status]}") from e
+        return Param(section, name, raw["value"], raw.get("unit", ""), st, raw.get("source", "user file"))
+    if not from_user:
+        raise ConfigError(f"{section}.{name}: defaults must be tables with value, status and source")
+    return Param(section, name, raw, "", Status.OVERRIDE, "user file")      # a bare value in a user file
+
+
+def _read(path: pathlib.Path) -> dict[str, Any]:
+    """Parse a TOML file (stdlib ``tomllib``, so no extra dependency)."""
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def load_parameters(path: str | pathlib.Path | None = None, overrides: dict[str, Any] | None = None) -> ParameterSet:
+    """Shipped defaults, then the optional user TOML ``path``, then ``overrides`` ({"section.name": value}).
+
+    In a user file a parameter may be a full table (``{value, unit, status, source}``) or a bare value, which becomes an
+    ``override``. Unknown (TBD) parameters stay unknown until somebody supplies them."""
+    data: dict[str, dict[str, Param]] = {}
+    # layer 1: every shipped defaults file (one per topic: cable, repeater, pfe, ...)
+    for f in sorted(DEFAULTS_DIR.glob("*.toml")):
+        for sec, params in _read(f).items():
+            for name, raw in params.items():
+                data.setdefault(sec, {})[name] = _parse_table(sec, name, raw, from_user=False)
+    # layer 2: the user's file; a key that does not exist in the defaults is a typo, so it is an error, not a silent new setting
+    if path is not None:
+        p = pathlib.Path(path)
+        if not p.exists():
+            raise ConfigError(f"parameter file {p} not found")
+        for sec, params in _read(p).items():
+            for name, raw in params.items():
+                if sec not in data or name not in data[sec]:
+                    raise ConfigError(f"{p.name}: unknown parameter {sec}.{name}")
+                old = data[sec][name]
+                new = _parse_table(sec, name, raw, from_user=True)
+                data[sec][name] = Param(sec, name, new.value, new.unit or old.unit, new.status, new.source)   # keep the unit if the user gave none
+    ps = ParameterSet(data)
+    # layer 3: programmatic or command-line overrides
+    if overrides:
+        ps = ps.with_overrides(overrides)
+    validate(ps)         # last: reject values that would make the physics meaningless
+    return ps
+
+
+__all__ = ["DEFAULTS_DIR", "TBD", "load_parameters"]

bolts/config/overrides.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""Parse ``section.key=value`` strings (command line ``--set``) into an override dictionary."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..errors import ConfigError
+
+
+def parse_overrides(items: list[str] | None) -> dict[str, Any]:
+    """``["pfe.max_voltage_kV_per_end=2.5", ...]`` -> ``{"pfe.max_voltage_kV_per_end": 2.5}``."""
+    out: dict[str, Any] = {}
+    for item in items or []:
+        if "=" not in item:
+            raise ConfigError(f"override {item!r} must look like section.key=value")
+        key, raw = item.split("=", 1)
+        try:
+            out[key.strip()] = json.loads(raw)       # numbers, true/false, lists, "quoted strings"
+        except json.JSONDecodeError:
+            out[key.strip()] = raw                    # bare words stay strings
+    return out

bolts/config/provenance.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# Copyright (C) 2026 Shibaji Chakraborty
+"""Parameter provenance: every number carries its unit, its status and where it came from.
+
+Statuses
+    sourced   taken from a document (the source string names it)
+    assumed   an illustrative placeholder, to be replaced or swept
+    unknown   ``TBD``: asking for it raises :class:`~bolts.errors.MissingParameter` instead of guessing
+    override  changed in code or on the command line for one run
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from ..errors import MissingParameter
+
+TBD = "TBD"
+
+
+class Status(StrEnum):
+    """Where a number stands; see the module docstring for what each value commits the code to."""
+
+    SOURCED = "sourced"
+    ASSUMED = "assumed"
+    UNKNOWN = "unknown"
+    OVERRIDE = "override"
+
+
+@dataclass(frozen=True)
+class Param:
+    """One parameter with its unit, status and source. Frozen: a changed value is a new Param with status ``override``."""
+
+    section: str
+    name: str
+    value: Any
+    unit: str
+    status: Status
+    source: str
+
+    @property
+    def key(self) -> str:
+        """``section.name``, as used in overrides and messages."""
+        return f"{self.section}.{self.name}"
+
+    @property
+    def is_unknown(self) -> bool:
+        """True while the value is the ``TBD`` marker."""
+        return isinstance(self.value, str) and self.value == TBD
+
+    def require(self) -> Any:
+        """The value, or :class:`MissingParameter` naming the parameter and the reason it is unknown."""
+        if self.is_unknown:
+            raise MissingParameter(f"{self.key} is unknown (TBD): {self.source}")
+        return self.value