ltbams 1.0.13__py3-none-any.whl → 1.0.15__py3-none-any.whl

ams/models/distributed/ev.py

@@ -12,13 +12,17 @@ class EV1(ModelData, Model):
     """
     Aggregated EV model for scheduling at transmission level.
 
-    For co-simulation with ADNES, it is expected to be used in
+    For co-simulation with ANDES, 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.
+    References
+    ----------
+    1. J. Wang et al., "Electric Vehicles Charging Time Constrained
+       Deliverable Provision of Secondary Frequency Regulation," in IEEE
+       Transactions on Smart Grid, vol. 15, no. 4, pp. 3892-3903, July
+       2024, doi: 10.1109/TSG.2024.3356948.
+    2. ANDES Documentation, EV1,
+       https://andes.readthedocs.io/en/stable/groupdoc/DG.html#ev1
     """
 
     def __init__(self, system, config):
@@ -53,7 +57,7 @@ class EV1(ModelData, Model):
 
 class EV2(EV1):
     """
-    EV aggregation model at transmission level, identical to :ref:`EV1`.
+    Alias for EV1.
     """
 
     def __init__(self, system=None, config=None) -> None:

ams/models/distributed/pvd1.py

@@ -52,13 +52,10 @@ class PVD1(PVD1Data, Model):
     ``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
+    References
+    ----------
+    1. ANDES Documentation, PVD1,
+       https://andes.readthedocs.io/en/stable/groupdoc/DG.html#pvd1
     """
 
     def __init__(self, system, config):

ams/models/group.py

@@ -3,22 +3,24 @@ import logging
 from andes.models.group import GroupBase as adGroupBase
 from andes.core.service import BackRef
 
+from ams.utils.misc import deprec_get_idx
+
 logger = logging.getLogger(__name__)
 
 
 class GroupBase(adGroupBase):
     """
-    Base class for groups.
+    Base class for groups, revised from
+    `andes.models.group.GroupBase`.
 
     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',))
 
+    @deprec_get_idx
     def get_idx(self):
         """
         Return the value of group idx sorted in a human-readable style.
@@ -27,6 +29,9 @@ class GroupBase(adGroupBase):
         -----
         This function sorts the idx values using a custom sorting key,
         which handles varying length strings with letters and numbers.
+
+        .. deprecated:: 1.0.0
+           Use ``get_all_idxes`` instead.
         """
         all_idx = [mdl.idx.v for mdl in self.models.values()]
         flat_list = [item for sublist in all_idx for item in sublist]
@@ -94,13 +99,10 @@ class RenGen(GroupBase):
     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
+    References
+    ----------
+    1. ANDES Documentation, RenGen,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#rengen
     """
 
     def __init__(self):
@@ -129,13 +131,10 @@ class DG(GroupBase):
     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
+    References
+    ----------
+    1. ANDES Documentation, SynGen,
+       https://andes.readthedocs.io/en/stable/groupdoc/SynGen.html#syngen
     """
 
     def __init__(self):
@@ -182,7 +181,7 @@ class StaticGen(GroupBase):
     Notes
     -----
     For co-simulation with ANDES, refer to the `ANDES StaticGen Documentation
-    <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_ for
+    <https://andes.readthedocs.io/en/stable/groupdoc/StaticGen.html#staticgen>`_ for
     replacing static generators with dynamic generators.
     """
 

ams/models/renewable/regc.py

@@ -39,12 +39,10 @@ class REGCA1(REGCData, Model):
     """
     Renewable generator scheduling model.
 
-    Reference:
-
-    [1] ANDES Documentation, REGCA1
-
-    Available:
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regca1
+    References
+    ----------
+    1. ANDES Documentation, REGCA1,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regca1
     """
 
     def __init__(self, system=None, config=None) -> None:
@@ -56,7 +54,7 @@ class REGCA1(REGCData, Model):
 class REGCV1(REGCData, Model):
     """
     Voltage-controlled converter model (virtual synchronous generator) with
-    inertia emulation.
+    inertia emulation, for scheduling purposes.
 
     Here Mmax and Dmax are assumed to be constant, but they might subject to
     the operating condition of the converter.
@@ -67,13 +65,10 @@ class REGCV1(REGCData, Model):
     - 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
