hermess.devices.inverter_filter

Inverter output-filter (electrical-plant) strategies.

The filter owns the converter’s network-interface states and writes their dynamics, driven by the switching voltage Vsw from the inner controller and the network voltage. It is the inverter analogue of the synchronous machine’s electromagnetic model (the electrical plant the controllers act on), here as a pluggable strategy that combines freely with any angle / voltage / inner / pll choice.

A filter exposes the terminal-current states (itd_ext / itq_ext, read by the host’s network injection gcall) and the capacitor-voltage / filter-current states that the control ladder reads through host.var_sym – which lets a quasi-static realization (LCL_static) make them algebraic transparently.

Attributes

FILTER_REGISTRY

Classes

Filter	Abstract base class for inverter output-filter models (pluggable strategy).
LCL	Dynamic LCL output filter (the framework default), with all quantities as
LCL_static	Quasi-static LCL filter: same topology as LCL, but the six filter

Module Contents

class hermess.devices.inverter_filter.Filter

Bases: abc.ABC

Abstract base class for inverter output-filter models (pluggable strategy).

Like the synchronous-machine strategies (AVR/governor/…), the filter does not own state arrays or DAE indices. It declares the states, private algebraics and parameters it needs, and the host Inverter registers them on itself (filter first, so its states occupy the leading block of the state vector). It reads host parameters/states by attribute (host.Lf, host.var_sym(dae, "Vfd_ext"), …).

abstract states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

algebs() → List[str]

Return ordered list of device-private algebraic variable names.

Default empty (dynamic filter: every quantity is a differential state). A quasi-static realization returns its quantities here instead and writes 0 = RHS residuals into dae.g.

Return type:

List[str]

algebs_units() → Dict[str, str]

Return type:

Dict[str, str]

algebs_x0() → Dict[str, float]

Return type:

Dict[str, float]

abstract units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

abstract params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

abstract x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

abstract descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

abstract fgcall(host, dae: hermess.system.Dae, omega_ref_vec, omega_b) → None

Write the filter dynamics into dae.f (and, for a quasi-static realization, the residuals into dae.g). The driving switching voltage (converter output, network frame) is read host-mediated via host.switching_voltage(dae).

Parameters:

• host – the Inverter instance (read params via host.Lf/…, states via host.var_sym(dae, name), the switching voltage via host.switching_voltage(dae), indices via host.Vfd_ext, host.vre, …).

• dae (hermess.system.Dae) – the DAE system object.

• omega_ref_vec – per-bus reference-frame frequency.

• omega_b – base speed (2*pi*fn) per device.

Return type:

None

provides() → Set[str]

Plant capability tags this filter exposes (e.g. "shunt_capacitor"), checked against the inner controller’s requirements at construction. Empty by default.

Return type:

Set[str]

abstract finit_sequential(host, dae: hermess.system.Dae) → Dict[str, numpy.ndarray]

Steady-state init of the filter from the power-flow terminal point. Returns a dict with the filter states plus the switching voltage Vswd/Vswq and terminal current itd_ext/itq_ext consumed downstream. The base raises: a filter without a sequential init is only usable with the joint init.

Parameters:

dae (hermess.system.Dae)

Return type:

Dict[str, numpy.ndarray]

class hermess.devices.inverter_filter.LCL

Bases: Filter

Dynamic LCL output filter (the framework default), with all quantities as differential states.

Capacitor voltage (Vfd_ext/Vfq_ext), converter-side filter current (ifd_ext/ifq_ext) and grid-side / terminal current (itd_ext/itq_ext), all in the network (external) dq frame, with the classic series-Rf-Lf / shunt-Cf / series-Rt-Lt topology.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

fgcall(host, dae: hermess.system.Dae, omega_ref_vec, omega_b) → None

Write the filter dynamics into dae.f (and, for a quasi-static realization, the residuals into dae.g). The driving switching voltage (converter output, network frame) is read host-mediated via host.switching_voltage(dae).

Parameters:

• host – the Inverter instance (read params via host.Lf/…, states via host.var_sym(dae, name), the switching voltage via host.switching_voltage(dae), indices via host.Vfd_ext, host.vre, …).

• dae (hermess.system.Dae) – the DAE system object.

• omega_ref_vec – per-bus reference-frame frequency.

• omega_b – base speed (2*pi*fn) per device.

Return type:

None

provides() → Set[str]

Plant capability tags this filter exposes (e.g. "shunt_capacitor"), checked against the inner controller’s requirements at construction. Empty by default.

Return type:

Set[str]

finit_sequential(host, dae: hermess.system.Dae) → Dict[str, numpy.ndarray]

Steady-state init of the LCL filter (decoupled from the controls): given the power-flow terminal voltage (vre/vim) and current (itd_ext/itq_ext), solve the 6 filter ODEs = 0 for the capacitor voltage, filter current, and the switching voltage Vsw the converter must output.

Parameters:

dae (hermess.system.Dae)

Return type:

Dict[str, numpy.ndarray]

class hermess.devices.inverter_filter.LCL_static

Bases: LCL

Quasi-static LCL filter: same topology as LCL, but the six filter quantities are device-private algebraic variables instead of differential states (the singular-perturbation reduction zeroing the fast LCL dynamics, d/dt -> 0). Appropriate when the network itself is quasi-static (line_dyn=False); a dynamic filter on a static network is physically incoherent (the host warns but allows it).

The 2*pi*f (omega_b) factor common to every term of the dynamic ODE is dropped on the 0 = RHS algebraic constraint: it is mathematically redundant and would inflate the finit Jacobian condition number.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

algebs() → List[str]

Return ordered list of device-private algebraic variable names.

Default empty (dynamic filter: every quantity is a differential state). A quasi-static realization returns its quantities here instead and writes 0 = RHS residuals into dae.g.

Return type:

List[str]

algebs_units() → Dict[str, str]

Return type:

Dict[str, str]

algebs_x0() → Dict[str, float]

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae, omega_ref_vec, omega_b) → None

Write the filter dynamics into dae.f (and, for a quasi-static realization, the residuals into dae.g). The driving switching voltage (converter output, network frame) is read host-mediated via host.switching_voltage(dae).

Parameters:

• host – the Inverter instance (read params via host.Lf/…, states via host.var_sym(dae, name), the switching voltage via host.switching_voltage(dae), indices via host.Vfd_ext, host.vre, …).

• dae (hermess.system.Dae) – the DAE system object.

• omega_ref_vec – per-bus reference-frame frequency.

• omega_b – base speed (2*pi*fn) per device.

Return type:

None

hermess.devices.inverter_filter.FILTER_REGISTRY: Dict[str, type]