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

ams/models/renewable/regc.py

@@ -0,0 +1,119 @@
+"""
+RenGen scheduling model.
+"""
+
+from andes.core.param import NumParam, IdxParam, ExtParam
+from andes.core.model import ModelData
+from ams.core.model import Model
+
+
+class REGCData(ModelData):
+    """
+    Data container for RenGen scheduling model.
+    """
+
+    def __init__(self):
+        ModelData.__init__(self)
+        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'
+                               )
+
+
+class REGCA1(REGCData, Model):
+    """
+    Renewable generator scheduling model.
+
+    Reference:
+
+    [1] ANDES Documentation, REGCA1
+
+    Available:
+    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regca1
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        REGCData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'RenGen'
+
+
+class REGCV1(REGCData, Model):
+    """
+    Voltage-controlled converter model (virtual synchronous generator) with
+    inertia emulation.
+
+    Here Mmax and Dmax are assumed to be constant, but they might subject to
+    the operating condition of the converter.
+
+    Notes
+    -----
+    - The generation is defined by group :ref:`StaticGen`
+    - Generation cost is defined by model :ref:`GCost`
+    - Inertia emulation cost is defined by model :ref:`VSGCost`
+
+    Reference:
+
+    [1] ANDES Documentation, REGCV1
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regcv1
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        REGCData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'VSG'
+        self.zone = ExtParam(model='Bus', src='zone',
+                             indexer=self.bus, export=False,
+                             info='Retrieved zone idx',
+                             vtype=str, default=None)
+        self.M = NumParam(default=10, tex_name='M',
+                          info='Inertia emulation',
+                          unit='s',
+                          power=True,)
+        self.D = NumParam(default=0, tex_name='D',
+                          info='Damping emulation',
+                          unit='p.u.',
+                          power=True,)
+        self.Mmax = NumParam(default=99, tex_name='M_{max}',
+                             info='Maximum inertia emulation',
+                             unit='s',
+                             power=True,)
+        self.Dmax = NumParam(default=99, tex_name='D_{max}',
+                             info='Maximum damping emulation',
+                             unit='p.u.',
+                             power=True,)
+
+
+class REGCV2(REGCV1):
+    """
+    Voltage-controlled VSC, identical to :ref:`REGCV1`.
+
+    Reference:
+
+    [1] ANDES Documentation, REGCV2
+
+    Available:
+
+    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regcv2
+    """
+
+    def __init__(self, system=None, config=None) -> None:
+        REGCV1.__init__(self, system, config)

ams/models/reserve.py

@@ -0,0 +1,94 @@
+"""
+Reserve model.
+"""
+
+from andes.core import (ModelData, IdxParam, NumParam)
+
+from ams.core.model import Model
+
+
+class ReserveData(ModelData):
+    def __init__(self):
+        super().__init__()
+        self.zone = IdxParam(model='Zone',
+                             default=None, info="Zone code",)
+
+
+class SFR(ReserveData, Model):
+    """
+    Zonal secondary frequency reserve (SFR) model.
+
+    Notes
+    -----
+    - ``Zone`` model is required for this model, and zone is defined by Param ``Bus.zone``.
+    """
+
+    def __init__(self, system, config):
+        ReserveData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Reserve'
+        self.du = NumParam(default=0,
+                           info='Zonal RegUp reserve demand',
+                           tex_name=r'd_{u}',)
+        self.dd = NumParam(default=0,
+                           info='Zonal RegDown reserve demand',
+                           tex_name=r'd_{d}',)
+
+
+class SR(ReserveData, Model):
+    """
+    Zonal spinning reserve (SR) model.
+
+    Notes
+    -----
+    - ``Zone`` model is required for this model, and zone is defined by Param ``Bus.zone``.
+    - ``demand`` is multiplied to online unused generation capacity.
+    """
+
+    def __init__(self, system, config):
+        ReserveData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Reserve'
+        self.demand = NumParam(default=0.1,
+                               info='Zonal spinning reserve demand',
+                               tex_name=r'd_{SR}')
+
+
+class NSR(ReserveData, Model):
+    """
+    Zonal non-spinning reserve (NSR) model.
+
+    Notes
+    -----
+    - ``Zone`` model is required for this model, and zone is defined by Param ``Bus.zone``.
+    - ``demand`` is multiplied to offline generation capacity.
+    """
+
+    def __init__(self, system, config):
+        ReserveData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Reserve'
+        self.demand = NumParam(default=0.1,
+                               info='Zonal non-spinning reserve demand',
+                               tex_name=r'd_{NSR}')
+
+
+class VSGR(ReserveData, Model):
+    """
+    Zonal VSG provided reserve model.
+
+    Notes
+    -----
+    - ``Zone`` model is required for this model, and zone is defined by Param ``Bus.zone``.
+    """
+
+    def __init__(self, system, config):
+        ReserveData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Reserve'
+        self.dvm = NumParam(default=0, unit='s',
+                            info='Zonal virtual inertia demand',
+                            tex_name=r'd_{VM}')
+        self.dvd = NumParam(default=0, unit='p.u.',
+                            info='Zonal virtual damping demand',
+                            tex_name=r'd_{VD}')

