ltbams 1.0.9__py3-none-any.whl → 1.0.11__py3-none-any.whl

ams/shared.py

@@ -6,7 +6,6 @@ This module is supplementary to the ``andes.shared`` module.
 import logging
 import unittest
 from functools import wraps
-from collections import OrderedDict
 from time import strftime
 
 import cvxpy as cp
@@ -21,10 +20,16 @@ logger = logging.getLogger(__name__)
 sps = LazyImport('import scipy.sparse as sps')
 np = LazyImport('import numpy as np')
 pd = LazyImport('import pandas as pd')
+ppoption = LazyImport('from pypower.ppoption import ppoption')
+runpf = LazyImport('from pypower.runpf import runpf')
+runopf = LazyImport('from pypower.runopf import runopf')
+opf = LazyImport('from gurobi_optimods import opf')
 
 # --- an empty ANDES system ---
 empty_adsys = adSystem(autogen_stale=False)
 ad_models = list(empty_adsys.models.keys())
+ad_pf_models = [mname for mname, model in empty_adsys.models.items() if model.flags.pflow]
+ad_dyn_models = [mname for mname, model in empty_adsys.models.items() if model.flags.tds and not model.flags.pflow]
 
 # --- NumPy constants ---
 # NOTE: In NumPy 2.0, np.Inf and np.NaN are deprecated.
@@ -105,49 +110,27 @@ def skip_unittest_without_MISOCP(f):
     return wrapper
 
 
-ppc_cols = OrderedDict([
-    ('bus', ['bus_i', 'type', 'pd', 'qd', 'gs', 'bs', 'area', 'vm', 'va',
-             'baseKV', 'zone', 'vmax', 'vmin', 'lam_p', 'lam_q',
-             'mu_vmax', 'mu_vmin']),
-    ('branch', ['fbus', 'tbus', 'r', 'x', 'b', 'rate_a', 'rateB_b', 'rate_c',
-                'tap', 'shift', 'status', 'angmin',
-                'angmax', 'pf', 'qf', 'pt', 'qt', 'mu_sf', 'mu_st',
-                'mu_angmin', 'mu_angmax']),
-    ('gen', ['bus', 'pg', 'qg', 'qmax', 'qmin', 'vg', 'mbase', 'status',
-             'pmax', 'pmin', 'pc1', 'pc2', 'qc1min', 'qc1max', 'qc2min',
-             'qc2max', 'ramp_agc', 'ramp_10', 'ramp_30', 'ramp_q',
-             'apf', 'mu_pmax', 'mu_pmin', 'mu_qmax', 'mu_qmin']),
-    ('gencost', ['model', 'startup', 'shutdown', 'n', 'c2', 'c1', 'c0']),
-])
+def skip_unittest_without_PYPOWER(f):
+    """
+    Decorator for skipping tests that require PYPOWER.
+    """
+    def wrapper(*args, **kwargs):
+        try:
+            import pypower  # NOQA
+        except ImportError:
+            raise unittest.SkipTest("PYPOWER is not installed.")
+        return f(*args, **kwargs)
+    return wrapper
 
 
-def ppc2df(ppc, model='bus', ppc_cols=ppc_cols):
+def skip_unittest_without_gurobi_optimods(f):
     """
-    Convert PYPOWER dict to pandas DataFrame.
-
-    Parameters
-    ----------
-    ppc : dict
-        PYPOWER case dict.
-    model : str
-        Model name.
-    ppc_cols : dict
-        Column names.
-
-    Returns
-    -------
-    pandas.DataFrame
-        DataFrame.
-
-    Examples
-    --------
-    >>> import ams
-    >>> sp = ams.system.example()
-    >>> ppc = ams.io.pypower.system2ppc(sp)
-    >>> ppc_bus = ams.shared.ppc2df(ppc, 'bus')
+    Decorator for skipping tests that require gurobi_optimods.
     """
-    if model not in ppc_cols.keys():
-        raise ValueError(f"Invalid model {model}")
-
-    df = pd.DataFrame(ppc[model], columns=ppc_cols[model][0:ppc[model].shape[1]])
-    return df
+    def wrapper(*args, **kwargs):
+        try:
+            import gurobi_optimods  # NOQA
+        except ImportError:
+            raise unittest.SkipTest("Gurobi is not installed.")
+        return f(*args, **kwargs)
+    return wrapper

ams/system.py

@@ -9,8 +9,7 @@ from typing import Dict, Optional
 
 import numpy as np
 
-from andes.core import Config
-from andes.system import System as andes_System
+from andes.system import System as adSystem
 from andes.system import (_config_numpy, load_config_rc)
 from andes.variables import FileMan
 
