pydynamicestimator.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 – but, unlike the SG’s is-a EM hook, it is a pluggable strategy (composition): the filter combines freely with any angle / voltage / inner / pll choice, so by the is-a/has-a rule it is a strategy, not an inheritance hook. See docs/inverter_modernization_design.md (§2, §6).

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 future 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 (states realization).
`LCL_static`	Quasi-static LCL filter: the SAME topology as `LCL`, but the six

Module Contents

class pydynamicestimator.devices.inverter_filter.Filter[source]

Bases: abc.ABC

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

Symmetric to the synchronous-machine strategies (AVR/governor/…): the filter does NOT own state arrays or DAE indices. It declares what states, private algebraics, parameters and estimation metadata 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][source]

Return ordered list of differential-state names.

Return type:: List[str]

algebs() → List[str][source]

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][source]

Return type:: Dict[str, str]

algebs_noise() → Dict[str, float][source]

Return type:: Dict[str, float]

algebs_x0() → Dict[str, float][source]

Return type:: Dict[str, float]

abstract units() → List[str][source]

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

Return type:: List[str]

abstract params() → Dict[str, float][source]

Return dict of parameter names -> default values.

Return type:: Dict[str, float]

abstract states_noise() → Dict[str, float][source]

Return process-noise weight for each state.

Return type:: Dict[str, float]

abstract states_init_error() → Dict[str, float][source]

Return initial error for each state.

Return type:: Dict[str, float]

abstract x0() → Dict[str, float][source]

Return default initial guess for each state.

Return type:: Dict[str, float]

abstract descriptions() → Dict[str, str][source]

Return descriptions for states and params.

Return type:: Dict[str, str]

abstract fgcall(host, dae: pydynamicestimator.system.Dae, omega_ref_vec, omega_b) → None[source]

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 (pydynamicestimator.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][source]

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: pydynamicestimator.system.Dae) → Dict[str, numpy.ndarray][source]

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 (e.g. an algebraic realization) is only usable with the joint init.

Parameters:: dae (pydynamicestimator.system.Dae)
Return type:: Dict[str, numpy.ndarray]

class pydynamicestimator.devices.inverter_filter.LCL[source]

Bases: Filter

Dynamic LCL output filter – the framework default (states realization).

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. Equivalent to the equations previously hardcoded in Inverter.fgcall; the trajectory is byte-identical.

states() → List[str][source]

Return ordered list of differential-state names.

Return type:: List[str]

units() → List[str][source]

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

Return type:: List[str]

params() → Dict[str, float][source]

Return dict of parameter names -> default values.

Return type:: Dict[str, float]

states_noise() → Dict[str, float][source]

Return process-noise weight for each state.

Return type:: Dict[str, float]

states_init_error() → Dict[str, float][source]

Return initial error for each state.

Return type:: Dict[str, float]

x0() → Dict[str, float][source]

Return default initial guess for each state.

Return type:: Dict[str, float]

descriptions() → Dict[str, str][source]

Return descriptions for states and params.

Return type:: Dict[str, str]

fgcall(host, dae: pydynamicestimator.system.Dae, omega_ref_vec, omega_b) → None[source]

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 (pydynamicestimator.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][source]

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: pydynamicestimator.system.Dae) → Dict[str, numpy.ndarray][source]

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 (pydynamicestimator.system.Dae)
Return type:: Dict[str, numpy.ndarray]

class pydynamicestimator.devices.inverter_filter.LCL_static[source]

Bases: LCL

Quasi-static LCL filter: the SAME topology as LCL, but the six filter quantities are device-private algebraic variables instead of differential states – the singular-perturbation / quasi-static reduction that zeroes 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).

Because the filter quantities are algebraic, this realization requires the one-shot joint init (the staged sequential init cannot initialize algebraic states) – the host switches to _init_method="joint" automatically when a filter declares algebraics.

Per docs/inverter_modernization_design.md §6/§7, 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][source]

Return ordered list of differential-state names.

Return type:: List[str]

units() → List[str][source]

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

Return type:: List[str]

states_noise() → Dict[str, float][source]

Return process-noise weight for each state.

Return type:: Dict[str, float]

states_init_error() → Dict[str, float][source]

Return initial error for each state.

Return type:: Dict[str, float]

x0() → Dict[str, float][source]

Return default initial guess for each state.

Return type:: Dict[str, float]

algebs() → List[str][source]

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][source]

Return type:: Dict[str, str]

algebs_noise() → Dict[str, float][source]

Return type:: Dict[str, float]

algebs_x0() → Dict[str, float][source]

Return type:: Dict[str, float]

fgcall(host, dae: pydynamicestimator.system.Dae, omega_ref_vec, omega_b) → None[source]

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 (pydynamicestimator.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

pydynamicestimator.devices.inverter_filter.FILTER_REGISTRY: Dict[str, type]