ltbams 0.9.12rc1__tar.gz → 0.9.13__tar.gz

{ltbams-0.9.12rc1/ltbams.egg-info → ltbams-0.9.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ltbams
-Version: 0.9.12rc1
+Version: 0.9.13
 Summary: Python software for scheduling modeling and co-simulation with dynanics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -35,11 +35,12 @@ License-File: LICENSE
 
 # LTB AMS
 
-Python Software for Power System Scheduling Modeling and Co-Simulation with Dynanic, serving as the market simulator for the [CURENT Largescale Testbed][LTB Repository].
+Python Software for Power System Scheduling Modeling and Co-Simulation with Dynamics, serving as the market simulator for the [CURENT Largescale Testbed][LTB Repository].
 
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://github.com/CURENT/ams/blob/master/LICENSE)
 ![platforms](https://anaconda.org/conda-forge/ltbams/badges/platforms.svg)
 [![Python Versions](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![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)
 ![Repo Size](https://img.shields.io/github/repo-size/CURENT/ams)
 [![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/)
@@ -63,7 +64,16 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 
 # Why AMS
 
-With the built-in interface with dynamic simulation engine, ANDES, AMS enables Dynamics Interfaced Stability Constrained Production Cost and Market Operation Modeling.
+With the built-in interface with ANDES, AMS enables **Dynamics Incorporated**
+**Stability-Constrained Scheduling**.
+
+This package can be helpful for power system engineers, researchers, and students
+who need to conduct scheduling studies and transient stability studies at given
+operating points.
+
+AMS is a **Modeling Framework** that provides a descriptive way to formulate
+scheduling problems. The optimization problems are then handled by **CVXPY**
+and solved with third-party solvers.
 
 AMS produces credible scheduling results and competitive performance.
 The following results show the comparison of DCOPF between AMS and other tools.
@@ -94,9 +104,10 @@ Use the following resources to get involved.
 # Installation
 
 ***NOTE:***
-- Version **0.9.9** has known issues. Please avoid using this version
+- Version **0.9.9** has known issues and has been yanked from PyPI
 - `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries
 - `cvxpy` versions **below 1.5** are incompatible with `numpy` versions **2.0 and above**
+- If solver `SCIP` run into import error, try to reinstall its Python interface by running `pip install pyscipopt --no-binary scip --force`
 
 AMS is released as ``ltbams`` on PyPI and conda-forge.
 Install from PyPI using pip:
@@ -119,15 +130,23 @@ pip install git+https://github.com/CURENT/ams.git
 
 # Example Usage
 
-Using AMS to run a Real-Time Economic Dispatch (RTED) simulation:
-
 ```python
 import ams
+import andes
+
+ss = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'))
+
+# solve RTED
+ss.RTED.run(solver='CLARABEL')
 
-ss = ams.load(ams.get_case('ieee14_uced.xlsx'))
-ss.RTED.run()
+ss.RTED.pg.v
+>>> array([1.8743862, 0.3226138, 0.01     , 0.02     , 0.01     ])
 
-print(ss.RTED.pg.v)
+# convert to ANDES case
+sa = ss.to_andes(addfile=andes.get_case('ieee14/ieee14_full.xlsx'),
+                 setup=True, verify=False)
+sa
+>>> <andes.system.System at 0x14bd98190>
 ```
 
 # Sponsors and Contributors

{ltbams-0.9.12rc1 → ltbams-0.9.13}/README.md

@@ -1,10 +1,11 @@
 # LTB AMS
 
-Python Software for Power System Scheduling Modeling and Co-Simulation with Dynanic, serving as the market simulator for the [CURENT Largescale Testbed][LTB Repository].
+Python Software for Power System Scheduling Modeling and Co-Simulation with Dynamics, serving as the market simulator for the [CURENT Largescale Testbed][LTB Repository].
 
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://github.com/CURENT/ams/blob/master/LICENSE)
 ![platforms](https://anaconda.org/conda-forge/ltbams/badges/platforms.svg)
 [![Python Versions](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![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)
 ![Repo Size](https://img.shields.io/github/repo-size/CURENT/ams)
 [![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/)
@@ -28,7 +29,16 @@ Python Software for Power System Scheduling Modeling and Co-Simulation with Dyna
 
 # Why AMS
 
-With the built-in interface with dynamic simulation engine, ANDES, AMS enables Dynamics Interfaced Stability Constrained Production Cost and Market Operation Modeling.
+With the built-in interface with ANDES, AMS enables **Dynamics Incorporated**
+**Stability-Constrained Scheduling**.
+
+This package can be helpful for power system engineers, researchers, and students
+who need to conduct scheduling studies and transient stability studies at given
+operating points.
+
+AMS is a **Modeling Framework** that provides a descriptive way to formulate
+scheduling problems. The optimization problems are then handled by **CVXPY**
+and solved with third-party solvers.
 
 AMS produces credible scheduling results and competitive performance.
 The following results show the comparison of DCOPF between AMS and other tools.
@@ -59,9 +69,10 @@ Use the following resources to get involved.
 # Installation
 
 ***NOTE:***
-- Version **0.9.9** has known issues. Please avoid using this version
+- Version **0.9.9** has known issues and has been yanked from PyPI
 - `kvxopt` is recommended to install via `conda` as sometimes ``pip`` struggles to set the correct path for compiled libraries
 - `cvxpy` versions **below 1.5** are incompatible with `numpy` versions **2.0 and above**
+- If solver `SCIP` run into import error, try to reinstall its Python interface by running `pip install pyscipopt --no-binary scip --force`
 
 AMS is released as ``ltbams`` on PyPI and conda-forge.
 Install from PyPI using pip:
@@ -84,15 +95,23 @@ pip install git+https://github.com/CURENT/ams.git
 
 # Example Usage
 
-Using AMS to run a Real-Time Economic Dispatch (RTED) simulation:
-
 ```python
 import ams
+import andes
+
+ss = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'))
+
+# solve RTED
+ss.RTED.run(solver='CLARABEL')
 
-ss = ams.load(ams.get_case('ieee14_uced.xlsx'))
-ss.RTED.run()
+ss.RTED.pg.v
+>>> array([1.8743862, 0.3226138, 0.01     , 0.02     , 0.01     ])
 
-print(ss.RTED.pg.v)
+# convert to ANDES case
+sa = ss.to_andes(addfile=andes.get_case('ieee14/ieee14_full.xlsx'),
+                 setup=True, verify=False)
+sa
+>>> <andes.system.System at 0x14bd98190>
 ```
 
 # Sponsors and Contributors

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/__init__.py

@@ -1,6 +1,7 @@
 from . import _version
 __version__ = _version.get_versions()['version']
 
+from ams import opt  # NOQA
 from ams import benchmarks  # NOQA
 
 from ams.main import config_logger, load, run  # NOQA
@@ -10,4 +11,4 @@ from ams.shared import ppc2df  # NOQA
 
 __author__ = 'Jining Wang'
 
-__all__ = ['System', 'get_case', 'System']
+__all__ = ['System', 'get_case']

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-11-14T17:13:01-0500",
+ "date": "2024-12-05T16:49:45-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "45fb4203850186bec30f88e946f06a972e8de216",
- "version": "0.9.12rc1"
+ "full-revisionid": "db9279e8765429827062032b803c756025c018b2",
+ "version": "0.9.13"
 }
 '''  # END VERSION_JSON
 

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/core/documenter.py

@@ -223,9 +223,10 @@ class RDocumenter:
         # add tables
         self.parent.syms.generate_symbols()
         out += self._obj_doc(max_width=max_width, export=export)
-        out += self._constr_doc(max_width=max_width, export=export)
         out += self._expr_doc(max_width=max_width, export=export)
+        out += self._constr_doc(max_width=max_width, export=export)
         out += self._var_doc(max_width=max_width, export=export)
+        out += self._exprc_doc(max_width=max_width, export=export)
         out += self._service_doc(max_width=max_width, export=export)
         out += self._param_doc(max_width=max_width, export=export)
         out += self.config.doc(max_width=max_width, export=export)
@@ -316,17 +317,26 @@ class RDocumenter:
                               rest_dict=rest_dict)
 
     def _expr_doc(self, max_width=78, export='plain'):
-        # expression documentation
+        # Expression documentation
         if len(self.parent.exprs) == 0:
             return ''
 
         # prepare temporary lists
-        names, var_names, info = list(), list(), list()
+        names, info = list(), list()
+        units, sources, units_rest = list(), list(), list()
 
         for p in self.parent.exprs.values():
             names.append(p.name)
-            var_names.append(p.var)
             info.append(p.info if p.info else '')
+            units.append(p.unit if p.unit else '')
+            units_rest.append(f'*{p.unit}*' if p.unit else '')
+
+            slist = []
+            if p.owner is not None and p.src is not None:
+                slist.append(f'{p.owner.class_name}.{p.src}')
+            elif p.owner is not None and p.src is None:
+                slist.append(f'{p.owner.class_name}')
+            sources.append(','.join(slist))
 
         # expressions based on output format
         expressions = []
@@ -342,13 +352,67 @@ class RDocumenter:
         expressions = math_wrap(expressions, export=export)
 
         plain_dict = OrderedDict([('Name', names),
-                                  ('Variable', var_names),
                                   ('Description', info),
+                                  ('Unit', units),
+                                  ])
+        rest_dict = OrderedDict([('Name', names),
+                                 ('Description', info),
+                                 ('Expression', expressions),
+                                 ('Unit', units_rest),
+                                 ('Source', sources),
+                                 ])
+
+        # convert to rows and export as table
+        return make_doc_table(title=title,
+                              max_width=max_width,
+                              export=export,
+                              plain_dict=plain_dict,
+                              rest_dict=rest_dict)
+
+    def _exprc_doc(self, max_width=78, export='plain'):
+        # ExpressionCalc documentation
+        if len(self.parent.exprcs) == 0:
+            return ''
+
+        # prepare temporary lists
+        names, info = list(), list()
+        units, sources, units_rest = list(), list(), list()
+
+        for p in self.parent.exprcs.values():
+            names.append(p.name)
+            info.append(p.info if p.info else '')
+            units.append(p.unit if p.unit else '')
+            units_rest.append(f'*{p.unit}*' if p.unit else '')
+
+            slist = []
+            if p.owner is not None and p.src is not None:
+                slist.append(f'{p.owner.class_name}.{p.src}')
+            elif p.owner is not None and p.src is None:
+                slist.append(f'{p.owner.class_name}')
+            sources.append(','.join(slist))
+
+        # expressions based on output format
+        expressions = []
+        if export == 'rest':
+            for p in self.parent.exprcs.values():
+                expr = _tex_pre(self, p, self.parent.syms.tex_map)
+                logger.debug(f'{p.name} math: {expr}')
+                expressions.append(expr)
+
+            title = 'ExpressionCalcs\n----------------------------------'
+        else:
+            title = 'ExpressionCalcs'
+        expressions = math_wrap(expressions, export=export)
+
+        plain_dict = OrderedDict([('Name', names),
+                                  ('Description', info),
+                                  ('Unit', units),
                                   ])
         rest_dict = OrderedDict([('Name', names),
-                                 ('Variable', var_names),
                                  ('Description', info),
                                  ('Expression', expressions),
+                                 ('Unit', units_rest),
+                                 ('Source', sources),
                                  ])
 
         # convert to rows and export as table
@@ -423,6 +487,8 @@ class RDocumenter:
             slist = []
             if p.owner is not None and p.src is not None:
                 slist.append(f'{p.owner.class_name}.{p.src}')
+            elif p.owner is not None and p.src is None:
+                slist.append(f'{p.owner.class_name}')
             sources.append(','.join(slist))
 
         # symbols based on output format
@@ -490,6 +556,8 @@ class RDocumenter:
             slist = []
             if p.owner is not None and p.src is not None:
                 slist.append(f'{p.owner.class_name}.{p.src}')
+            elif p.owner is not None and p.src is None:
+                slist.append(f'{p.owner.class_name}')
             sources.append(','.join(slist))
 
         # symbols based on output format

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/core/matprocessor.py

@@ -13,7 +13,7 @@ from andes.thirdparty.npfunc import safe_div
 from andes.shared import tqdm, tqdm_nb
 from andes.utils.misc import elapsed, is_notebook
 
-from ams.opt.omodel import Param
+from ams.opt import Param
 from ams.shared import pd, sps
 
 logger = logging.getLogger(__name__)
@@ -140,7 +140,9 @@ class MParam(Param):
 
 class MatProcessor:
     """
-    Class for matrix processing in AMS system.
+    Class for matrices processing in AMS system.
+    The connectivity matrices `Cft`, `Cg`, `Cl`, and `Csh` ***have taken*** the
+    devices connectivity into account.
 
     The MParams' row names and col names are assigned in `System.setup()`.
     """

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/core/param.py

@@ -10,7 +10,7 @@ from typing import Optional, Iterable
 import numpy as np
 from scipy.sparse import issparse
 
-from ams.opt.omodel import Param
+from ams.opt import Param
 
 logger = logging.getLogger(__name__)
 

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/core/service.py

@@ -10,7 +10,7 @@ import scipy.sparse as spr
 
 from andes.core.service import BaseService
 
-from ams.opt.omodel import Param
+from ams.opt import Param
 
 
 logger = logging.getLogger(__name__)
@@ -33,8 +33,6 @@ class RBaseService(BaseService, Param):
         Description.
     vtype : Type, optional
         Variable type.
-    model : str, optional
-        Model name.
     no_parse: bool, optional
         True to skip parsing the service.
     sparse: bool, optional
@@ -106,8 +104,8 @@ class ValueService(RBaseService):
         Description.
     vtype : Type, optional
         Variable type.
-    model : str, optional
-        Model name.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -155,8 +153,8 @@ class ROperationService(RBaseService):
         Description.
     vtype : Type, optional
         Variable type.
-    model : str, optional
-        Model name.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -194,6 +192,8 @@ class LoadScale(ROperationService):
         Unit.
     info : str, optional
         Description.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -236,7 +236,7 @@ class NumOp(ROperationService):
 
     Note that the scalar output is converted to a 1D array.
 
-    The optional kwargs are passed to the input function.
+    The `rargs` are passed to the input function.
 
     Parameters
     ----------
@@ -397,8 +397,6 @@ class NumOpDual(NumOp):
         Description.
     vtype : Type, optional
         Variable type.
-    model : str, optional
-        Model name.
     rfun : Callable, optional
         Function to apply to the output of ``fun``.
     rargs : dict, optional
@@ -407,6 +405,8 @@ class NumOpDual(NumOp):
         Expand the dimensions of the output array along a specified axis.
     array_out : bool, optional
         Whether to force the output to be an array.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -467,6 +467,10 @@ class MinDur(NumOpDual):
         Unit.
     info : str, optional
         Description.
+    vtype : Type, optional
+        Variable type.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -537,8 +541,12 @@ class NumHstack(NumOp):
         Description.
     vtype : Type, optional
         Variable type.
-    model : str, optional
-        Model name.
+    rfun : Callable, optional
+        Function to apply to the output of ``fun``.
+    rargs : dict, optional
+        Keyword arguments to pass to ``rfun``.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -624,8 +632,12 @@ class ZonalSum(NumOp):
         Description.
     vtype : Type
         Variable type.
-    model : str
-        Model name.
+    rfun : Callable, optional
+        Function to apply to the output of ``fun``.
+    rargs : dict, optional
+        Keyword arguments to pass to ``rfun``.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -676,7 +688,7 @@ class VarSelect(NumOp):
     A numerical matrix to select a subset of a 2D variable,
     ``u.v[:, idx]``.
 
-    For example, if nned to select Energy Storage output
+    For example, if need to select Energy Storage output
     power from StaticGen `pg`, following definition can be used:
     ```python
     class RTED:
@@ -709,6 +721,8 @@ class VarSelect(NumOp):
         Keyword arguments to pass to ``rfun``.
     array_out : bool, optional
         Whether to force the output to be an array.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -790,7 +804,7 @@ class VarReduction(NumOp):
     u : Callable
         The input matrix variable.
     fun : Callable
-        The reduction function that takes a shape parameter (1D shape) as input.
+        The reduction function that takes a shape argument (1D shape) as input.
     name : str, optional
         The name of the instance.
     tex_name : str, optional
@@ -801,8 +815,12 @@ class VarReduction(NumOp):
         A description of the operation.
     vtype : Type, optional
         The variable type.
-    model : str, optional
-        The model name associated with the operation.
+    rfun : Callable, optional
+        Function to apply to the output of ``fun``.
+    rargs : dict, optional
+        Keyword arguments to pass to ``rfun``.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """
@@ -818,13 +836,11 @@ class VarReduction(NumOp):
                  rfun: Callable = None,
                  rargs: dict = None,
                  no_parse: bool = False,
-                 sparse: bool = False,
-                 **kwargs):
+                 sparse: bool = False,):
         super().__init__(name=name, tex_name=tex_name, unit=unit,
                          info=info, vtype=vtype,
                          u=u, fun=None, rfun=rfun, rargs=rargs,
-                         no_parse=no_parse, sparse=sparse,
-                         **kwargs)
+                         no_parse=no_parse, sparse=sparse,)
         self.fun = fun
 
     @property
@@ -859,8 +875,12 @@ class RampSub(NumOp):
         Description.
     vtype : Type
         Variable type.
-    model : str
-        Model name.
+    rfun : Callable, optional
+        Function to apply to the output of ``fun``.
+    rargs : dict, optional
+        Keyword arguments to pass to ``rfun``.
+    no_parse: bool, optional
+        True to skip parsing the service.
     sparse: bool, optional
         True to return output as scipy csr_matrix.
     """

{ltbams-0.9.12rc1 → ltbams-0.9.13}/ams/core/symprocessor.py

@@ -89,6 +89,9 @@ class SymProcessor:
             (r'(== 0|<= 0)$', ''),  # remove the comparison operator
             (r'cp\.(Minimize|Maximize)', r'float'),  # remove cp.Minimize/Maximize
             (r'\bcp.\b', 'np.'),
+            (r'\bexp\b', 'np.exp'),
+            (r'\blog\b', 'np.log'),
+            (r'\bconj\b', 'np.conj'),
         ])
 
         self.status = {
@@ -124,9 +127,7 @@ class SymProcessor:
 
         # Vars
         for vname, var in self.parent.vars.items():
-            tmp = sp.symbols(f'{var.name}')
-            # tmp = sp.symbols(var.name)
-            self.inputs_dict[vname] = tmp
+            self.inputs_dict[vname] = sp.symbols(f'{vname}')
             self.sub_map[rf"\b{vname}\b"] = f"self.om.{vname}"
             self.tex_map[rf"\b{vname}\b"] = rf'{var.tex_name}'
             self.val_map[rf"\b{vname}\b"] = f"rtn.{vname}.v"
@@ -163,6 +164,13 @@ class SymProcessor:
             if not service.no_parse:
                 self.val_map[rf"\b{sname}\b"] = f"rtn.{sname}.v"
 
+        # Expressions
+        for ename, expr in self.parent.exprs.items():
+            self.inputs_dict[ename] = sp.symbols(f'{ename}')
+            self.sub_map[rf"\b{ename}\b"] = f"self.om.{ename}"
+            self.val_map[rf"\b{ename}\b"] = f"rtn.{ename}.v"
+            self.tex_map[rf"\b{ename}\b"] = f'{expr.tex_name}'
+
         # Constraints
         # NOTE: constraints are included in sub_map for ExpressionCalc
         # thus, they don't have the suffix `.v`