geopulse.network

Grounded-conductor network models.

Cable, power grid, pipeline, and railway networks all implement the same ConductorNetwork ABC.

class geopulse.network.Branch(branch_id, from_node, to_node, resistance_Ohm, length_m)

Bases: object

A branch (conductor segment) between two nodes.

Parameters:

• branch_id (str)

• from_node (str)

• to_node (str)

• resistance_Ohm (float)

• length_m (float)

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.ConductorNetwork

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()

Return all nodes in the network.

Return type:

Sequence[Node]

abstractmethod get_branches()

Return all branches in the network.

Return type:

Sequence[Branch]

abstractmethod assemble_network_admittance()

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()

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)

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)

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.Node(node_id, latitude_deg, longitude_deg, earthing_impedance_Ohm=0.0)

Bases: object

A node (grounding point) in the conductor network.

Parameters:

• node_id (str)

• latitude_deg (float)

• longitude_deg (float)

• earthing_impedance_Ohm (float)

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

Modules

base	Abstract base class for grounded conductor networks.
cable	Submarine cable network — refactor of SCUBAS — STUB (WP2).
graph	Network graph utilities: adjacency, admittance assembly — STUB (WP2).
pipeline	Pipeline network via Distributed-Source Transmission-Line (DSTL) theory.
powergrid	Power-grid conductor network (substations + transmission lines).
railway	Railway traction / track-circuit network — STUB (WP4).
thevenin	Thévenin voltage V_th = ∫E·dl for a conductor branch — STUB (WP2).