ams/models/shunt.py

@@ -0,0 +1,14 @@
+from andes.models.shunt.shunt import ShuntData
+
+from ams.core.model import Model
+
+
+class Shunt(ShuntData, Model):
+    """
+    Phasor-domain shunt compensator Model.
+    """
+
+    def __init__(self, system=None, config=None):
+        ShuntData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'StaticShunt'

ams/models/static/__init__.py

@@ -0,0 +1,2 @@
+from ams.models.static.pq import PQ  # NOQA
+from ams.models.static.gen import PV, Slack  # NOQA

ams/models/static/gen.py

@@ -0,0 +1,165 @@
+from collections import OrderedDict
+
+from andes.core.param import NumParam, ExtParam
+from andes.models.static.pv import PVData
+from andes.models.static.slack import SlackData
+
+from ams.core.model import Model
+from ams.core.var import Algeb
+
+
+class GenParam:
+    """
+    Additional parameters for static generators.
+    """
+
+    def __init__(self) -> None:
+        self.ctrl = NumParam(default=1,
+                             info="generator controllability",
+                             tex_name=r'c_{trl}',
+                             unit='bool',)
+        self.uf = NumParam(default=0,
+                           info="enforced on/off status; 0 unenforced, 1 enforced on, -1 enforced off",
+                           tex_name=r'u_{f}',
+                           unit='int',
+                           vrange=(-1, 1))
+        self.Pc1 = NumParam(default=0.0,
+                            info="lower real power output of PQ capability curve",
+                            tex_name=r'P_{c1}',
+                            unit='p.u.')
+        self.Pc2 = NumParam(default=0.0,
+                            info="upper real power output of PQ capability curve",
+                            tex_name=r'P_{c2}',
+                            unit='p.u.')
+        self.Qc1min = NumParam(default=0.0,
+                               info="minimum reactive power output at Pc1",
+                               tex_name=r'Q_{c1min}',
+                               unit='p.u.')
+        self.Qc1max = NumParam(default=0.0,
+                               info="maximum reactive power output at Pc1",
+                               tex_name=r'Q_{c1max}',
+                               unit='p.u.')
+        self.Qc2min = NumParam(default=0.0,
+                               info="minimum reactive power output at Pc2",
+                               tex_name=r'Q_{c2min}',
+                               unit='p.u.')
+        self.Qc2max = NumParam(default=0.0,
+                               info="maximum reactive power output at Pc2",
+                               tex_name=r'Q_{c2max}',
+                               unit='p.u.')
+        self.Ragc = NumParam(default=999.0,
+                             info="ramp rate for load following/AGC",
+                             tex_name=r'R_{agc}',
+                             unit='p.u./h')
+        self.R10 = NumParam(default=999.0,
+                            info="ramp rate for 10 minute reserves",
+                            tex_name=r'R_{10}',
+                            unit='p.u./h')
+        self.R30 = NumParam(default=999.0,
+                            info="30 minute ramp rate",
+                            tex_name=r'R_{30}',
+                            unit='p.u./h')
+        self.Rq = NumParam(default=999.0,
+                           info="ramp rate for reactive power (2 sec timescale)",
+                           tex_name=r'R_{q}',
+                           unit='p.u./h')
+        self.apf = NumParam(default=0.0,
+                            info="area participation factor",
+                            tex_name=r'a_{pf}')
+        self.pg0 = NumParam(default=0.0,
+                            info='active power start point (system base)',
+                            tex_name=r'p_{g0}',
+                            unit='p.u.',
+                            )
+        self.td1 = NumParam(default=1,
+                            info='minimum ON duration',
+                            tex_name=r't_{d1}',
+                            unit='h',
+                            )
+        self.td2 = NumParam(default=0.5,
+                            info='minimum OFF duration',
+                            tex_name=r't_{d2}',
+                            unit='h',
+                            )
+
+
+class PVModel(Model):
+    """
+    PV generator model (power flow) with q limit and PV-PQ conversion.
+    """
+
+    def __init__(self, system=None, config=None):
+        super().__init__(system, config)
+        self.group = 'StaticGen'
+
+        self.config.add(OrderedDict((('pv2pq', 0),
+                                     ('npv2pq', 0),
+                                     ('min_iter', 2),
+                                     ('err_tol', 0.01),
+                                     ('abs_violation', 1),
+                                     )))
+        self.config.add_extra("_help",
+                              pv2pq="convert PV to PQ in PFlow at Q limits",
+                              npv2pq="max. # of conversion each iteration, 0 - auto",
+                              min_iter="iteration number starting from which to enable switching",
+                              err_tol="iteration error below which to enable switching",
+                              abs_violation='use absolute (1) or relative (0) limit violation',
+                              )
+
+        self.config.add_extra("_alt",
+                              pv2pq=(0, 1),
+                              npv2pq=">=0",
+                              min_iter='int',
+                              err_tol='float',
+                              abs_violation=(0, 1),
+                              )
+        self.config.add_extra("_tex",
+                              pv2pq="z_{pv2pq}",
+                              npv2pq="n_{pv2pq}",
+                              min_iter="sw_{iter}",
+                              err_tol=r"\epsilon_{tol}"
+                              )
+
+        self.zone = ExtParam(model='Bus', src='zone', indexer=self.bus, export=False,
+                             info='Retrieved zone idx', vtype=str, default=None,
+                             )
+
+        self.ud = Algeb(info='commitment decision',
+                        unit='bool',
+                        tex_name=r'u_d',
+                        name='ud',
+                        )
+        self.p = Algeb(info='active power generation',
+                       unit='p.u.',
+                       tex_name='p',
+                       name='p',
+                       )
+        self.q = Algeb(info='reactive power generation',
+                       unit='p.u.',
+                       tex_name='q',
+                       name='q',
+                       )
+
+
+class PV(PVData, GenParam, PVModel):
+    """
+    PV generator model.
+
+    TODO: implement type conversion in config
+    """
+
+    def __init__(self, system, config):
+        PVData.__init__(self)
+        GenParam.__init__(self)
+        PVModel.__init__(self, system, config)
+
+
+class Slack(SlackData, GenParam, PVModel):
+    """
+    Slack generator model.
+    """
+
+    def __init__(self, system=None, config=None):
+        SlackData.__init__(self)
+        GenParam.__init__(self)
+        PVModel.__init__(self, system, config)

