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

ams/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-05-23T00:18:06-0400",
+ "date": "2025-05-29T20:16:06-0400",
  "dirty": false,
  "error": null,
- "full-revisionid": "f467fb0017c81d3946c1c566802adc4f411ad05e",
- "version": "1.0.10"
+ "full-revisionid": "2166f4368af3d382720af38408153a70502eb9f5",
+ "version": "1.0.12"
 }
 '''  # END VERSION_JSON
 

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

@@ -3,7 +3,6 @@ Module for system matrix make.
 """
 
 import logging
-import os
 import sys
 from typing import Optional
 
@@ -14,6 +13,9 @@ from andes.shared import tqdm, tqdm_nb
 from andes.utils.misc import elapsed, is_notebook
 
 from ams.opt import Param
+
+from ams.utils.paths import get_export_path
+
 from ams.shared import pd, sps
 
 logger = logging.getLogger(__name__)
@@ -75,31 +77,28 @@ class MParam(Param):
         """
         Export the matrix to a CSV file.
 
+        In the exported CSV, columns are the bus idxes, and Line idxes are
+        used as row indexes.
+
         Parameters
         ----------
         path : str, optional
-            Path to the output CSV file.
+            Path of the csv file to export.
 
         Returns
         -------
         str
-            The path of the exported csv file
+            The exported csv file name
         """
 
-        if path is None:
-            if self.owner.system.files.fullname is None:
-                logger.info("Input file name not detacted. Using `Untitled`.")
-                file_name = f'Untitled_{self.name}'
-            else:
-                file_name = os.path.splitext(self.owner.system.files.fullname)[0]
-                file_name += f'_{self.name}'
-            path = os.path.join(os.getcwd(), file_name + '.csv')
-        else:
-            file_name = os.path.splitext(os.path.basename(path))[0]
+        path, file_name = get_export_path(self.owner.system,
+                                          self.name,
+                                          path=path,
+                                          fmt='csv')
 
         pd.DataFrame(data=self.v, columns=self.col_names, index=self.row_names).to_csv(path)
 
-        return file_name + '.csv'
+        return file_name
 
     @property
     def v(self):

ams/interface.py

@@ -8,7 +8,7 @@ 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
@@ -107,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

ams/io/matpower.py

@@ -455,16 +455,6 @@ def system2mpc(system) -> dict:
 
     This function is revised from ``andes.io.matpower.system2mpc``.
 
-    In the ``gen`` section, slack generators are listed before PV generators.
-
-    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.
-
-    The coefficients ``c2`` and ``c1`` in the generator cost data are scaled by
-    ``base_mva`` to match MATPOWER's unit convention (MW).
-
     Parameters
     ----------
     system : ams.core.system.System
@@ -474,6 +464,21 @@ def system2mpc(system) -> dict:
     -------
     mpc : dict
         A dictionary in MATPOWER format representing the converted AMS system.
+
+    Notes
+    -----
+    - In the `gen` section, slack generators are listed before PV generators.
+    - For uncontrolled generators (`ctrl.v == 0`), their max and min power
+      limits are set to their initial power (`p0.v`) in the converted MPC.
+    - 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.
+    - The coefficients `c2` and `c1` in the generator cost data are scaled by
+      `baseMVA`.
+    - 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.
     """
 
     mpc = dict(version='2',
@@ -514,15 +519,31 @@ def system2mpc(system) -> dict:
     # --- PQ ---
     if system.PQ.n > 0:
         pq_pos = system.Bus.idx2uid(system.PQ.bus.v)
-        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
+
+        p0e = system.PQ.u.v * system.PQ.p0.v
+        q0e = system.PQ.u.v * system.PQ.q0.v
+
+        # NOTE: ensure multiple PQ on the same bus are summed
+        # rather than overwritten. Same for Shunt.
+        p = np.zeros(system.Bus.n)
+        q = np.zeros(system.Bus.n)
+        np.add.at(p, pq_pos, p0e)
+        np.add.at(q, pq_pos, q0e)
+        bus[:, 2] = p * base_mva
+        bus[:, 3] = q * base_mva
 
     # --- Shunt ---
     if system.Shunt.n > 0:
         shunt_pos = system.Bus.idx2uid(system.Shunt.bus.v)
-        bus[shunt_pos, 4] = system.Shunt.g.v * base_mva
-        bus[shunt_pos, 5] = system.Shunt.b.v * base_mva
+
+        ge = system.Shunt.u.v * system.Shunt.g.v
+        be = system.Shunt.u.v * system.Shunt.b.v
+        g = np.zeros(system.Bus.n)
+        b = np.zeros(system.Bus.n)
+        np.add.at(g, shunt_pos, ge)
+        np.add.at(b, shunt_pos, be)
+        bus[:, 4] = g * base_mva
+        bus[:, 5] = b * base_mva
 
     # --- PV ---
     if system.PV.n > 0:
@@ -709,11 +730,6 @@ def write(system, outfile: str, overwrite: bool = None) -> bool:
     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
@@ -727,6 +743,21 @@ def write(system, outfile: str, overwrite: bool = None) -> bool:
     -------
     bool
         True if the file was successfully written, False otherwise.
+
+    Notes
+    -----
+    - In the `gen` section, slack generators are listed before PV generators.
+    - For uncontrolled generators (`ctrl.v == 0`), their max and min power
+      limits are set to their initial power (`p0.v`) in the converted MPC.
+    - 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.
+    - The coefficients `c2` and `c1` in the generator cost data are scaled by
+      `baseMVA`.
+    - 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.
     """
     if not confirm_overwrite(outfile, overwrite=overwrite):
         return False

ams/io/psse.py

@@ -46,6 +46,8 @@ def write_raw(system, outfile: str, overwrite: bool = None):
     """
     Convert AMS system to PSS/E RAW file.
 
+    This method has not been fully benchmarked yet!
+
     Parameters
     ----------
     system : System

ams/routines/grbopt.py

@@ -10,6 +10,8 @@ import scipy.io
 from andes.shared import np, pd
 from andes.utils.misc import elapsed
 
+from ams.core import Config
+
 from ams.io.pypower import system2ppc
 
 from ams.opt import Var, Objective
@@ -39,9 +41,13 @@ class OPF(DCPF1):
         self.info = 'Optimal Power Flow'
         self.type = 'ACED'
 
+        # Overwrite the config to be empty, as it is not used in this routine
+        self.config = Config(self.class_name)
+
         self.obj = Objective(name='obj',
                              info='total cost, placeholder',
                              e_str='sum(c2 * pg**2 + c1 * pg + c0)',
+                             unit='$',
                              sense='min',)
 
         self.pi = Var(info='Lagrange multiplier on real power mismatch',
@@ -97,23 +103,22 @@ class OPF(DCPF1):
         """
         Run the OPF routine using gurobi-optimods.
 
-        This method invokes `self.solve(**kwargs)`, which internally utilizes
-        `gurobi-optimods` to solve the OPF problem.
+        This method invokes `gurobi-optimods.opf.solve_opf` to solve the OPF problem.
 
-        Keyword arguments
-        -------------------
-        - ``opftype`` : str
+        Parameters
+        ----------
+        - opftype : str
             Type of OPF to solve (default: 'AC').
-        - ``branch_switching`` : bool
+        - branch_switching : bool
             Enable branch switching (default: False).
-        - ``min_active_branches`` : float
+        - min_active_branches : float
             Defines the minimum number of branches that must be turned on when
             branch switching is active, i.e. the minimum number of turned on
             branches is equal to ``numbranches * min_active_branches``. Has no
             effect if ``branch_switching`` is set to False.
-        - ``use_mip_start`` : bool
+        - use_mip_start : bool
             Use MIP start (default: False).
-        - ``time_limit`` : float
+        - time_limit : float
             Time limit for the solver (default: 0.0, no limit).
         """
         if not self.initialized: