ltbams 1.0.12__py3-none-any.whl → 1.0.14__py3-none-any.whl

ams/models/timeslot.py

@@ -10,12 +10,42 @@ from ams.core.model import Model
 def str_list_oconv(x):
     """
     Convert list into a list literal.
+
+    Revised from `andes.models.timeseries.str_list_oconv`, where
+    the output type is converted to a list of strings.
     """
     # NOTE: convert elements to string from number first, then join them
     str_x = [str(i) for i in x]
     return ','.join(str_x)
 
 
+class GCommit(ModelData, Model):
+    """
+    Time slot model for generator commitment decisions.
+
+    This class holds commitment decisions for generators,
+    and should be used in multi-period scheduling routines that need
+    generator commitment decisions.
+
+    For example, in Unit Commitment (UC) problems, there is a variable
+    `ugd` representing the unit commitment decisions for each generator.
+    After solving the UC problem, the `ugd` values can be used for
+    Economic Dispatch (ED) as a parameter.
+
+    .. versionadded:: 1.0.13
+    """
+
+    def __init__(self, system=None, config=None):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+
+        self.ug = NumParam(info='unit commitment decisions',
+                           tex_name=r'u_{g}',
+                           iconvert=str_list_iconv,
+                           oconvert=str_list_oconv,
+                           vtype=int)
+
+
 class TimeSlot(ModelData, Model):
     """
     Base model for time slot data used in multi-interval scheduling.

ams/models/zone.py

@@ -17,9 +17,8 @@ class Zone(ModelData, Model):
 
     Notes
     -----
-    1. Zone is a collection of buses.
-    2. Model ``Zone`` is not actually defined in ANDES.
-
+    - A zone is a collection of buses.
+    - The ``Zone`` model is not defined in ANDES up to version 1.9.3.
     """
 
     def __init__(self, system, config):
@@ -39,7 +38,6 @@ class Zone(ModelData, Model):
         -------
         str
             Formatted table
-
         """
         if self.n:
             header = ['Zone ID', 'Bus ID']

ams/opt/exprcalc.py

@@ -102,6 +102,17 @@ class ExpressionCalc(OptzBase):
         else:
             return self.optz.value
 
+    @v.setter
+    def v(self, value):
+        """
+        Set the ExpressionCalc value.
+        """
+        if self.optz is None:
+            raise ValueError("ExpressionCalc is not evaluated yet.")
+        if not isinstance(value, (int, float, np.ndarray)):
+            raise TypeError(f"Value must be a number or numpy array, got {type(value)}.")
+        self.optz.value = value
+
     @property
     def e(self):
         """

ams/opt/optzbase.py

@@ -174,13 +174,14 @@ class OptzBase:
         """
         Return all the indexes of this item.
 
-        .. note::
-            New in version 1.0.0.
-
         Returns
         -------
         list
             A list of indexes.
+
+        Notes
+        -----
+        .. versionadded:: 1.0.0
         """
 
         if self.is_group:

ams/report.py

@@ -30,13 +30,8 @@ def report_info(system) -> list:
 
 class Report:
     """
-    Report class to store routine analysis reports.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
+    Report class to store routine analysis reports,
+    revised from `andes.report.Report`.
     """
 
     def __init__(self, system):

ams/routines/dcopf.py

@@ -17,19 +17,22 @@ logger = logging.getLogger(__name__)
 
 class DCOPF(DCPFBase):
     """
-    DC optimal power flow (DCOPF).
+    DC optimal power flow (DCOPF) using B-theta formulation.
 
     Notes
     -----
-    1. The nodal price is calculated as ``pi`` in ``pic``.
-    2. Devices online status of ``StaticGen``, ``StaticLoad``, and ``Shunt`` are considered in the connectivity
-       matrices ``Cft``, ``Cg``, ``Cl``, and ``Csh``.
+    - The nodal price is calculated as ``pi`` in ``pic``.
+    - Devices online status of ``StaticGen``, ``StaticLoad``, and ``Shunt`` are considered in the connectivity
+      matrices ``Cft``, ``Cg``, ``Cl``, and ``Csh``.
 
     References
     ----------
     1. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas, “MATPOWER: Steady-State
        Operations, Planning, and Analysis Tools for Power Systems Research and Education,” IEEE
        Trans. Power Syst., vol. 26, no. 1, pp. 12-19, Feb. 2011
+    2. Y. Chen et al., "Security-Constrained Unit Commitment for Electricity Market: Modeling,
+       Solution Methods, and Future Challenges," in IEEE Transactions on Power Systems, vol. 38, no. 5,
+       pp. 4668-4681, Sept. 2023
     """
 
     def __init__(self, system, config):

