ltbams 1.0.4__tar.gz → 1.0.5__tar.gz

{ltbams-1.0.4/ltbams.egg-info → ltbams-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.4
+Version: 1.0.5
 Summary: Python software for scheduling modeling and co-simulation with dynamics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -37,7 +37,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![codecov](https://codecov.io/gh/CURENT/ams/graph/badge.svg?token=RZI5GLLBQH)](https://codecov.io/gh/CURENT/ams)
 
-![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)
+[![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)](https://github.com/CURENT/ams/tags)
 ![GitHub commits since latest release (branch)](https://img.shields.io/github/commits-since/curent/ams/latest/develop)
 [![GitHub last commit (master)](https://img.shields.io/github/last-commit/CURENT/ams/master?label=last%20commit%20to%20master)](https://github.com/CURENT/ams/commits/master/)
 [![GitHub last commit (develop)](https://img.shields.io/github/last-commit/CURENT/ams/develop?label=last%20commit%20to%20develop)](https://github.com/CURENT/ams/commits/develop/)
@@ -152,7 +152,7 @@ pip install git+https://github.com/CURENT/ams.git
 - `cvxpy` is distributed with the open source solvers CLARABEL, OSQP, and SCS, but MIP-capable solvers need separate installation
 - `cvxpy` versions **below 1.5** are incompatible with `numpy` versions **2.0 and above**
 - If the solver `SCIP` encounters an import error caused by a missing `libscip.9.1.dylib`, try reinstalling its Python interface by running `pip install pyscipopt --no-binary scip --force`
-- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries
+- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries, more detailes can be found in this closed issue [Bug with dependency kvxopt 1.3.2.0](https://github.com/CURENT/andes/issues/508)
 - Versions **1.0.0** and **1.0.1** are only available on PyPI
 - Version **0.9.9** has known issues and has been yanked from PyPI
 

{ltbams-1.0.4 → ltbams-1.0.5}/README.md

@@ -9,7 +9,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![codecov](https://codecov.io/gh/CURENT/ams/graph/badge.svg?token=RZI5GLLBQH)](https://codecov.io/gh/CURENT/ams)
 
-![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)
+[![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)](https://github.com/CURENT/ams/tags)
 ![GitHub commits since latest release (branch)](https://img.shields.io/github/commits-since/curent/ams/latest/develop)
 [![GitHub last commit (master)](https://img.shields.io/github/last-commit/CURENT/ams/master?label=last%20commit%20to%20master)](https://github.com/CURENT/ams/commits/master/)
 [![GitHub last commit (develop)](https://img.shields.io/github/last-commit/CURENT/ams/develop?label=last%20commit%20to%20develop)](https://github.com/CURENT/ams/commits/develop/)
@@ -124,7 +124,7 @@ pip install git+https://github.com/CURENT/ams.git
 - `cvxpy` is distributed with the open source solvers CLARABEL, OSQP, and SCS, but MIP-capable solvers need separate installation
 - `cvxpy` versions **below 1.5** are incompatible with `numpy` versions **2.0 and above**
 - If the solver `SCIP` encounters an import error caused by a missing `libscip.9.1.dylib`, try reinstalling its Python interface by running `pip install pyscipopt --no-binary scip --force`
-- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries
+- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries, more detailes can be found in this closed issue [Bug with dependency kvxopt 1.3.2.0](https://github.com/CURENT/andes/issues/508)
 - Versions **1.0.0** and **1.0.1** are only available on PyPI
 - Version **0.9.9** has known issues and has been yanked from PyPI
 

{ltbams-1.0.4 → ltbams-1.0.5}/ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-04-05T23:02:48-0400",
+ "date": "2025-04-09T22:08:11-0400",
  "dirty": false,
  "error": null,
- "full-revisionid": "af7a4e10ba2e35c4180562cf62f69ba5523c6725",
- "version": "1.0.4"
+ "full-revisionid": "115b1575b21ff871fe878121b3ca1cb6020b1a93",
+ "version": "1.0.5"
 }
 '''  # END VERSION_JSON
 

{ltbams-1.0.4 → ltbams-1.0.5}/ams/opt/exprcalc.py

@@ -8,6 +8,8 @@ import re
 
 import numpy as np
 
+from ams.shared import sps  # NOQA
+
 import cvxpy as cp
 
 from ams.utils import pretty_long_message
@@ -68,7 +70,7 @@ class ExpressionCalc(OptzBase):
         msg = f" - Expression <{self.name}>: {self.code}"
         logger.debug(pretty_long_message(msg, _prefix, max_length=_max_length))
         try:
-            local_vars = {'self': self, 'np': np, 'cp': cp}
+            local_vars = {'self': self, 'np': np, 'cp': cp, 'sps': sps}
             self.optz = self._evaluate_expression(self.code, local_vars=local_vars)
         except Exception as e:
             raise Exception(f"Error in evaluating ExpressionCalc <{self.name}>.\n{e}")

{ltbams-1.0.4 → ltbams-1.0.5}/ams/routines/__init__.py

@@ -11,6 +11,7 @@ all_routines = OrderedDict([
     ('cpf', ['CPF']),
     ('acopf', ['ACOPF']),
     ('dcopf', ['DCOPF']),
+    ('dcopf2', ['DCOPF2']),
     ('ed', ['ED', 'EDDG', 'EDES']),
     ('rted', ['RTED', 'RTEDDG', 'RTEDES', 'RTEDVIS']),
     ('uc', ['UC', 'UCDG', 'UCES']),

{ltbams-1.0.4 → ltbams-1.0.5}/ams/routines/dcopf.py

@@ -19,7 +19,11 @@ class DCOPF(DCPFBase):
     """
     DC optimal power flow (DCOPF).
 
-    The nodal price is calculated as ``pi`` in ``pic``.
+    Notes
+    -----
+    1. The nodal price is calculated as ``pi`` in ``pic``.
+    1. Devices online status of `StaticGen`, `StaticLoad`, and `Shunt` are considered in the connectivity
+    matrices `Cft`, `Cg`, `Cl`, and `Csh`.
 
     References
     ----------
@@ -153,7 +157,7 @@ class DCOPF(DCPFBase):
         Parameters
         ----------
         kloss : float, optional
-            The loss factor for the conversion. Defaults to 1.2.
+            The loss factor for the conversion. Defaults to 1.0.
         """
         exec_time = self.exec_time
         if self.exec_time == 0 or self.exit_code != 0:

ltbams-1.0.5/ams/routines/dcopf2.py

@@ -0,0 +1,95 @@
+"""
+DCOPF routines.
+"""
+import logging
+
+import numpy as np
+from ams.core.param import RParam
+from ams.core.service import NumOp
+
+from ams.routines.dcopf import DCOPF
+from ams.opt import ExpressionCalc
+
+from ams.shared import sps
+
+
+logger = logging.getLogger(__name__)
+
+
+class DCOPF2(DCOPF):
+    """
+    DC optimal power flow (DCOPF) using PTDF.
+    For large cases, it is recommended to build the PTDF first, especially when incremental
+    build is necessary.
+
+    Notes
+    -----
+    1. This routine requires PTDF matrix.
+    1. Nodal price ``pi`` is calculated with three parts.
+    1. Bus angle ``aBus`` is calculated after solving the problem.
+    """
+
+    def __init__(self, system, config):
+        DCOPF.__init__(self, system, config)
+        self.info = 'DCOPF using PTDF'
+        self.type = 'DCED'
+
+        # NOTE: in this way, we still follow the implementation that devices
+        # connectivity status is considered in connection matrix
+        self.ued = NumOp(u=self.Cl,
+                         name='ued', tex_name=r'u_{e,d}',
+                         info='Effective load connection status',
+                         fun=np.sum, args=dict(axis=0),
+                         no_parse=True)
+        self.uesh = NumOp(u=self.Csh,
+                          name='uesh', tex_name=r'u_{e,sh}',
+                          info='Effective shunt connection status',
+                          fun=np.sum, args=dict(axis=0),
+                          no_parse=True)
+
+        self.PTDF = RParam(info='PTDF',
+                           name='PTDF', tex_name=r'P_{TDF}',
+                           model='mats', src='PTDF',
+                           no_parse=True, sparse=True)
+
+        # --- 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.pi.e_str = pi
+
+    def _post_solve(self):
+        """Calculate aBus"""
+        super()._post_solve()
+        sys = self.system
+        Pbus = sys.mats.Cg._v @ self.pg.v
+        Pbus -= sys.mats.Cl._v @ self.pd.v
+        Pbus -= sys.mats.Csh._v @ self.gsh.v
+        Pbus -= self.Pbusinj.v
+        aBus = sps.linalg.spsolve(sys.mats.Bbus._v, Pbus)
+        slack0_uid = sys.Bus.idx2uid(sys.Slack.bus.v[0])
+        self.aBus.v = aBus - aBus[slack0_uid]
+        return super()._post_solve()
+
+    def init(self, **kwargs):
+        if self.system.mats.PTDF._v is None:
+            logger.warning('PTDF is not available, build it now')
+            self.system.mats.build_ptdf()
+        return super().init(**kwargs)

{ltbams-1.0.4 → ltbams-1.0.5}/ams/routines/routine.py

@@ -585,6 +585,8 @@ class RoutineBase:
             True to rebuild the system matrices. Set to False to speed up the process
             if no system matrices are changed.
         """
+        if not self.initialized:
+            return self.init()
         t0, _ = elapsed()
         re_finalize = False
         # sanitize input

{ltbams-1.0.4 → ltbams-1.0.5}/docs/source/examples/index.rst

@@ -31,4 +31,5 @@ folder of the repository
 
    ../_examples/demo/demo_ESD1.ipynb
    ../_examples/demo/demo_AGC.ipynb
-   ../_examples/demo/demo_debug.ipynb
+   ../_examples/demo/demo_debug.ipynb
+   ../_examples/demo/demo_mat.ipynb

{ltbams-1.0.4 → ltbams-1.0.5}/docs/source/release-notes.rst

@@ -9,6 +9,13 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
+v1.0.5 (2024-04-09)
+--------------------
+
+- Include sensitivity matrices calculation demo in documentation
+- Add ``DCOPF2``, a PTDF-based DCOPF routine
+- Fix bug when update routine parameters before it is initialized
+
 v1.0.4 (2024-04-05)
 --------------------
 

{ltbams-1.0.4 → ltbams-1.0.5/ltbams.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltbams
-Version: 1.0.4
+Version: 1.0.5
 Summary: Python software for scheduling modeling and co-simulation with dynamics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -37,7 +37,7 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![codecov](https://codecov.io/gh/CURENT/ams/graph/badge.svg?token=RZI5GLLBQH)](https://codecov.io/gh/CURENT/ams)
 
-![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)
+[![GitHub Tag](https://img.shields.io/github/v/tag/CURENT/ams)](https://github.com/CURENT/ams/tags)
 ![GitHub commits since latest release (branch)](https://img.shields.io/github/commits-since/curent/ams/latest/develop)
 [![GitHub last commit (master)](https://img.shields.io/github/last-commit/CURENT/ams/master?label=last%20commit%20to%20master)](https://github.com/CURENT/ams/commits/master/)
 [![GitHub last commit (develop)](https://img.shields.io/github/last-commit/CURENT/ams/develop?label=last%20commit%20to%20develop)](https://github.com/CURENT/ams/commits/develop/)
@@ -152,7 +152,7 @@ pip install git+https://github.com/CURENT/ams.git
 - `cvxpy` is distributed with the open source solvers CLARABEL, OSQP, and SCS, but MIP-capable solvers need separate installation
 - `cvxpy` versions **below 1.5** are incompatible with `numpy` versions **2.0 and above**
 - If the solver `SCIP` encounters an import error caused by a missing `libscip.9.1.dylib`, try reinstalling its Python interface by running `pip install pyscipopt --no-binary scip --force`
-- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries
+- `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries, more detailes can be found in this closed issue [Bug with dependency kvxopt 1.3.2.0](https://github.com/CURENT/andes/issues/508)
 - Versions **1.0.0** and **1.0.1** are only available on PyPI
 - Version **0.9.9** has known issues and has been yanked from PyPI
 

{ltbams-1.0.4 → ltbams-1.0.5}/ltbams.egg-info/SOURCES.txt

@@ -116,6 +116,7 @@ ams/routines/__init__.py
 ams/routines/acopf.py
 ams/routines/cpf.py
 ams/routines/dcopf.py
+ams/routines/dcopf2.py
 ams/routines/dcpf.py
 ams/routines/dcpf0.py
 ams/routines/dopf.py
@@ -191,6 +192,7 @@ tests/test_report.py
 tests/test_repr.py
 tests/test_routine.py
 tests/test_rtn_dcopf.py
+tests/test_rtn_dcopf2.py
 tests/test_rtn_dcpf.py
 tests/test_rtn_ed.py
 tests/test_rtn_pflow.py

ltbams-1.0.5/tests/test_rtn_dcopf2.py

@@ -0,0 +1,103 @@
+import unittest
+import numpy as np
+
+import ams
+
+
+class TestDCOPF2(unittest.TestCase):
+    """
+    Test routine `DCOPF2`.
+    """
+
+    def setUp(self) -> None:
+        self.ss = ams.load(ams.get_case("5bus/pjm5bus_demo.xlsx"),
+                           setup=True, default_config=True, no_output=True)
+        # decrease load first
+        self.ss.PQ.set(src='p0', attr='v', idx=['PQ_1', 'PQ_2'], value=[0.3, 0.3])
+        # build PTDF
+        self.ss.mats.build_ptdf()
+
+    def test_init(self):
+        """
+        Test initialization.
+        """
+        self.ss.DCOPF2.init()
+        self.assertTrue(self.ss.DCOPF2.initialized, "DCOPF2 initialization failed!")
+
+    def test_trip_gen(self):
+        """
+        Test generator tripping.
+        """
+        stg = 'PV_1'
+        self.ss.StaticGen.set(src='u', idx=stg, attr='v', value=0)
+
+        self.ss.DCOPF2.update()
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        self.assertTrue(self.ss.DCOPF2.converged, "DCOPF2 did not converge under generator trip!")
+        self.assertAlmostEqual(self.ss.DCOPF2.get(src='pg', attr='v', idx=stg),
+                               0, places=6,
+                               msg="Generator trip does not take effect!")
+
+        self.ss.StaticGen.set(src='u', idx=stg, attr='v', value=1)  # reset
+
+    def test_trip_line(self):
+        """
+        Test line tripping.
+        """
+        self.ss.Line.set(src='u', attr='v', idx='Line_3', value=0)
+
+        self.ss.DCOPF2.update()
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        self.assertTrue(self.ss.DCOPF2.converged, "DCOPF2 did not converge under line trip!")
+        self.assertAlmostEqual(self.ss.DCOPF2.get(src='plf', attr='v', idx='Line_3'),
+                               0, places=6,
+                               msg="Line trip does not take effect!")
+
+        self.ss.Line.alter(src='u', idx='Line_3', value=1)  # reset
+
+    def test_set_load(self):
+        """
+        Test setting and tripping load.
+        """
+        # --- run DCOPF2 ---
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        pgs = self.ss.DCOPF2.pg.v.sum()
+
+        # --- set load ---
+        self.ss.PQ.set(src='p0', attr='v', idx='PQ_1', value=0.1)
+        self.ss.DCOPF2.update()
+
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        pgs_pqt = self.ss.DCOPF2.pg.v.sum()
+        self.assertLess(pgs_pqt, pgs, "Load set does not take effect!")
+
+        # --- trip load ---
+        self.ss.PQ.set(src='u', attr='v', idx='PQ_2', value=0)
+        self.ss.DCOPF2.update()
+
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        pgs_pqt2 = self.ss.DCOPF2.pg.v.sum()
+        self.assertLess(pgs_pqt2, pgs_pqt, "Load trip does not take effect!")
+
+    def test_dc2ac(self):
+        """
+        Test `DCOPF2.dc2ac()` method.
+        """
+        self.ss.DCOPF2.run(solver='CLARABEL')
+        self.ss.DCOPF2.dc2ac()
+        self.assertTrue(self.ss.DCOPF2.converted, "AC conversion failed!")
+        self.assertTrue(self.ss.DCOPF2.exec_time > 0, "Execution time is not greater than 0.")
+
+        stg_idx = self.ss.StaticGen.get_all_idxes()
+        pg_dcopf = self.ss.DCOPF2.get(src='pg', attr='v', idx=stg_idx)
+        pg_acopf = self.ss.ACOPF.get(src='pg', attr='v', idx=stg_idx)
+        np.testing.assert_almost_equal(pg_dcopf, pg_acopf, decimal=3)
+
+        bus_idx = self.ss.Bus.get_all_idxes()
+        v_dcopf = self.ss.DCOPF2.get(src='vBus', attr='v', idx=bus_idx)
+        v_acopf = self.ss.ACOPF.get(src='vBus', attr='v', idx=bus_idx)
+        np.testing.assert_almost_equal(v_dcopf, v_acopf, decimal=3)
+
+        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)