ltbams 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

ams/models/distributed/esd1.py

@@ -0,0 +1,71 @@
+"""
+Distributed energy storage model.
+"""
+
+from andes.core.param import NumParam
+
+from ams.core.model import Model
+
+from ams.models.distributed.pvd1 import PVD1Data
+
+
+class ESD1Data(PVD1Data):
+    """
+    ESD1 model data.
+    """
+
+    def __init__(self):
+        PVD1Data.__init__(self)
+
+        self.SOCmin = NumParam(default=0.0, tex_name='SOC_{min}',
+                               info='Minimum required value for SOC in limiter',
+                               )
+
+        self.SOCmax = NumParam(default=1.0, tex_name='SOC_{max}',
+                               info='Maximum allowed value for SOC in limiter',
+                               )
+
+        self.SOCinit = NumParam(default=0.5, tex_name='SOC_{init}',
+                                info='Initial state of charge',
+                                )
+
+        self.En = NumParam(default=100.0, tex_name='E_n',
+                           info='Rated energy capacity',
+                           unit="MWh"
+                           )
+
+        self.EtaC = NumParam(default=1.0, tex_name='Eta_C',
+                             info='Efficiency during charging',
+                             vrange=(0, 1),
+                             )
+
+        self.EtaD = NumParam(default=1.0, tex_name='Eta_D',
+                             info='Efficiency during discharging',
+                             vrange=(0, 1),
+                             )
+
+
+class ESD1(ESD1Data, Model):
+    """
+    Distributed energy storage model, revised from ANDES ``ESD1`` model for
+    scheduling.
+
+    Following parameters are omitted from the original dynamic model:
+    ``fn``, ``busf``, ``xc``, ``pqflag``, ``igreg``, ``v0``, ``v1``,
+    ``dqdv``, ``fdbd``, ``ddn``, ``ialim``, ``vt0``, ``vt1``, ``vt2``,
+    ``vt3``, ``vrflag``, ``ft0``, ``ft1``, ``ft2``, ``ft3``, ``frflag``,
+    ``tip``, ``tiq``, ``recflag``.
+
+    Reference:
+
+    [1] ANDES Documentation, ESD1
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/DG.html#esd1
+    """
+
+    def __init__(self, system, config):
+        ESD1Data.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'DG'

ams/models/distributed/ev.py

@@ -0,0 +1,60 @@
+"""
+EV model.
+"""
+
+from andes.core.param import NumParam, IdxParam
+from andes.core.model import ModelData
+
+from ams.core.model import Model
+
+
+class EV1(ModelData, Model):
+    """
+    Aggregated EV model for scheduling at transmission level.
+
+    For co-simulation with ADNES, it is expected to be used in
+    conjunction with the dynamic models `EV1` or `EV2`.
+
+    Reference:
+
+    [1] J. Wang et al., "Electric Vehicles Charging Time Constrained Deliverable Provision of Secondary
+    Frequency Regulation," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3356948.
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'DG'
+
+        self.bus = IdxParam(model='Bus',
+                            info="interface bus idx",
+                            mandatory=True,
+                            )
+        self.gen = IdxParam(info="static generator index",
+                            mandatory=True,
+                            )
+        self.Sn = NumParam(default=100.0, tex_name='S_n',
+                           info='device MVA rating',
+                           unit='MVA',
+                           )
+        self.gammap = NumParam(default=1.0,
+                               info="P ratio of linked static gen",
+                               tex_name=r'\gamma_P'
+                               )
+        self.gammaq = NumParam(default=1.0,
+                               info="Q ratio of linked static gen",
+                               tex_name=r'\gamma_Q'
+                               )
+        self.N = NumParam(default=10000,
+                          info="number of related EVs",
+                          tex_name='N'
+                          )
+
+
+class EV2(EV1):
+    """
+    EV aggregation model at transmission level, identical to :ref:`EV1`.
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        EV1.__init__(self, system, config)

ams/models/distributed/pvd1.py

