ltbams 0.9.10__tar.gz → 0.9.12__tar.gz

{ltbams-0.9.10 → ltbams-0.9.12}/LICENSE

@@ -670,7 +670,7 @@ Also add information on how to contact you by electronic and paper mail.
   If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    AMS  Copyright (C) 2023 Jinning Wang
+    AMS  Copyright (C) 2023 - 2024 Jinning Wang
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ltbams
-Version: 0.9.10
+Version: 0.9.12
 Summary: Python software for scheduling modeling and co-simulation with dynanics.
 Home-page: https://github.com/CURENT/ams
 Author: Jinning Wang
@@ -14,21 +14,23 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 or later (G
 Classifier: Environment :: Console
 Description-Content-Type: text/markdown
 Provides-Extra: all
-Provides-Extra: coverage 
+Provides-Extra: coverage             
 Provides-Extra: dev
 Provides-Extra: doc
-Provides-Extra: flake8 
-Provides-Extra: ipython 
-Provides-Extra: myst-parser 
-Provides-Extra: nbsphinx 
-Provides-Extra: numpydoc 
-Provides-Extra: pydata-sphinx-theme 
-Provides-Extra: pyscipopt 
-Provides-Extra: pytest
-Provides-Extra: pytest-cov 
-Provides-Extra: sphinx 
-Provides-Extra: sphinx-copybutton 
-Provides-Extra: sphinx-panels 
+Provides-Extra: flake8               
+Provides-Extra: ipython              
+Provides-Extra: myst-parser          
+Provides-Extra: nbsphinx             
+Provides-Extra: numpydoc             
+Provides-Extra: pandoc               
+Provides-Extra: pydata-sphinx-theme  
+Provides-Extra: pyscipopt            
+Provides-Extra: pytest               
+Provides-Extra: pytest-cov           
+Provides-Extra: sphinx               
+Provides-Extra: sphinx-copybutton    
+Provides-Extra: sphinx-panels        
+Provides-Extra: toml                 
 License-File: LICENSE
 
 # LTB AMS
@@ -37,7 +39,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)](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-blue)](https://www.python.org/)
+[![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/)
 ![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/)
@@ -61,7 +63,12 @@ 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**.
+
+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.
@@ -92,7 +99,7 @@ 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**
 
@@ -115,6 +122,19 @@ Install from GitHub source:
 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
+
+ss = ams.load(ams.get_case('ieee14_uced.xlsx'))
+ss.RTED.run()
+
+print(ss.RTED.pg.v)
+```
+
 # Sponsors and Contributors
 AMS is the scheduling simulation engine for the CURENT Largescale Testbed (LTB).
 More information about CURENT LTB can be found at the [LTB Repository][LTB Repository].

{ltbams-0.9.10 → ltbams-0.9.12}/README.md

@@ -4,7 +4,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)](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-blue)](https://www.python.org/)
+[![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/)
 ![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 +28,12 @@ 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**.
+
+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,7 +64,7 @@ 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**
 
@@ -82,6 +87,19 @@ Install from GitHub source:
 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
+
+ss = ams.load(ams.get_case('ieee14_uced.xlsx'))
+ss.RTED.run()
+
+print(ss.RTED.pg.v)
+```
+
 # Sponsors and Contributors
 AMS is the scheduling simulation engine for the CURENT Largescale Testbed (LTB).
 More information about CURENT LTB can be found at the [LTB Repository][LTB Repository].

ltbams-0.9.12/ams/__init__.py

@@ -0,0 +1,14 @@
+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
+from ams.system import System  # NOQA
+from ams.utils.paths import get_case, list_cases  # NOQA
+from ams.shared import ppc2df  # NOQA
+
+__author__ = 'Jining Wang'
+
+__all__ = ['System', 'get_case']

{ltbams-0.9.10 → ltbams-0.9.12}/ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-09-03T22:41:38-0400",
+ "date": "2024-11-23T17:09:40-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "8bc9504a8281c16236c73decd8e7365b682c706c",
- "version": "0.9.10"
+ "full-revisionid": "377b36f113e1e88f8c2d21d3c6ab8ff3728cffb0",
+ "version": "0.9.12"
 }
 '''  # END VERSION_JSON
 

ltbams-0.9.12/ams/benchmarks.py

@@ -0,0 +1,302 @@
+"""
+Benchmark functions.
+"""
+
+import datetime
+import sys
+import importlib.metadata as importlib_metadata
+import logging
+
+try:
+    import pandapower as pdp
+    PANDAPOWER_AVAILABLE = True
+except ImportError:
+    PANDAPOWER_AVAILABLE = False
+    logging.warning("pandapower is not available. Some functionalities will be disabled.")
+
+from andes.utils.misc import elapsed
+
+import ams
+
+logger = logging.getLogger(__name__)
+
+_failed_time = -1
+_failed_obj = -1
+
+cols_pre = ['ams_mats', 'ams_parse', 'ams_eval', 'ams_final', 'ams_postinit']
+
+
+def get_tool_versions(tools=None):
+    """
+    Get the current time, Python version, and versions of specified tools.
+
+    Parameters
+    ----------
+    tools : list of str, optional
+        List of tool names to check versions. If None, a default list of tools is used.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the tool names and their versions.
+    """
+    if tools is None:
+        tools = ['ltbams', 'andes', 'cvxpy',
+                 'gurobipy', 'mosek', 'piqp',
+                 'pandapower', 'numba']
+
+    # Get current time and Python version
+    last_run_time = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    python_version = sys.version
+
+    # Collect tool versions
+    tool_versions = {}
+    for tool in tools:
+        try:
+            version = importlib_metadata.version(tool)
+            tool_versions[tool] = version
+        except importlib_metadata.PackageNotFoundError:
+            logger.error(f"Package {tool} not found.")
+            tool_versions[tool] = "Not installed"
+
+    # Print the results in a formatted way
+    logger.warning(f"Last run time: {last_run_time}")
+    logger.warning(f"Python: {python_version}\n")
+
+    # Calculate the width of the columns
+    max_tool_length = max(len(tool) for tool in tool_versions)
+    max_version_length = max(len(version) for version in tool_versions.values())
+
+    # Print the header
+    logger.warning(f"{'Tool':<{max_tool_length}}  {'Version':<{max_version_length}}")
+    logger.warning(f"{'-' * max_tool_length}  {'-' * max_version_length}")
+
+    # Print each tool and its version
+    for tool, version in tool_versions.items():
+        logger.warning(f"{tool:<{max_tool_length}}  {version:<{max_version_length}}")
+
+    return tool_versions
+
+
+def time_routine_solve(system, routine='DCOPF', **kwargs):
+    """
+    Run the specified routine with the given solver and method.
+
+    Parameters
+    ----------
+    system : ams.System
+        The system object containing the routine.
+    routine : str, optional
+        The name of the routine to run. Defaults to 'DCOPF'.
+
+    Other Parameters
+    ----------------
+    solver : str, optional
+        The solver to use.
+    ignore_dpp : bool, optional
+        Whether to ignore DPP. Defaults to True.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the elapsed time (s) and the objective value ($).
+    """
+    rtn = system.routines[routine]
+    solver = kwargs.get('solver', None)
+    try:
+        t, _ = elapsed()
+        rtn.run(**kwargs)
+        _, s0 = elapsed(t)
+        elapsed_time = float(s0.split(' ')[0])
+        obj_value = rtn.obj.v
+    except Exception as e:
+        logger.error(f"Error running routine {routine} with solver {solver}: {e}")
+        elapsed_time = _failed_time
+        obj_value = _failed_obj
+    return elapsed_time, obj_value
+
+
+def pre_solve(system, routine):
+    """
+    Time the routine preparation process.
+
+    Parameters
+    ----------
+    system : ams.System
+        The system object containing the routine.
+    routine : str
+        The name of the routine to prepare
+
+    Returns
+    -------
+    dict
+        A dictionary containing the preparation times in seconds for each step:
+        'mats', 'parse', 'evaluate', 'finalize', 'postinit'.
+    """
+    rtn = system.routines[routine]
+
+    # Initialize AMS
+    # --- matrices build ---
+    t_mats, _ = elapsed()
+    system.mats.build(force=True)
+    _, s_mats = elapsed(t_mats)
+
+    # --- code generation ---
+    t_parse, _ = elapsed()
+    rtn.om.parse(force=True)
+    _, s_parse = elapsed(t_parse)
+
+    # --- code evaluation ---
+    t_evaluate, _ = elapsed()
+    rtn.om.evaluate(force=True)
+    _, s_evaluate = elapsed(t_evaluate)
+
+    # --- problem finalization ---
+    t_finalize, _ = elapsed()
+    rtn.om.finalize(force=True)
+    _, s_finalize = elapsed(t_finalize)
+
+    # --- rest init process ---
+    t_postinit, _ = elapsed()
+    rtn.init()
+    _, s_postinit = elapsed(t_postinit)
+
+    s_float = [float(s.split(' ')[0]) for s in [s_mats, s_parse, s_evaluate, s_finalize, s_postinit]]
+
+    pre_time = dict(zip(cols_pre, s_float))
+    return pre_time
+
+
+def time_pdp_dcopf(ppn):
+    """
+    Test the execution time of DCOPF using pandapower.
+
+    Parameters
+    ----------
+    ppn : pandapowerNet
+        The pandapower network object.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the elapsed time (s) and the objective value ($).
+    """
+    try:
+        t_pdp, _ = elapsed()
+        pdp.rundcopp(ppn)
+        _, s_pdp = elapsed(t_pdp)
+        elapsed_time = float(s_pdp.split(' ')[0])
+        obj_value = ppn.res_cost
+    except Exception as e:
+        logger.error(f"Error running pandapower: {e}")
+        elapsed_time = _failed_time
+        obj_value = _failed_obj
+    return elapsed_time, obj_value
+
+
+def time_routine(system, routine='DCOPF', solvers=['CLARABEL'],
+                 **kwargs):
+    """
+    Time the specified routine with the given solvers.
+
+    Parameters
+    ----------
+    system : ams.System
+        The system object containing the routine.
+    routine : str, optional
+        The name of the routine to run. Defaults to 'DCOPF'.
+    solvers : list of str, optional
+        List of solvers to use. Defaults to ['CLARABEL'].
+
+    Other Parameters
+    ----------------
+    ignore_dpp : bool, optional
+        Whether to ignore DPP. Defaults to True.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the preparation times and the solution times in
+        seconds for each solver.
+    """
+    pre_time = pre_solve(system, routine)
+    sol = {f'{solver}': {'time': 0, 'obj': 0} for solver in solvers}
+
+    for solver in solvers:
+        if solver != 'pandapower':
+            s, obj = time_routine_solve(system, routine, solver=solver, **kwargs)
+            sol[solver]['time'] = s
+            sol[solver]['obj'] = obj
+        elif solver == 'pandapower' and PANDAPOWER_AVAILABLE and routine == 'DCOPF':
+            ppc = ams.io.pypower.system2ppc(system)
+            ppn = pdp.converter.from_ppc(ppc, f_hz=system.config.freq)
+            s, obj = time_pdp_dcopf(ppn)
+            sol[solver]['time'] = s
+            sol[solver]['obj'] = obj
+        else:
+            sol[solver]['time'] = _failed_time
+            sol[solver]['obj'] = _failed_obj
+
+    return pre_time, sol
+
+
+def time_dcopf_with_lf(system, solvers=['CLARABEL'], load_factors=[1], ignore_dpp=False):
+    """
+    Time the execution of DCOPF with varying load factors.
+
+    Parameters
+    ----------
+    system : ams.System
+        The system object containing the routine.
+    solvers : list of str, optional
+        List of solvers to use. Defaults to ['CLARABEL'].
+    load_factors : list of float, optional
+        List of load factors to apply. Defaults to None.
+    ignore_dpp : bool, optional
+        Whether to ignore DPP.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the list of times and the list of objective values.
+    """
+    pre_time = pre_solve(system, 'DCOPF')
+    sol = {f'{solver}': {'time': 0, 'obj': 0} for solver in solvers}
+
+    pd0 = system.PQ.p0.v.copy()
+    pq_idx = system.PQ.idx.v
+
+    for solver in solvers:
+        if solver != 'pandapower':
+            obj_all = 0
+            t_all, _ = elapsed()
+            for lf_k in load_factors:
+                system.PQ.set(src='p0', attr='v', idx=pq_idx, value=lf_k * pd0)
+                system.DCOPF.update(params=['pd'])
+                _, obj = time_routine_solve(system, 'DCOPF',
+                                            solver=solver, ignore_dpp=ignore_dpp)
+                obj_all += obj
+            _, s_all = elapsed(t_all)
+            system.PQ.set(src='p0', attr='v', idx=pq_idx, value=pd0)
+            s = float(s_all.split(' ')[0])
+            sol[solver]['time'] = s
+            sol[solver]['obj'] = obj_all
+        elif solver == 'pandapower' and PANDAPOWER_AVAILABLE:
+            ppc = ams.io.pypower.system2ppc(system)
+            ppn = pdp.converter.from_ppc(ppc, f_hz=system.config.freq)
+            p_mw0 = ppn.load['p_mw'].copy()
+            t_all, _ = elapsed()
+            obj_all = 0
+            for lf_k in load_factors:
+                ppn.load['p_mw'] = lf_k * p_mw0
+                _, obj = time_pdp_dcopf(ppn)
+                obj_all += obj
+            _, s_all = elapsed(t_all)
+            s = float(s_all.split(' ')[0])
+            sol[solver]['time'] = s
+            sol[solver]['obj'] = obj_all
+        else:
+            sol[solver]['time'] = _failed_time
+            sol[solver]['obj'] = _failed_obj
+
+    return pre_time, sol

{ltbams-0.9.10 → ltbams-0.9.12}/ams/cli.py

@@ -29,6 +29,12 @@ def create_parser():
     -------
     argparse.ArgumentParser
         Parser with all AMS options
+
+    Notes
+    -----
+    Revised from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     parser = argparse.ArgumentParser()

{ltbams-0.9.10 → ltbams-0.9.12}/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