hermess.devices.inverter_voltage
================================

.. py:module:: hermess.devices.inverter_voltage

.. autoapi-nested-parse::

   Inverter outer voltage-control strategies (the reactive / voltage side).

   The voltage controller is the AVR-analogue of the converter: it turns the
   reactive-power / voltage setpoints into the voltage-magnitude reference ``Vcd``
   that the inner control ladder regulates the capacitor voltage to. It owns the
   reactive-power measurement state ``Qc_tilde`` and the ``Qref`` / ``Vref``
   setpoints.

   The strategy owns the ``Qc_tilde`` state but the host writes its measurement-
   filter equation ``d Qc_tilde/dt = omega_f (Qc - Qc_tilde)`` because ``Qc`` comes
   from the shared Park-transform loop in ``Inverter.fgcall``.



Attributes
----------

.. autoapisummary::

   hermess.devices.inverter_voltage.VOLTAGE_REGISTRY


Classes
-------

.. autoapisummary::

   hermess.devices.inverter_voltage.VoltageControl
   hermess.devices.inverter_voltage.QVDroop


Module Contents
---------------

.. py:class:: VoltageControl

   Bases: :py:obj:`abc.ABC`


   Abstract base class for inverter outer voltage-control strategies.

   Must expose the voltage-magnitude reference: :meth:`fgcall` returns the ``Vcd``
   vector consumed by the inner control ladder (host-mediated via
   ``host.voltage_command``). Reads host params/states/setpoints by attribute.


   .. py:method:: states() -> List[str]
      :abstractmethod:



   .. py:method:: algebs() -> List[str]


   .. py:method:: algebs_units() -> Dict[str, str]


   .. py:method:: algebs_x0() -> Dict[str, float]


   .. py:method:: units() -> List[str]
      :abstractmethod:



   .. py:method:: params() -> Dict[str, float]
      :abstractmethod:



   .. py:method:: x0() -> Dict[str, float]
      :abstractmethod:



   .. py:method:: descriptions() -> Dict[str, str]
      :abstractmethod:



   .. py:method:: setpoints() -> Dict[str, float]
      :abstractmethod:



   .. py:method:: fgcall(host, dae: hermess.system.Dae)
      :abstractmethod:


      Publish the voltage-magnitude reference on ``host.Vcd`` (read by the inner
      controller via ``host.voltage_command(dae)``). The host writes the
      ``Qc_tilde`` measurement-filter equation (``Qc`` is host-computed).



   .. py:method:: finit_sequential(host, dae: hermess.system.Dae, Qc: numpy.ndarray, Vcd: numpy.ndarray) -> Dict[str, numpy.ndarray]
      :abstractmethod:


      Resolve the voltage controller's states/setpoints from the
      (frame-invariant) reactive power ``Qc`` and the inner controller's voltage
      command ``Vcd``. This is where the Q-V gauge lives. The base raises; each
      voltage law declares its own resolution.



.. py:class:: QVDroop

   Bases: :py:obj:`VoltageControl`


   Reactive-power / voltage droop: ``Vcd = Vref + Kq (Qref - Qc_tilde)``.

   Owns the filtered reactive-power state ``Qc_tilde``, the droop gain ``Kq`` and
   the ``Qref`` / ``Vref`` setpoints.


   .. py:method:: states() -> List[str]


   .. py:method:: units() -> List[str]


   .. py:method:: params() -> Dict[str, float]


   .. py:method:: x0() -> Dict[str, float]


   .. py:method:: setpoints() -> Dict[str, float]


   .. py:method:: descriptions() -> Dict[str, str]


   .. py:method:: fgcall(host, dae: hermess.system.Dae)

      Publish the voltage-magnitude reference on ``host.Vcd`` (read by the inner
      controller via ``host.voltage_command(dae)``). The host writes the
      ``Qc_tilde`` measurement-filter equation (``Qc`` is host-computed).



   .. py:method:: finit_sequential(host, dae: hermess.system.Dae, Qc: numpy.ndarray, Vcd: numpy.ndarray) -> Dict[str, numpy.ndarray]

      Resolve the voltage controller's states/setpoints from the
      (frame-invariant) reactive power ``Qc`` and the inner controller's voltage
      command ``Vcd``. This is where the Q-V gauge lives. The base raises; each
      voltage law declares its own resolution.



.. py:data:: VOLTAGE_REGISTRY
   :type:  Dict[str, type]