@@ -23,9 +22,17 @@ from ams.routines.type import TypeBase
 from ams.models import file_classes
 from ams.routines import all_routines
 from ams.utils.paths import get_config_path
+from ams.core import Config
 from ams.core.matprocessor import MatProcessor
 from ams.interface import to_andes
 from ams.report import Report
+from ams.shared import ad_dyn_models
+
+from ams.io.matpower import system2mpc
+from ams.io.matpower import write as wrtite_m
+from ams.io.xlsx import write as write_xlsx
+from ams.io.json import write as write_json
+from ams.io.psse import write_raw
 
 logger = logging.getLogger(__name__)
 
@@ -42,7 +49,7 @@ def disable_methods(methods):
         setattr(System, method, disable_method(getattr(System, method)))
 
 
-class System(andes_System):
+class System(adSystem):
     """
     A subclass of ``andes.system.System``, this class encapsulates data, models,
     and routines for scheduling modeling and analysis in power systems.
@@ -389,6 +396,43 @@ class System(andes_System):
         self.is_setup = False
         self.setup()
 
+    def add(self, model, param_dict=None, **kwargs):
+        """
+        Add a device instance for an existing model.
+
+        Revised from ``andes.system.System.add()``.
+        """
+        if model not in self.models and (model not in self.model_aliases):
+            if model in ad_dyn_models:
+                logger.debug("ANDES dynamic model <%s> is skipped.", model)
+            else:
+                logger.warning("<%s> is not an existing model.", model)
+            return
+
+        if self.is_setup:
+            raise NotImplementedError("Adding devices are not allowed after setup.")
+
+        group_name = self.__dict__[model].group
+        group = self.groups[group_name]
+
+        if param_dict is None:
+            param_dict = {}
+        if kwargs is not None:
+            param_dict.update(kwargs)
+
+        # remove `uid` field
+        param_dict.pop('uid', None)
+
+        idx = param_dict.pop('idx', None)
+        if idx is not None and (not isinstance(idx, str) and np.isnan(idx)):
+            idx = None
+
+        idx = group.get_next_idx(idx=idx, model_name=model)
+        self.__dict__[model].add(idx=idx, **param_dict)
+        group.add(idx=idx, model=self.__dict__[model])
+
+        return idx
+
     def setup(self):
         """
         Set up system for studies.
@@ -421,7 +465,16 @@ class System(andes_System):
             adjusted_params_str = ', '.join(adjusted_params)
             msg = f"Zero Line parameters detected, adjusted to default values: {adjusted_params_str}."
             logger.info(msg)
-
+        # --- bus type correction ---
+        pq_bus = self.PQ.bus.v
+        pv_bus = self.PV.bus.v
+        slack_bus = self.Slack.bus.v
+        # TODO: how to include islanded buses?
+        if self.Bus.n > 0 and np.all(self.Bus.type.v == 1):
+            self.Bus.alter(src='type', idx=pq_bus, value=1)
+            self.Bus.alter(src='type', idx=pv_bus, value=2)
+            self.Bus.alter(src='type', idx=slack_bus, value=3)
+            logger.info("All bus type are PQ, adjusted given load and generator connection status.")
         # === no device addition or removal after this point ===
         self.calc_pu_coeff()   # calculate parameters in system per units
 
@@ -662,10 +715,73 @@ class System(andes_System):
 
         return False
 
+    def to_mpc(self):
+        """
+        Export an AMS system to a MATPOWER dict.
+
+        Returns
+        -------
+        dict
+            A dictionary representing the MATPOWER case.
+        """
+        return system2mpc(self)
+
+    def to_m(self, outfile: str, overwrite: bool = None):
+        """
+        Export an AMS system to a MATPOWER M-file.
+
+        Parameters
+        ----------
+        outfile : str
+            The output file name.
+        overwrite : bool, optional
+            If True, overwrite the existing file. Default is None.
+        """
+        return wrtite_m(self, outfile=outfile, overwrite=overwrite)
+
+    def to_xlsx(self, outfile: str, overwrite: bool = None):
+        """
+        Export an AMS system to an Excel file.
+
+        Parameters
+        ----------
+        outfile : str
+            The output file name.
+        overwrite : bool, optional
+            If True, overwrite the existing file. Default is None.
+        """
+        return write_xlsx(self, outfile=outfile, overwrite=overwrite)
+
+    def to_json(self, outfile: str, overwrite: bool = None):
+        """
+        Export an AMS system to a JSON file.
+
+        Parameters
+        ----------
+        outfile : str
+            The output file name.
+        overwrite : bool, optional
+            If True, overwrite the existing file. Default is None.
+        """
+        return write_json(self, outfile=outfile, overwrite=overwrite)
+
+    def to_raw(self, outfile: str, overwrite: bool = None):
+        """
+        Export an AMS system to a v33 PSS/E RAW file.
+
+        Parameters
+        ----------
+        outfile : str
+            The output file name.
+        overwrite : bool, optional
+            If True, overwrite the existing file. Default is None.
+        """
+        return write_raw(self, outfile=outfile, overwrite=overwrite)
 
 # --------------- Helper Functions ---------------
 # NOTE: _config_numpy, load_config_rc are imported from andes.system
 