@@ -0,0 +1,67 @@
+"""
+Distributed PV models.
+"""
+
+from andes.core.param import IdxParam, NumParam
+from andes.core.model import ModelData
+
+from ams.core.model import Model
+
+
+class PVD1Data(ModelData):
+    """
+    PVD1 model data.
+    """
+
+    def __init__(self):
+        ModelData.__init__(self)
+
+        self.bus = IdxParam(model='Bus',
+                            info="interface bus id (place holder)",
+                            mandatory=True,
+                            )
+
+        self.gen = IdxParam(info="static generator index",
+                            mandatory=True,
+                            )
+
+        self.Sn = NumParam(default=100.0, tex_name='S_n',
+                           info='device MVA rating',
+                           unit='MVA',
+                           )
+
+        self.gammap = NumParam(default=1.0, tex_name=r'\gamma_p',
+                               info='Ratio of ESD1.pref0 w.r.t to that of static PV',
+                               vrange='(0, 1]',
+                               )
+
+        self.gammaq = NumParam(default=1.0, tex_name=r'\gamma_q',
+                               info='Ratio of ESD1.qref0 w.r.t to that of static PV',
+                               vrange='(0, 1]',
+                               )
+
+
+class PVD1(PVD1Data, Model):
+    """
+    Distributed PV model, revised from ANDES ``PVD1`` model for
+    scheduling.
+
+    Following parameters are omitted from the original dynamic model:
+    ``fn``, ``busf``, ``xc``, ``pqflag``, ``igreg``, ``v0``, ``v1``,
+    ``dqdv``, ``fdbd``, ``ddn``, ``ialim``, ``vt0``, ``vt1``, ``vt2``,
+    ``vt3``, ``vrflag``, ``ft0``, ``ft1``, ``ft2``, ``ft3``, ``frflag``,
+    ``tip``, ``tiq``, ``recflag``.
+
+    Reference:
+
+    [1] ANDES Documentation, PVD1
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/DG.html#pvd1
+    """
+
+    def __init__(self, system, config):
+        PVD1Data.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'DG'

ams/models/group.py