ams/models/static/pq.py

@@ -0,0 +1,61 @@
+from collections import OrderedDict
+
+from andes.core.param import NumParam, ExtParam
+from andes.models.static.pq import PQData
+
+from ams.core.model import Model
+
+
+class PQ(PQData, Model):
+    """
+    PQ load model.
+
+    TODO: implement type conversion in config
+    """
+
+    def __init__(self, system, config):
+        PQData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'StaticLoad'
+        self.config.add(OrderedDict((('pq2z', 1),
+                                     ('p2p', 0.0),
+                                     ('p2i', 0.0),
+                                     ('p2z', 1.0),
+                                     ('q2q', 0.0),
+                                     ('q2i', 0.0),
+                                     ('q2z', 1.0),
+                                     )))
+        self.config.add_extra("_help",
+                              pq2z="pq2z conversion if out of voltage limits",
+                              p2p="P constant power percentage for TDS. Must have (p2p+p2i+p2z)=1",
+                              p2i="P constant current percentage",
+                              p2z="P constant impedance percentage",
+                              q2q="Q constant power percentage for TDS. Must have (q2q+q2i+q2z)=1",
+                              q2i="Q constant current percentage",
+                              q2z="Q constant impedance percentage",
+                              )
+        self.config.add_extra("_alt",
+                              pq2z="(0, 1)",
+                              p2p="float",
+                              p2i="float",
+                              p2z="float",
+                              q2q="float",
+                              q2i="float",
+                              q2z="float",
+                              )
+        self.config.add_extra("_tex",
+                              pq2z="z_{pq2z}",
+                              p2p=r"\gamma_{p2p}",
+                              p2i=r"\gamma_{p2i}",
+                              p2z=r"\gamma_{p2z}",
+                              q2q=r"\gamma_{q2q}",
+                              q2i=r"\gamma_{q2i}",
+                              q2z=r"\gamma_{q2z}",
+                              )
+
+        self.zone = ExtParam(model='Bus', src='zone', indexer=self.bus, export=False,
+                             info='Retrieved zone idx', vtype=str, default=None,
+                             )
+        self.ctrl = NumParam(default=1,
+                             info="load controllability",
+                             tex_name=r'c_{trl}',)

