ltbams 1.0.9__py3-none-any.whl → 1.0.11__py3-none-any.whl

ams/core/__init__.py

@@ -1,2 +1,3 @@
 from ams.core.model import Model  # NOQA
 from ams.core.var import Algeb  # NOQA
+from ams.core.common import Config  # NOQA

ams/core/common.py

@@ -0,0 +1,30 @@
+import logging
+
+from andes.core.common import Config as AndesConfig
+
+logger = logging.getLogger(__name__)
+
+
+class Config(AndesConfig):
+    """
+    A class for storing configuration, can be used in system,
+    model, routine, and other modules.
+
+    Revised from `andes.core.common.Config`.
+    """
+
+    def __init__(self, name, dct=None, **kwargs):
+        super().__init__(name, dct, **kwargs)
+
+    def update(self, dct: dict = None, **kwargs):
+        """
+        Update the configuration from a file.
+        """
+        if dct is not None:
+            kwargs.update(dct)
+
+        for key, val in kwargs.items():
+            self._set(key, val)
+            self._dict[key] = val
+
+        self.check()

ams/core/documenter.py

@@ -6,26 +6,12 @@ import re
 
 import logging
 from collections import OrderedDict
-from andes.core.documenter import Documenter as andes_Documenter
 from andes.utils.tab import make_doc_table, math_wrap
 
 logger = logging.getLogger(__name__)
 
 
-def disable_method(func):
-    def wrapper(*args, **kwargs):
-        msg = f"Method `{func.__name__}` is included in ANDES Documenter but not supported in AMS Documenter."
-        logger.warning(msg)
-        return None
-    return wrapper
-
-
-def disable_methods(methods):
-    for method in methods:
-        setattr(Documenter, method, disable_method(getattr(Documenter, method)))
-
-
-class Documenter(andes_Documenter):
+class Documenter:
     """
     Helper class for documenting models.
 
@@ -37,16 +23,6 @@ class Documenter(andes_Documenter):
 
     def __init__(self, parent):
         self.parent = parent
-        self.system = parent.system
-        self.class_name = parent.class_name
-        self.config = parent.config
-        self.params = parent.params
-        self.algebs = parent.algebs
-        self.services = parent.services
-
-        func_to_disable = ['_init_doc', '_eq_doc',
-                           '_discrete_doc', '_block_doc']
-        disable_methods(func_to_disable)
 
     def get(self, max_width=78, export='plain'):
         """
@@ -68,14 +44,15 @@ class Documenter(andes_Documenter):
         if export == 'rest':
             max_width = 0
             model_header = '-' * 80 + '\n'
-            out += f'.. _{self.class_name}:\n\n'
+            out += f'.. _{self.parent.class_name}:\n\n'
         else:
             model_header = ''
 
         if export == 'rest':
-            out += model_header + f'{self.class_name}\n' + model_header
+            out += model_header + f'{self.parent.class_name}\n' + model_header
         else:
-            out += model_header + f'Model <{self.class_name}> in Group <{self.parent.group}>\n' + model_header
+            out += model_header + \
+                f'Model <{self.parent.class_name}> in Group <{self.parent.group}>\n' + model_header
 
         if self.parent.__doc__ is not None:
             out += inspect.cleandoc(self.parent.__doc__)
@@ -86,20 +63,35 @@ class Documenter(andes_Documenter):
         out += self._var_doc(max_width=max_width, export=export)
         out += self._service_doc(max_width=max_width, export=export)
         # TODO: fix and add the config doc later on
-        # out += self.config.doc(max_width=max_width, export=export)
+        # out += self.parent.config.doc(max_width=max_width, export=export)
 
         return out
 
     def _var_doc(self, max_width=78, export='plain'):
+        """
+        Export formatted model variable documentation as a string.
+
+        Parameters
+        ----------
+        max_width : int, optional = 80
+            Maximum table width. If export format is ``rest`` it will be unlimited.
+        export : str, optional = 'plain'
+            Export format, 'plain' for plain text, 'rest' for restructuredText.
+
+        Returns
+        -------
+        str
+            Tabulated output in a string
+        """
         # variable documentation
