ltbams 1.0.8__py3-none-any.whl → 1.0.10__py3-none-any.whl

ams/shared.py

@@ -6,7 +6,7 @@ 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
 
@@ -20,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.
@@ -35,7 +41,9 @@ _prefix = r" - --------------> | "  # NOQA
 _max_length = 80                    # NOQA
 
 # NOTE: copyright
-copyright_msg = 'Copyright (C) 2023-2025 Jinning Wang'
+copyright_msg = "Copyright (C) 2023-2025 Jinning Wang"
+nowarranty_msg = "AMS comes with ABSOLUTELY NO WARRANTY"
+report_time = strftime("%m/%d/%Y %I:%M:%S %p")
 
 # NOTE: copied from CVXPY documentation, last checked on 2024/10/30, v1.5
 mip_solvers = ['CBC', 'COPT', 'GLPK_MI', 'CPLEX', 'GUROBI',
@@ -102,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,7 +9,6 @@ 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 (_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__)
 
@@ -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

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/getting_started/formats/matpower.rst

@@ -181,3 +181,138 @@ Generator Cost Data
 
 #. Not currently used by any Matpower functions.
 #. MODEL = 1, :math:`f(p)` is defined by the coordinates :math:`(p_1, f_1), (p_2, f_2), . . . , (p_N , f_N)`; MODEL = 2, :math:`f(p) = c_{n}p^{n} + ... + c_{1}p^{1} + c_{0}`.
+
+
+Generator Types
+~~~~~~~~~~~~~~~~~~~~
++------+---------------------------------------------------------------+
+| code | description                                                   |
++------+---------------------------------------------------------------+
+| BA   | Energy Storage, Battery                                       |
++------+---------------------------------------------------------------+
+| CE   | Energy Storage, Compressed Air                                |
++------+---------------------------------------------------------------+
+| CP   | Energy Storage, Concentrated Solar Power                      |
++------+---------------------------------------------------------------+
+| FW   | Energy Storage, Flywheel                                      |
++------+---------------------------------------------------------------+
+| PS   | Hydraulic Turbine, Reversible (pumped storage)                |
++------+---------------------------------------------------------------+
+| ES   | Energy Storage, Other                                         |
++------+---------------------------------------------------------------+
+| ST   | Steam Turbine (includes nuclear, geothermal, and solar steam) |
++------+---------------------------------------------------------------+
+| GT   | Combustion (Gas) Turbine                                      |
++------+---------------------------------------------------------------+
+| IC   | Internal Combustion Engine (diesel, piston, reciprocating)    |
++------+---------------------------------------------------------------+
+| CA   | Combined Cycle Steam Part                                     |
++------+---------------------------------------------------------------+
+| CT   | Combined Cycle Combustion Turbine Part                        |
++------+---------------------------------------------------------------+
+| CS   | Combined Cycle Single Shaft                                   |
++------+---------------------------------------------------------------+
+| CC   | Combined Cycle Total Unit                                     |
++------+---------------------------------------------------------------+
+| HA   | Hydrokinetic, Axial Flow Turbine                              |
++------+---------------------------------------------------------------+
+| HB   | Hydrokinetic, Wave Buoy                                       |
++------+---------------------------------------------------------------+
+| HK   | Hydrokinetic, Other                                           |
++------+---------------------------------------------------------------+
+| HY   | Hydroelectric Turbine                                         |
++------+---------------------------------------------------------------+
+| BT   | Turbines Used in a Binary Cycle                               |
++------+---------------------------------------------------------------+
+| PV   | Photovoltaic                                                  |
++------+---------------------------------------------------------------+
+| WT   | Wind Turbine, Onshore                                         |
++------+---------------------------------------------------------------+
+| WS   | Wind Turbine, Offshore                                        |
++------+---------------------------------------------------------------+
+| FC   | Fuel Cell                                                     |
++------+---------------------------------------------------------------+
+| OT   | Other                                                         |
++------+---------------------------------------------------------------+
+| UN   | Unknown                                                       |
++------+---------------------------------------------------------------+
+| JE   | Jet Engine                                                    |
++------+---------------------------------------------------------------+
+| NB   | ST - Boiling Water Nuclear Reactor                            |
++------+---------------------------------------------------------------+
+| NG   | ST - Graphite Nuclear Reactor                                 |
++------+---------------------------------------------------------------+
+| NH   | ST - High Temperature Gas Nuclear Reactor                     |
++------+---------------------------------------------------------------+
+| NP   | ST - Pressurized Water Nuclear Reactor                        |
++------+---------------------------------------------------------------+
+| IT   | Internal Combustion Turbo Charged                             |
++------+---------------------------------------------------------------+
+| SC   | Synchronous Condenser                                         |
++------+---------------------------------------------------------------+
+| DC   | DC ties                                                       |
++------+---------------------------------------------------------------+
+| MP   | Motor/Pump                                                    |
++------+---------------------------------------------------------------+
+| W1   | Wind Turbine, Type 1                                          |
++------+---------------------------------------------------------------+
+| W2   | Wind Turbine, Type 2                                          |
++------+---------------------------------------------------------------+
+| W3   | Wind Turbine, Type 3                                          |
++------+---------------------------------------------------------------+
+| W4   | Wind Turbine, Type 4                                          |
++------+---------------------------------------------------------------+
+| SV   | Static Var Compensator                                        |
++------+---------------------------------------------------------------+
+| DL   | Dispatchable Load                                             |
++------+---------------------------------------------------------------+
+
+Fuel Types
+~~~~~~~~~~~~~~~~
++-------------+---------------------------------------+
+| code        | description                           |
++-------------+---------------------------------------+
+| biomass     | Biomass                               |
++-------------+---------------------------------------+
+| coal        | Coal                                  |
++-------------+---------------------------------------+
+| dfo         | Distillate Fuel Oil                   |
++-------------+---------------------------------------+
+| geothermal  | Geothermal                            |
++-------------+---------------------------------------+
+| hydro       | Hydro                                 |
++-------------+---------------------------------------+
+| hydrops     | Hydro Pumped Storage                  |
++-------------+---------------------------------------+
+| jetfuel     | Jet Fuel                              |
++-------------+---------------------------------------+
+| lng         | Liquefied Natural Gas                 |
++-------------+---------------------------------------+
+| ng          | Natural Gas                           |
++-------------+---------------------------------------+
+| nuclear     | Nuclear                               |
++-------------+---------------------------------------+
+| oil         | Unspecified Oil                       |
++-------------+---------------------------------------+
+| refuse      | Refuse, Municipal Solid Waste         |
++-------------+---------------------------------------+
+| rfo         | Residual Fuel Oil                     |
++-------------+---------------------------------------+
+| solar       | Solar                                 |
++-------------+---------------------------------------+
+| syncgen     | Synchronous Condenser                 |
++-------------+---------------------------------------+
+| wasteheat   | Waste Heat                            |
++-------------+---------------------------------------+
+| wind        | Wind                                  |
++-------------+---------------------------------------+
+| wood        | Wood or Wood Waste                    |
++-------------+---------------------------------------+
+| other       | Other                                 |
++-------------+---------------------------------------+
+| unknown     | Unknown                               |
++-------------+---------------------------------------+
+| dl          | Dispatchable Load                     |
++-------------+---------------------------------------+
+| ess         | Energy Storage System                 |
++-------------+---------------------------------------+

docs/source/getting_started/formats/pypower.rst

@@ -3,8 +3,7 @@
 PYPOWER
 --------
 
-AMS includes `PYPOWER cases <https://github.com/CURENT/ams/tree/develop/ams/cases/pypower>`_
-in version 2 for scheduling modeling and analysis. PYPOWER cases follow the same format as MATPOWER.
+AMS supports PYPOWER PY case file. PYPOWER cases follow a similar format as MATPOWER.
 
 The PYPOWER case is defined as a Python dictionary that includes ``bus``, ``gen``, ``branch``,
 ``areas``, and ``gencost``.

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,6 +9,35 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 v1.0
 ==========
 
+v1.0.10 (2024-xx-xx)
+--------------------
+
+- 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 (2024-04-23)
+--------------------
+
+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)
 --------------------
 
@@ -400,50 +429,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