Sources

The :mod:groundfield.sources module exposes the source types that drive a :class:World: :class:CurrentSource (impressed current into an electrode cluster) and :class:VoltageSource (impressed voltage between an injection electrode and an explicit return electrode).

Since 0.5.0 the public :data:Source annotation is a Pydantic discriminated union (Annotated[Union[...], Discriminator("kind")]) with a companion :data:SourceAdapter for stand-alone source-dict validation. JSON / dict round-trips report errors against the selected sub-class instead of dumping the whole union's validator chain.

Round-tripping a source list

from groundfield.sources import SourceAdapter

dicts = [
    {"kind": "current", "name": "inj_1",
     "attached_to": "g1", "magnitude": 1.0},
    {"kind": "voltage", "name": "v_aux",
     "attached_to": "g1", "return_to": "g_aux", "magnitude": 100.0},
]
sources = [SourceAdapter.validate_python(d) for d in dicts]

The discriminator surface (Pass 5) and the typed validation surface keep error messages local to the offending source.

API reference

sources

Source models for current injection.

Grounding studies are dominated by current sources: ground-fault currents, test currents in loop measurements, lightning partial currents. Voltage sources are rare and are provided here as an optional subclass for completeness.

A source is attached to an electrode (or a conductor). The actual distribution of the injected current onto the discretised segments is done by the solver.

Notes

:data:Source is a discriminated union — Pydantic uses the kind field to pick the correct sub-class on validation and JSON round-trip. This means error messages for malformed source dicts point at the specific sub-class (CurrentSource / VoltageSource) selected by kind, instead of dumping the entire union's validator chain.

CurrentSource

Bases: _SourceBase

Impressed current source.

Attributes:

Name	Type	Description
magnitude	float	Current amplitude in A (RMS in the frequency domain).
phase_deg	float	Phase angle in degrees. Default 0.

VoltageSource

Bases: _SourceBase

Impressed voltage source (special case).

Rarely used, kept here for full multi-port tests.