+
 def example(setup=True, no_output=True, **kwargs):
     """
     Return an :py:class:`ams.system.System` object for the

ams/utils/paths.py

@@ -184,7 +184,7 @@ def get_pycode_path(pycode_path=None, mkdir=False):
     """
 
     if pycode_path is None:
-        pycode_path = os.path.join(get_dot_andes_path(), 'pycode')
+        pycode_path = os.path.join(get_dot_ams_path(), 'pycode')
 
     if mkdir is True:
         os.makedirs(pycode_path, exist_ok=True)
@@ -203,7 +203,7 @@ def get_pkl_path():
 
     """
     pkl_name = 'calls.pkl'
-    ams_path = get_dot_andes_path()
+    ams_path = get_dot_ams_path()
 
     if not os.path.exists(ams_path):
         os.makedirs(ams_path)
@@ -213,7 +213,7 @@ def get_pkl_path():
     return pkl_path
 
 
-def get_dot_andes_path():
+def get_dot_ams_path():
     """
     Return the path to ``$HOME/.ams``
     """

docs/source/api.rst

@@ -48,6 +48,8 @@ Routines
    ams.routines.routine
    ams.routines.dcopf
    ams.routines.pflow
+   ams.routines.pypower
+   ams.routines.grbopt
 
 
 Optimization

docs/source/examples/index.rst

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

docs/source/genroutineref.py

@@ -7,7 +7,7 @@ import ams
 
 if not (os.path.isfile('routineref.rst') and os.path.isfile('configref.rst')):
 
-    ss = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'))
+    ss = ams.load(ams.get_case('5bus/pjm5bus_demo.json'))
 
     # write the top-level index file
 

docs/source/getting_started/install.rst

@@ -43,7 +43,7 @@ Create an environment for AMS (recommended)
 
 .. code:: bash
 
-     mamba create --name ams python=3.8
+     mamba create --name ams python=3.10
 
 Activate the new environment with
 
@@ -83,10 +83,7 @@ To install packages in the ``dev`` when installing AMS, do:
 
 .. code:: bash
 
-    pip install -r requirements-dev.txt
-
-One can also inspect the ``requirements-dev.txt`` to identify the packages
-for manual installation.
+    pip install .[dev]
 
 .. _Develop Install:
 
@@ -131,6 +128,7 @@ Install dependencies with
     mamba install --file requirements.txt
     mamba install --file requirements-dev.txt
     mamba install --file requirements-doc.txt
+    mamba install --file requirements-nlp.txt
 
 Alternatively, you can install them with ``pip``:
 
@@ -139,12 +137,17 @@ Alternatively, you can install them with ``pip``:
     pip install -r requirements.txt
     pip install -r requirements-dev.txt
     pip install -r requirements-doc.txt
+    pip install -r requirements-nlp.txt
+
+Alternatively, if you have a modern version of pip (>=23.1), you can install all dependencies specified in ``pyproject.toml`` with:
+
+    pip install .[dev,doc,nlp]
 
 Step 3: Install AMS in the development mode using
 
 .. code:: bash
 
-      python3 -m pip install -e .
+    python3 -m pip install -e .
 
 Note the dot at the end. Pip will take care of the rest.
 

docs/source/release-notes.rst

@@ -9,7 +9,34 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
-v1.0.9 (2024-04-23)
+v1.0.11 (2025-05-23)
+----------------------
+
+- Refactor Documenter
+- Fix bug in documentation building
+
+v1.0.10 (2025-05-23)
+----------------------
+
+- Add bus type correction in ``system.System.setup()``
+- Revise ``ams.io.psse.read`` to complete model Zone when necessary
+- Use numerical Area and Zone idx in MATPOWER and PSSE RAW file conversion
+- Support JSON format addfile when converting to ANDES case
+- Add PSS/E v33 RAW file writer
+- In class ``System``, add wrapper methods ``to_mpc``, ``to_m``, ``to_xlsx``,
+  ``to_json``, and ``to_raw`` for easier case file export
+- Add wrapper routines for PYPOWER: ``DCPF1``, ``PFlow1``, ``DCOPF1``, and ``ACOPF1``
+- In routine ``DCOPF`` and its derivatives, add ExpressionCalc ``mu1`` ``mu2`` to
+  calculate Lagrange multipliers of line flow limits constraints
+- Add wrapper routine ``OPF`` for gurobi_optimods
+- Add a demo to show newly added wrapper routines, see
+  ``examples/demonstration/demo_wrapper_routines.ipynb``
+- Revise ``andes.common.config.Config.update`` to ensure configuration parameters
+  are consistently updated in both the object and its internal ``_dict``
+- Remove legacy revised PYPOWER module
+- Remove function ``ams.shared.ppc2df``
+
+v1.0.9 (2025-04-23)
 --------------------
 
 Improve MATPOWER file converter:
@@ -17,7 +44,7 @@ Improve MATPOWER file converter:
 - Add a M file case writer
 - Include Area and Zone in both MATPOWER read and write
 
-v1.0.8 (2024-04-20)
+v1.0.8 (2025-04-20)
 --------------------
 
 - Run workflow "Publish" only on push tag event
@@ -27,7 +54,7 @@ v1.0.8 (2024-04-20)
 - Include ``gentype`` and ``genfuel`` when parsing MATPOWER cases
 - Fix logging level in ``ACOPF.run``
 
-v1.0.7 (2024-04-14)
+v1.0.7 (2025-04-14)
 --------------------
 
 - Address several wording issues in the documentation
@@ -41,44 +68,44 @@ v1.0.7 (2024-04-14)
   parameters conversion
 - Update case files
 
-v1.0.6 (2024-04-10)
+v1.0.6 (2025-04-10)
 --------------------
 
 - Enhance handling of Type 1 gencost: Automatically fallback to Type 2 gencost
 - Add parameter correction for zero line angle difference
 
-v1.0.5 (2024-04-09)
+v1.0.5 (2025-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)
+v1.0.4 (2025-04-05)
 --------------------
 
 - Fix format in release notes
 - Add badges of GitHub relesase and commits in README
 - Add a demo to show sensitivity matrices calculation
 
-v1.0.3 (2024-03-17)
+v1.0.3 (2025-03-17)
 --------------------
 
 - Bug fix in function ``ams.interface.parse_addfile``, released in v1.0.3a1
 
-v1.0.2 (2024-02-01)
+v1.0.2 (2025-02-01)
 --------------------
 
 - Enhance the GitHub Actions workflow file
 - Deprecate andes logger configuration in ``config_logger``
 - Deprecate solver specification in ``demo_ESD1``
 
-v1.0.1 (2024-01-26)
+v1.0.1 (2025-01-26)
 --------------------
 
 Hotfix: removed dependencies on `SCIP` and `pyscipopt` to resolve installation issues
 
-v1.0.0 (2024-01-24)
+v1.0.0 (2025-01-24)
 --------------------
 
 - **Breaking Change**: rename model ``Region`` to ``Zone`` for clarity. Prior case
@@ -408,50 +435,3 @@ v0.4 (2023-01)
 -------------------
 
 This release outlines the package.
-
-Known Limitations
-=================
-
-- For builit-in PYPOWER-based ACOPF, the known largest solvable case is "pglib_opf_case1354_pegase.m"
-- Batch processing is not supported yet
-- Routine ``DCOPF`` has been extensively benchmarked with pandapower and MATPOWER.
-- Routines besides above mentioned are not fully benchmarked yet.
-
-Roadmap
-=======
-
-This section lists out some potential features that may be added in the future.
-Note that the proposed features are not guaranteed to be implemented and subject to change.
-
-Electric Vehicle for Grid Service
-------------------------------------------
-
-A charging-time-constrained EV aggregation based on the state-space model
-
-References:
-
-[1] J. Wang et al., "Electric Vehicles Charging Time Constrained Deliverable Provision of Secondary
-Frequency Regulation," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3356948.
-
-[2] M. Wang et al., "State Space Model of Aggregated Electric Vehicles for Frequency Regulation," in
-IEEE Transactions on Smart Grid, vol. 11, no. 2, pp. 981-994, March 2020, doi: 10.1109/TSG.2019.2929052.
-
-Distribution OPF
---------------------------
-
-- Distribution networks OPF and its LMP
-- DG siting and sizing considering energy equity
-
-References:
-
-[1] H. Yuan, F. Li, Y. Wei and J. Zhu, "Novel Linearized Power Flow and Linearized OPF Models for
-Active Distribution Networks With Application in Distribution LMP," in IEEE Transactions on Smart Grid,
-vol. 9, no. 1, pp. 438-448, Jan. 2018, doi: 10.1109/TSG.2016.2594814.
-
-[2] C. Li, F. Li, S. Jiang, X. Wang and J. Wang, "Siting and Sizing of DG Units Considering Energy
-Equity: Model, Solution, and Guidelines," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3350914.
-
-Planning
---------------------------
-
-- Transmission expansion planning