ams/models/timeslot.py

@@ -0,0 +1,69 @@
+"""
+Model for rolling horizon used in scheduling.
+"""
+
+from andes.core import ModelData, NumParam
+from andes.models.timeseries import str_list_iconv
+from ams.core.model import Model
+
+
+def str_list_oconv(x):
+    """
+    Convert list into a list literal.
+    """
+    # NOTE: convert elements to string from number first, then join them
+    str_x = [str(i) for i in x]
+    return ','.join(str_x)
+
+
+class TimeSlot(ModelData, Model):
+    """
+    Time slot data for rolling horizon.
+    """
+
+    def __init__(self, system=None, config=None):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Horizon'
+
+        self.sd = NumParam(info='zonal load scaling factor',
+                           tex_name=r's_{d}',
+                           iconvert=str_list_iconv,
+                           oconvert=str_list_oconv,
+                           vtype=float)
+
+
+class EDTSlot(TimeSlot):
+    """
+    Time slot model for ED.
+
+    `sd` is the zonal load scaling factor.
+    Cells in `sd` should have `nz` values seperated by comma,
+    where `nz` is the number of `Zone` in the system.
+
+    `ug` is the unit commitment decisions.
+    Cells in `ug` should have `ng` values seperated by comma,
+    where `ng` is the number of `StaticGen` in the system.
+    """
+
+    def __init__(self, system=None, config=None):
+        TimeSlot.__init__(self, system, config)
+
+        self.ug = NumParam(info='unit commitment decisions',
+                           tex_name=r'u_{g}',
+                           iconvert=str_list_iconv,
+                           oconvert=str_list_oconv,
+                           vtype=int)
+
+
+class UCTSlot(TimeSlot):
+    """
+    Time slot model for UC.
+
+    `sd` is the zonal load scaling factor.
+    Cells in `sd` should have `nz` values seperated by comma,
+    where `nz` is the number of `Zone` in the system.
+    """
+
+    def __init__(self, system=None, config=None):
+        TimeSlot.__init__(self, system, config)

ams/models/zone.py

@@ -0,0 +1,49 @@
+import logging
+
+from andes.core.model import ModelData
+from andes.utils.tab import Tab
+from andes.core.service import BackRef
+
+from ams.core.model import Model
+
+logger = logging.getLogger(__name__)
+
+
+class Zone(ModelData, Model):
+    """
+    Zone model for zonal items.
+
+    An ``area`` can have multiple zones.
+
+    Notes
+    -----
+    1. Zone is a collection of buses.
+    2. Model ``Zone`` is not actually defined in ANDES.
+
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+
+        self.group = 'Collection'
+
+        self.Bus = BackRef()
+        self.ACTopology = BackRef()
+
+    def bus_table(self):
+        """
+        Return a formatted table with area idx and bus idx correspondence
+
+        Returns
+        -------
+        str
+            Formatted table
+
+        """
+        if self.n:
+            header = ['Zone ID', 'Bus ID']
+            rows = [(i, j) for i, j in zip(self.idx.v, self.Bus.v)]
+            return Tab(header=header, data=rows).draw()
+        else:
+            return ''

ams/opt/__init__.py

@@ -0,0 +1,12 @@
+"""
+Module for optimization modeling.
+"""
+
+from ams.opt.optzbase import OptzBase, ensure_symbols, ensure_mats_and_parsed  # NOQA
+from ams.opt.var import Var  # NOQA
+from ams.opt.exprcalc import ExpressionCalc  # NOQA
+from ams.opt.param import Param  # NOQA
+from ams.opt.constraint import Constraint  # NOQA
+from ams.opt.objective import Objective  # NOQA
+from ams.opt.expression import Expression  # NOQA
+from ams.opt.omodel import OModelBase, OModel  # NOQA