hermess.devices.inverter_filter =============================== .. py:module:: hermess.devices.inverter_filter .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: hermess.devices.inverter_filter.FILTER_REGISTRY Classes ------- .. autoapisummary:: hermess.devices.inverter_filter.Filter hermess.devices.inverter_filter.LCL hermess.devices.inverter_filter.LCL_static Module Contents --------------- .. py:class:: Filter Bases: :py:obj:`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")``, ...). .. py:method:: states() -> List[str] :abstractmethod: Return ordered list of differential-state names. .. py:method:: 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``. .. py:method:: algebs_units() -> Dict[str, str] .. py:method:: algebs_x0() -> Dict[str, float] .. py:method:: units() -> List[str] :abstractmethod: Return units for each state, same length as states(). .. py:method:: params() -> Dict[str, float] :abstractmethod: Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] :abstractmethod: Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] :abstractmethod: Return descriptions for states and params. .. py:method:: fgcall(host, dae: hermess.system.Dae, omega_ref_vec, omega_b) -> None :abstractmethod: 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)``. :param 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, ...). :param dae: the DAE system object. :param omega_ref_vec: per-bus reference-frame frequency. :param omega_b: base speed (2*pi*fn) per device. .. py:method:: 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. .. py:method:: finit_sequential(host, dae: hermess.system.Dae) -> Dict[str, numpy.ndarray] :abstractmethod: 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. .. py:class:: LCL Bases: :py:obj:`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. .. py:method:: states() -> List[str] Return ordered list of differential-state names. .. py:method:: units() -> List[str] Return units for each state, same length as states(). .. py:method:: params() -> Dict[str, float] Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] Return descriptions for states and params. .. py:method:: 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)``. :param 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, ...). :param dae: the DAE system object. :param omega_ref_vec: per-bus reference-frame frequency. :param omega_b: base speed (2*pi*fn) per device. .. py:method:: 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. .. py:method:: 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. .. py:class:: LCL_static Bases: :py:obj:`LCL` Quasi-static LCL filter: same topology as :class:`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. .. py:method:: states() -> List[str] Return ordered list of differential-state names. .. py:method:: units() -> List[str] Return units for each state, same length as states(). .. py:method:: x0() -> Dict[str, float] Return default initial guess for each state. .. py:method:: 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``. .. py:method:: algebs_units() -> Dict[str, str] .. py:method:: algebs_x0() -> Dict[str, float] .. py:method:: 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)``. :param 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, ...). :param dae: the DAE system object. :param omega_ref_vec: per-bus reference-frame frequency. :param omega_b: base speed (2*pi*fn) per device. .. py:data:: FILTER_REGISTRY :type: Dict[str, type]