-        if len(self.algebs) == 0:
+        if len(self.parent.algebs) == 0:
             return ''
 
         names, symbols, units = list(), list(), list()
         info = list()
         units_rest, ty = list(), list()
 
-        for p in self.algebs.values():
+        for p in self.parent.algebs.values():
             names.append(p.name)
             ty.append(p.class_name)
             info.append(p.info if p.info else '')
@@ -110,7 +102,7 @@ class Documenter(andes_Documenter):
 
         # replace with latex math expressions if export is ``rest``
         if export == 'rest':
-            symbols = [item.tex_name for item in self.algebs.values()]
+            symbols = [item.tex_name for item in self.parent.algebs.values()]
             symbols = math_wrap(symbols, export=export)
             title = 'Variables\n---------'
 
@@ -132,14 +124,29 @@ class Documenter(andes_Documenter):
                               rest_dict=rest_dict)
 
     def _service_doc(self, max_width=78, export='plain'):
-        if len(self.services) == 0:
+        """
+        Export formatted model service documentation as a string.
+
+        Parameters
+        ----------
+        max_width : int, optional = 80
+            Maximum table width. If export format is ``rest`` it will be unlimited.
+        export : str, optional = 'plain'
+            Export format, 'plain' for plain text, 'rest' for restructuredText.
+
+        Returns
+        -------
+        str
+            Tabulated output in a string
+        """
+        if len(self.parent.services) == 0:
             return ''
 
         names, symbols = list(), list()
         info = list()
         class_names = list()
 
-        for p in self.services.values():
+        for p in self.parent.services.values():
             names.append(p.name)
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
@@ -165,6 +172,74 @@ class Documenter(andes_Documenter):
                               plain_dict=plain_dict,
                               rest_dict=rest_dict)
 
+    def _param_doc(self, max_width=78, export='plain'):
+        """
+        Export formatted model parameter documentation as a string.
+
+        Parameters
+        ----------
+        max_width : int, optional = 80
+            Maximum table width. If export format is ``rest`` it will be unlimited.
+
+        export : str, optional = 'plain'
+            Export format, 'plain' for plain text, 'rest' for restructuredText.
+
+        Returns
+        -------
+        str
+            Tabulated output in a string
+        """
+        if len(self.parent.params) == 0:
+            return ''
+
+        # prepare temporary lists
+        names, units, class_names = list(), list(), list()
+        info, defaults, properties = list(), list(), list()
+        units_rest = list()
+
+        for p in self.parent.params.values():
+            names.append(p.name)
+            class_names.append(p.class_name)
+            info.append(p.info if p.info else '')
+            defaults.append(p.default if p.default is not None else '')
+            units.append(f'{p.unit}' if p.unit else '')
+            units_rest.append(f'*{p.unit}*' if p.unit else '')
+
+            plist = []
+            for key, val in p.property.items():
+                if val is True:
+                    plist.append(key)
+            properties.append(','.join(plist))
+
+        # symbols based on output format
+        if export == 'rest':
+            symbols = [item.tex_name for item in self.parent.params.values()]
+            symbols = math_wrap(symbols, export=export)
+            title = 'Parameters\n----------'
+        else:
+            symbols = [item.name for item in self.parent.params.values()]
+            title = 'Parameters'
+
+        plain_dict = OrderedDict([('Name', names),
+                                  ('Description', info),
+                                  ('Default', defaults),
+                                  ('Unit', units),
+                                  ('Properties', properties)])
+
+        rest_dict = OrderedDict([('Name', names),
+                                 ('Symbol', symbols),
+                                 ('Description', info),
+                                 ('Default', defaults),
+                                 ('Unit', units_rest),
+                                 ('Properties', properties)])
+
+        # convert to rows and export as table
+        return make_doc_table(title=title,
+                              max_width=max_width,
+                              export=export,
+                              plain_dict=plain_dict,
+                              rest_dict=rest_dict)
+
 
 class RDocumenter:
     """
@@ -172,20 +247,12 @@ class RDocumenter:
 
     Parameters
     ----------
-    parent : Model
-        The `Model` instance to document
+    parent : ams.core.routine.RoutineBase
+        The `RoutineBase` instance to document
     """
 
     def __init__(self, parent):
         self.parent = parent
