ltbams 1.0.14__tar.gz → 1.0.16__tar.gz

{ltbams-1.0.14/ltbams.egg-info → ltbams-1.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.14
+Version: 1.0.16
 Summary: Python software for scheduling modeling and co-simulation with dynamics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -57,6 +57,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 
 ![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)
 [![DOI:10.1109/TSTE.2025.3528027](https://zenodo.org/badge/DOI/10.1109/TSTE.2025.3528027.svg)](https://ieeexplore.ieee.org/document/10836855)
+[![pyOpenSci Peer-Reviewed](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/174)
 
 | Badges |  |  |
 |---|---|---|

{ltbams-1.0.14 → ltbams-1.0.16}/README.md

@@ -6,6 +6,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 
 ![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)
 [![DOI:10.1109/TSTE.2025.3528027](https://zenodo.org/badge/DOI/10.1109/TSTE.2025.3528027.svg)](https://ieeexplore.ieee.org/document/10836855)
+[![pyOpenSci Peer-Reviewed](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/174)
 
 | Badges |  |  |
 |---|---|---|

{ltbams-1.0.14 → ltbams-1.0.16}/ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-08-31T23:37:40-0700",
+ "date": "2025-09-28T19:45:45-0700",
  "dirty": false,
  "error": null,
- "full-revisionid": "595ed3a3be7f707c7c4aa79ac73bffa58919dc81",
- "version": "1.0.14"
+ "full-revisionid": "ddabb4c2a9b5a75423288423d6a13e030aa13e84",
+ "version": "1.0.16"
 }
 '''  # END VERSION_JSON
 

{ltbams-1.0.14 → ltbams-1.0.16}/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
@@ -21,6 +21,7 @@ def str_list_oconv(x):
 
 class GCommit(ModelData, Model):
     """
+    UNDER DEVELOPMENT!
     Time slot model for generator commitment decisions.
 
     This class holds commitment decisions for generators,
@@ -31,14 +32,14 @@ class GCommit(ModelData, Model):
     `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.
-
-    .. versionadded:: 1.0.13
     """
 
+    # 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,
@@ -74,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):
@@ -93,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):

{ltbams-1.0.14 → ltbams-1.0.16}/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,

{ltbams-1.0.14 → ltbams-1.0.16}/ams/routines/dcopf2.py

@@ -26,8 +26,18 @@ class DCOPF2(DCOPF):
     Notes
     -----
     - This routine requires PTDF matrix.
-    - Nodal price ``pi`` is calculated with three parts.
+    - 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
     ----------
@@ -61,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"""

{ltbams-1.0.14 → ltbams-1.0.16}/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:

{ltbams-1.0.14 → ltbams-1.0.16}/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__)
 
@@ -509,7 +509,15 @@ class RoutineBase:
                                           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')
@@ -1116,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
     ----------

{ltbams-1.0.14 → ltbams-1.0.16}/docs/source/examples/index.rst

@@ -30,3 +30,4 @@ folder of the repository
    ../_examples/demo/demo_debug.ipynb
    ../_examples/demo/demo_mat.ipynb
    ../_examples/demo/demo_wrapper_routines.ipynb
+   ../_examples/demo/demo_dcopf.ipynb

{ltbams-1.0.14 → ltbams-1.0.16}/docs/source/genroutineref.py

@@ -22,15 +22,27 @@ and view details.
 
 Typical acronyms used in AMS include:
 
-+------------+--------------------+
-| Acronym    | Meaning            |
-+============+====================+
-| OPF        | Optimal Power Flow |
-+------------+--------------------+
-| ED         | Economic Dispatch  |
-+------------+--------------------+
-| UC         | Unit Commitment    |
-+------------+--------------------+
++------------+---------------------------+
+| Acronym    | Meaning                   |
++============+===========================+
+| AC-        | Alternating Current       |
++------------+---------------------------+
+| DC-        | Direct Current            |
++------------+---------------------------+
+| RT-        | Real-Time                 |
++------------+---------------------------+
+| -DG       | Distributed Generation     |
++------------+---------------------------+
+| -ES        | Energy Storage            |
++------------+---------------------------+
+| -OPF       | Optimal Power Flow        |
++------------+---------------------------+
+| -ED        | Economic Dispatch         |
++------------+---------------------------+
+| -UC        | Unit Commitment           |
++------------+---------------------------+
+| LMP        | Locational Marginal Price |
++------------+---------------------------+
 
 """
 

{ltbams-1.0.14 → ltbams-1.0.16}/docs/source/release-notes.rst

@@ -9,6 +9,20 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
+v1.0.16 (2025-09-28)
+----------------------
+
+- Add GitHub action to automatically upload release to Zenodo
+
+v1.0.15 (2025-09-28)
+----------------------
+
+- Fix ``DCOPF2.pb`` to use PTDF-based formulation
+- Add a demo to compare ``DCOPF2`` and ``DCOPF``, see
+  ``examples/demonstration/demo_dcopf.ipynb``
+- In DC type routines, set `vBus` value as 1 for placeholder
+- Include Summary and Objective value in exported JSON
+
 v1.0.14 (2025-08-29)
 ----------------------
 

{ltbams-1.0.14 → ltbams-1.0.16/ltbams.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.14
+Version: 1.0.16
 Summary: Python software for scheduling modeling and co-simulation with dynamics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -57,6 +57,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 
 ![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)
 [![DOI:10.1109/TSTE.2025.3528027](https://zenodo.org/badge/DOI/10.1109/TSTE.2025.3528027.svg)](https://ieeexplore.ieee.org/document/10836855)
+[![pyOpenSci Peer-Reviewed](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/174)
 
 | Badges |  |  |
 |---|---|---|

{ltbams-1.0.14 → ltbams-1.0.16}/tests/test_rtn_dcopf2.py

@@ -101,3 +101,36 @@ class TestDCOPF2(unittest.TestCase):
         a_dcopf = self.ss.DCOPF2.get(src='aBus', attr='v', idx=bus_idx)
         a_acopf = self.ss.ACOPF.get(src='aBus', attr='v', idx=bus_idx)
         np.testing.assert_almost_equal(a_dcopf, a_acopf, decimal=3)
+
+    def test_align_dcopf(self):
+        """
+        Test if results from `DCOPF2` are aligned with those from `DCOPF`.
+        """
+        self.ss.DCOPF.run(solver='CLARABEL')
+        self.ss.mats.build_ptdf()
+        self.ss.DCOPF2.run(solver='CLARABEL')
+
+        pg_idx = self.ss.StaticGen.get_all_idxes()
+        bus_idx = self.ss.Bus.idx.v
+        line_idx = self.ss.Line.idx.v
+
+        DECIMALS = 4
+        pg = self.ss.DCOPF.get(src='pg', attr='v', idx=pg_idx)
+        pg2 = self.ss.DCOPF2.get(src='pg', attr='v', idx=pg_idx)
+        np.testing.assert_almost_equal(pg, pg2, decimal=DECIMALS,
+                                       err_msg="pg between DCOPF2 and DCOPF not match!")
+
+        aBus = self.ss.DCOPF.get(src='aBus', attr='v', idx=bus_idx)
+        aBus2 = self.ss.DCOPF2.get(src='aBus', attr='v', idx=bus_idx)
+        np.testing.assert_almost_equal(aBus, aBus2, decimal=DECIMALS,
+                                       err_msg="aBus between DCOPF2 and DCOPF not match!")
+
+        pi = self.ss.DCOPF.get(src='pi', attr='v', idx=bus_idx)
+        pi2 = self.ss.DCOPF2.get(src='pi', attr='v', idx=bus_idx)
+        np.testing.assert_almost_equal(pi, pi2, decimal=DECIMALS,
+                                       err_msg="pi between DCOPF2 and DCOPF not match!")
+
+        plf = self.ss.DCOPF.get(src='plf', attr='v', idx=line_idx)
+        plf2 = self.ss.DCOPF2.get(src='plf', attr='v', idx=line_idx)
+        np.testing.assert_almost_equal(plf, plf2, decimal=DECIMALS,
+                                       err_msg="plf between DCOPF2 and DCOPF not match!")