PyELSSA 0.1.0__tar.gz → 0.1.1__tar.gz

{pyelssa-0.1.0 → pyelssa-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyELSSA
-Version: 0.1.0
+Version: 0.1.1
 Summary: This is 'ELSSA in Python' package owned by Network Rail Infrastructure Limited.
 License: Open Source Non-Commercial License (OSNCL) v2.0
 License-File: LICENSE
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: h5py
 Requires-Dist: matplotlib
 Requires-Dist: numpy
 Requires-Dist: pandas

{pyelssa-0.1.0 → pyelssa-0.1.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "PyELSSA"
-version = "0.1.0"
+version = "0.1.1"
 description = "This is 'ELSSA in Python' package owned by Network Rail Infrastructure Limited."
 authors = ["Jieming Ye <Jieming.Ye@networkrail.co.uk>"]
 readme = "README.md"
@@ -29,6 +29,7 @@ pandas = "*"
 matplotlib = "*"
 scipy = "*"
 psutil = "*"
+h5py = "*"
 
 [tool.poetry.group.dev.dependencies]
 flake8 = "*"

{pyelssa-0.1.0 → pyelssa-0.1.1}/src/PyELSSA/__init__.py

@@ -8,7 +8,7 @@
 # Copyright (c) 2026 [Jieming Ye]
 #
 # This Python source code is licensed under the 
-# Open Source Non-Commercial License (OSNCL) v1.0
+# Open Source Non-Commercial License (OSNCL) v2.0
 # See LICENSE for details.
 #=================================================================
 """

{pyelssa-0.1.0 → pyelssa-0.1.1}/src/PyELSSA/configuration.py

@@ -8,7 +8,7 @@
 # Copyright (c) 2026 [Jieming Ye]
 #
 # This Python source code is licensed under the 
-# Open Source Non-Commercial License (OSNCL) v1.0
+# Open Source Non-Commercial License (OSNCL) v2.0
 # See LICENSE for details.
 #=================================================================
 """

pyelssa-0.1.1/src/PyELSSA/core/__init__.py

@@ -0,0 +1,27 @@
+from .network import Network, Conductor, CONDUCTOR_LIBRARY
+from .carson import (series_impedance_matrix, shunt_admittance_matrix,
+                     carson_PQ_theta, potential_coeff_matrix)
+from .ybus import YbusBuilder
+from .modal import modal_decompose, symmetrical_components
+from .harmonic import sweep, mode_shape, find_resonances
+from .elssa import (read_cross_section, parse_setup, build_from_elssa,
+                    parse_locations, parse_conn_sets)
+from .harmonic_sweep import sweep_Zfx, resonance_map, all_resonances_at
+from .qqtt import (dispersion, band_edges, cell_abcd, loop_zy_from_network,
+                   kronig_penney_comparison)
+from .train_epr import train_epr_sweep, train_epr_profile
+
+__all__ = [
+    "System",
+    "Network", "Conductor", "CONDUCTOR_LIBRARY",
+    "series_impedance_matrix", "shunt_admittance_matrix",
+    "carson_PQ_theta", "potential_coeff_matrix",
+    "YbusBuilder", "modal_decompose", "symmetrical_components",
+    "sweep", "mode_shape", "find_resonances",
+    "read_cross_section", "parse_setup", "build_from_elssa",
+    "parse_locations", "parse_conn_sets",
+    "sweep_Zfx", "resonance_map", "all_resonances_at",
+    "dispersion", "band_edges", "cell_abcd", "loop_zy_from_network",
+    "kronig_penney_comparison",
+    "train_epr_sweep", "train_epr_profile",
+]

pyelssa-0.1.1/src/PyELSSA/core/busbar.py

@@ -0,0 +1,118 @@
+"""
+busbar.py -- supply-point busbar element for PyELSSA.
+
+In ELSSA a "busbar" is the common connection at a feeder station / supply point
+where the grid supply (via the SGT/ATFT), the transformer secondary, and the
+outgoing feeders all tie together. The base model represents the supply as a
+centre-tapped source injected at the supply location; this module treats that
+location as a first-class BUSBAR node and adds the quantities an engineer needs
+there:
+
+  * Busbar FAULT LEVEL -- the fault current the busbar and its switchgear must
+    interrupt (a fault from the busbar OLE to the return/earth at the supply
+    point). This is the fundamental switchgear-rating and protection-grading
+    quantity, and it was the most likely intent of ELSSA's unfinished busbar tag.
+
+  * Busbar VOLTAGE -- the supply-point voltage that everything downstream
+    references (the point of common coupling with the grid).
+
+  * MULTI-FEEDER support -- several feeders sharing one supply busbar, so the
+    interaction between feeders through the shared supply is captured (one
+    feeder's load pulling the busbar voltage seen by the others).
+
+This is implemented on top of the validated bordered-MNA solve: a busbar fault
+is the same rank-1 (Sherman-Morrison) fault update Study.fault() uses, applied
+at the busbar node. No change to the validated assembly -- the busbar is a view
+onto the supply location plus the fault/voltage queries there.
+"""
+from __future__ import annotations
+import numpy as np
+from dataclasses import dataclass
+from typing import Optional, List, Dict
+
+
+@dataclass
+class BusbarResult:
+    location_m: float
+    fault_level_ka: float          # busbar fault current (OLE-to-rail at busbar)
+    voltage_kv: float              # no-load busbar voltage (OLE-to-rail)
+    fault_mva: float               # apparent fault level S = sqrt(3)*V*I (3-ph equiv)
+    cond_ole: int
+    cond_rail: int
+
+
+class Busbar:
+    """A supply-point busbar at a chainage. Provides fault level and voltage,
+    using the feeder's OLE and rail conductors as the busbar terminals.
+
+    study      : a solved Study
+    location_m : the supply-point chainage (e.g. the ATFT/ATFS location)
+    feeder_key : which feeder's conductors define the busbar terminals
+                 (defaults to the first feeder). The OLE conductor is the
+                 busbar live side; the traction rail is the return.
+    """
+    def __init__(self, study, location_m: float, feeder_key: Optional[str] = None):
+        self.study = study
+        self.location_m = location_m
+        if feeder_key is None:
+            feeder_key = next(iter(study.feeders)) if study.feeders else None
+        self.feeder_key = feeder_key
+        if feeder_key is not None and feeder_key in study.feeders:
+            f = study.feeders[feeder_key]
+            self.cond_ole = f.cw0
+            self.cond_rail = f.rail0
+        else:
+            # fall back to common defaults (OLE cond, rail cond) if no feeders
+            self.cond_ole = 4
+            self.cond_rail = 10
+
+    # ---- busbar voltage ------------------------------------------------
+    def voltage_kv(self) -> float:
+        """No-load busbar voltage (OLE-to-rail) at the supply point."""
+        st = self.study
+        ia = st.node(self.location_m, self.cond_ole)
+        ib = st.node(self.location_m, self.cond_rail)
+        return abs(st.V0[ia] - st.V0[ib]) / 1e3
+
+    # ---- busbar fault level (switchgear rating) ------------------------
+    def fault_level(self, zf: complex = 0.0) -> BusbarResult:
+        """Fault level AT the busbar: a fault from the busbar OLE to the rail
+        (return) at the supply location. This is the current the busbar
+        switchgear must interrupt. zf is an optional fault-arc impedance
+        (0 = bolted fault, the worst case)."""
+        st = self.study
+        r = st.fault(self.location_m, cond_a=self.cond_ole,
+                     cond_b=self.cond_rail, **({} if zf == 0 else {}))
+        Ika = abs(r.I) / 1e3
+        Vkv = self.voltage_kv()
+        # apparent single-phase fault level at the busbar (V*I); for a 25 kV
+        # single-phase traction busbar this is the relevant rating figure.
+        mva = Vkv * Ika
+        return BusbarResult(location_m=self.location_m, fault_level_ka=Ika,
+                            voltage_kv=Vkv, fault_mva=mva,
+                            cond_ole=self.cond_ole, cond_rail=self.cond_rail)
+
+    # ---- feeder interaction through the busbar -------------------------
+    def feeder_voltages(self, feeder_keys: Optional[List[str]] = None,
+                        sample_m: Optional[float] = None) -> Dict[str, float]:
+        """No-load OLE-to-rail voltage seen by each feeder at the busbar (or at
+        `sample_m` if given). Sampling at the busbar location -- not the feeder
+        start, which may sit in an unenergised transition zone -- gives the
+        physically meaningful supply voltage each feeder sees. With load present
+        (via a train solve) this reveals the busbar/feeder interaction."""
+        st = self.study
+        keys = feeder_keys or list(st.feeders.keys())
+        x = sample_m if sample_m is not None else self.location_m
+        out = {}
+        for k in keys:
+            f = st.feeders[k]
+            ia = st.node(x, f.cw0); ib = st.node(x, f.rail0)
+            out[k] = abs(st.V0[ia] - st.V0[ib]) / 1e3
+        return out
+
+
+def busbar_fault_levels(study, locations_m: List[float],
+                        feeder_key: Optional[str] = None) -> List[BusbarResult]:
+    """Compute busbar fault level at several supply points at once -- e.g. all
+    ATFT/ATFS locations -- for switchgear rating across the route."""
+    return [Busbar(study, loc, feeder_key).fault_level() for loc in locations_m]

pyelssa-0.1.1/src/PyELSSA/core/carson.py

@@ -0,0 +1,371 @@
+"""
+Carson's earth-return series impedance for a multiconductor system.
+
+Rigorous infinite-series form (Carson 1926). All quantities in SI.
+Geometry in metres, frequency in Hz, earth resistivity in ohm-metre.
+
+The series impedance between conductors i and j (per unit length) is:
+
+    Z_ij = R_internal*delta_ij  +  j*omega*mu0/(2*pi) * ln(1/D_ij)
+           +  (Carson earth-return correction:  4*omega*1e-7 * (P + jQ))
+
+where D_ij is the geometric distance term (GMR for self, axial spacing
+for mutual) and P, Q are Carson's correction terms evaluated from the
+series in the parameter `a`.
+
+References: Carson (1926); Dommel EMTP Theory Book, ch. on line constants.
+"""
+
+from __future__ import annotations
+import numpy as np
+
+MU0 = 4.0e-7 * np.pi          # H/m
+EPS0 = 8.8541878128e-12       # F/m
+
+
+def _elssa_artificial_offset_active(x: np.ndarray) -> bool:
+    """Detect ELSSA cross-sections that use 1000 m x-offset blocks as route IDs.
+
+    Braybrooke/6200-style ELSSA CSVs use x coordinates such as 1004,
+    2004, 5004, etc.  Those thousand-metre offsets are not literal physical
+    separations for the Carson mutual impedance calculation; they are route /
+    track-group offsets used by ELSSA to keep parallel systems separated in
+    the cross-section table.
+    """
+    x = np.asarray(x, float)
+    return bool(np.nanmax(x) > 900.0 and (np.nanmax(x) - np.nanmin(x)) > 900.0)
+
+
+def _elssa_far_offset_mutual_ohm_per_m(dx: float, f: float) -> complex:
+    """ELSSA-compatible mutual Z for artificial route-offset separations.
+
+    This is a 50 Hz compatibility branch reverse-engineered against compiled
+    ELSSA Section.Z for the Braybrooke/6200 model.  It is used only when the
+    cross-section clearly contains artificial thousand-metre route offsets and
+    the conductor pair is separated by a large route offset (default >=500 m).
+
+    Compiled ELSSA Section.Z for those pairs is approximately:
+        Re(Zm) = 0.049345 ohm/km at 50 Hz
+        Im(Zm) = A / (|dx| + B)^2 + C ohm/km at 50 Hz
+
+    where |dx| is the artificial route-offset separation in metres.  Local
+    conductor pairs remain on the normal Carson branch.
+    """
+    D = max(abs(float(dx)), 1.0)
+    scale = float(f) / 50.0
+    real_per_km = 0.049345 * scale
+    imag_per_km = (32666.8256 / ((D + 286.648982) ** 2) - 0.0001257778) * scale
+    # Do not suppress this term.  Compiled ELSSA Section.Z extracts for the
+    # 6200/Braybrooke model retain this mutual coupling between the artificial
+    # route-offset groups.  The accidental ``0 *`` here disconnected the groups
+    # magnetically while leaving only explicit bonds/cables between them.
+    return (real_per_km + 1j * imag_per_km) / 1000.0
+
+
+def carson_PQ_theta(a: float, theta: float, kmax: int = 60) -> tuple[float, float]:
+    """
+    Carson's P and Q with the angle theta between the line connecting
+    conductor i and its own image, and the line connecting i to j's image.
+
+    For self impedance theta = 0.
+    For mutual impedance, theta is the angle subtended at conductor i by
+    conductor j and j's image (i.e. cos(theta) = (yi+yj)/Dij_image).
+
+    Convergent series (Dommel EMTP Theory Book eqns 4.50-4.61).
+    """
+    # Coefficient magnitudes b_k
+    kmax = int(kmax)
+    b = np.zeros(kmax + 3)
+    c = np.zeros(kmax + 3)
+    d = np.zeros(kmax + 3)
+    sign = np.zeros(kmax + 3)
+
+    b[1] = np.sqrt(2.0) / 6.0
+    b[2] = 1.0 / 16.0
+    # sign sequence: +,+,-,-,+,+,...
+    s = 1.0
+    for k in range(1, kmax + 1):
+        sign[k] = s
+        if k % 2 == 0:
+            s = -s
+    # magnitude recurrence: b_k = b_{k-2} * 1/(k*(k+2))
+    for k in range(3, kmax + 1):
+        b[k] = b[k - 2] / (k * (k + 2.0))
+    # apply signs
+    bsig = sign * b
+
+    # c_2 and recurrence
+    c[2] = 1.3659315
+    for k in range(4, kmax + 1, 2):
+        c[k] = c[k - 2] + 1.0 / k + 1.0 / (k + 2.0)
+    d = (np.pi / 4.0) * bsig
+
+    P = np.pi / 8.0 * (1.0)  # k=0 term
+    Q = -0.0386 + 0.5 * np.log(2.0 / a)
+
+    # k = 1 terms
+    P += -bsig[1] * a * np.cos(theta)
+    Q += bsig[1] * a * np.cos(theta)
+
+    # k = 2 terms (involve c2, d2, and ln)
+    a2 = a * a
+    P += (bsig[2] * a2) * (c[2] - np.log(a)) * np.cos(2 * theta) \
+        + bsig[2] * a2 * theta * np.sin(2 * theta)
+    Q += d[2] * a2 * np.cos(2 * theta)
+
+    # k >= 3 terms
+    ak = a2 * a  # a^3
+    for k in range(3, kmax + 1):
+        ck = np.cos(k * theta)
+        sk = np.sin(k * theta)
+        if k % 2 == 1:  # odd k: contributes to P and Q via b,d
+            P += -bsig[k] * ak * ck
+            Q += bsig[k] * ak * ck
+        else:           # even k
+            P += bsig[k] * ak * (c[k] - np.log(a)) * ck
+            P += bsig[k] * ak * theta * sk
+            Q += d[k] * ak * ck
+        ak *= a
+    return P, Q
+
+
+
+def elssa_series_impedance_matrix(
+    x: np.ndarray,
+    y: np.ndarray,
+    gmr: np.ndarray,
+    r_ac: np.ndarray,
+    f: float,
+    rho: float = 100.0,
+) -> np.ndarray:
+    """ELSSA/TIPS ``tracksectionz`` series matrix (ohm/m).
+
+    This is the numerical formulation recovered from the MATLAB R2014a
+    ``createsection`` build audit.  At 50 Hz and rho=100 ohm.m it reproduces
+    the exported 86x86 ECML matrix to floating-point precision.
+
+    ELSSA uses the classic simplified Carson constants rather than the
+    rigorous infinite series:
+
+    * earth-return resistance = 0.049345 ohm/km at 50 Hz;
+    * equivalent earth depth ``De = 658.5*sqrt(rho/f)`` metres;
+    * self X = k*ln(De/GMR);
+    * mutual X = k*ln(D_image/D_direct).
+
+    The compiled routine evaluates every ordered matrix entry using the signed
+    height difference ``De + y[j] - y[i]``.  Consequently the exported matrix
+    is slightly non-symmetric when conductor heights differ.  Although unusual,
+    preserving this behaviour is necessary for bit-level parity with the
+    p-coded function and the MATLAB solution.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    gmr = np.asarray(gmr, dtype=float)
+    r_ac = np.asarray(r_ac, dtype=float)
+    if not (len(x) == len(y) == len(gmr) == len(r_ac)):
+        raise ValueError("x, y, gmr and r_ac must have the same length")
+    if f <= 0 or rho <= 0:
+        raise ValueError("ELSSA series impedance requires f>0 and rho>0")
+    if np.any(gmr <= 0):
+        raise ValueError("all conductor GMR values must be positive")
+
+    n = len(x)
+    omega = 2.0 * np.pi * float(f)
+    xcoef_per_m = omega * MU0 / (2.0 * np.pi)
+    de = 658.5 * np.sqrt(float(rho) / float(f))
+    # Numeric constant exported by MATLAB at 50 Hz.  The simplified Carson
+    # earth resistance is linear with frequency and independent of geometry.
+    re_per_m = (0.049345 * (float(f) / 50.0)) / 1000.0
+
+    Z = np.empty((n, n), dtype=complex)
+    for i in range(n):
+        Z[i, i] = (r_ac[i] + re_per_m) + 1j * (
+            xcoef_per_m * np.log(de / gmr[i])
+        )
+        for j in range(n):
+            if i == j:
+                continue
+            dx = x[j] - x[i]
+            dy = y[j] - y[i]
+            d_direct = np.hypot(dx, dy)
+            if d_direct <= 0.0:
+                raise ValueError(
+                    f"conductors {i + 1} and {j + 1} occupy the same physical location"
+                )
+            # The compiled routine evaluates every ordered matrix entry.  The
+            # signed height difference means Z[i,j] and Z[j,i] can differ when
+            # conductor heights differ.  This non-symmetric result is unusual
+            # physically but is exactly what MATLAB exports and solves.
+            d_image = np.hypot(dx, de + dy)
+            Z[i, j] = re_per_m + 1j * (
+                xcoef_per_m * np.log(d_image / d_direct)
+            )
+    return Z
+
+
+def series_impedance_matrix(
+    x: np.ndarray,
+    y: np.ndarray,
+    gmr: np.ndarray,
+    r_ac: np.ndarray,
+    f: float,
+    rho: float = 100.0,
+    kmax: int = 60,
+) -> np.ndarray:
+    """
+    Full n x n series impedance matrix (ohm/m) via Carson's rigorous series.
+
+    Parameters
+    ----------
+    x, y : (n,) arrays of horizontal / height coordinates (m). y > 0 above earth.
+    gmr  : (n,) geometric mean radii (m).
+    r_ac : (n,) AC resistances per unit length (ohm/m) at frequency f.
+    f    : frequency (Hz).
+    rho  : earth resistivity (ohm.m).
+    """
+    x = np.asarray(x, float)
+    y = np.asarray(y, float).copy()
+    y_raw = y.copy()   # true heights, for direct-distance recovery below
+    # Floor heights: rails sit at ~grade (y=0) and some conductors are quoted
+    # slightly below. Carson's image method needs y>0. Use a small positive
+    # height for at-grade conductors (their self-impedance is then dominated by
+    # GMR and earth return, which is physically correct for a rail on ballast).
+    y = np.where(y < 0.05, 0.05, y)
+    gmr = np.asarray(gmr, float)
+    r_ac = np.asarray(r_ac, float)
+    n = len(x)
+    elssa_offset_mode = _elssa_artificial_offset_active(x)
+    omega = 2.0 * np.pi * f
+    Z = np.zeros((n, n), dtype=complex)
+
+    # a-parameter scale:  a = D * sqrt(omega*mu0/rho)
+    k_a = np.sqrt(omega * MU0 / rho)
+    pref = omega * MU0 / (2.0 * np.pi)          # for the ln term (jX_geo)
+    earth_pref = 4.0 * omega * 1.0e-7           # = omega*mu0/pi ; multiplies (P+jQ)
+
+    for i in range(n):
+        for j in range(i, n):
+            if i == j:
+                Dij = gmr[i]
+                # distance to own image
+                Dimg = 2.0 * y[i]
+                theta = 0.0
+                a = Dimg * k_a
+                P, Q = carson_PQ_theta(a, theta, kmax)
+                Xgeo = pref * np.log(Dimg / Dij)  # ideal-earth reactance using image
+                Rc = earth_pref * P
+                Xc = earth_pref * Q
+                Z[i, i] = (r_ac[i] + Rc) + 1j * (Xgeo + Xc)
+            else:
+                dx = x[i] - x[j]
+
+                # ELSSA route-offset compatibility branch.  In Braybrooke/6200
+                # style cross-sections, x positions around 1000, 2000, 5000...
+                # are route identifiers rather than literal 1-5 km conductor
+                # spacings.  For those large artificial separations, compiled
+                # ELSSA Section.Z uses a far-offset mutual term rather than the
+                # rigorous Carson series evaluated at the literal distance.
+                if elssa_offset_mode and abs(dx) >= 500.0:
+                    zij = _elssa_far_offset_mutual_ohm_per_m(dx, f)
+                    Z[i, j] = zij
+                    Z[j, i] = zij
+                    continue
+
+                # Direct physical separation must use the raw conductor
+                # heights whenever either conductor has been lifted by the
+                # numerical earth-height floor.  The earlier implementation
+                # used the floored heights except when the separation collapsed
+                # to exactly zero.  That was wrong for LSC/signalling cables
+                # placed at y=0/-0.01 m next to conductors at y=0.05 m: their
+                # vertical separation was lost and the mutual reactance became
+                # too large.  ELSSA's compiled Section.Z uses the real direct
+                # separation for Dij while still using a positive image height
+                # for Dimg/Carson earth-return terms.
+                raw_Dij = np.hypot(dx, y_raw[i] - y_raw[j])
+                if (y_raw[i] < 0.05 or y_raw[j] < 0.05) and raw_Dij > 1e-9:
+                    Dij = raw_Dij
+                else:
+                    dy = y[i] - y[j]
+                    Dij = np.hypot(dx, dy)             # direct distance
+                if Dij < 1e-6:   # final protection against coincident points
+                    Dij = max(raw_Dij, 1e-3)
+                Dimg = np.hypot(dx, y[i] + y[j])       # distance to image of j
+                cos_t = (y[i] + y[j]) / Dimg
+                cos_t = np.clip(cos_t, -1.0, 1.0)
+                theta = np.arccos(np.clip(cos_t, -1.0, 1.0))
+                a = Dimg * k_a
+                P, Q = carson_PQ_theta(a, theta, kmax)
+                Xgeo = pref * np.log(Dimg / Dij)
+                Rc = earth_pref * P
+                Xc = earth_pref * Q
+                zij = Rc + 1j * (Xgeo + Xc)
+                Z[i, j] = zij
+                Z[j, i] = zij
+    return Z
+
+
+def potential_coeff_matrix(x, y, radius) -> np.ndarray:
+    """
+    Maxwell potential coefficient matrix P (m/F units before 1/(2*pi*eps0)).
+    Returns P such that  C = 2*pi*eps0 * inv(P)  (F/m).
+    Uses method of images (perfect earth).
+    """
+    x = np.asarray(x, float); y_raw = np.asarray(y, float).copy()
+    r = np.asarray(radius, float)
+    # Height floor for the image method (same as the series Carson matrix). Keep
+    # the raw heights to recover true separations when the floor collapses a pair.
+    y = np.where(y_raw < 0.05, 0.05, y_raw)
+    n = len(x)
+    P = np.zeros((n, n))
+    for i in range(n):
+        for j in range(n):
+            if i == j:
+                P[i, i] = np.log(2.0 * y[i] / r[i])
+            else:
+                dx = x[i] - x[j]
+                Dij = np.hypot(dx, y[i] - y[j])
+                if Dij < 1e-6:
+                    # height floor collapsed two distinct conductors onto the
+                    # same point: recover the true geometric separation from the
+                    # raw (pre-floor) heights so log(Dimg/Dij) stays finite.
+                    Dij = max(np.hypot(dx, y_raw[i] - y_raw[j]), 1e-3)
+                Dimg = np.hypot(dx, y[i] + y[j])
+                P[i, j] = np.log(Dimg / Dij)
+    return P / (2.0 * np.pi * EPS0)
+
+
+def shunt_admittance_matrix(x, y, radius, f) -> np.ndarray:
+    """Shunt admittance Y = j*omega*C (S/m), multiconductor.
+
+    The Maxwell image method assumes thin conductors well ABOVE earth
+    (height >> radius). At-grade and buried conductors (rails on ballast,
+    buried cable cores) violate this: their height is <= their radius, the
+    self potential-coefficient log(2y/r) goes to zero or negative, and the
+    resulting C matrix is non-physical (negative eigenvalues). Physically
+    such conductors sit essentially AT earth potential and couple
+    capacitively to earth, not through the air to the overhead line. We
+    therefore build C only among the genuinely-elevated conductors and give
+    the at-grade ones a direct (large) capacitance to earth with negligible
+    air-path mutual coupling. The result is a positive-definite, physical C.
+    """
+    x = np.asarray(x, float); y = np.asarray(y, float); r = np.asarray(radius, float)
+    n = len(x)
+    # genuinely elevated: height comfortably exceeds radius (thin-wire valid)
+    elevated = y > np.maximum(3.0 * r, 0.3)
+    Y = np.zeros((n, n), dtype=complex)
+    if elevated.sum() >= 1:
+        idx = np.where(elevated)[0]
+        P = potential_coeff_matrix(x[idx], y[idx], r[idx])
+        C = np.linalg.inv(P)
+        for a, i in enumerate(idx):
+            for b, j in enumerate(idx):
+                Y[i, j] = 1j * 2.0 * np.pi * f * C[a, b]
+    # at-grade / buried conductors: capacitance to EARTH only (they are ~at
+    # earth potential). Use a representative large value; in practice these
+    # conductors' shunt path to earth is dominated by their bonding, not air
+    # capacitance, so the exact value barely matters for the solved network.
+    at_grade = ~elevated
+    for i in np.where(at_grade)[0]:
+        # small self-capacitance to earth (cable/rail to ground, ~order nF/km)
+        Y[i, i] += 1j * 2.0 * np.pi * f * 20e-9 / 1000.0  # 20 nF/km to earth
+    return Y