-        self.system = parent.system
-        self.class_name = parent.class_name
-        self.config = parent.config
-        self.services = parent.services
-        self.rparams = parent.rparams
-        self.vars = parent.vars
-        self.constrs = parent.constrs
-        self.obj = parent.obj
 
     def get(self, max_width=78, export='plain'):
         """
@@ -207,14 +274,15 @@ class RDocumenter:
         if export == 'rest':
             max_width = 0
             model_header = '-' * 80 + '\n'
-            out += f'.. _{self.class_name}:\n\n'
+            out += f'.. _{self.parent.class_name}:\n\n'
         else:
             model_header = ''
 
         if export == 'rest':
-            out += model_header + f'{self.class_name}\n' + model_header
+            out += model_header + f'{self.parent.class_name}\n' + model_header
         else:
-            out += model_header + f'Routine <{self.class_name}> in Type <{self.parent.type}>\n' + model_header
+            out += model_header + \
+                f'Routine <{self.parent.class_name}> in Type <{self.parent.type}>\n' + model_header
 
         if self.parent.__doc__ is not None:
             out += inspect.cleandoc(self.parent.__doc__)
@@ -229,20 +297,20 @@ class RDocumenter:
         out += self._exprc_doc(max_width=max_width, export=export)
         out += self._service_doc(max_width=max_width, export=export)
         out += self._param_doc(max_width=max_width, export=export)
-        out += self.config.doc(max_width=max_width, export=export)
+        out += self.parent.config.doc(max_width=max_width, export=export)
 
         return out
 
     def _service_doc(self, max_width=78, export='plain'):
         # routine service documentation
-        if len(self.services) == 0:
+        if len(self.parent.services) == 0:
             return ''
 
         names, symbols = list(), list()
         info = list()
         class_names = list()
 
-        for p in self.services.values():
+        for p in self.parent.services.values():
             names.append(p.name)
             info.append(p.info if p.info else '')
             class_names.append(p.class_name)
@@ -251,7 +319,7 @@ class RDocumenter:
 
         # replace with latex math expressions if export is ``rest``
         if export == 'rest':
-            symbols = [item.tex_name for item in self.services.values()]
+            symbols = [item.tex_name for item in self.parent.services.values()]
             symbols = math_wrap(symbols, export=export)
             title = 'Services\n---------'
 
@@ -272,13 +340,13 @@ class RDocumenter:
 
     def _constr_doc(self, max_width=78, export='plain'):
         # constraint documentation
-        if len(self.constrs) == 0:
+        if len(self.parent.constrs) == 0:
             return ''
 
         # prepare temporary lists
         names, class_names, info = list(), list(), list()
 
-        for p in self.constrs.values():
+        for p in self.parent.constrs.values():
             names.append(p.name)
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
@@ -286,7 +354,7 @@ class RDocumenter:
         # expressions based on output format
         expressions = []
         if export == 'rest':
-            for p in self.constrs.values():
+            for p in self.parent.constrs.values():
                 expr = _tex_pre(self, p, self.parent.syms.tex_map)
                 if p.is_eq:
                     expr = f'{expr} = 0'
@@ -460,7 +528,7 @@ class RDocumenter:
         # NOTE: this is for the optimization variables
         # not the _var_doc for ANDES parameters
         # variable documentation
-        if len(self.vars) == 0:
+        if len(self.parent.vars) == 0:
             return ''
 
         # prepare temporary lists
@@ -469,7 +537,7 @@ class RDocumenter:
         sources = list()
         units_rest = list()
 
-        for p in self.vars.values():
+        for p in self.parent.vars.values():
             names.append(p.name)
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
@@ -493,11 +561,11 @@ class RDocumenter:
 
         # symbols based on output format
         if export == 'rest':
-            symbols = [item.tex_name for item in self.vars.values()]
+            symbols = [item.tex_name for item in self.parent.vars.values()]
             symbols = math_wrap(symbols, export=export)
             title = 'Vars\n----------------------------------'
         else:
-            symbols = [item.name for item in self.vars.values()]
+            symbols = [item.name for item in self.parent.vars.values()]
             title = 'Vars'
 
         plain_dict = OrderedDict([('Name', names),
@@ -536,7 +604,7 @@ class RDocumenter:
         str
             Tabulated output in a string
         """
