geopulse.network.base

Abstract base class for grounded conductor networks.

Infrastructure-agnostic interface: a submarine cable, a power grid, a pipeline, and a railway all implement the same ABC. The solver module never knows which kind of infrastructure it is solving — only nodes, branches, admittances, and Thévenin voltages.

References

Classes

Branch(branch_id, from_node, to_node, ...)

A branch (conductor segment) between two nodes.

ConductorNetwork()

Abstract base class for grounded conductor networks.

Node(node_id, latitude_deg, longitude_deg[, ...])

A node (grounding point) in the conductor network.
class geopulse.network.base.Branch(branch_id, from_node, to_node, resistance_Ohm, length_m)[source]

Bases: object

A branch (conductor segment) between two nodes.

Parameters:
branch_id

Unique identifier.

Type:

str

from_node

node_id of the start node.

Type:

str

to_node

node_id of the end node.

Type:

str

resistance_Ohm

Total DC resistance of the branch in Ohms.

Type:

float

length_m

Physical length of the branch in meters.

Type:

float

branch_id: str
from_node: str
to_node: str
resistance_Ohm: float
length_m: float
class geopulse.network.base.ConductorNetwork[source]

Bases: ABC

Abstract base class for grounded conductor networks.

Subclasses (all deferred to later phases):

  • CableNetwork — submarine cables (SCUBAS refactor).

  • PowerGridNetwork — substations + transmission lines.

  • PipelineNetwork — DSTL (Boteler 1997).

  • RailwayNetwork — track circuits + traction substations.

abstractmethod get_nodes()[source]

Return all nodes in the network.

Return type:

Sequence[Node]

abstractmethod get_branches()[source]

Return all branches in the network.

Return type:

Sequence[Branch]

abstractmethod assemble_network_admittance()[source]

Assemble the network admittance matrix Y_n.

Return type:

ndarray

Returns:

numpy.ndarray – Symmetric, real-valued matrix. Shape (n_nodes, n_nodes). Units: Siemens.

Notes

Y_n[i, i] = sum of admittances of branches connected to node i. Y_n[i, j] = -admittance of the branch between i and j.

abstractmethod assemble_earthing_impedance()[source]

Assemble the diagonal earthing-impedance matrix Z_e.

Return type:

ndarray

Returns:

numpy.ndarray – Diagonal matrix. Shape (n_nodes, n_nodes). Units: Ohms.

abstractmethod compute_thevenin_voltages(ex_Vm, ey_Vm, lat_deg, lon_deg)[source]

Compute the Thévenin equivalent voltage for each branch.

V_th(ab) = ∫_a^b E(r) · dl. For a uniform E-field over the branch length this reduces to V_th = Ex · Δx + Ey · Δy.

Parameters:

  • ex_Vm (ndarray) – North-south and east-west E-field components in V/m.

  • ey_Vm (ndarray) – North-south and east-west E-field components in V/m.

  • lat_deg (ndarray) – Coordinates of the E-field evaluation points.

  • lon_deg (ndarray) – Coordinates of the E-field evaluation points.

Return type:

ndarray

Returns:

numpy.ndarray – Thévenin voltage per branch. Shape (n_branches,). Units: V.

abstractmethod classmethod from_file(path)[source]

Load a network from disk (JSON, GeoJSON, or YAML).

Parameters:

path (str) – Path to the network definition file.

Return type:

ConductorNetwork

Returns:

ConductorNetwork – The loaded network.

class geopulse.network.base.Node(node_id, latitude_deg, longitude_deg, earthing_impedance_Ohm=0.0)[source]

Bases: object

A node (grounding point) in the conductor network.

Parameters:
node_id

Unique identifier (e.g. "SUB_01" for a substation, "KP_100" for a kilometer post on a pipeline).

Type:

str

latitude_deg

Geographic latitude, degrees north.

Type:

float

longitude_deg

Geographic longitude, degrees east.

Type:

float

earthing_impedance_Ohm

Impedance to remote earth in Ohms. Default: 0.0 (perfectly grounded). Use numpy.inf for ungrounded (floating) nodes.

Type:

float, optional

node_id: str
latitude_deg: float
longitude_deg: float
earthing_impedance_Ohm: float = 0.0