+    References
+    ----------
+    1. ANDES Documentation, REGCV1,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regcv1
     """
 
     def __init__(self, system=None, config=None) -> None:
@@ -100,15 +95,12 @@ class REGCV1(REGCData, Model):
 
 class REGCV2(REGCV1):
     """
-    Voltage-controlled VSC, identical to :ref:`REGCV1`.
-
-    Reference:
-
-    [1] ANDES Documentation, REGCV2
-
-    Available:
+    Alias for REGCV1, for scheduling purposes.
 
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regcv2
+    References
+    ----------
+    1. ANDES Documentation, REGCV2,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regcv2
     """
 
     def __init__(self, system=None, config=None) -> None:

ams/models/timeslot.py

@@ -1,5 +1,5 @@
 """
-Model for rolling horizon used in scheduling.
+Models for multi-period scheduling.
 """
 
 from andes.core import ModelData, NumParam
@@ -10,12 +10,43 @@ from ams.core.model import Model
 def str_list_oconv(x):
     """
     Convert list into a list literal.
+
+    Revised from `andes.models.timeseries.str_list_oconv`, where
+    the output type is converted to a list of strings.
     """
     # NOTE: convert elements to string from number first, then join them
     str_x = [str(i) for i in x]
     return ','.join(str_x)
 
 
+class GCommit(ModelData, Model):
+    """
+    UNDER DEVELOPMENT!
+    Time slot model for generator commitment decisions.
+
+    This class holds commitment decisions for generators,
+    and should be used in multi-period scheduling routines that need
+    generator commitment decisions.
+
+    For example, in Unit Commitment (UC) problems, there is a variable
+    `ugd` representing the unit commitment decisions for each generator.
+    After solving the UC problem, the `ugd` values can be used for
+    Economic Dispatch (ED) as a parameter.
+    """
+
+    # TODO: .. versionadded:: 1.0.13
+    def __init__(self, system=None, config=None):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+
+        # TODO: add IdxParam of generator
+        self.ug = NumParam(info='unit commitment decisions',
+                           tex_name=r'u_{g}',
+                           iconvert=str_list_iconv,
+                           oconvert=str_list_oconv,
+                           vtype=int)
+
+
 class TimeSlot(ModelData, Model):
     """
     Base model for time slot data used in multi-interval scheduling.
@@ -44,6 +75,13 @@ class EDTSlot(TimeSlot):
     `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.
+
+    Warnings
+    --------
+    The order of generators in `ug` is determined by the input
+    file, not by explicit mapping. This may cause misinterpretation
+    if the loaded data order changes.
+    Involved routines include: `ED` `UC` and their derivatives.
     """
 
     def __init__(self, system=None, config=None):
@@ -63,6 +101,13 @@ class UCTSlot(TimeSlot):
     `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.
+
+    Warnings
+    --------
+    The order of generators in `ug` is determined by the input
+    file, not by explicit mapping. This may cause misinterpretation
+    if the loaded data order changes.
+    Involved routines include: `ED` `UC` and their derivatives.
     """
 
     def __init__(self, system=None, config=None):

ams/models/zone.py

@@ -17,9 +17,8 @@ class Zone(ModelData, Model):
 
     Notes
     -----
-    1. Zone is a collection of buses.
-    2. Model ``Zone`` is not actually defined in ANDES.
-
+    - A zone is a collection of buses.
+    - The ``Zone`` model is not defined in ANDES up to version 1.9.3.
     """
 
     def __init__(self, system, config):
@@ -39,7 +38,6 @@ class Zone(ModelData, Model):
         -------
         str
             Formatted table
-
         """
         if self.n:
             header = ['Zone ID', 'Bus ID']

ams/opt/exprcalc.py

@@ -24,9 +24,11 @@ class ExpressionCalc(OptzBase):
     """
     Class for calculating expressions.
 
-    Note that `ExpressionCalc` is not a CVXPY expression, and it should not be used
-    in the optimization model.
-    It is used to calculate expression values **after** successful optimization.
+    This class is useful for performing post-solve calculations, but it does not
+    participate in the optimization model itself.
+
+    Note: `ExpressionCalc` is not a CVXPY expression and should NOT be referenced
+    in `e_str` by any other components, including other instances of `ExpressionCalc`.
     """
 
     def __init__(self,

ams/opt/optzbase.py

@@ -174,13 +174,14 @@ class OptzBase:
         """
         Return all the indexes of this item.
 
-        .. note::
-            New in version 1.0.0.
-
         Returns
         -------
         list
             A list of indexes.
+
+        Notes
+        -----
+        .. versionadded:: 1.0.0
         """
 
         if self.is_group:

ams/report.py

@@ -30,13 +30,8 @@ def report_info(system) -> list:
 
 class Report:
     """
-    Report class to store routine analysis reports.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
+    Report class to store routine analysis reports,
+    revised from `andes.report.Report`.
     """
 
     def __init__(self, system):

ams/routines/dcopf.py

@@ -17,19 +17,22 @@ logger = logging.getLogger(__name__)
 
 class DCOPF(DCPFBase):
     """
-    DC optimal power flow (DCOPF).
+    DC optimal power flow (DCOPF) using B-theta formulation.
 
     Notes
     -----
-    1. The nodal price is calculated as ``pi`` in ``pic``.
-    2. Devices online status of ``StaticGen``, ``StaticLoad``, and ``Shunt`` are considered in the connectivity
-       matrices ``Cft``, ``Cg``, ``Cl``, and ``Csh``.
+    - The nodal price is calculated as ``pi`` in ``pic``.
+    - Devices online status of ``StaticGen``, ``StaticLoad``, and ``Shunt`` are considered in the connectivity
+      matrices ``Cft``, ``Cg``, ``Cl``, and ``Csh``.
 
     References
     ----------
     1. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas, “MATPOWER: Steady-State
        Operations, Planning, and Analysis Tools for Power Systems Research and Education,” IEEE
        Trans. Power Syst., vol. 26, no. 1, pp. 12-19, Feb. 2011
+    2. Y. Chen et al., "Security-Constrained Unit Commitment for Electricity Market: Modeling,
+       Solution Methods, and Future Challenges," in IEEE Transactions on Power Systems, vol. 38, no. 5,
+       pp. 4668-4681, Sept. 2023
     """
 
     def __init__(self, system, config):

ams/routines/dcopf2.py

@@ -18,15 +18,35 @@ logger = logging.getLogger(__name__)
 
 class DCOPF2(DCOPF):
     """
-    DC optimal power flow (DCOPF) using PTDF.
+    DC optimal power flow (DCOPF) using PTDF formulation.
+
     For large cases, it is recommended to build the PTDF first, especially when incremental
     build is necessary.
 
     Notes
     -----
