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

ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-08-18T15:13:43-0700",
+ "date": "2025-08-31T23:37:40-0700",
  "dirty": false,
  "error": null,
- "full-revisionid": "1aab83cb951d517c906fe117499d482da8b6e66b",
- "version": "1.0.13"
+ "full-revisionid": "595ed3a3be7f707c7c4aa79ac73bffa58919dc81",
+ "version": "1.0.14"
 }
 '''  # END VERSION_JSON
 

ams/cli.py

@@ -23,18 +23,13 @@ command_aliases = {
 
 def create_parser():
     """
-    Create a parser for the command-line interface.
+    Create a parser for the command-line interface,
+    revised from `andes.cli.create_parser`.
 
     Returns
     -------
     argparse.ArgumentParser
         Parser with all AMS options
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
     """
 
     parser = argparse.ArgumentParser()

ams/core/common.py

@@ -1,16 +1,20 @@
 import logging
 
-from andes.core.common import Config as AndesConfig
+from andes.core.common import Config as adConfig
 
 logger = logging.getLogger(__name__)
 
 
-class Config(AndesConfig):
+class Config(adConfig):
     """
     A class for storing configuration, can be used in system,
     model, routine, and other modules.
 
-    Revised from `andes.core.common.Config`.
+    Revised from `andes.core.common.Config`, where update method
+    is modified to ensure values in the dictionary are set
+    in the configuration object.
+
+    .. versionadded:: 1.0.11
     """
 
     def __init__(self, name, dct=None, **kwargs):

ams/core/documenter.py

@@ -13,7 +13,8 @@ logger = logging.getLogger(__name__)
 
 class Documenter:
     """
-    Helper class for documenting models.
+    Helper class for documenting models, inspired by
+    `andes.core.documenter.Documenter`.
 
     Parameters
     ----------

ams/core/matprocessor.py

@@ -244,7 +244,7 @@ class MatProcessor:
     The connectivity matrices `Cft`, `Cg`, `Cl`, and `Csh` ***have taken*** the
     devices connectivity into account.
 
-    The MParams' row names and col names are assigned in `System.setup()`.
+    The MParams row names and col names are assigned in `System.setup()`.
     """
 
     def __init__(self, system):
@@ -627,7 +627,7 @@ class MatProcessor:
                 luid = [system.Line.idx2uid(line)]
                 self.PTDF.row_names = [line]
             except ValueError:
-                raise ValueError(f"Line {line} not found.")
+                raise ValueError(f"Line {line} not found.") from None
         elif isinstance(line, list):
             luid = system.Line.idx2uid(line)
             self.PTDF.row_names = line
@@ -725,7 +725,7 @@ class MatProcessor:
             try:
                 luid = [system.Line.idx2uid(line)]
             except ValueError:
-                raise ValueError(f"Line {line} not found.")
+                raise ValueError(f"Line {line} not found.") from None
         elif isinstance(line, list):
             luid = system.Line.idx2uid(line)
 
@@ -811,7 +811,7 @@ class MatProcessor:
             try:
                 luid = [self.system.Line.idx2uid(line)]
             except ValueError:
-                raise ValueError(f"Line {line} not found.")
+                raise ValueError(f"Line {line} not found.") from None
         elif isinstance(line, list):
             luid = self.system.Line.idx2uid(line)
 

ams/core/model.py

@@ -235,9 +235,11 @@ class Model:
 
         Notes
         -----
-        New in version 0.9.14: Added the signature `attr` to alter specific attributes.
-        This feature is useful when you need to manipulate parameter values in the system
-        base and ensure that these changes are reflected in the dumped case file.
+        .. versionchanged:: 0.9.14
+
+        The ``attr`` argument was added to allow altering specific attributes.
+        This is useful when manipulating parameter values in the system base
+        and ensuring that changes are reflected in the dumped case file.
         """
 
         instance = self.__dict__[src]
@@ -307,6 +309,11 @@ class Model:
         Return the index of the model instance.
         Equivalent to ``self.idx.v``, develoepd for consistency with group method
         ``get_idx``.
+
+        Notes
+        -----
+        .. deprecated:: 1.0.0
+           Use ``get_all_idxes`` instead.
         """
         return self.idx.v
 
@@ -314,13 +321,14 @@ class Model:
         """
         Return all the indexes of this model.
 
-        .. note::
-            New in version 1.0.0. Add to follow the group method ``get_all_idxes``.
-
         Returns
         -------
         list
             A list of indexes.
+
+        Notes
+        -----
+        .. versionadded:: 1.0.0
         """
         return self.idx.v
 

ams/core/param.py

@@ -252,6 +252,9 @@ class RParam(Param):
         Notes
         -----
         - The value will sort by the indexer if indexed.
+
+        .. deprecated:: 1.0.0
+           Use ``get_all_idxes`` instead.
         """
         if self.indexer is None:
             if self.is_group:
@@ -283,9 +286,6 @@ class RParam(Param):
         """
         Get all the indexes of the parameter.
 
-        .. note::
-            New in version 1.0.0.
-
         Returns
         -------
         idx : list
@@ -294,6 +294,8 @@ class RParam(Param):
         Notes
         -----
         - The value will sort by the indexer if indexed.
+
+        .. versionadded:: 1.0.0
         """
         if self.indexer is None:
             if self.is_group:

ams/core/symprocessor.py

@@ -1,7 +1,13 @@
 """
-Symbolic processor class for AMS routines.
+Symbolic processor class for AMS routines,
+revised from `andes.core.symprocessor`.
 
-This module is revised from ``andes.core.symprocessor``.
+Revised from the ANDES project:
+https://github.com/CURENT/andes
+
+Original author: Hantao Cui
+
+License: GNU General Public License v3.0 (GPL-3.0)
 """
 
 import logging

ams/core/var.py

@@ -14,7 +14,7 @@ class Algeb:
     """
     Algebraic variable class.
 
-    This class is simplified from ``andes.core.var.Algeb``.
+    Simplified from `andes.core.var.Algeb`.
     """
 
     def __init__(self,

ams/extension/eva.py

@@ -2,13 +2,6 @@
 EV Aggregator module.
 
 EVD is the generated datasets, and EVA is the aggregator model.
-
-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.
-[2] M. Wang, Y. Mu, Q. Shi, H. Jia and F. Li, "Electric Vehicle Aggregator Modeling and Control for
-Frequency Regulation Considering Progressive State Recovery," in IEEE Transactions on Smart Grid,
-vol. 11, no. 5, pp. 4176-4189, Sept. 2020, doi: 10.1109/TSG.2020.2981843.
 """
 
 import logging
@@ -50,6 +43,17 @@ class EVD(ModelData, Model):
     """
     In the EVD, each single EV is recorded as a device with its own parameters.
     The parameters are generated from given statistical distributions.
+
+    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. M. Wang, Y. Mu, Q. Shi, H. Jia and F. Li, "Electric Vehicle Aggregator
+       Modeling and Control for Frequency Regulation Considering Progressive
+       State Recovery," in IEEE Transactions on Smart Grid, vol. 11, no. 5,
+       pp. 4176-4189, Sept. 2020, doi: 10.1109/TSG.2020.2981843.
     """
 
     def __init__(self, N=10000, Ns=20, Tagc=4, SOCf=0.2, r=0.5,

ams/interface.py

@@ -177,9 +177,9 @@ def to_andes(system, addfile=None,
 
     Notes
     -----
-    1. Power flow models in the addfile will be skipped and only dynamic models will be used.
-    2. The addfile format is guessed based on the file extension. Currently only ``xlsx`` is supported.
-    3. Index in the addfile is automatically adjusted when necessary.
+    - Power flow models in the addfile will be skipped and only dynamic models will be used.
+    - The addfile format is guessed based on the file extension. Currently only ``xlsx`` is supported.
+    - Index in the addfile is automatically adjusted when necessary.
     """
     t0, _ = elapsed()
 
@@ -446,9 +446,9 @@ class Dynamic:
 
     Notes
     -----
-    1. Using the file conversion ``to_andes()`` will automatically
-       link the AMS system to the converted ANDES system in the
-       attribute ``dyn``.
+    - Using the file conversion ``to_andes()`` will automatically
+      link the AMS system to the converted ANDES system in the
+      attribute ``dyn``.
 
     Examples
     --------
@@ -503,7 +503,7 @@ class Dynamic:
 
         Notes
         -----
-        1. AGC power reference ``paux`` is not included in this function.
+        - AGC power reference ``paux`` is not included in this function.
         """
         # 1) TurbineGov
         syg_idx = sp.dyn.link['syg_idx'].dropna().tolist()  # SynGen idx

ams/io/json.py

@@ -11,7 +11,9 @@ from collections import OrderedDict
 from andes.io.json import (testlines, read)  # NOQA
 from andes.utils.paths import confirm_overwrite
 
-from ams.shared import empty_adsys, ad_models
+from ams.shared import pd
+from ams.shared import summary_row, summary_name, model2df
+
 
 logger = logging.getLogger(__name__)
 
@@ -24,7 +26,8 @@ def write(system, outfile, skip_empty=True, overwrite=None,
     If to_andes is True, only write models that are in ANDES,
     but the outfile might not be able to be read back into AMS.
 
-    Revise function ``andes.io.json.write`` to skip non-andes models.
+    Revised from `andes.io.json.write`, where non-andes models
+    are skipped if `to_andes` is True.
 
     Parameters
     ----------
@@ -63,20 +66,21 @@ def _dump_system(system, skip_empty, orient='records', to_andes=False):
     them all in an OrderedDict.
     """
     out = OrderedDict()
+    summary_found = False
     for name, instance in system.models.items():
-        if skip_empty and instance.n == 0:
+        df = model2df(instance, skip_empty, to_andes=to_andes)
+        if df is None:
             continue
-        if to_andes:
-            if name not in ad_models:
-                continue
-            # NOTE: ommit parameters that are not in ANDES
-            skip_params = []
-            ams_params = list(instance.params.keys())
-            andes_params = list(empty_adsys.models[name].params.keys())
-            skip_params = list(set(ams_params) - set(andes_params))
-            df = instance.cache.df_in.drop(skip_params, axis=1, errors='ignore')
-            out[name] = df.to_dict(orient=orient)
-        else:
-            df = instance.cache.df_in
-            out[name] = df.to_dict(orient=orient)
+
+        if name == summary_name:
+            df = pd.concat([pd.DataFrame([summary_row]), df], ignore_index=True)
+            df.index.name = "uid"
+            summary_found = True
+        out[name] = df.to_dict(orient=orient)
+
+    if not summary_found:
+        df = pd.DataFrame([summary_row])
+        df.index.name = "uid"
+        out[summary_name] = df.to_dict(orient=orient)
+
     return json.dumps(out, indent=2)

ams/io/matpower.py

@@ -36,10 +36,11 @@ def read(system, file):
 
 def m2mpc(infile: str) -> dict:
     """
-    Parse a MATPOWER file and return a dictionary containing the parsed data.
+    Parse a MATPOWER file and return a dictionary containing the parsed data,
+    revised from `andes.io.matpower.m2mpc`.
 
     This function processes MATPOWER case files and extracts relevant fields
-    into a structured dictionary. It is revised from ``andes.io.matpower.m2mpc``.
+    into a structured dictionary.
 
     Supported fields include:
     - `baseMVA`: The system base power in MVA.
@@ -181,9 +182,8 @@ def m2mpc(infile: str) -> dict:
 
 def mpc2system(mpc: dict, system) -> bool:
     """
-    Load an mpc dict into an empty AMS system.
-
-    Revised from ``andes.io.matpower.mpc2system``.
+    Load an mpc dict into an empty AMS system, revised from
+    `andes.io.matpower.mpc2system`.
 
     Note that `mbase` in mpc is converted to `Sn`, but it is not actually used in
     MATPOWER nor AMS.
@@ -453,7 +453,7 @@ def system2mpc(system) -> dict:
     """
     Convert a **setup** AMS system to a MATPOWER mpc dictionary.
 
-    This function is revised from ``andes.io.matpower.system2mpc``.
+    Revised from `andes.io.matpower.system2mpc`.
 
     Parameters
     ----------

ams/io/psse.py

@@ -16,7 +16,8 @@ def read(system, file):
     """
     Read PSS/E RAW file v32/v33 formats.
 
-    Revised from ``andes.io.psse.read`` to complete model ``Zone`` when necessary.
+    Revised from `andes.io.psse.read`, where model ``Zone`` is completed
+    when necessary.
     """
     ret = ad_read(system, file)
     # Extract zone data

ams/io/xlsx.py

@@ -7,7 +7,8 @@ import logging
 
 from andes.io.xlsx import (read, testlines, confirm_overwrite, _add_book)  # NOQA
 
-from ams.shared import pd, empty_adsys, ad_models
+from ams.shared import pd
+from ams.shared import summary_row, summary_name, model2df
 
 
 logger = logging.getLogger(__name__)
@@ -20,7 +21,8 @@ def write(system, outfile,
     """
     Write loaded AMS system data into an xlsx file
 
-    Revised function ``andes.io.xlsx.write`` to skip non-andes models.
+    Revised from `andes.io.xlsx.write`, where non-ANDES models
+    are skipped if `to_andes` is True.
 
     Parameters
     ----------
@@ -59,22 +61,25 @@ def _write_system(system, writer, skip_empty, to_andes=False):
     """
     Write the system to pandas ExcelWriter
 
-    Rewrite function ``andes.io.xlsx._write_system`` to skip non-andes sheets.
+    Revised from `andes.io.xlsx._write_system`, where non-ANDES models
+    are skipped if `to_andes` is True.
     """
+    summary_found = False
     for name, instance in system.models.items():
-        if skip_empty and instance.n == 0:
+        df = model2df(instance, skip_empty, to_andes=to_andes)
+        if df is None:
             continue
-        instance.cache.refresh("df_in")
-        if to_andes:
-            if name not in ad_models:
-                continue
-            # NOTE: ommit parameters that are not in ANDES
-            skip_params = []
-            ams_params = list(instance.params.keys())
-            andes_params = list(empty_adsys.models[name].params.keys())
-            skip_params = list(set(ams_params) - set(andes_params))
-            df = instance.cache.df_in.drop(skip_params, axis=1, errors='ignore')
-        else:
-            df = instance.cache.df_in
+
+        if name == summary_name:
+            df = pd.concat([pd.DataFrame([summary_row]), df], ignore_index=True)
+            df.index.name = "uid"
+            summary_found = True
+
         df.to_excel(writer, sheet_name=name, freeze_panes=(1, 0))
+
+    if not summary_found:
+        df = pd.DataFrame([summary_row])
+        df.index.name = "uid"
+        df.to_excel(writer, sheet_name=summary_name, freeze_panes=(1, 0))
+
     return writer

ams/main.py

@@ -48,7 +48,7 @@ def config_logger(stream_level=logging.INFO, *,
     stream : bool, optional
         Create a `StreamHandler` for `stdout` if ``True``.
         If ``False``, the handler will not be created.
-    file : bool, optionsl
+    file : bool, optional
         True if logging to ``log_file``.
     log_file : str, optional
         Logg file name for `FileHandler`, ``'ams.log'`` by default.
@@ -67,9 +67,12 @@ def config_logger(stream_level=logging.INFO, *,
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
     lg = logging.getLogger('ams')
     lg.setLevel(logging.DEBUG)
@@ -118,6 +121,7 @@ def load(case, setup=True,
     """
     Load a case and set up a system without running routine.
     Return a system.
+    Revised from `andes.main.load`.
 
     Takes other kwargs recognizable by ``System``,
     such as ``addfile``, ``input_path``, and ``no_putput``.
@@ -137,12 +141,6 @@ def load(case, setup=True,
     If one need to add devices in addition to these from the case
     file, do ``setup=False`` and call ``System.add()`` to add devices.
     When done, manually invoke ``setup()`` to set up the system.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
     """
     if use_input_path:
         input_path = kwargs.get('input_path', '')
@@ -172,6 +170,8 @@ def run_case(case, *, routine='pflow', profile=False,
     Run single simulation case for the given full path.
     Use ``run`` instead of ``run_case`` whenever possible.
 
+    Revised from `andes.main.run_case`.
+
     Argument ``input_path`` will not be prepended to ``case``.
 
     Arguments recognizable by ``load`` can be passed to ``run_case``.
@@ -192,12 +192,6 @@ def run_case(case, *, routine='pflow', profile=False,
     add_book : str, optional
         Name of the device to be added to an excel case
         as a new sheet.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
     """
 
     pr = cProfile.Profile()
@@ -270,9 +264,12 @@ def _run_mp_proc(cases, ncpu=NCPUS_PHYSICAL, **kwargs):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
 
     # start processes
@@ -310,9 +307,12 @@ def _run_mp_pool(cases, ncpu=NCPUS_PHYSICAL, verbose=logging.INFO, **kwargs):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
 
     pool = Pool(ncpu)
@@ -369,9 +369,12 @@ def run(filename, input_path='', verbose=20, mp_verbose=30,
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
 
     if is_interactive() and len(logger.handlers) == 0:
@@ -497,9 +500,12 @@ def misc(edit_config='', save_config='', show_license=False, clean=True, recursi
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
 
     if edit_conf(edit_config):
@@ -527,13 +533,8 @@ def misc(edit_config='', save_config='', show_license=False, clean=True, recursi
 
 def doc(attribute=None, list_supported=False, config=False, **kwargs):
     """
-    Quick documentation from command-line.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
+    Quick documentation from command-line,
+    revised from `andes.main.doc`.
     """
     system = System()
     if attribute is not None:
@@ -558,13 +559,8 @@ def demo(**kwargs):
 
 def versioninfo():
     """
-    Print version info for AMS and dependencies.
-
-    Notes
-    -----
-    Revised from the ANDES project (https://github.com/CURENT/andes).
-    Original author: Hantao Cui
-    License: GPL3
+    Print version info for AMS and dependencies,
+    revised from `andes.main.versioninfo`.
     """
 
     import numpy as np
@@ -630,9 +626,12 @@ def edit_conf(edit_config: Optional[Union[str, bool]] = ''):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
     ret = False
 
@@ -689,9 +688,12 @@ def save_conf(config_path=None, overwrite=None, **kwargs):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
     ret = False
 
@@ -729,9 +731,12 @@ def remove_output(recursive=False):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
     found = False
     cwd = os.getcwd()
@@ -764,9 +769,12 @@ def selftest(quick=False, extra=False, **kwargs):
 
     Notes
     -----
-    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Copied from the ANDES project:
+    https://github.com/CURENT/andes
+
     Original author: Hantao Cui
-    License: GPL3
+
+    License: GNU General Public License v3.0 (GPL-3.0)
     """
 
     # map verbosity level from logging to unittest

ams/models/distributed/esd1.py

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