ams/routines/dcopf2.py

@@ -18,15 +18,25 @@ logger = logging.getLogger(__name__)
 
 class DCOPF2(DCOPF):
     """
-    DC optimal power flow (DCOPF) using PTDF.
+    DC optimal power flow (DCOPF) using PTDF formulation.
+
     For large cases, it is recommended to build the PTDF first, especially when incremental
     build is necessary.
 
     Notes
     -----
-    1. This routine requires PTDF matrix.
-    2. Nodal price ``pi`` is calculated with three parts.
-    3. Bus angle ``aBus`` is calculated after solving the problem.
+    - This routine requires PTDF matrix.
+    - Nodal price ``pi`` is calculated with three parts.
+    - Bus angle ``aBus`` is calculated after solving the problem.
+
+    References
+    ----------
+    1. R. D. Zimmerman, C. E. Murillo-Sanchez, and R. J. Thomas, “MATPOWER: Steady-State
+       Operations, Planning, and Analysis Tools for Power Systems Research and Education,” IEEE
+       Trans. Power Syst., vol. 26, no. 1, pp. 12-19, Feb. 2011
+    2. Y. Chen et al., "Security-Constrained Unit Commitment for Electricity Market: Modeling,
+       Solution Methods, and Future Challenges," in IEEE Transactions on Power Systems, vol. 38, no. 5,
+       pp. 4668-4681, Sept. 2023
     """
 
     def __init__(self, system, config):

ams/routines/dopf.py

@@ -17,7 +17,7 @@ class DOPF(DCOPF):
     UNDER DEVELOPMENT!
 
     References
-    -----------------
+    ----------
     1. L. Bai, J. Wang, C. Wang, C. Chen, and F. Li, “Distribution Locational Marginal Pricing (DLMP)
        for Congestion Management and Voltage Support,” IEEE Trans. Power Syst., vol. 33, no. 4,
        pp. 4061-4073, Jul. 2018, doi: 10.1109/TPWRS.2017.2767632.
@@ -116,7 +116,7 @@ class DOPFVIS(DOPF):
     UNDER DEVELOPMENT!
 
     References
-    -----------------
+    ----------
     1. L. Bai, J. Wang, C. Wang, C. Chen, and F. Li, “Distribution Locational Marginal Pricing (DLMP)
        for Congestion Management and Voltage Support,” IEEE Trans. Power Syst., vol. 33, no. 4,
        pp. 4061-4073, Jul. 2018, doi: 10.1109/TPWRS.2017.2767632.

ams/routines/ed.py