-    1. This routine requires PTDF matrix.
-    2. Nodal price ``pi`` is calculated with three parts.
-    3. Bus angle ``aBus`` is calculated after solving the problem.
+    - This routine requires PTDF matrix.
+    - LMP ``pi`` is calculated with two parts, energy price and congestion price.
+    - Bus angle ``aBus`` is calculated after solving the problem.
+    - In export results, ``pi`` and ``pic`` are kept for each bus, while ``pie``
+      can be restored manually by ``pie = pi - pic`` if needed.
+
+    Warning
+    -------
+    In this implementation, the dual variables for constraints have opposite signs compared
+    to the mathematical formulation: 1. The dual of `pb` returns a negative value, so energy
+    price is computed as `-pb.dual_variables[0]`. 2. Similarly, a minus sign is applied to
+    the duals of `plfub` and `plflb` when calculating congestion price. The reason for this
+    sign difference is not yet fully understood.
+
+    References
+    ----------
+    1. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas, “MATPOWER: Steady-State
+       Operations, Planning, and Analysis Tools for Power Systems Research and Education,” IEEE
+       Trans. Power Syst., vol. 26, no. 1, pp. 12-19, Feb. 2011
+    2. Y. Chen et al., "Security-Constrained Unit Commitment for Electricity Market: Modeling,
+       Solution Methods, and Future Challenges," in IEEE Transactions on Power Systems, vol. 38, no. 5,
+       pp. 4668-4681, Sept. 2023
     """
 
     def __init__(self, system, config):
@@ -51,29 +71,34 @@ class DCOPF2(DCOPF):
                            name='PTDF', tex_name=r'P_{TDF}',
                            model='mats', src='PTDF',
                            no_parse=True, sparse=True)
+        self.PTDFt = NumOp(u=self.PTDF,
+                           name='PTDFt', tex_name=r'P_{TDF}^T',
+                           info='PTDF transpose',
+                           fun=np.transpose, no_parse=True)
+
+        # --- rewrite Constraint pb: power balance ---
+        self.pb.e_str = 'sum(pg) - sum(pd)'
 
         # --- rewrite Expression plf: line flow---
         self.plf.e_str = 'PTDF @ (Cg@pg - Cl@pd - Csh@gsh - Pbusinj)'
 
         # --- rewrite nodal price ---
-        self.Cft = RParam(info='Line connection matrix',
-                          name='Cft', tex_name=r'C_{ft}',
-                          model='mats', src='Cft',
-                          no_parse=True, sparse=True,)
-        self.pilb = ExpressionCalc(info='Congestion price, dual of <plflb>',
-                                   name='pilb',
-                                   model='Line', src=None,
-                                   e_str='plflb.dual_variables[0]')
-        self.piub = ExpressionCalc(info='Congestion price, dual of <plfub>',
-                                   name='piub',
-                                   model='Line', src=None,
-                                   e_str='plfub.dual_variables[0]')
-        self.pib = ExpressionCalc(info='Energy price, dual of <pb>',
-                                  name='pib',
-                                  model='Bus', src=None,
-                                  e_str='pb.dual_variables[0]')
-        pi = 'pb.dual_variables[0] + Cft@(plfub.dual_variables[0] - plflb.dual_variables[0])'
+        self.pie = ExpressionCalc(info='Energy price',
+                                  name='pie', unit='$/p.u.',
+                                  e_str='-pb.dual_variables[0]')
+        pic = '-PTDFt@(plfub.dual_variables[0] - plflb.dual_variables[0])'
+        self.pic = ExpressionCalc(info='Congestion price',
+                                  name='pic', unit='$/p.u.',
+                                  e_str=pic,
+                                  model='Bus', src=None)
+
+        # NOTE: another implementation of self.pi.e_str can be:
+        # self.pi.e_str = self.pie.e_str + self.pic.e_str
+        # but it is less intuitive to read, as this implementation is not likely
+        # to be used again in other routines.
+        pi = '-pb.dual_variables[0] - PTDFt@(plfub.dual_variables[0] - plflb.dual_variables[0])'
         self.pi.e_str = pi
+        self.pi.info = 'locational marginal price (LMP)'
 
     def _post_solve(self):
         """Calculate aBus"""

ams/routines/dcpf.py

@@ -3,6 +3,8 @@ Power flow routines.
 """
 import logging
 
+import numpy as np
+
 from ams.opt import Var, Constraint, Expression, Objective
 from ams.routines.routine import RoutineBase
 
@@ -173,6 +175,9 @@ class DCPFBase(RoutineBase):
         """
         Post-solve calculations.
         """
+        # NOTE: for DC type routines, set vBus to 1.0 p.u. as placeholder
+        self.vBus.v = np.ones(self.vBus.shape)
+
         # NOTE: unpack Expressions if owner and arc are available
         for expr in self.exprs.values():
             if expr.owner and expr.src:

ams/routines/dopf.py

@@ -17,7 +17,7 @@ class DOPF(DCOPF):
     UNDER DEVELOPMENT!
 
     References
-    -----------------
+    ----------
     1. L. Bai, J. Wang, C. Wang, C. Chen, and F. Li, “Distribution Locational Marginal Pricing (DLMP)
        for Congestion Management and Voltage Support,” IEEE Trans. Power Syst., vol. 33, no. 4,
        pp. 4061-4073, Jul. 2018, doi: 10.1109/TPWRS.2017.2767632.
@@ -116,7 +116,7 @@ class DOPFVIS(DOPF):
     UNDER DEVELOPMENT!
 
     References
-    -----------------
+    ----------
     1. L. Bai, J. Wang, C. Wang, C. Chen, and F. Li, “Distribution Locational Marginal Pricing (DLMP)
        for Congestion Management and Voltage Support,” IEEE Trans. Power Syst., vol. 33, no. 4,
        pp. 4061-4073, Jul. 2018, doi: 10.1109/TPWRS.2017.2767632.

ams/routines/ed.py