@@ -0,0 +1,231 @@
+import logging
+
+from andes.models.group import GroupBase as adGroupBase
+from andes.core.service import BackRef
+
+logger = logging.getLogger(__name__)
+
+
+class GroupBase(adGroupBase):
+    """
+    Base class for groups.
+
+    Add common_vars and common_params to the group class.
+
+    This class is revised from ``andes.models.group.GroupBase``.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('idx',))
+
+    def get_idx(self):
+        """
+        Return the value of group idx sorted in a human-readable style.
+
+        Notes
+        -----
+        This function sorts the idx values using a custom sorting key,
+        which handles varying length strings with letters and numbers.
+        """
+        all_idx = [mdl.idx.v for mdl in self.models.values()]
+        flat_list = [item for sublist in all_idx for item in sublist]
+        return flat_list
+
+    def _check_src(self, src: str):
+        """
+        Helper function for checking if ``src`` is a shared field.
+
+        The requirement is not strictly enforced and is only for debugging purposed.
+
+        Disable debug logging in dispath modeling.
+        """
+        if src not in self.common_vars + self.common_params:
+            logger.debug(f'Group <{self.class_name}> does not share property <{src}>.')
+
+    def __repr__(self):
+        dev_text = 'device' if self.n == 1 else 'devices'
+        return f'{self.class_name} ({self.n} {dev_text}) at {hex(id(self))}'
+
+    def __setattr__(self, key, value):
+        if hasattr(value, 'owner'):
+            if value.owner is None:
+                value.owner = self
+        if hasattr(value, 'name'):
+            if value.name is None:
+                value.name = key
+
+        if isinstance(value, BackRef):
+            self.services_ref[key] = value
+
+        super().__setattr__(key, value)
+
+    def set_backref(self, name, from_idx, to_idx):
+        """
+        Set idxes to ``BackRef``, and set them to models.
+        """
+
+        uid = self.idx2uid(to_idx)
+        self.services_ref[name].v[uid].append(from_idx)
+
+        model = self.idx2model(to_idx)
+        model.set_backref(name, from_idx, to_idx)
+
+
+class Undefined(GroupBase):
+    """
+    The undefined group. Holds models with no ``group``.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+
+class ACTopology(GroupBase):
+    def __init__(self):
+        super().__init__()
+        self.common_vars.extend(('a', 'v'))
+
+
+class RenGen(GroupBase):
+    """
+    Renewable generator (converter) group.
+
+    See ANDES Documentation SynGen here for the notes on replacing StaticGen and setting the power
+    ratio parameters.
+
+    Reference:
+
+    [1] ANDES Documentation, RenGen, [Online]
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/RenGen.html#rengen
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus', 'gen', 'Sn', 'q0'))
+        self.common_vars.extend(('Pe', 'Qe'))
+
+
+class VSG(GroupBase):
+    """
+    Renewable generator with virtual synchronous generator (VSG) control group.
+
+    Note that this is a group separate from ``RenGen`` for VSG scheduling study.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus', 'gen', 'Sn'))
+        self.common_vars.extend(('Pe', 'Qe'))
+
+
+class DG(GroupBase):
+    """
+    Distributed generation (small-scale).
+
+    See ANDES Documentation SynGen here for the notes on replacing StaticGen and setting the power
+    ratio parameters.
+
+    Reference:
+
+    [1] ANDES Documentation, SynGen, [Online]
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/SynGen.html#syngen
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus', 'fn'))
+
+
+class Cost(GroupBase):
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('gen',))
+
+
+class Collection(GroupBase):
+    """
+    Collection of topology models
+    """
+
+    def __init__(self):
+        super().__init__()
+
+
+class Horizon(GroupBase):
+    """
+    Time horizon group.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+
+class Reserve(GroupBase):
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('zone',))
+
+
+class StaticGen(GroupBase):
+    """
+    Generator group.
+
+    Notes
+    -----
+    For co-simulation with ANDES, check
+    `ANDES StaticGen <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_
+    for replacing static generators with dynamic generators.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus', 'Sn', 'Vn', 'p0', 'q0', 'ra', 'xs', 'subidx',
+                                   'pmax', 'pmin', 'pg0', 'ctrl', 'R10', 'td1', 'td2',
+                                   'zone'))
+        self.common_vars.extend(('p', 'q'))
+
+
+class ACLine(GroupBase):
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus1', 'bus2', 'r', 'x'))
+
+
+class ACShort(GroupBase):
+    def __init__(self):
+        super(ACShort, self).__init__()
+        self.common_params.extend(('bus1', 'bus2'))
+
+
+class StaticLoad(GroupBase):
+    """
+    Static load group.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.common_params.extend(('bus', 'p0', 'q0', 'ctrl', 'zone'))
+
+
+class StaticShunt(GroupBase):
+    """
+    Static shunt compensator group.
+    """
+    pass
+
+
+class Information(GroupBase):
+    """
+    Group for information container models.
+    """
+
+    def __init__(self):
+        GroupBase.__init__(self)
+        self.common_params = []

ams/models/info.py

@@ -0,0 +1,26 @@
+"""
+Module for the information container models.
+"""
+from andes.core.param import DataParam
+from andes.core.model.modeldata import ModelData
+
+from ams.core.model import Model
+
+
+class Summary(ModelData, Model):
+    """
+    Class for storing system summary.
+    Can be used for random information or notes.
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self, three_params=False)
+
+        self.field = DataParam(info='field name')
+        self.comment = DataParam(info='information, comment, or anything')
+        self.comment2 = DataParam(info='comment field 2')
+        self.comment3 = DataParam(info='comment field 3')
+        self.comment4 = DataParam(info='comment field 4')
+
+        Model.__init__(self, system, config)
+        self.group = 'Information'

ams/models/line.py

@@ -0,0 +1,238 @@
+from andes.models.line.line import LineData
+from andes.models.line.jumper import JumperData
+from andes.core.param import NumParam
+from andes.shared import deg2rad, np, spmatrix
+
+from ams.core.model import Model
+
+
+class Line(LineData, Model):
+    """
+    AC transmission line model.
+
+    The model is also used for two-winding transformer. Transformers can set the
+    tap ratio in ``tap`` and/or phase shift angle ``phi``.
+
+    Note that the bus admittance matrix is built on fly and is not stored in the
+    object.
+
+    Notes
+    -----
+    There is a known issue that adding Algeb ``ud`` will cause Line.algebs run into
+    AttributeError: 'NoneType' object has no attribute 'n'. Not figured out why yet.
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        LineData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'ACLine'
+
+        self.amin = NumParam(default=-360 * deg2rad,
+                             info="minimum angle difference, from bus - to bus",
+                             unit='rad',
+                             tex_name=r'a_{min}',
+                             )
+        self.amax = NumParam(default=360 * deg2rad,
+                             info="maximum angle difference, from bus - to bus",
+                             unit='rad',
+                             tex_name=r'a_{max}',
+                             )
+        self.rate_a.unit = 'p.u.'
+        self.rate_b.unit = 'p.u.'
+        self.rate_c.unit = 'p.u.'
+        self.rate_a.default = 999.0
+        self.rate_b.default = 999.0
+        self.rate_c.default = 999.0
+
+        # NOTE: following parameters are prepared for building matrices
+        # they are initialized here but populated in ``System.setup()``.
+        self.a1a = None
+        self.a2a = None
+
+    # NOTE: following code are minly copied from `andes.models.line.Line`
+    # and they are not fully verified
+    # potential issues:
+    # `build_Bp` contains 'fdxb', which is not included in the input parameters,
+    # and the results are the negative of `Bbus` from `makeBdc` in PYPOWER
+    # `build_Bpp` ignores the line resistance for all three methods
+    # `build_Bdc` results are the negative of `Bbus` from `makeBdc` in PYPOWER
+    # `build_y` results have inignorable differences at diagonal elements with `makeYbus` in PYPOWER
+
+    def build_y(self):
+        """
+        Build bus admittance matrix. Copied from ``andes.models.line.line.Line``.
+
+        Returns
+        -------
+        Y : spmatrix
+            Bus admittance matrix.
+        """
+
+        nb = self.system.Bus.n
+
+        y1 = self.u.v * (self.g1.v + self.b1.v * 1j)
+        y2 = self.u.v * (self.g2.v + self.b2.v * 1j)
+        y12 = self.u.v / (self.r.v + self.x.v * 1j)
+        m = self.tap.v * np.exp(1j * self.phi.v)
+        m2 = self.tap.v**2
+        mconj = np.conj(m)
+
+        # build self and mutual admittances into Y
+        Y = spmatrix((y12 + y1 / m2), self.a1a, self.a1a, (nb, nb), 'z')
+        Y -= spmatrix(y12 / mconj, self.a1a, self.a2a, (nb, nb), 'z')
+        Y -= spmatrix(y12 / m, self.a2a, self.a1a, (nb, nb), 'z')
+        Y += spmatrix(y12 + y2, self.a2a, self.a2a, (nb, nb), 'z')
+
+        return Y
+
+    def build_Bp(self, method='fdpf'):
+        """
+        Function for building B' matrix.
+
+        Parameters
+        ----------
+        method : str
+            Method for building B' matrix. Choose from 'fdpf', 'fdbx', 'dcpf'.
+
+        Returns
+        -------
+        Bp : spmatrix
+            B' matrix.
+        """
+        nb = self.system.Bus.n
+
+        if method not in ("fdpf", "fdbx", "dcpf"):
+            raise ValueError(f"Invalid method {method}; choose from 'fdpf', 'fdbx', 'dcpf'")
+
+        # Build B prime matrix -- FDPF
+        # `y1`` neglects line charging shunt, and g1 is usually 0 in HV lines
+        # `y2`` neglects line charging shunt, and g2 is usually 0 in HV lines
+        y1 = self.u.v * self.g1.v
+        y2 = self.u.v * self.g2.v
+
+        # `m` neglected tap ratio
+        m = np.exp(self.phi.v * 1j)
+        mconj = np.conj(m)
+        m2 = np.ones(self.n)
+
+        if method in ('fdxb', 'dcpf'):
+            # neglect line resistance in Bp in XB method
+            y12 = self.u.v / (self.x.v * 1j)
+        else:
+            y12 = self.u.v / (self.r.v + self.x.v * 1j)
+
+        Bdc = spmatrix((y12 + y1) / m2, self.a1a, self.a1a, (nb, nb), 'z')
+        Bdc -= spmatrix(y12 / mconj, self.a1a, self.a2a, (nb, nb), 'z')
+        Bdc -= spmatrix(y12 / m, self.a2a, self.a1a, (nb, nb), 'z')
+        Bdc += spmatrix(y12 + y2, self.a2a, self.a2a, (nb, nb), 'z')
+        Bdc = Bdc.imag()
+
+        for item in range(nb):
+            if abs(Bdc[item, item]) == 0:
+                Bdc[item, item] = 1e-6 + 0j
+
+        return Bdc
+
+    def build_Bpp(self, method='fdpf'):
+        """
+        Function for building B'' matrix.
+
+        Parameters
+        ----------
+        method : str
+            Method for building B'' matrix. Choose from 'fdpf', 'fdbx', 'dcpf'.
+
+        Returns
+        -------
+        Bpp : spmatrix
+            B'' matrix.
+        """
+
+        nb = self.system.Bus.n
+
+        if method not in ("fdpf", "fdbx", "dcpf"):
+            raise ValueError(f"Invalid method {method}; choose from 'fdpf', 'fdbx', 'dcpf'")
+
+        # Build B double prime matrix
+        # y1 neglected line charging shunt, and g1 is usually 0 in HV lines
+        # y2 neglected line charging shunt, and g2 is usually 0 in HV lines
+        # m neglected phase shifter
+        y1 = self.u.v * (self.g1.v + self.b1.v * 1j)
+        y2 = self.u.v * (self.g2.v + self.b2.v * 1j)
+
+        m = self.tap.v
+        m2 = abs(m)**2
+
+        if method in ('fdbx', 'fdpf', 'dcpf'):
+            # neglect line resistance in Bpp in BX method
+            y12 = self.u.v / (self.x.v * 1j)
+        else:
+            y12 = self.u.v / (self.r.v + self.x.v * 1j)
+
+        Bpp = spmatrix((y12 + y1) / m2, self.a1a, self.a1a, (nb, nb), 'z')
+        Bpp -= spmatrix(y12 / np.conj(m), self.a1a, self.a2a, (nb, nb), 'z')
+        Bpp -= spmatrix(y12 / m, self.a2a, self.a1a, (nb, nb), 'z')
+        Bpp += spmatrix(y12 + y2, self.a2a, self.a2a, (nb, nb), 'z')
+        Bpp = Bpp.imag()
+
+        for item in range(nb):
+            if abs(Bpp[item, item]) == 0:
+                Bpp[item, item] = 1e-6 + 0j
+
+        return Bpp
+
+    def build_Bdc(self):
+        """
+        The MATPOWER-flavor Bdc matrix for DC power flow.
+
+        The method neglects line charging and line resistance. It retains tap ratio.
+
+        Returns
+        -------
+        Bdc : spmatrix
+            Bdc matrix.
+        """
+
+        nb = self.system.Bus.n
+
+        y12 = self.u.v / (self.x.v * 1j)
+        y12 = y12 / self.tap.v
+
+        Bdc = spmatrix(y12, self.a1a, self.a1a, (nb, nb), 'z')
+        Bdc -= spmatrix(y12, self.a1a, self.a2a, (nb, nb), 'z')
+        Bdc -= spmatrix(y12, self.a2a, self.a1a, (nb, nb), 'z')
+        Bdc += spmatrix(y12, self.a2a, self.a2a, (nb, nb), 'z')
+        Bdc = Bdc.imag()
+
+        for item in range(nb):
+            if abs(Bdc[item, item]) == 0:
+                Bdc[item, item] = 1e-6
+
+        return Bdc
+
+
+class Jumper(JumperData, Model):
+    """
+    Jumper is a device to short two buses (merging two buses into one).
+
+    Jumper can connect two buses satisfying one of the following conditions:
+
+    - neither bus is voltage-controlled
+    - either bus is voltage-controlled
+    - both buses are voltage-controlled, and the voltages are the same.
+
+    If the buses are controlled in different voltages, power flow will
+    not solve (as the power flow through the jumper will be infinite).
+
+    In the solutions, the ``p`` and ``q`` are flowing out of bus1
+    and flowing into bus2.
+
+    Setting a Jumper's connectivity status ``u`` to zero will disconnect the two
+    buses. In the case of a system split, one will need to call
+    ``System.connectivity()`` immediately following the split to detect islands.
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        JumperData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'ACShort'

ams/models/renewable/__init__.py

@@ -0,0 +1,5 @@
+"""
+Top-level package for renewable models.
+"""
+
+from ams.models.renewable.regc import REGCA1, REGCV1, REGCV2  # NOQA