@@ -120,11 +120,11 @@ class ED(RTED, MPBase, SRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``
-    2. The tie-line flow is not implemented in this model.
-    3. ``EDTSlot.ug`` is used instead of ``StaticGen.u`` for generator commitment.
-    4. Following reserves are balanced for each "Area": RegUp reserve ``rbu``,
-       RegDn reserve ``rbd``, and Spinning reserve ``rsr``.
+    - Formulations has been adjusted with interval ``config.t``
+    - The tie-line flow is not implemented in this model.
+    - ``EDTSlot.ug`` is used instead of ``StaticGen.u`` for generator commitment.
+    - Following reserves are balanced for each "Area": RegUp reserve ``rbu``,
+      RegDn reserve ``rbd``, and Spinning reserve ``rsr``.
     """
 
     def __init__(self, system, config):

ams/routines/grbopt.py

@@ -34,6 +34,8 @@ class OPF(DCPF1):
     Refer to the gurobi-optimods documentation for further details:
 
     https://gurobi-optimods.readthedocs.io/en/stable/mods/opf/opf.html
+
+    .. versionadded:: 1.0.10
     """
 
     def __init__(self, system, config):

ams/routines/pflow.py

@@ -30,7 +30,7 @@ class PFlow(RoutineBase):
     ----------
     1. M. L. Crow, Computational methods for electric power systems. 2015.
     2. ANDES Documentation - Simulation and Plot.
-       https://docs.andes.app/en/latest/_examples/ex1.html
+       https://andes.readthedocs.io/en/stable/_examples/ex1.html
     """
 
     def __init__(self, system, config):

ams/routines/pypower.py

@@ -32,6 +32,8 @@ class DCPF1(RoutineBase):
     - This class does not implement the AMS-style DC power flow formulation.
     - For detailed mathematical formulations and algorithmic details, refer to the
       MATPOWER User's Manual, section on Power Flow.
+
+    .. versionadded:: 1.0.10
     """
 
     def __init__(self, system, config):
@@ -362,6 +364,8 @@ class PFlow1(DCPF1):
       MATPOWER User's Manual, section on Power Flow.
     - Fast-Decoupled (XB version) and Fast-Decoupled (BX version) algorithms are
       not fully supported yet.
+
+    .. versionadded:: 1.0.10
     """
 
     def __init__(self, system, config):
@@ -436,6 +440,8 @@ class DCOPF1(DCPF1):
     - For detailed mathematical formulations and algorithmic details, refer to the
       MATPOWER User's Manual, section on Optimal Power Flow.
     - Algorithms 400, 500, 600, and 700 are not fully supported yet.
+
+    .. versionadded:: 1.0.10
     """
 
     def __init__(self, system, config):
@@ -586,6 +592,8 @@ class ACOPF1(DCOPF1):
     - This class does not implement the AMS-style AC optimal power flow formulation.
     - For detailed mathematical formulations and algorithmic details, refer to the
       MATPOWER User's Manual, section on Optimal Power Flow.
+
+    .. versionadded:: 1.0.10
     """
 
     def __init__(self, system, config):

ams/routines/routine.py

@@ -3,8 +3,9 @@ Module for routine data.
 """
 
 import logging
-from typing import Optional, Union, Type, Iterable, Dict
+import json
 from collections import OrderedDict
+from typing import Optional, Union, Type, Iterable, Dict
 
 import numpy as np
 
@@ -431,6 +432,95 @@ class RoutineBase:
             logger.warning(msg)
             return False
 
+    def load_json(self, path):
+        """
+        Load scheduling results from a json file.
+
+        Parameters
+        ----------
+        path : str
+            Path of the json file to load.
+
+        Returns
+        -------
+        bool
+            True if the loading is successful, False otherwise.
+
+        .. versionadded:: 1.0.13
+        """
+        try:
+            with open(path, 'r') as f:
+                data = json.load(f)
+        except Exception as e:
+            logger.error(f"Failed to load JSON file: {e}")
+            return False
+
+        if not self.initialized:
+            self.init()
+
+        # Unpack variables and expressions from JSON
+        for group, group_data in data.items():
+            if not isinstance(group_data, dict):
+                continue
+            for key, values in group_data.items():
+                if key == 'idx':
+                    continue
+                # Find the corresponding variable or expression
+                if key in self.vars:
+                    var = self.vars[key]
+                    # Assign values to the variable
+                    try:
+                        var.v = np.array(values)
+                    except Exception as e:
+                        logger.warning(f"Failed to assign values to var '{key}': {e}")
+                elif key in self.exprs:
+                    continue
+                elif key in self.exprcs:
+                    exprc = self.exprcs[key]
+                    # Assign values to the expression calculation
+                    try:
+                        exprc.v = np.array(values)
+                    except Exception as e:
+                        logger.warning(f"Failed to assign values to exprc '{key}': {e}")
+        logger.info(f"Loaded results from {path}")
+        return True
+
+    def export_json(self, path=None):
+        """
+        Export scheduling results to a json file.
+
+        Parameters
+        ----------
+        path : str, optional
+            Path of the json file to export.
+
+        Returns
+        -------
+        str
+            The exported json file name
+
+        .. versionadded:: 1.0.13
+        """
+        if not self.converged:
+            logger.warning("Routine did not converge, aborting export.")
+            return None
+
+        path, file_name = get_export_path(self.system,
+                                          self.class_name + '_out',
+                                          path=path, fmt='json')
+
+        data_dict = dict()
+
+        group_data(self, data_dict, self.vars, 'v')
+        group_data(self, data_dict, self.exprs, 'v')
+        group_data(self, data_dict, self.exprcs, 'v')
+
+        with open(path, 'w') as f:
+            json.dump(data_dict, f, indent=4,
+                      default=lambda x: x.tolist() if isinstance(x, np.ndarray) else x)
+
+        return file_name
+
     def export_csv(self, path=None):
         """
         Export scheduling results to a csv file.
@@ -1022,3 +1112,37 @@ def collect_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
             logger.debug(f"Error with collecting data for '{key}': {e}")
             data_v = [np.nan] * len(idx_v)
         data_dict.update(OrderedDict(zip([f'{key} {dev}' for dev in idx_v], data_v)))
+
+
+def group_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
+    """
+    Collect data for export from grouped items.
+
+    Parameters
+    ----------
+    rtn : ams.routines.routine.RoutineBase
+        The routine to collect data from.
+    data_dict : Dict
+        The data dictionary to populate.
+    items : dict
+        Dictionary of items to collect data from.
+    attr : str
+        Attribute to collect data for.
+
+    .. versionadded:: 1.0.13
+    """
+    for key, item in items.items():
+        if item.owner is None:
+            continue
+        if item.owner.class_name not in data_dict.keys():
+            idx_v = item.get_all_idxes()
+            data_dict[item.owner.class_name] = dict(idx=idx_v)
+        else:
+            idx_v = data_dict[item.owner.class_name]['idx']
+        try:
+            data_v = rtn.get(src=key, attr=attr, idx=idx_v,
+                             horizon=rtn.timeslot.v if hasattr(rtn, 'timeslot') else None)
+        except Exception as e:
+            logger.warning(f"Error with collecting data for '{key}': {e}")
+            data_v = [np.nan] * item.owner.n
+        data_dict[item.owner.class_name][key] = data_v

ams/routines/rted.py

@@ -125,10 +125,10 @@ class RTED(DCOPF, RTEDBase, SFRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``, 5/60 [Hour] by default.
-    2. The tie-line flow related constraints are ommited in this formulation.
-    3. The power balance is solved for the entire system.
-    4. The SFR is solved for each area.
+    - Formulations has been adjusted with interval ``config.t``, 5/60 [Hour] by default.
+    - The tie-line flow related constraints are ommited in this formulation.
+    - Power generation is balanced for the entire system.
+    - SFR is balanced for each area.
     """
 
     def __init__(self, system, config):
@@ -487,7 +487,7 @@ class RTEDVIS(RTED, VISBase):
     Please ensure that the parameters `dvm` and `dvd` are set according to the system base.
 
     References
-    -----------------
+    ----------
     1. B. She, F. Li, H. Cui, J. Wang, Q. Zhang and R. Bo, "Virtual Inertia Scheduling (VIS) for
        Real-Time Economic Dispatch of IBR-Penetrated Power Systems," in IEEE Transactions on
        Sustainable Energy, vol. 15, no. 2, pp. 938-951, April 2024, doi: 10.1109/TSTE.2023.3319307.

ams/routines/uc.py

@@ -69,8 +69,8 @@ class UC(DCOPF, RTEDBase, MPBase, SRBase, NSRBase):
 
     Notes
     -----
-    1. Formulations has been adjusted with interval ``config.t``
-    2. The tie-line flow has not been implemented in formulations.
+    - The formulations has been adjusted with interval ``config.t``
+    - The tie-line flow has not been implemented in formulations.
 
     References
     ----------

ams/shared.py

@@ -4,6 +4,7 @@ Shared constants and delayed imports.
 This module is supplementary to the ``andes.shared`` module.
 """
 import logging
+import sys
 import unittest
 from functools import wraps
 from time import strftime
@@ -14,6 +15,7 @@ from andes.utils.lazyimport import LazyImport
 
 from andes.system import System as adSystem
 
+from ._version import get_versions
 
 logger = logging.getLogger(__name__)
 
@@ -24,6 +26,7 @@ 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')
+tqdm = LazyImport('from tqdm.auto import tqdm')
 
 # --- an empty ANDES system ---
 empty_adsys = adSystem(autogen_stale=False)
@@ -44,6 +47,15 @@ _max_length = 80                    # NOQA
 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")
+version_msg = f"AMS {get_versions()['version']}"
+
+summary_row = {'field': 'Info',
+               'comment': version_msg,
+               'comment2': report_time,
+               'comment3': nowarranty_msg,
+               'comment4': copyright_msg}
+
+summary_name = "Summary"  # ensure model Summary's name is consistent
 
 # NOTE: copied from CVXPY documentation, last checked on 2024/10/30, v1.5
 mip_solvers = ['CBC', 'COPT', 'GLPK_MI', 'CPLEX', 'GUROBI',
@@ -118,7 +130,7 @@ def skip_unittest_without_PYPOWER(f):
         try:
             import pypower  # NOQA
         except ImportError:
-            raise unittest.SkipTest("PYPOWER is not installed.")
+            raise unittest.SkipTest("PYPOWER is not available.")
         return f(*args, **kwargs)
     return wrapper
 
@@ -131,6 +143,91 @@ def skip_unittest_without_gurobi_optimods(f):
         try:
             import gurobi_optimods  # NOQA
         except ImportError:
-            raise unittest.SkipTest("Gurobi is not installed.")
+            raise unittest.SkipTest("gurobi_optimods is not available.")
         return f(*args, **kwargs)
     return wrapper
+
+
+def _init_pbar(total, unit, no_tqdm):
+    """Initializes and returns a tqdm progress bar."""
+    pbar = tqdm(total=total, unit=unit, ncols=80, ascii=True,
+                file=sys.stdout, disable=no_tqdm)
+    pbar.update(0)
+    return pbar
+
+
+def _update_pbar(pbar, current, total):
+    """Updates and closes the progress bar."""
+    perc = np.round(min((current / total) * 100, 100), 2)
+    if pbar.total is not None:  # Check if pbar is still valid
+        last_pc = pbar.n / pbar.total * 100  # Get current percentage based on updated value
+    else:
+        last_pc = 0
+
+    perc_diff = perc - last_pc
+    if perc_diff >= 1:
+        pbar.update(perc_diff)
+
+    # Ensure pbar finishes at 100% and closes
+    if pbar.n < pbar.total:  # Check if it's not already at total
+        pbar.update(pbar.total - pbar.n)  # Update remaining
+    pbar.close()
+
+
+def ams_params_not_in_andes(mdl_name, am_params):
+    """
+    Helper function to return parameters not in the ANDES model.
+    If the model is not in the ANDES system, it returns an empty list.
+
+    Parameters
+    ----------
+    mdl_name : str
+        The name of the model.
+    am_params : list
+        A list of parameters from the AMS model.
+
+    Returns
+    -------
+    list
+        A list of parameters that are not in the ANDES model.
+    """
+    if mdl_name not in ad_models:
+        return []
+    ad_params = list(empty_adsys.models[mdl_name].params.keys())
+    return list(set(am_params) - set(ad_params))
+
+
+def model2df(instance, skip_empty, to_andes):
+    """
+    Prepare a DataFrame from the model instance for output.
+
+    Parameters
+    ----------
+    instance : ams.model.Model
+        The model instance to prepare.
+    skip_empty : bool
+        Whether to skip empty models.
+    to_andes : bool
+        Whether to prepare the DataFrame for ANDES.
+
+    Returns
+    -------
+    pd.DataFrame
+        The prepared DataFrame.
+    """
+    name = instance.class_name
+
+    if skip_empty and instance.n == 0:
+        return None
+
+    if name not in ad_models and to_andes:
+        return None
+
+    instance.cache.refresh("df_in")
+    df = instance.cache.df_in
+
+    if to_andes:
+        skipped_params = ams_params_not_in_andes(name, df.columns.tolist())
+        df = df.drop(skipped_params, axis=1, errors='ignore')
+
+    return df