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

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
     ----------
@@ -646,6 +646,8 @@ def mpc2m(mpc: dict, outfile: str) -> str:
         MATPOWER mpc dictionary.
     outfile : str
         Path to the output M-file.
+
+    .. versionadded:: 1.0.10
     """
     with open(outfile, 'w') as f:
         # Add version info
@@ -758,6 +760,8 @@ def write(system, outfile: str, overwrite: bool = None) -> bool:
     - Unlike the XLSX and JSON converters, this implementation uses value providers
       (`v`) instead of vin. As a result, any changes made through `model.set` will be
       reflected in the generated MPC.
+
+    .. versionadded:: 1.0.10
     """
     if not confirm_overwrite(outfile, overwrite=overwrite):
         return False

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
@@ -56,6 +57,8 @@ def write_raw(system, outfile: str, overwrite: bool = None):
         The output file path.
     overwrite : bool, optional
         If True, overwrite the file if it exists. If False, do not overwrite.
+
+    .. versionadded:: 1.0.10
     """
     if not confirm_overwrite(outfile, overwrite=overwrite):
         return False

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):

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: