ltbams 0.9.9__py3-none-any.whl → 1.0.2__py3-none-any.whl

ams/io/pypower.py

@@ -0,0 +1,103 @@
+"""
+PYPOWER reader for AMS.
+"""
+import logging
+
+import numpy as np
+
+from ams.io.matpower import mpc2system, system2mpc
+
+logger = logging.getLogger(__name__)
+
+
+def testlines(infile):
+    """
+    Test if this file is in the PYPOWER format.
+
+    NOT YET IMPLEMENTED.
+    """
+    return True
+
+
+def read(system, file):
+    """
+    Read a PYPOWER case file into ppc and return an AMS system by calling ``ppc2system``.
+
+    Parameters
+    ----------
+    system : ams.system
+        Empty AMS system to load data into.
+    file : str
+        The path to the PYPOWER file.
+
+    Returns
+    -------
+    system : ams.system.System
+        The AMS system that loaded the data.
+    """
+    ppc = py2ppc(file)
+    return ppc2system(ppc, system)
+
+
+def py2ppc(infile: str) -> dict:
+    """
+    Parse PYPOWER file and return a dictionary with the data.
+
+    Parameters
+    ----------
+    infile : str
+        The path to the PYPOWER file.
+
+    Returns
+    -------
+    ppc : dict
+        The PYPOWER case dict.
+    """
+    exec(open(f"{infile}").read())
+    for name, value in locals().items():
+        # Check if the variable name starts with "case"
+        if name.startswith("case"):
+            ppc = value()
+    return ppc
+
+
+def ppc2system(ppc: dict, system) -> bool:
+    """
+    Alias for ``mpc2system``. Refer to :py:mod:`ams.io.matpower.mpc2system` for more details.
+
+    Load an PYPOWER case dict into an empth AMS system.
+
+    Parameters
+    ----------
+    ppc : dict
+        The PYPOWER case dict.
+    system : ams.system
+        Empty AMS system to load data into.
+
+    Returns
+    -------
+    bool
+        True if successful; False otherwise.
+    """
+    return mpc2system(ppc, system)
+
+
+def system2ppc(system) -> dict:
+    """
+    Alias for ``system2mpc``. Refer to :py:mod:`ams.io.matpower.system2mpc` for more details.
+
+    Convert data from an AMS system to an mpc dict.
+
+    In the ``gen`` section, slack generators preceeds PV generators.
+    """
+    mpc = system2mpc(system)
+    np.set_printoptions(suppress=True)
+    # Map the original bus indices to consecutive values
+    # Adjust discontinuous bus indices
+    BUS_I = mpc['bus'][:, 0].astype(int)
+    bus_map = {busi0: i for i, busi0 in enumerate(BUS_I)}
+    mpc['bus'][:, 0] = np.array([bus_map[busi0] for busi0 in BUS_I])
+    mpc['gen'][:, 0] = np.array([bus_map[busi0] for busi0 in mpc['gen'][:, 0].astype(int)])
+    mpc['branch'][:, 0] = np.array([bus_map[busi0] for busi0 in mpc['branch'][:, 0].astype(int)])
+    mpc['branch'][:, 1] = np.array([bus_map[busi0] for busi0 in mpc['branch'][:, 1].astype(int)])
+    return mpc

ams/io/xlsx.py

