ltbams 0.9.9__tar.gz → 0.9.11__tar.gz

ltbams-0.9.11/CONTRIBUTING.rst

@@ -0,0 +1,102 @@
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every
+little bit helps, and credit will always be given.
+
+You can contribute in many ways:
+
+Types of Contributions
+----------------------
+
+Report Bugs
+~~~~~~~~~~~
+
+Report bugs at https://github.com/CURENT/ams/issues.
+
+If you are reporting a bug, please include:
+
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug"
+is open to whoever wants to implement it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with "feature"
+is open to whoever wants to implement it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+AMS could always use more documentation, whether
+as part of the official AMS docs, in docstrings,
+or even on the web in blog posts, articles, and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at https://github.com/CURENT/ams/issues.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute? Here's how to set up `ams` for local development.
+
+1. Fork the `ams` repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone git@github.com:your_name_here/ams.git
+
+3. Install your local copy into a virtualenv. Assuming you have virtualenv wrapper installed, this is how you
+set up your fork for local development::
+
+    $ mkvirtualenv ams
+    $ cd ams/
+    $ pip install -e .[dev]
+
+4. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+
+    $ flake8 ams tests
+    $ ams selftest
+
+
+6. Commit your changes and push your branch to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+7. Submit a pull request through the GitHub website.
+
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.rst.
+3. The pull request should work for Python 3.9 and up. Check
+   https://github.com/CURENT/ams/actions
+   and make sure that the tests pass for all supported Python versions.

{ltbams-0.9.9 → ltbams-0.9.11}/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.11/MANIFEST.in

@@ -0,0 +1,17 @@
+include CONTRIBUTING.rst
+include LICENSE
+include README.md
+include requirements.txt
+include requirements-extra.txt
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include ams/cases *.xlsx *.m *.raw *.dyr *.py *.json
+recursive-include docs *.rst *.png conf.py Makefile make.bat
+
+include versioneer.py
+include ams/_version.py
+
+# If including data files in the package, add them like:
+# include path/to/data_file

ltbams-0.9.11/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: ltbams
+Version: 0.9.11
+Summary: UNKNOWN
+Home-page: UNKNOWN
+License: UNKNOWN
+Platform: UNKNOWN
+License-File: LICENSE
+
+UNKNOWN
+

{ltbams-0.9.9 → ltbams-0.9.11}/README.md

@@ -4,11 +4,10 @@ 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/)
-[![HitCount](https://hits.dwyl.com/CURENT/ams.svg)](https://hits.dwyl.com/CURENT/ams)
 [![libraries](https://img.shields.io/librariesio/release/pypi/ltbams)](https://libraries.io/pypi/ltbams)
 [![Structure](https://img.shields.io/badge/code_base-visualize-blue)](https://mango-dune-07a8b7110.1.azurestaticapps.net/?repo=CURENT%2Fams)
 
@@ -60,8 +59,9 @@ Use the following resources to get involved.
 # Installation
 
 ***NOTE:***
-- ``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**.
+- Version **0.9.9** has known issues. Please avoid using this version
+- `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**
 
 AMS is released as ``ltbams`` on PyPI and conda-forge.
 Install from PyPI using pip:
@@ -82,6 +82,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.11/ams/__init__.py

@@ -0,0 +1,13 @@
+from . import _version
+__version__ = _version.get_versions()['version']
+
+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', 'System']

{ltbams-0.9.9 → ltbams-0.9.11}/ams/_version.py

@@ -1,5 +1,5 @@
 
-# This file was generated by 'versioneer.py' (0.29) from
+# This file was generated by 'versioneer.py' (0.22) from
 # revision-control system data, or from the parent directory name of an
 # unpacked source archive. Distribution tarballs contain a pre-generated copy
 # of this file.
@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-09-02T17:38:15-0400",
+ "date": "2024-11-14T16:34:57-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "0b3b3c26e50a763fbd1cb0daaca46b556a062396",
- "version": "0.9.9"
+ "full-revisionid": "9dcd290dc6532149fcd0b4f26fb5e9af4bf4bf36",
+ "version": "0.9.11"
 }
 '''  # END VERSION_JSON
 

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