hermess.devices.device ====================== .. py:module:: hermess.devices.device Attributes ---------- .. autoapisummary:: hermess.devices.device.sin hermess.devices.device.cos hermess.devices.device.sqrt Classes ------- .. autoapisummary:: hermess.devices.device.Element hermess.devices.device.BusInit hermess.devices.device.Disturbance hermess.devices.device.Line hermess.devices.device.DeviceRect Module Contents --------------- .. py:data:: sin .. py:data:: cos .. py:data:: sqrt .. py:class:: Element Metaclass to be used for all elements to be added .. py:attribute:: n :type: int :value: 0 .. py:attribute:: u :type: list[bool] :value: [] .. py:attribute:: name :type: list[str] :value: [] .. py:attribute:: _type :type: Optional[str] :value: None .. py:attribute:: _name :type: Optional[str] :value: None .. py:attribute:: int :type: dict[str, Union[str, int]] .. py:attribute:: _data :type: dict[str, Any] .. py:attribute:: _params :type: dict[str, float] .. py:attribute:: _setpoints :type: dict[str, float] .. py:attribute:: _descr :type: dict[str, str] .. py:attribute:: _mand :type: list[str] :value: [] .. py:attribute:: properties :type: dict[str, bool] .. py:method:: add(idx: Optional[str] = None, name: Optional[str] = None, **kwargs) -> None Add an element device Args: idx (str, optional): Unique identifier for the device. Generated if not provided. name (str, optional): Name of the device. Generated if not provided. **kwargs: Custom parameters to overwrite defaults. .. py:class:: BusInit Bases: :py:obj:`Element` Metaclass to be used for all elements to be added .. py:attribute:: _type :value: 'Bus_init_or_unknwon' .. py:attribute:: _name :value: 'Bus_init_or_unknown' .. py:attribute:: bus :type: list[Optional[str]] :value: [] .. py:attribute:: p :type: list[float] :value: [] .. py:attribute:: q :type: list[float] :value: [] .. py:attribute:: v :type: list[float] :value: [] .. py:attribute:: type :type: list[Optional[str]] :value: [] .. py:class:: Disturbance Bases: :py:obj:`Element` Metaclass to be used for all elements to be added .. py:attribute:: _type :value: 'Disturbance' .. py:attribute:: _name :value: 'Disturbance' .. py:attribute:: type .. py:attribute:: time .. py:attribute:: bus_i .. py:attribute:: bus_j .. py:attribute:: y :type: numpy.ndarray .. py:attribute:: bus .. py:attribute:: p_delta .. py:attribute:: q_delta .. py:method:: sort_chrono() .. py:class:: Line Bases: :py:obj:`Element` :param r: Series resistance value in per unit (p.u.). :type r: ndarray[float] :param x: Series reactance value in per unit (p.u.). :type x: ndarray[float] :param g: Total shunt conductance value in per unit (p.u.). :type g: ndarray[float] :param b: Total shunt susceptance value in per unit (p.u.). :type b: ndarray[float] :param trafo: Off-nominal line transformer ratio. :type trafo: ndarray[float] :param bus_i: Name of the sending-end bus. :type bus_i: ndarray[str] :param bus_j: Name of the receiving-end bus. :type bus_j: ndarray[str] .. py:attribute:: _type :value: 'Transmission_line' .. py:attribute:: _name :value: 'Transmission_line' .. py:attribute:: states :value: ['i_ijr', 'i_iji'] .. py:attribute:: r .. py:attribute:: x .. py:attribute:: g .. py:attribute:: b .. py:attribute:: trafo .. py:attribute:: bus_i .. py:attribute:: bus_j .. py:method:: fcall(grid: hermess.system.GridSim, dae: hermess.system.DaeSim) -> None Call all differential equations for all lines. This function should be used only in case lines are modeled dynamically. If they are modeled statically they are automatically incorporated within grid class .. py:class:: DeviceRect Bases: :py:obj:`Element` Dynamic or static device modeled in rectangular coordinates. Used as a parent class for all devices modeled in rectangular coordinates. .. attribute:: properties Flags for method calls (e.g., 'gcall', 'fcall'). :type: dict[str, bool] .. attribute:: xf Final state results for the simulation. :type: dict[str, np.ndarray] .. attribute:: xinit Initial state values for all devices of the instance. :type: dict[State, list[float]] .. attribute:: xmin Minimum limited state value. :type: list[float] .. attribute:: xmax Maximum limited state value. :type: list[float] .. attribute:: _params Device parameters, such as rated voltage, power, and frequency and internal parameters. :type: dict[str, float] .. attribute:: _data Additional data which will be used in a list, one entry for each device of this object instance. :type: dict[str, str] .. attribute:: bus Buses where the device is connected. Each device has an entry in the list. :type: list[Optional[str]] .. attribute:: states State variables. :type: list[States] .. attribute:: units Units of state variables. :type: list[States] .. attribute:: ns Total number of states in the model. :type: float .. attribute:: vre Order of the real voltage value for each device in the overall DAE model. :type: list[float] .. attribute:: vim Order of the real voltage value for each device in the overall DAE model. :type: list[float] .. attribute:: _algebs Algebraic variables ('vre', 'vim'). :type: list[str] .. attribute:: _descr Descriptions for key parameters. :type: dict[str, str] .. py:attribute:: _init_method :type: str :value: 'joint' .. py:attribute:: xf :type: dict[str, numpy.ndarray] .. py:attribute:: yf_int :type: dict[str, numpy.ndarray] .. py:attribute:: xinit :type: dict[str, list[float]] .. py:attribute:: xmin :type: list[float] :value: [] .. py:attribute:: xmax :type: list[float] :value: [] .. py:attribute:: Vn .. py:attribute:: fn .. py:attribute:: Sn .. py:attribute:: bus :type: list[Optional[str]] :value: [] .. py:attribute:: states :type: list[str] :value: [] .. py:attribute:: units :type: list[str] :value: [] .. py:attribute:: ns :type: int :value: 0 .. py:attribute:: _algebs :type: list[str] :value: ['vre', 'vim'] .. py:attribute:: vre .. py:attribute:: vim .. py:attribute:: _algebs_int :type: list[str] :value: [] .. py:attribute:: _algebs_int_x0 :type: dict[str, float] .. py:attribute:: _algebs_int_units :type: dict[str, str] .. py:attribute:: _x0 :type: dict[str, float] .. py:attribute:: _descr .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: _init_data() -> None .. py:method:: xy_index(dae: hermess.system.Dae, grid: hermess.system.Grid) -> None Initializes indices for states, algebraic variables, unknown inputs, and switches. :param dae: Object managing differential-algebraic equations. :type dae: Dae :param grid: Object managing the electrical grid and node indices. :type grid: Grid .. py:method:: add(idx=None, name=None, **kwargs) -> None Add an element device Args: idx (str, optional): Unique identifier for the device. Generated if not provided. name (str, optional): Name of the device. Generated if not provided. **kwargs: Custom parameters to overwrite defaults. .. py:method:: save_data(dae: hermess.system.Dae) -> None .. py:method:: finit_anchor_residuals(dae: hermess.system.Dae) -> list Extra steady-state anchor residuals (each an n-vector that must equal 0) a device declares to keep its initialization Newton system square. The joint init pins each device's state ODEs (``f = 0``) plus two quantities through the bus-current balance (``g[vre]``/``g[vim]``), so a square system requires ``n_setpoints == 2`` (the SG: Pref + Vref). A device with more setpoints returns ``n_setpoints - 2`` anchor residuals to balance them. Empty by default. Example: the inverter has 3 setpoints (Pref/Qref/Vref) but the bus equations pin only 2; it returns one anchor (Qref = Qc) here. .. py:method:: finit(dae: hermess.system.Dae) -> None Initialize the device, dispatching on :attr:`_init_method` (``"joint"`` -> :meth:`_finit_joint`, ``"sequential"`` -> :meth:`_finit_sequential`). .. py:method:: _finit_sequential(dae: hermess.system.Dae) -> None :abstractmethod: Staged, device-specific initialization. Devices that declare ``_init_method = 'sequential'`` implement this; the default has none. .. py:method:: finit_guess(dae: hermess.system.Dae) Newton seed for the joint init, machine-major ``[states of inst 0 | states of inst 1 | ...]``, or None for the default (class-level ``_x0`` repeated per instance). Overrides may also refresh setpoint arrays (e.g. ``Pref``), which the joint solve consumes as setpoint guesses. .. py:method:: _finit_joint(dae: hermess.system.Dae) -> None One-shot initialization: solve the device's steady state (states + setpoints + private algebraics, balanced by the bus equations and any device-declared anchor residuals) as a single Newton system, with a Levenberg-Marquardt fallback. Initialize the device by setting up setpoints, initial states based on the power flow solution. :param dae: The DAE object used to simulate the system. :type dae: Dae .. py:method:: fgcall(dae: hermess.system.Dae) -> None A method that executes the differential and algebraic equations of the model and adds them to the appropriate places in the Dae class :param dae: an instance of a class Dae :type dae: :return: None :rtype: None