ltbams 1.0.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-04-10T23:17:16-0400",
+ "date": "2025-04-14T02:15:15-0400",
  "dirty": false,
  "error": null,
- "full-revisionid": "3dbdbfee9ce8361b7975c9333179b88c01560137",
- "version": "1.0.6"
+ "full-revisionid": "ba5d62c3b3d080ab5ffe03e04883a3492dc121eb",
+ "version": "1.0.7"
 }
 '''  # END VERSION_JSON
 

ams/core/matprocessor.py

@@ -492,11 +492,8 @@ class MatProcessor:
 
         References
         ----------
-        [1] PowerWorld Documentation, Power Transfer Distribution Factors, [Online]
-
-        Available:
-
-        https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Power_Transfer_Distribution_Factors.htm
+        1. PowerWorld Documentation, Power Transfer Distribution Factors,
+           https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Power_Transfer_Distribution_Factors.htm
         """
         system = self.system
 
@@ -616,11 +613,8 @@ class MatProcessor:
 
         References
         ----------
-        [1] PowerWorld Documentation, Line Outage Distribution Factors, [Online]
-
-        Available:
-
-        https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Line_Outage_Distribution_Factors_LODFs.htm
+        1. PowerWorld Documentation, Line Outage Distribution Factors,
+           https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Line_Outage_Distribution_Factors_LODFs.htm
         """
         system = self.system
 
@@ -716,7 +710,7 @@ class MatProcessor:
     def build_otdf(self, line=None):
         """
         Build the Outrage Transfer Distribution Factor (OTDF) matrix for line
-        k outage: :math:`OTDF_k = PTDF + LODF[:, k] @ PTDF[k, ]`.
+        k outage: $OTDF_k = PTDF + LODF[:, k] @ PTDF[k, ]$.
 
         OTDF_k[m, n] means the increased line flow on line `m` when there is
         1 p.u. power injection at bus `n` when line `k` is outage.
@@ -737,11 +731,8 @@ class MatProcessor:
 
         References
         ----------
-        [1] PowerWorld Documentation, Line Outage Distribution Factors, [Online]
-
-        Available:
-
-        https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Line_Outage_Distribution_Factors_LODFs.htm
+        1. PowerWorld Documentation, Line Outage Distribution Factors,
+           https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/Line_Outage_Distribution_Factors_LODFs.htm
         """
         if (self.PTDF._v is None) or (self.LODF._v is None):
             raise ValueError("Internal PTDF and LODF are not available. Please build them first.")

ams/core/service.py

@@ -176,7 +176,8 @@ class ROperationService(RBaseService):
 
 class LoadScale(ROperationService):
     """
-    Get zonal load by scale nodal load given the corresponding load scale factor.
+    Retrieve zonal load by scaling nodal load using the specified load scale factor.
+    The load scale factor is defined for each "Area".
 
     Parameters
     ----------
@@ -220,8 +221,8 @@ class LoadScale(ROperationService):
         u_idx = self.u.get_all_idxes()
         ue = self.u.owner.get(src='u', attr='v', idx=u_idx)
         u_bus = self.u.owner.get(src='bus', attr='v', idx=u_idx)
-        u_zone = sys.Bus.get(src='zone', attr='v', idx=u_bus)
-        u_yloc = np.array(sys.Zone.idx2uid(u_zone))
+        u_area = sys.Bus.get(src='area', attr='v', idx=u_bus)
+        u_yloc = np.array(sys.Area.idx2uid(u_area))
         p0s = np.multiply(self.sd.v[:, u_yloc].transpose(),
                           (ue * self.u.v)[:, np.newaxis])
         if self.sparse:

ams/interface.py

@@ -56,6 +56,8 @@ def sync_adsys(amsys, adsys):
     """
     Sync parameters value of PFlow models between AMS and ANDES systems.
 
+    This function should be used carefully when per unit conversion is involved.
+
     Parameters
     ----------
     amsys : AMS.system.System
@@ -84,10 +86,23 @@ def sync_adsys(amsys, adsys):
     return True
 
 
-def _to_andes_pflow(system, no_output=False, default_config=True, **kwargs):
+def to_andes_pflow(system, no_output=False, default_config=True, **kwargs):
     """
     Helper function to convert the AMS system to an ANDES system with only
     power flow models.
+
+    The returned ANDES system is ***not*** setup.
+
+    Parameters
+    ----------
+    system: System
+        The AMS system to be converted to ANDES format.
+    no_output: bool, optional
+        To ANDES system.
+    default_config: bool, optional
+        To ANDES system.
+    kwargs:
+        Additional arguments to be passed to ``andes.system.System()``.
     """
 
     adsys = andes_System(no_outpu=no_output, default_config=default_config, **kwargs)
@@ -101,8 +116,6 @@ def _to_andes_pflow(system, no_output=False, default_config=True, **kwargs):
         for row in mdl.cache.df_in[mdl_cols].to_dict(orient='records'):
             adsys.add(mdl_name, row)
 
-    sync_adsys(amsys=system, adsys=adsys)
-
     return adsys
 
 
@@ -169,7 +182,7 @@ def to_andes(system, addfile=None,
     t0, _ = elapsed()
 
     # --- convert power flow models ---
-    adsys = _to_andes_pflow(system, no_output=no_output, default_config=default_config, **kwargs)
+    adsys = to_andes_pflow(system, no_output=no_output, default_config=default_config, **kwargs)
 
     _, s = elapsed(t0)
 

ams/models/__init__.py

@@ -18,7 +18,7 @@ ams_file_classes = list([
     ('reserve', ['SFR', 'SR', 'NSR', 'VSGR']),
     ('cost', ['GCost', 'SFRCost', 'SRCost', 'NSRCost', 'VSGCost']),
     ('cost', ['DCost']),
-    ('timeslot', ['TimeSlot', 'EDTSlot', 'UCTSlot']),
+    ('timeslot', ['EDTSlot', 'UCTSlot']),
 ])
 
 file_classes = ams_file_classes

ams/models/group.py

@@ -188,7 +188,7 @@ class StaticGen(GroupBase):
         super().__init__()
         self.common_params.extend(('bus', 'Sn', 'Vn', 'p0', 'q0', 'ra', 'xs', 'subidx',
                                    'pmax', 'pmin', 'pg0', 'ctrl', 'R10', 'td1', 'td2',
-                                   'zone'))
+                                   'area', 'zone'))
         self.common_vars.extend(('p', 'q'))
 
 
@@ -211,7 +211,7 @@ class StaticLoad(GroupBase):
 
     def __init__(self):
         super().__init__()
-        self.common_params.extend(('bus', 'p0', 'q0', 'ctrl', 'zone'))
+        self.common_params.extend(('bus', 'p0', 'q0', 'ctrl', 'area', 'zone'))
 
 
 class StaticShunt(GroupBase):

ams/models/line.py

@@ -18,8 +18,8 @@ class Line(LineData, Model):
 
     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.
+    1. Adding Algeb ``ud`` causes Line.algebs to encounter an AttributeError: 'NoneType'
+       object has no attribute 'n'. The root cause is still under investigation.
     """
 
     def __init__(self, system=None, config=None) -> None:

ams/models/renewable/regc.py

@@ -2,7 +2,7 @@
 RenGen scheduling model.
 """
 
-from andes.core.param import NumParam, IdxParam, ExtParam
+from andes.core.param import NumParam, IdxParam
 from andes.core.model import ModelData
 from ams.core.model import Model
 
@@ -80,10 +80,6 @@ class REGCV1(REGCData, Model):
         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',

ams/models/reserve.py

@@ -10,8 +10,8 @@ from ams.core.model import Model
 class ReserveData(ModelData):
     def __init__(self):
         super().__init__()
-        self.zone = IdxParam(model='Zone',
-                             default=None, info="Zone code",)
+        self.area = IdxParam(model='Area',
+                             default=None, info="Area idx",)
 
 
 class SFR(ReserveData, Model):

ams/models/static/gen.py

@@ -120,8 +120,8 @@ class PVModel(Model):
                               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.area = ExtParam(model='Bus', src='area', indexer=self.bus, export=False,
+                             info='Retrieved area idx', vtype=str, default=None,
                              )
 
         self.ud = Algeb(info='commitment decision',

ams/models/static/pq.py

@@ -53,8 +53,8 @@ class PQ(PQData, Model):
                               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.area = ExtParam(model='Bus', src='area', indexer=self.bus, export=False,
+                             info='Retrieved area idx', vtype=str, default=None,
                              )
         self.ctrl = NumParam(default=1,
                              info="load controllability",

ams/models/timeslot.py

@@ -18,7 +18,7 @@ def str_list_oconv(x):
 
 class TimeSlot(ModelData, Model):
     """
-    Time slot data for rolling horizon.
+    Base model for time slot data used in multi-interval scheduling.
     """
 
     def __init__(self, system=None, config=None):

ams/routines/dcopf.py

@@ -152,7 +152,7 @@ class DCOPF(DCPFBase):
 
     def dc2ac(self, kloss=1.0, **kwargs):
         """
-        Convert the RTED results with ACOPF.
+        Convert the results using ACOPF.
 
         Parameters
         ----------

ams/routines/dopf.py

@@ -16,11 +16,11 @@ class DOPF(DCOPF):
 
     UNDER DEVELOPMENT!
 
-    Reference:
-
-    [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.
+    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.
     """
 
     def __init__(self, system, config):
@@ -115,11 +115,11 @@ class DOPFVIS(DOPF):
 
     UNDER DEVELOPMENT!
 
-    Reference:
-
-    [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.
+    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.
     """
 
     def __init__(self, system, config):

ams/routines/ed.py

@@ -109,8 +109,7 @@ class MPBase:
 class ED(RTED, MPBase, SRBase):
     """
     DC-based multi-period economic dispatch (ED).
-    Dispath interval ``config.t`` (:math:``T_{cfg}``) is introduced, 1 [Hour] by default.
-
+    Dispatch interval ``config.t`` ($T_{cfg}$) is introduced, 1 [Hour] by default.
     ED extends DCOPF as follows:
 
     - Vars ``pg``, ``pru``, ``prd`` are extended to 2D
@@ -120,10 +119,10 @@ 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``.
     """
 
     def __init__(self, system, config):

ams/routines/pflow.py

@@ -12,7 +12,7 @@ from andes.utils.misc import elapsed
 from ams.core.param import RParam
 from ams.routines.routine import RoutineBase
 from ams.opt import Var, Expression, Objective
-from ams.interface import _to_andes_pflow, sync_adsys
+from ams.interface import to_andes_pflow, sync_adsys
 
 logger = logging.getLogger(__name__)
 
@@ -28,10 +28,9 @@ class PFlow(RoutineBase):
 
     References
     ----------
-    [1] M. L. Crow, Computational methods for electric power systems. 2015.
-
-    [2] ANDES Documentation - Simulation and Plot. [Online]. Available:
-    https://docs.andes.app/en/latest/_examples/ex1.html
+    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
     """
 
     def __init__(self, system, config):
@@ -102,10 +101,10 @@ class PFlow(RoutineBase):
 
         kwargs go to andes.system.System().
         """
-        self._adsys = _to_andes_pflow(self.system,
-                                      no_output=self.system.files.no_output,
-                                      config=self.config.as_dict(),
-                                      **kwargs)
+        self._adsys = to_andes_pflow(self.system,
+                                     no_output=self.system.files.no_output,
+                                     config=self.config.as_dict(),
+                                     **kwargs)
         self._adsys.setup()
         self.om.init()
         self.initialized = True
@@ -132,7 +131,7 @@ class PFlow(RoutineBase):
         self.exec_time = float(s.split(" ")[0])
 
         self.unpack()
-        return True
+        return self.converged
 
     def _post_solve(self):
         """

ams/routines/rted.py

@@ -20,22 +20,22 @@ class RTEDBase:
     """
 
     def __init__(self):
-        # --- zone ---
-        self.zg = RParam(info='Gen zone',
+        # --- area ---
+        self.zg = RParam(info='Gen area',
                          name='zg', tex_name='z_{one,g}',
-                         model='StaticGen', src='zone',
+                         model='StaticGen', src='area',
                          no_parse=True)
-        self.zd = RParam(info='Load zone',
+        self.zd = RParam(info='Load area',
                          name='zd', tex_name='z_{one,d}',
-                         model='StaticLoad', src='zone',
+                         model='StaticLoad', src='area',
                          no_parse=True)
-        self.gs = ZonalSum(u=self.zg, zone='Zone',
+        self.gs = ZonalSum(u=self.zg, zone='Area',
                            name='gs', tex_name=r'S_{g}',
-                           info='Sum Gen vars vector in shape of zone',
+                           info='Sum Gen vars vector in shape of area',
                            no_parse=True, sparse=True)
-        self.ds = ZonalSum(u=self.zd, zone='Zone',
+        self.ds = ZonalSum(u=self.zd, zone='Area',
                            name='ds', tex_name=r'S_{d}',
-                           info='Sum pd vector in shape of zone',
+                           info='Sum pd vector in shape of area',
                            no_parse=True,)
         self.pdz = NumOpDual(u=self.ds, u2=self.pd,
                              fun=np.multiply,
@@ -110,10 +110,9 @@ class SFRBase:
 class RTED(DCOPF, RTEDBase, SFRBase):
     """
     DC-based real-time economic dispatch (RTED).
+
     RTED extends DCOPF with:
 
-    - Mapping dicts to interface with ANDES
-    - Function ``dc2ac`` to do the AC conversion
     - Vars for SFR reserve: ``pru`` and ``prd``
     - Param for linear SFR cost: ``cru`` and ``crd``
     - Param for SFR requirement: ``du`` and ``dd``
@@ -127,8 +126,9 @@ 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 has not been implemented in formulations.
+    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.
     """
 
     def __init__(self, system, config):
@@ -176,14 +176,6 @@ class RTED(DCOPF, RTEDBase, SFRBase):
         self.obj.e_str = cost
 
     def dc2ac(self, kloss=1.0, **kwargs):
-        """
-        Convert the RTED results with ACOPF.
-
-        Parameters
-        ----------
-        kloss : float, optional
-            The loss factor for the conversion. Defaults to 1.2.
-        """
         exec_time = self.exec_time
         if self.exec_time == 0 or self.exit_code != 0:
             logger.warning(f'{self.class_name} is not executed successfully, quit conversion.')
@@ -467,9 +459,9 @@ class VISBase:
                      model='VSG', src='D',
                      nonneg=True,)
 
-        self.gvsg = ZonalSum(u=self.zvsg, zone='Zone',
+        self.gvsg = ZonalSum(u=self.zvsg, zone='Area',
                              name='gvsg', tex_name=r'S_{g}',
-                             info='Sum VSG vars vector in shape of zone',
+                             info='Sum VSG vars vector in shape of area',
                              no_parse=True)
         self.Mub = Constraint(name='Mub', is_eq=False,
                               info='M upper bound',
@@ -494,12 +486,11 @@ class RTEDVIS(RTED, VISBase):
     This class implements real-time economic dispatch with virtual inertia scheduling.
     Please ensure that the parameters `dvm` and `dvd` are set according to the system base.
 
-    Reference:
-
-    [1] B. She, F. Li, H. Cui, J. Wang, Q. Zhang and R. Bo, "Virtual
-    Inertia Scheduling (VIS) for Real-time Economic Dispatch of
-    IBRs-penetrated Power Systems," in IEEE Transactions on
-    Sustainable Energy, doi: 10.1109/TSTE.2023.3319307.
+    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.
     """
 
     def __init__(self, system, config):

ams/routines/uc.py

@@ -288,7 +288,7 @@ class UC(DCOPF, RTEDBase, MPBase, SRBase, NSRBase):
         gen['idx'] = self.system.PV.idx.v
         gen['pmax'] = self.system.PV.get(src='pmax', attr='v', idx=gen['idx'])
         gen['bus'] = self.system.PV.get(src='bus', attr='v', idx=gen['idx'])
-        gen['zone'] = self.system.PV.get(src='zone', attr='v', idx=gen['idx'])
+        gen['area'] = self.system.PV.get(src='area', attr='v', idx=gen['idx'])
         gcost_idx = self.system.GCost.find_idx(keys='gen', values=gen['idx'])
         gen['c2'] = self.system.GCost.get(src='c2', attr='v', idx=gcost_idx)
         gen['c1'] = self.system.GCost.get(src='c1', attr='v', idx=gcost_idx)

ams/system.py

@@ -410,25 +410,18 @@ class System(andes_System):
 
         # --- model parameters range check ---
         # TODO: there might be other parameters check?
-        # Line rate
-        adjust_rate = []
-        default_rate = 999
-        for rate in [self.Line.rate_a, self.Line.rate_b, self.Line.rate_c]:
-            if np.any(rate.v == 0):
-                adjust_rate.append(rate.name)
-                rate.v[rate.v == 0] = default_rate
-        if adjust_rate:
-            adjusted_rate = ', '.join(adjust_rate)
-            msg = f"Zero line rates detacted in {adjusted_rate}, "
-            msg += f"adjusted to {default_rate}."
+        adjusted_params = []
+        param_to_check = ['rate_a', 'rate_b', 'rate_c', 'amax', 'amin']
+        for pname in param_to_check:
+            param = self.Line.params[pname]
+            if np.any(param.v == 0):
+                adjusted_params.append(pname)
+                param.v[param.v == 0] = param.default
+        if adjusted_params:
+            adjusted_params_str = ', '.join(adjusted_params)
+            msg = f"Zero Line parameters detected, adjusted to default values: {adjusted_params_str}."
             logger.info(msg)
-        # Line max angle difference
-        if np.any(self.Line.amax.v == 0):
-            self.Line.amax.v[self.Line.amax.v == 0] = 2 * np.pi
-            logger.info("Zero line amax detected, adjusted to 2*pi.")
-        if np.any(self.Line.amin.v == 0):
-            self.Line.amin.v[self.Line.amin.v == 0] = -2 * np.pi
-            logger.info("Zero line amin detected, adjusted to -2*pi.")
+
         # === no device addition or removal after this point ===
         self.calc_pu_coeff()   # calculate parameters in system per units
 

docs/source/api.rst

@@ -30,7 +30,9 @@ Model
 
    ams.core.model
    ams.core.param
+   ams.core.var
    ams.core.service
+   ams.core.matprocessor
 
 
 Routines

docs/source/release-notes.rst

@@ -9,6 +9,18 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
+v1.0.7 (2024-04-14)
+--------------------
+
+- Address several wording issues in the documentation
+- Switch to ``Area`` from ``Zone`` for zonal calculation
+- Extend common parameters in groups ``StaticGen`` and ``StaticLoad`` with ``area``
+- Set case ``pjm5bus_demo.xlsx`` as a all-inclusive case
+- Include module ``MatProcessor`` in the API documentation
+- Improve Line parameters correction in ``System.setup()``
+- Make func ``interface._to_andes_pflow`` public
+- Update case files
+
 v1.0.6 (2024-04-10)
 --------------------
 

{ltbams-1.0.6.dist-info → ltbams-1.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.6
+Version: 1.0.7
 Summary: Python software for scheduling modeling and co-simulation with dynamics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang