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

ams/_version.py

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

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):

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/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"""

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/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
     ----------

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

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 |
++------------+---------------------------+
 
 """
 

docs/source/release-notes.rst

@@ -9,6 +9,15 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
+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.dist-info → ltbams-1.0.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.14
+Version: 1.0.15
 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.dist-info → ltbams-1.0.15.dist-info}/RECORD

@@ -1,6 +1,6 @@
 ams/__init__.py,sha256=q-9-f0YCg6aaTW19VCkY6VosfvRA2ObI9mF1f_3016Y,313
 ams/__main__.py,sha256=EB4GfGiKgvnQ_psNr0QwPoziYvjmGvQ2yVsBwQtfrLw,170
-ams/_version.py,sha256=BikZvXVZg-CCtVazeGNbDsJ_SnSEAX5lEIleKSitfVU,498
+ams/_version.py,sha256=Y9hMQAuHXt_45lOoYtSA44yQCwKbKuDs8CYDfeESO-k,498
 ams/cli.py,sha256=OuQc4xotv0dCgEIEaw-ZFEfDZvt1w9QQ9yjeaJiDe_s,6067
 ams/interface.py,sha256=wYqoh_rK4vHidJjWnE5VZHzonm4D-uCzZt0Z9oFBKVo,45233
 ams/main.py,sha256=OFbEtXEIuv-zSFccyN_1Mrg8XEn4TZTHXa3Ly-zbxmo,23559
@@ -61,7 +61,7 @@ ams/models/info.py,sha256=Oh0Xo5J4ZHBsNIkMOzIwv_DegsX1inyuv3Q5CpCfyQw,788
 ams/models/line.py,sha256=ju5h1BcW4kgVWm_lgl8zWhSYqlsUjbdoUwzz2t0Vx1s,2770
 ams/models/reserve.py,sha256=3BjWCyKrPL4CwTvmzRxk25H8Nkxh-Rz0Ne17I9Y2TUA,2816
 ams/models/shunt.py,sha256=h5QV33EcCd86XRR0sMIzcO0PTeTirkWaxi8imPKzOi0,337
-ams/models/timeslot.py,sha256=yTIezlphWLrnfelkd80yPfpqnx9VkhvUOvYy_TxH_KU,3057
+ams/models/timeslot.py,sha256=z_LDZZOjYFG_R_1jwBWSsLKsD-OoauWo027Z2J_JIMQ,3639
 ams/models/zone.py,sha256=-oOmPiMa8I7TzgheKEZOImXWv273ri6TURhmzy_ygkE,1089
 ams/models/distributed/__init__.py,sha256=3uiMHT2YRq79DXIB1jni6wP7dNoQMjU1bMTUpr4P6Rc,161
 ams/models/distributed/esd1.py,sha256=Ojqp_dJOJqa65u8kZ-oreA5cxruX2kXZ5AeNAAeYV7g,2136
@@ -74,7 +74,7 @@ ams/models/static/gen.py,sha256=QXklOYlnU7QHWy-WFJwhxuNItUPqFsLJIjAO4sGMUbg,7087
 ams/models/static/pq.py,sha256=SCwAqhqvKy_PFHp6VYO_zgv3v6gI5pK3KvT3RNX-nvA,2782
 ams/opt/__init__.py,sha256=INsl8yxtOzTKqV9pzVxlL6RSGDRaUDwxpZMY1QROrF4,459
 ams/opt/constraint.py,sha256=ERT9zwjQyGkvDo465Yd0wBexlIhjVmw0MyWq4BWnWoI,5534
-ams/opt/exprcalc.py,sha256=7io0vEZu5zqsEnetocasRT1tu7o7g0TXw7iJf2YFIxI,4317
+ams/opt/exprcalc.py,sha256=Dkopx7U5VnfeqN6VDAx1iqaF60dRxvHpNErnhZN1rm4,4422
 ams/opt/expression.py,sha256=WrWnYliB61uHA_wQjtYgtAXdpgSN1pNqQmWvzHWSsdE,5569
 ams/opt/objective.py,sha256=W0dQfW5dHNdWEc2DQtWYNGMuhMY6Pu-HTD0n7-izDZA,5519
 ams/opt/omodel.py,sha256=hEtfKoSNssSxHgUDdep79pifNTsywytDTjgGgne7nKM,12750