@@ -0,0 +1,80 @@
+"""
+Excel reader and writer for AMS.
+
+This module leverages the existing parser and writer in andes.io.xlsx.
+"""
+import logging
+
+from andes.io.xlsx import (read, testlines, confirm_overwrite, _add_book)  # NOQA
+
+from ams.shared import pd, empty_adsys, ad_models
+
+
+logger = logging.getLogger(__name__)
+
+
+def write(system, outfile,
+          skip_empty=True, overwrite=None, add_book=None,
+          to_andes=False,
+          ):
+    """
+    Write loaded AMS system data into an xlsx file
+
+    Revised function ``andes.io.xlsx.write`` to skip non-andes models.
+
+    Parameters
+    ----------
+    system : System
+        A loaded system with parameters
+    outfile : str
+        Path to the output file
+    skip_empty : bool
+        Skip output of empty models (n = 0)
+    overwrite : bool, optional
+        None to prompt for overwrite selection; True to overwrite; False to not overwrite
+    add_book : str, optional
+        An optional model to be added to the output spreadsheet
+    to_andes : bool, optional
+        Write to an ANDES system, where non-ANDES models are skipped
+
+    Returns
+    -------
+    bool
+        True if file written; False otherwise
+    """
+    if not confirm_overwrite(outfile, overwrite=overwrite):
+        return False
+
+    writer = pd.ExcelWriter(outfile, engine='xlsxwriter')
+    writer = _write_system(system, writer, skip_empty, to_andes=to_andes)
+    writer = _add_book(system, writer, add_book)
+
+    writer.close()
+
+    logger.info('xlsx file written to "%s"', outfile)
+    return True
+
+
+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.
+    """
+    for name, instance in system.models.items():
+        if skip_empty and instance.n == 0:
+            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
+        df.to_excel(writer, sheet_name=name, freeze_panes=(1, 0))
+    return writer

ams/main.py

@@ -60,9 +60,16 @@ def config_logger(stream_level=logging.INFO, *,
         `StreamHandler` verbosity level.
     file_level : {10, 20, 30, 40, 50}, optional
         `FileHandler` verbosity level.
+
     Returns
     -------
     None
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
     lg = logging.getLogger('ams')
     lg.setLevel(logging.DEBUG)
@@ -105,7 +112,6 @@ def config_logger(stream_level=logging.INFO, *,
         coloredlogs.install(logger=lg, level=stream_level, fmt=sh_formatter_str)
 
 
-# TODO: check ``load`` later on to see if some of them can be removed
 def load(case, setup=True,
          use_input_path=True,
          **kwargs):
@@ -131,6 +137,12 @@ 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', '')
@@ -180,6 +192,12 @@ 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()
@@ -249,6 +267,12 @@ def _run_mp_proc(cases, ncpu=NCPUS_PHYSICAL, **kwargs):
     Run multiprocessing with `Process`.
 
     Return values from `run_case` are not preserved. Always return `True` when done.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     # start processes
@@ -283,6 +307,12 @@ def _run_mp_pool(cases, ncpu=NCPUS_PHYSICAL, verbose=logging.INFO, **kwargs):
         Verbosity level during multiprocessing
     verbose : 10, 20, 30, 40, 50
         Verbosity level outside multiprocessing
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     pool = Pool(ncpu)
@@ -337,6 +367,11 @@ def run(filename, input_path='', verbose=20, mp_verbose=30,
     System or exit_code
         An instance of system (if `cli == False`) or an exit code otherwise..
 
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     if is_interactive() and len(logger.handlers) == 0:
@@ -459,6 +494,12 @@ def misc(edit_config='', save_config='', show_license=False, clean=True, recursi
          overwrite=None, version=False, **kwargs):
     """
     Miscellaneous commands.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     if edit_conf(edit_config):
@@ -487,6 +528,12 @@ 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
     """
     system = System()
     if attribute is not None:
@@ -512,19 +559,25 @@ 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
     """
 
     import numpy as np
     import cvxpy
     import andes
-    from ams.shared import INSTALLED_SOLVERS
+    from ams.shared import installed_solvers
 
     versions = {'Python': platform.python_version(),
                 'ams': get_versions()['version'],
                 'andes': andes.__version__,
                 'numpy': np.__version__,
                 'cvxpy': cvxpy.__version__,
-                'solvers': ', '.join(INSTALLED_SOLVERS),
+                'solvers': ', '.join(installed_solvers),
                 }
     maxwidth = max([len(k) for k in versions.keys()])
 
@@ -574,6 +627,12 @@ def edit_conf(edit_config: Optional[Union[str, bool]] = ''):
     -------
     bool
         ``True`` is a config file is found and an editor is opened. ``False`` if ``edit_config`` is False.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
     ret = False
 
@@ -627,6 +686,12 @@ def save_conf(config_path=None, overwrite=None, **kwargs):
     -------
     bool
         ``True`` is the save action is run. ``False`` otherwise.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
     ret = False
 
@@ -644,7 +709,7 @@ def save_conf(config_path=None, overwrite=None, **kwargs):
     return ret
 
 
-# TODO: list AMS output files here
+# TODO: change to AMS output types
 def remove_output(recursive=False):
     """
     Remove the outputs generated by AMS, including power flow reports
@@ -661,6 +726,12 @@ def remove_output(recursive=False):
     bool
         ``True`` is the function body executes with success. ``False``
         otherwise.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
     found = False
     cwd = os.getcwd()
@@ -690,6 +761,12 @@ def remove_output(recursive=False):
 def selftest(quick=False, extra=False, **kwargs):
     """
     Run unit tests.
