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

ams/models/distributed/ev.py

@@ -12,13 +12,17 @@ class EV1(ModelData, Model):
     """
     Aggregated EV model for scheduling at transmission level.
 
-    For co-simulation with ADNES, it is expected to be used in
+    For co-simulation with ANDES, it is expected to be used in
     conjunction with the dynamic models `EV1` or `EV2`.
 
-    Reference:
-
-    [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.
+    References
+    ----------
+    1. J. Wang et al., "Electric Vehicles Charging Time Constrained
+       Deliverable Provision of Secondary Frequency Regulation," in IEEE
+       Transactions on Smart Grid, vol. 15, no. 4, pp. 3892-3903, July
+       2024, doi: 10.1109/TSG.2024.3356948.
+    2. ANDES Documentation, EV1,
+       https://andes.readthedocs.io/en/stable/groupdoc/DG.html#ev1
     """
 
     def __init__(self, system, config):
@@ -53,7 +57,7 @@ class EV1(ModelData, Model):
 
 class EV2(EV1):
     """
-    EV aggregation model at transmission level, identical to :ref:`EV1`.
+    Alias for EV1.
     """
 
     def __init__(self, system=None, config=None) -> None:

ams/models/distributed/pvd1.py

@@ -52,13 +52,10 @@ class PVD1(PVD1Data, Model):
     ``vt3``, ``vrflag``, ``ft0``, ``ft1``, ``ft2``, ``ft3``, ``frflag``,
     ``tip``, ``tiq``, ``recflag``.
 
-    Reference:
-
-    [1] ANDES Documentation, PVD1
-
-    Available:
-
-    https://docs.andes.app/en/latest/groupdoc/DG.html#pvd1
+    References
+    ----------
+    1. ANDES Documentation, PVD1,
+       https://andes.readthedocs.io/en/stable/groupdoc/DG.html#pvd1
     """
 
     def __init__(self, system, config):

ams/models/group.py

@@ -3,22 +3,24 @@ import logging
 from andes.models.group import GroupBase as adGroupBase
 from andes.core.service import BackRef
 
+from ams.utils.misc import deprec_get_idx
+
 logger = logging.getLogger(__name__)
 
 
 class GroupBase(adGroupBase):
     """
-    Base class for groups.
+    Base class for groups, revised from
+    `andes.models.group.GroupBase`.
 
     Add common_vars and common_params to the group class.
-
-    This class is revised from ``andes.models.group.GroupBase``.
     """
 
     def __init__(self):
         super().__init__()
         self.common_params.extend(('idx',))
 
+    @deprec_get_idx
     def get_idx(self):
         """
         Return the value of group idx sorted in a human-readable style.
@@ -27,6 +29,9 @@ class GroupBase(adGroupBase):
         -----
         This function sorts the idx values using a custom sorting key,
         which handles varying length strings with letters and numbers.
+
+        .. deprecated:: 1.0.0
+           Use ``get_all_idxes`` instead.
         """
         all_idx = [mdl.idx.v for mdl in self.models.values()]
         flat_list = [item for sublist in all_idx for item in sublist]
@@ -94,13 +99,10 @@ class RenGen(GroupBase):
     See ANDES Documentation SynGen here for the notes on replacing StaticGen and setting the power
     ratio parameters.
 
-    Reference:
-
-    [1] ANDES Documentation, RenGen, [Online]
-
-    Available:
-
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#rengen
+    References
+    ----------
+    1. ANDES Documentation, RenGen,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#rengen
     """
 
     def __init__(self):
@@ -129,13 +131,10 @@ class DG(GroupBase):
     See ANDES Documentation SynGen here for the notes on replacing StaticGen and setting the power
     ratio parameters.
 
-    Reference:
-
-    [1] ANDES Documentation, SynGen, [Online]
-
-    Available:
-
-    https://docs.andes.app/en/latest/groupdoc/SynGen.html#syngen
+    References
+    ----------
+    1. ANDES Documentation, SynGen,
+       https://andes.readthedocs.io/en/stable/groupdoc/SynGen.html#syngen
     """
 
     def __init__(self):
@@ -182,7 +181,7 @@ class StaticGen(GroupBase):
     Notes
     -----
     For co-simulation with ANDES, refer to the `ANDES StaticGen Documentation
-    <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_ for
+    <https://andes.readthedocs.io/en/stable/groupdoc/StaticGen.html#staticgen>`_ for
     replacing static generators with dynamic generators.
     """
 

ams/models/renewable/regc.py

@@ -39,12 +39,10 @@ class REGCA1(REGCData, Model):
     """
     Renewable generator scheduling model.
 
-    Reference:
-
-    [1] ANDES Documentation, REGCA1
-
-    Available:
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regca1
+    References
+    ----------
+    1. ANDES Documentation, REGCA1,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regca1
     """
 
     def __init__(self, system=None, config=None) -> None:
@@ -56,7 +54,7 @@ class REGCA1(REGCData, Model):
 class REGCV1(REGCData, Model):
     """
     Voltage-controlled converter model (virtual synchronous generator) with
-    inertia emulation.
+    inertia emulation, for scheduling purposes.
 
     Here Mmax and Dmax are assumed to be constant, but they might subject to
     the operating condition of the converter.
@@ -67,13 +65,10 @@ class REGCV1(REGCData, Model):
     - Generation cost is defined by model :ref:`GCost`
     - Inertia emulation cost is defined by model :ref:`VSGCost`
 
-    Reference:
-
-    [1] ANDES Documentation, REGCV1
-
-    Available:
-
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regcv1
+    References
+    ----------
+    1. ANDES Documentation, REGCV1,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regcv1
     """
 
     def __init__(self, system=None, config=None) -> None:
@@ -100,15 +95,12 @@ class REGCV1(REGCData, Model):
 
 class REGCV2(REGCV1):
     """
-    Voltage-controlled VSC, identical to :ref:`REGCV1`.
-
-    Reference:
-
-    [1] ANDES Documentation, REGCV2
-
-    Available:
+    Alias for REGCV1, for scheduling purposes.
 
-    https://docs.andes.app/en/latest/groupdoc/RenGen.html#regcv2
+    References
+    ----------
+    1. ANDES Documentation, REGCV2,
+       https://andes.readthedocs.io/en/stable/groupdoc/RenGen.html#regcv2
     """
 
     def __init__(self, system=None, config=None) -> None:

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/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/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/routine.py

@@ -445,6 +445,8 @@ class RoutineBase:
         -------
         bool
             True if the loading is successful, False otherwise.
+
+        .. versionadded:: 1.0.13
         """
         try:
             with open(path, 'r') as f:
@@ -496,12 +498,15 @@ class RoutineBase:
         -------
         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,
+        path, file_name = get_export_path(self.system,
+                                          self.class_name + '_out',
                                           path=path, fmt='json')
 
         data_dict = dict()
@@ -1123,6 +1128,8 @@ def group_data(rtn: RoutineBase, data_dict: Dict, items: Dict, attr: str):
         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:

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

@@ -15,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__)
 
@@ -46,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',
@@ -162,3 +172,62 @@ def _update_pbar(pbar, current, total):
     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