@@ -84,14 +84,14 @@ ams/opt/var.py,sha256=cpDiELo37E7IoTDlVn_NbkuFNQ88oey23YOF6Gpg6zM,7707
 ams/routines/__init__.py,sha256=V_IyEb5qLBrZ4zc_eVe-Rc0G_j-u881tvEzcEejhNv8,647
 ams/routines/acopf.py,sha256=dLVTh84KiBvLyG2auNsIfcufsl6N-9FcXWjpdYrQfYQ,208
 ams/routines/dcopf.py,sha256=QagOUPWgBIh9zhh2LQp7aZw0kx3n-JKtClVh7X3M-yI,11874
-ams/routines/dcopf2.py,sha256=4Q9qsgYmYgH7p9SB_0VXyFaDOOXxAS82ctbN_l-mILY,4146
-ams/routines/dcpf.py,sha256=lGZ9LmCL1DsFB-sNxI7NGrq0qd_iBRMDPJmU5022t20,8242
+ams/routines/dcopf2.py,sha256=GNXyydfVKRYx4gW_5mdWhnA2eDDYFSUGK-AuJnEC-fI,4899
+ams/routines/dcpf.py,sha256=qZ2MSOmn53lz2Q54Cy_tIZ3TSKYJuN1YQsQez1XRukQ,8384
 ams/routines/dopf.py,sha256=IRvkwYF80sYAPI0iUS5L6c2jChFT3vl8tELf7LA6V7Q,6275
 ams/routines/ed.py,sha256=-OpoWiTEMDC5dHcumJikKPsp7DoyfxQ0sRXjKhWQ6vE,11870
 ams/routines/grbopt.py,sha256=hEDy7L-lSd7QxSN_GAyDLaLkhIpxl6csXz6ntdKT_fw,5510
 ams/routines/pflow.py,sha256=vFnf61cYv7gWJSGqcQrMOaw-aOODd2eJMLpQ4aM1PQM,9438
 ams/routines/pypower.py,sha256=VnqMQZkBIvDe3tDbTJcxYz04idon5XvmGlf7OSs8kOI,27334
-ams/routines/routine.py,sha256=-8vsi6UVznz1_1S7yrmWLuu-DPfYxeBaTJlxp9QNE5k,39594
+ams/routines/routine.py,sha256=eDscTniBpFh9SZ8pTV1pmi-b_6JwL5OYOgiXmPUUNxE,39981
 ams/routines/rted.py,sha256=-5UOeEGx3ZOrF0FG0M0OUPP2tIfajQmKyZHTQ3c6kaE,22058
 ams/routines/type.py,sha256=lvTWSnCYIbRJXIm3HX6jA0Hv-WWYusTOUPfoW8DITlU,3877
 ams/routines/uc.py,sha256=L9LpwjoqKoUzIwYq-G-r1zRTMGfbaSWSwT8GZuf_nB0,15650
@@ -103,14 +103,14 @@ docs/make.bat,sha256=9UgKGb4SdP006622fJiFxeFT1BeycYAs6hDbV1xwPy8,804
 docs/source/api.rst,sha256=BRzdDFDzDwVL7Jr_Xj-O5Icgx0gt5hNNd1OjvPl7ap0,1490
 docs/source/conf.py,sha256=UyoWogZTUNSJU7pQS_JaR28nKddW94zr01LYoIciZZw,6688
 docs/source/genmodelref.py,sha256=IhmF7bDw8BXPvLD8V3WjQNrfc-H07r5iS-_4DHbbp-8,1420