+
+    Notes
+    -----
+    Copied from the ANDES project (https://github.com/CURENT/andes).
+    Original author: Hantao Cui
+    License: GPL3
     """
 
     # map verbosity level from logging to unittest

ams/models/__init__.py

@@ -0,0 +1,24 @@
+"""
+The package for models used in scheduling modeling.
+
+The file_classes includes the list of file classes and their corresponding classes.
+"""
+
+
+ams_file_classes = list([
+    ('info', ['Summary']),
+    ('bus', ['Bus']),
+    ('static', ['PQ', 'Slack', 'PV']),
+    ('shunt', ['Shunt']),
+    ('line', ['Line', 'Jumper']),
+    ('distributed', ['PVD1', 'ESD1', 'EV1', 'EV2']),
+    ('renewable', ['REGCA1', 'REGCV1', 'REGCV2']),
+    ('area', ['Area']),
+    ('zone', ['Zone']),
+    ('reserve', ['SFR', 'SR', 'NSR', 'VSGR']),
+    ('cost', ['GCost', 'SFRCost', 'SRCost', 'NSRCost', 'VSGCost']),
+    ('cost', ['DCost']),
+    ('timeslot', ['TimeSlot', 'EDTSlot', 'UCTSlot']),
+])
+
+file_classes = ams_file_classes

ams/models/area.py

@@ -0,0 +1,40 @@
+import logging
+
+from andes.models.area import AreaData
+from andes.utils.tab import Tab
+from andes.core.service import BackRef
+
+from ams.core.model import Model
+
+logger = logging.getLogger(__name__)
+
+
+class Area(AreaData, Model):
+    """
+    Area model.
+    """
+    def __init__(self, system, config):
+        AreaData.__init__(self)
+        Model.__init__(self, system, config)
+
+        self.group = 'Collection'
+
+        self.Bus = BackRef()
+        self.ACTopology = BackRef()
+
+    def bus_table(self):
+        """
+        Return a formatted table with area idx and bus idx correspondence
+
+        Returns
+        -------
+        str
+            Formatted table
+
+        """
+        if self.n:
+            header = ['Area ID', 'Bus ID']
+            rows = [(i, j) for i, j in zip(self.idx.v, self.Bus.v)]
+            return Tab(header=header, data=rows).draw()
+        else:
+            return ''

ams/models/bus.py

@@ -0,0 +1,52 @@
+import logging
+
+import numpy as np
+
+from andes.core.param import NumParam
+from andes.models.bus import BusData
+
+from ams.core.var import Algeb
+from ams.core.model import Model
+
+logger = logging.getLogger(__name__)
+
+
+class Bus(BusData, Model):
+    """
+    AC Bus model.
+    """
+
+    def __init__(self, system, config):
+        BusData.__init__(self)
+        Model.__init__(self, system, config)
+
+        self.group = 'ACTopology'
+        # NOTE: in ANDES, self.zone is defined to trace a non-existing model "Zone"
+        # in AMS, model "Zone" is developed,
+        # so we need to change the model name of IdxParam self.zone
+        self.zone.model = 'Zone'
+
+        self.type = NumParam(name='type',
+                             info='bus type, 1=PQ, 2=PV, 3=ref, 4=isolated (place holder)',
+                             default=1,
+                             vtype=int,
+                             )
+
+        self.a = Algeb(name='a',
+                       tex_name=r'\theta',
+                       info='voltage angle',
+                       unit='rad',
+                       )
+        self.v = Algeb(name='v',
+                       tex_name='V',
+                       info='voltage magnitude',
+                       unit='p.u.',
+                       )
+
+        # island information
+        self.n_islanded_buses = 0
+        self.island_sets = list()
+        self.islanded_buses = list()  # list of lists containing bus uid of islands
+        self.islands = list()         # same as the above
+        self.islanded_a = np.array([])
+        self.islanded_v = np.array([])

ams/models/cost.py

@@ -0,0 +1,169 @@
+"""
+Cost model.
+"""
+
+from andes.core import (ModelData, IdxParam, NumParam)
+
+from ams.core.model import Model
+
+
+class GCostData(ModelData):
+    def __init__(self):
+        super().__init__()
+        self.gen = IdxParam(info="static generator index",
+                            model='StaticGen',
+                            mandatory=True,
+                            )
+        self.type = NumParam(default=2,
+                             info='Cost model type. 1 for piecewise linear, 2 for polynomial',
+                             power=False,
+                             tex_name=r't_{ype}',
+                             vrange=(1, 2),
+                             )
+        self.csu = NumParam(default=0,
+                            info='startup cost in US dollars',
+                            power=False,
+                            tex_name=r'c_{su}',
+                            unit='$',
+                            )
+        self.csd = NumParam(default=0,
+                            info='shutdown cost in US dollars',
+                            power=False,
+                            tex_name=r'c_{sd}',
+                            unit='$',
+                            )
+        self.c2 = NumParam(default=0,
+                           info='coefficient 2',
+                           power=False,
+                           tex_name=r'c_{2}',
+                           unit=r'$/(p.u.*h)^2',
+                           )
+        self.c1 = NumParam(default=0,
+                           info='coefficient 1',
+                           power=False,
+                           tex_name=r'c_{1}',
+                           unit=r'$/p.u.*h',
+                           )
+        self.c0 = NumParam(default=0,
+                           info='coefficient 0',
+                           power=False,
+                           tex_name=r'c_{0}',
+                           unit=r'$',
+                           )
+
+
+# TODO: double check the picewise linear part documentation
+class GCost(GCostData, Model):
+    """
+    Generator cost model, similar to MATPOWER ``gencost`` format.
+
+    ``type`` is the cost model type. 1 for piecewise linear, 2 for polynomial.
+
+    In piecewise linear cost model, cost function f(p) is defined by a set of points:
+    (p0, c0), (p1, c1), (p2, c2), where p0 < p1 < p2.
+
+    In quadratic cost model, cost function f(p) is defined by a set of coefficients:
+    f(p) = c2 * p^2 + c1 * p + c0.
+    """
+
+    def __init__(self, system, config):
+        GCostData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Cost'
+
+
+class SFRCost(ModelData, Model):
+    """
+    Linear SFR cost model.
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Cost'
+        self.gen = IdxParam(info="static generator index",
+                            model='StaticGen',
+                            mandatory=True,)
+        self.cru = NumParam(default=0,
+                            tex_name=r'c_{r}', unit=r'$/(p.u.*h)',
+                            info='cost for RegUp reserve',)
+        self.crd = NumParam(default=0,
+                            tex_name=r'c_{r}', unit=r'$/(p.u.*h)',
+                            info='cost for RegDn reserve',)
+
+
+class SRCost(ModelData, Model):
+    """
+    Linear spinning reserve cost model.
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.gen = IdxParam(info="static generator index",
+                            model='StaticGen',
+                            mandatory=True,)
+        self.csr = NumParam(default=0,
+                            tex_name=r'c_{sr}', unit=r'$/(p.u.*h)',
+                            info='cost for spinning reserve',)
+
+
+class NSRCost(ModelData, Model):
+    """
+    Linear non-spinning reserve cost model.
+    """
+
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.gen = IdxParam(info="static generator index",
+                            model='StaticGen',
+                            mandatory=True,)
+        self.cnsr = NumParam(default=0,
+                             tex_name=r'c_{nsr}', unit=r'$/(p.u.*h)',
+                             info='cost for non-spinning reserve',)
+
+
+class DCost(ModelData, Model):
+    """
+    Linear cost model for dispatchable loads.
+    """
+    def __init__(self, system, config):
+        ModelData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Cost'
+        self.pq = IdxParam(info="static load index",
+                           mandatory=True,)
+        self.cdp = NumParam(default=999,
+                            tex_name=r'c_{d,p}', unit=r'$/(p.u.*h)',
+                            info='cost for unserve load penalty',)
+
+
+class VSGCostData(ModelData):
+    def __init__(self):
+        super().__init__()
+        self.reg = IdxParam(info="Renewable generator idx",
+                            model='RenGen',
+                            mandatory=True,
+                            )
+        self.cm = NumParam(default=0,
+                           info='cost for emulated inertia (M)',
+                           tex_name=r'c_{r}',
+                           unit=r'$/s',
+                           )
+        self.cd = NumParam(default=0,
+                           info='cost for emulated damping (D)',
+                           tex_name=r'c_{r}',
+                           unit=r'$/p.u.',
+                           )
+
+
+class VSGCost(VSGCostData, Model):
+    """
+    Linear cost model for VSG emulated inertia (M) and damping (D).
+    """
+
+    def __init__(self, system, config):
+        VSGCostData.__init__(self)
+        Model.__init__(self, system, config)
+        self.group = 'Cost'

ams/models/distributed/__init__.py

@@ -0,0 +1,3 @@
+from ams.models.distributed.pvd1 import PVD1  # NOQA
+from ams.models.distributed.esd1 import ESD1  # NOQA
+from ams.models.distributed.ev import EV1, EV2  # NOQA