@@ -120,11 +120,11 @@ class ED(RTED, MPBase, SRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``
-    2. The tie-line flow is not implemented in this model.
-    3. ``EDTSlot.ug`` is used instead of ``StaticGen.u`` for generator commitment.
-    4. Following reserves are balanced for each "Area": RegUp reserve ``rbu``,
-       RegDn reserve ``rbd``, and Spinning reserve ``rsr``.
+    - Formulations has been adjusted with interval ``config.t``
+    - The tie-line flow is not implemented in this model.
+    - ``EDTSlot.ug`` is used instead of ``StaticGen.u`` for generator commitment.
+    - Following reserves are balanced for each "Area": RegUp reserve ``rbu``,
+      RegDn reserve ``rbd``, and Spinning reserve ``rsr``.
     """
 
     def __init__(self, system, config):

ams/routines/pflow.py

@@ -30,7 +30,7 @@ class PFlow(RoutineBase):
     ----------
     1. M. L. Crow, Computational methods for electric power systems. 2015.
     2. ANDES Documentation - Simulation and Plot.
-       https://docs.andes.app/en/latest/_examples/ex1.html
+       https://andes.readthedocs.io/en/stable/_examples/ex1.html
     """
 
     def __init__(self, system, config):

ams/routines/routine.py

@@ -21,7 +21,7 @@ from ams.opt import Param, Var, Constraint, Objective, ExpressionCalc, Expressio
 
 from ams.utils.paths import get_export_path
 
-from ams.shared import pd
+from ams.shared import pd, summary_row, summary_name
 
 logger = logging.getLogger(__name__)
 
@@ -445,6 +445,8 @@ class RoutineBase:
         -------
         bool
             True if the loading is successful, False otherwise.
+
+        .. versionadded:: 1.0.13
         """
         try:
             with open(path, 'r') as f:
@@ -496,15 +498,26 @@ class RoutineBase:
         -------
         str
             The exported json file name
+
+        .. versionadded:: 1.0.13
         """
         if not self.converged:
             logger.warning("Routine did not converge, aborting export.")
             return None
 
-        path, file_name = get_export_path(self.system, self.class_name,
+        path, file_name = get_export_path(self.system,
+                                          self.class_name + '_out',
                                           path=path, fmt='json')
 
-        data_dict = dict()
+        data_dict = OrderedDict()
+
+        # insert summary
+        df = pd.DataFrame([summary_row])
+        df.index.name = "uid"
+        data_dict.update({summary_name: df.to_dict(orient='records')})
+
+        # insert objective value
+        data_dict.update(OrderedDict(Objective=self.obj.v))
 
         group_data(self, data_dict, self.vars, 'v')
         group_data(self, data_dict, self.exprs, 'v')
@@ -1111,7 +1124,8 @@ def collect_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
 
 def group_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
     """
-    Collect data for export from grouped items.
+    Collect data for export by groups, adding device idx in each group.
+    This is useful when exporting to dictionary formats like JSON.
 
     Parameters
     ----------
@@ -1123,6 +1137,8 @@ def group_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
         Dictionary of items to collect data from.
     attr : str
         Attribute to collect data for.
+
+    .. versionadded:: 1.0.13
     """
     for key, item in items.items():
         if item.owner is None:

ams/routines/rted.py

@@ -125,10 +125,10 @@ class RTED(DCOPF, RTEDBase, SFRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``, 5/60 [Hour] by default.
-    2. The tie-line flow related constraints are ommited in this formulation.
-    3. The power balance is solved for the entire system.
-    4. The SFR is solved for each area.
+    - Formulations has been adjusted with interval ``config.t``, 5/60 [Hour] by default.
+    - The tie-line flow related constraints are ommited in this formulation.
+    - Power generation is balanced for the entire system.
+    - SFR is balanced for each area.
     """
 
     def __init__(self, system, config):
@@ -487,7 +487,7 @@ class RTEDVIS(RTED, VISBase):
     Please ensure that the parameters `dvm` and `dvd` are set according to the system base.
 
     References
-    -----------------
+    ----------
     1. B. She, F. Li, H. Cui, J. Wang, Q. Zhang and R. Bo, "Virtual Inertia Scheduling (VIS) for
        Real-Time Economic Dispatch of IBR-Penetrated Power Systems," in IEEE Transactions on
        Sustainable Energy, vol. 15, no. 2, pp. 938-951, April 2024, doi: 10.1109/TSTE.2023.3319307.

ams/routines/uc.py

@@ -69,8 +69,8 @@ class UC(DCOPF, RTEDBase, MPBase, SRBase, NSRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``
-    2. The tie-line flow has not been implemented in formulations.
+    - The formulations has been adjusted with interval ``config.t``
+    - The tie-line flow has not been implemented in formulations.
 
     References
     ----------