-docs/source/genroutineref.py,sha256=bIdsE2eg7DO5IWbMlnj9B-zT_BdKrJycsveFLnJB4dE,1427
+docs/source/genroutineref.py,sha256=0Fac6ZPY0TVfRvunq-FY6iax-_N6EEcoeVXVZmkfV4k,2006
 docs/source/index.rst,sha256=oAdRBWTLCX8nEMVatfDFkn0dtvinOK7vg4QUekT4jns,2738
-docs/source/release-notes.rst,sha256=rwDneax-bHJsfRpjxidmOvfO3S0RTTGrQ3m6L7MsE6A,14397
+docs/source/release-notes.rst,sha256=tsSEDXGQGi9kH8-gnGb-SslytqfRFRto6iEJDgWyrXI,14709
 docs/source/_templates/autosummary/base.rst,sha256=zl3U4baR4a6YjsHyT-x9zCOrHwKZOVUdWn1NPX2u3bc,106
 docs/source/_templates/autosummary/class.rst,sha256=Hv_igCsLsUpM62_zN0nqj6FSfKnS5xLyu8ZldMbfOAk,668
 docs/source/_templates/autosummary/module.rst,sha256=YdbpCudOrEU-JbuSlzGvcOI2hn_KrCM6FW5HcGqkaEE,1113
 docs/source/_templates/autosummary/module_toctree.rst,sha256=sg30OdqFDLyo8Y3hl9V-s2BXb1bzcjjqqWaWi-C3qFM,1126
-docs/source/examples/index.rst,sha256=yXR54WHHcBY38-h9LkdTBcNq3HDeT6eSNyrMmafq12E,792
+docs/source/examples/index.rst,sha256=8nnW6jISleIz3IBWmqWtQcaOEdgMonY1UfWYs3NjTnM,830
 docs/source/getting_started/copyright.rst,sha256=d3S7FjrbysVqQd3pEBadrrkcQOZ7sYYeDTCOS4goPC8,715
 docs/source/getting_started/index.rst,sha256=mcp1NdUwbPoNzpn7Owf5Qzfd6J_--ToU52PjmrbwjBY,1512
 docs/source/getting_started/install.rst,sha256=pCL5GDNxwkWnrPaO48i9c0bBPT_dYAWvD2CQ7Oi2P_0,7400
@@ -135,8 +135,8 @@ docs/source/modeling/index.rst,sha256=TasRAJSglc5KAZaGAj9TLMktOO2TtzZsqG5WvvZXB_
 docs/source/modeling/model.rst,sha256=j7OSvoXnDht6rGpgwPiJklsCWrebfx4DxIN-G8r6iFo,7086
 docs/source/modeling/routine.rst,sha256=BkUE3y5L1lA7LP9Nyzc4zzY-tF3t4k7egBE188kybHY,4286
 docs/source/modeling/system.rst,sha256=NMOPNMOKG1_dRyNPPx-MiCKbbpadxWJxGyU6geRUsvQ,1374
-ltbams-1.0.14.dist-info/METADATA,sha256=zjk9Vm4fc4cSiPVp0GLN1em6xNJg4iazn59Y1CRHJx0,14199
-ltbams-1.0.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ltbams-1.0.14.dist-info/entry_points.txt,sha256=FA56FlhO_yVNeEf810SrorVQb7_Xsmo3_EW-W-ijUfA,37
-ltbams-1.0.14.dist-info/top_level.txt,sha256=5QQ_oDY9sa52MVmqCjqjUq07BssHOKmDSaQ8EZi6DOw,9
-ltbams-1.0.14.dist-info/RECORD,,
+ltbams-1.0.15.dist-info/METADATA,sha256=K6aLQwj_aKgX8n92MvowKSeKLlI72bAjR8rX-QOES0E,14333
+ltbams-1.0.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ltbams-1.0.15.dist-info/entry_points.txt,sha256=FA56FlhO_yVNeEf810SrorVQb7_Xsmo3_EW-W-ijUfA,37
+ltbams-1.0.15.dist-info/top_level.txt,sha256=5QQ_oDY9sa52MVmqCjqjUq07BssHOKmDSaQ8EZi6DOw,9
+ltbams-1.0.15.dist-info/RECORD,,