-        if len(self.rparams) == 0:
+        if len(self.parent.rparams) == 0:
             return ''
 
         # prepare temporary lists
@@ -545,7 +613,7 @@ class RDocumenter:
         sources = list()
         units_rest = list()
 
-        for p in self.rparams.values():
+        for p in self.parent.rparams.values():
             names.append(p.name)
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
@@ -562,11 +630,11 @@ class RDocumenter:
 
         # symbols based on output format
         if export == 'rest':
-            symbols = [item.tex_name for item in self.rparams.values()]
+            symbols = [item.tex_name for item in self.parent.rparams.values()]
             symbols = math_wrap(symbols, export=export)
             title = 'Parameters\n----------------------------------'
         else:
-            symbols = [item.name for item in self.rparams.values()]
+            symbols = [item.name for item in self.parent.rparams.values()]
             title = 'Parameters'
 
         plain_dict = OrderedDict([('Name', names),

ams/core/model.py

@@ -7,13 +7,13 @@ from collections import OrderedDict
 from typing import Iterable
 
 import numpy as np
-from andes.core.common import Config
 from andes.core.param import ExtParam
 from andes.core.service import BaseService, BackRef
 from andes.utils.func import list_flatten
 
 from ams.core.documenter import Documenter
 from ams.core.var import Algeb
+from ams.core.common import Config
 
 from ams.utils.misc import deprec_get_idx
 

ams/core/symprocessor.py

@@ -174,7 +174,7 @@ class SymProcessor:
         # Constraints
         # NOTE: constraints are included in sub_map for ExpressionCalc
         # thus, they don't have the suffix `.v`
-        for cname, constraint in self.parent.constrs.items():
+        for cname, _ in self.parent.constrs.items():
             self.sub_map[rf"\b{cname}\b"] = f'self.rtn.{cname}.optz'
 
         # store tex names defined in `self.config`

ams/extension/eva.py

@@ -17,7 +17,6 @@ from collections import OrderedDict
 
 import scipy.stats as stats
 
-from andes.core import Config
 from andes.core.param import NumParam
 from andes.core.model import ModelData
 from andes.shared import np, pd
@@ -25,6 +24,7 @@ from andes.utils.misc import elapsed
 
 from ams.core.model import Model
 from ams.utils.paths import ams_root
+from ams.core import Config
 
 logger = logging.getLogger(__name__)
 

ams/interface.py

@@ -3,11 +3,12 @@ Module for interfacing ANDES
 """
 
 import os
+import json
 import logging
 from collections import OrderedDict, Counter
 
 from andes.utils.misc import elapsed
-from andes.system import System as andes_System
+from andes.system import System as adSystem
 
 from ams.utils import create_entry
 from ams.io import input_formats
@@ -81,7 +82,8 @@ def sync_adsys(amsys, adsys):
             try:
                 ad_mdl.set(src=param, attr='v', idx=idx,
                            value=am_mdl.get(src=param, attr='v', idx=idx))
-            except Exception:
+            except Exception as e:
+                logger.warning(f"Failed to sync parameter '{param}' for model '{mname}': {e}")
                 continue
     return True
 
@@ -105,7 +107,7 @@ def to_andes_pflow(system, no_output=False, default_config=True, **kwargs):
         Additional arguments to be passed to ``andes.system.System()``.
     """
 
-    adsys = andes_System(no_outpu=no_output, default_config=default_config, **kwargs)
+    adsys = adSystem(no_outpu=no_output, default_config=default_config, **kwargs)
     # FIXME: is there a systematic way to do this? Other config might be needed
     adsys.config.freq = system.config.freq
     adsys.config.mva = system.config.mva
@@ -242,24 +244,43 @@ def parse_addfile(adsys, amsys, addfile):
             logger.debug('Addfile format guessed as %s.', key)
             break
 
-    if key != 'xlsx':
-        logger.error('Addfile format "%s" is not supported yet.', add_format)
-        # FIXME: xlsx input file with dyr addfile result into KeyError: 'Toggle'
-        # add_parser = importlib.import_module('andes.io.' + add_format)
-        # if not add_parser.read_add(system, addfile):
-        #     logger.error('Error parsing addfile "%s" with %s parser.', addfile, add_format)
-        return adsys
+    # FIXME: xlsx input file with dyr addfile result into KeyError: 'Toggle'
+    # add_parser = importlib.import_module('andes.io.' + add_format)
+    # if not add_parser.read_add(system, addfile):
+    #     logger.error('Error parsing addfile "%s" with %s parser.', addfile, add_format)
 
     # Try parsing the addfile
     logger.info('Parsing additional file "%s"...', addfile)
 
-    reader = pd.ExcelFile(addfile)
+    if add_format == 'xlsx':
+        reads = pd.read_excel(addfile,
+                              sheet_name=None,
+                              index_col=0,
+                              engine='openpyxl',
+                              )
+    elif add_format == 'json':
+        if isinstance(addfile, str):
+            f = open(addfile, 'r')
+        else:
+            f = addfile
+
+        json_in = json.load(f)
+
+        if f is not addfile:
+            f.close()
+
+        reads = dict()
+        for keys, dct in json_in.items():
+            reads[keys] = pd.DataFrame(dct)
+    else:
+        logger.error("Unsupported addfile format, only 'xlsx' and 'json' formats are supported.")
+        return adsys
 
     pflow_mdl = list(pflow_dict.keys())
 
     pflow_mdls_overlap = []
     for mdl_name in pflow_dict.keys():
-        if mdl_name in reader.sheet_names:
+        if mdl_name in reads.keys():
             pflow_mdls_overlap.append(mdl_name)
 
     if len(pflow_mdls_overlap) > 0:
@@ -269,14 +290,10 @@ def parse_addfile(adsys, amsys, addfile):
 
     pflow_mdl_nonempty = [mdl for mdl in pflow_mdl if amsys.models[mdl].n > 0]
     logger.debug(f"Non-empty PFlow models: {pflow_mdl}")
-    pflow_df_models = pd.read_excel(addfile,
-                                    sheet_name=pflow_mdl_nonempty,
-                                    index_col=0,
-                                    engine='openpyxl',
-                                    )
-    # drop rows that all nan
-    for name, df in pflow_df_models.items():
-        df.dropna(axis=0, how='all', inplace=True)
+    pflow_df_models = {}
+    for key, df in reads.items():
+        if key in pflow_mdl_nonempty:
+            pflow_df_models[key] = df.dropna(axis=0, how='all', inplace=False)
 
     # collect idx_map if difference exists
     idx_map = OrderedDict([])
@@ -290,13 +307,12 @@ def parse_addfile(adsys, amsys, addfile):
             idx_map[name] = dict(zip(ad_idx, am_idx))
 
     # --- dynamic models to be added ---
-    mdl_to_keep = list(set(reader.sheet_names) - set(pflow_mdl))
+    mdl_to_keep = list(set(reads.keys()) - set(pflow_mdl))
     mdl_to_keep.sort(key=str.lower)
-    df_models = pd.read_excel(addfile,
-                              sheet_name=mdl_to_keep,
-                              index_col=0,
-                              engine='openpyxl',
-                              )
+    df_models = {}
+    for key, df in reads.items():
+        if key in mdl_to_keep:
+            df_models[key] = df.dropna(axis=0, how='all', inplace=False)
 
     # adjust models index
     for name, df in df_models.items():

ams/io/matpower.py

@@ -188,6 +188,9 @@ def mpc2system(mpc: dict, system) -> bool:
     Note that `mbase` in mpc is converted to `Sn`, but it is not actually used in
     MATPOWER nor AMS.
 
+    In converted AMS system, StaticGen idxes are 1-based, while the sequence follow
+    the order of the original MATPOWER data.
+
     Parameters
     ----------
     system : ams.system.System
@@ -401,22 +404,27 @@ def mpc2system(mpc: dict, system) -> bool:
                        )
 
     # --- Area ---
-    area_id = np.unique(system.Bus.area.v).astype(int)
-    for area in area_id:
-        area_idx = f'AREA_{area}'
-        system.add('Area', idx=area_idx, name=area)
-    bus_area = system.Bus.area.v
-    bus_area = [f'AREA_{int(area)}' for area in bus_area]
-    system.Bus.area.v = bus_area
+    area = system.Bus.area.v
+    area_map = {}
+    if area:
+        for a in set(area):
+            a_new = system.add('Area',
+                               param_dict=dict(idx=a, name=a))
+            area_map[a] = a_new
+        system.Bus.area.v = [area_map[a] for a in area]
 
     # --- Zone ---
-    zone_id = np.unique(system.Bus.zone.v).astype(int)
-    for zone in zone_id:
-        zone_idx = f'ZONE_{zone}'
-        system.add('Zone', idx=zone_idx, name=zone)
-    bus_zone = system.Bus.zone.v
-    bus_zone = [f'ZONE_{int(zone)}' for zone in bus_zone]
-    system.Bus.zone.v = bus_zone
+    zone = system.Bus.zone.v
+    zone_map = {}
+    if zone:
+        n_zone = system.Area.n
+        for z in set(zone):
+            z_new = system.add('Zone',
+                               param_dict=dict(idx=int(n_zone + 1),
+                                               name=f'{n_zone + 1}'))
+            zone_map[z] = z_new
+            n_zone += 1
+        system.Bus.zone.v = [zone_map[z] for z in zone]
 
     return True
 
@@ -506,8 +514,9 @@ def system2mpc(system) -> dict:
     # --- PQ ---
     if system.PQ.n > 0:
         pq_pos = system.Bus.idx2uid(system.PQ.bus.v)
-        bus[pq_pos, 2] = system.PQ.p0.v * base_mva
-        bus[pq_pos, 3] = system.PQ.q0.v * base_mva
+        u = system.PQ.u.v
+        bus[pq_pos, 2] = u * system.PQ.p0.v * base_mva
+        bus[pq_pos, 3] = u * system.PQ.q0.v * base_mva
 
     # --- Shunt ---
     if system.Shunt.n > 0:
@@ -695,11 +704,16 @@ def mpc2m(mpc: dict, outfile: str) -> str:
 
 def write(system, outfile: str, overwrite: bool = None) -> bool:
     """
-    Export an AMS system to a MATPOWER mpc file.
+    Export an AMS system to a MATPOWER M-file.
 
     This function converts an AMS system object into a MATPOWER-compatible
     mpc dictionary and writes it to a specified output file in MATPOWER format.
 
+    In the converted MPC, the indices of area (bus[:, 6]) and zone (bus[:, 10])
+    may differ from the original MPC. However, the mapping relationship is preserved.
+    For example, if the original MPC numbers areas starting from 1, the converted
+    MPC may number them starting from 0.
+
     Parameters
     ----------
     system : ams.system.System