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

docs/source/index.rst

@@ -0,0 +1,108 @@
+.. AMS documentation master file, created by
+   sphinx-quickstart on Thu Jan 26 15:32:32 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+==================
+AMS documentation
+==================
+**Useful Links**: `Source Repository`_ | `Report Issues`_ | `Q&A`_  | `LTB Repository`_
+| `ANDES Repository`_
+
+.. _`Source Repository`: https://github.com/CURENT/ams
+.. _`Report Issues`: https://github.com/CURENT/ams/issues
+.. _`Q&A`: https://github.com/CURENT/ams/discussions
+.. _`ANDES Repository`: https://github.com/CURENT/andes
+.. _`LTB Repository`: https://github.com/CURENT/
+
+LTB AMS is an open-source packages for scheduling modeling, serving as the market
+simulator for the CURENT Large scale Testbed (LTB).
+
+AMS enables **flexible** scheduling modeling and **interoprability** with the in-house
+dynamic simulator ANDES.
+
+.. panels::
+    :card: + intro-card text-center
+    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+
+    ---
+
+    Getting started
+    ^^^^^^^^^^^^^^^
+
+    New to AMS? Check out the getting started guides.
+
+    +++
+
+    .. link-button:: getting-started
+            :type: ref
+            :text: To the getting started guides
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+
+    Examples
+    ^^^^^^^^
+
+    The examples of using AMS for power system scheduling study.
+
+    +++
+
+    .. link-button:: scripting_examples
+            :type: ref
+            :text: To the examples
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+
+    Model development guide
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    New scheduling modeling in AMS.
+
+    +++
+
+    .. link-button:: development
+            :type: ref
+            :text: To the development guide
+            :classes: btn-block btn-secondary stretched-link
+    ---
+
+    API reference
+    ^^^^^^^^^^^^^
+
+    The API reference of AMS.
+
+    +++
+
+    .. link-button:: api_reference
+            :type: ref
+            :text: To the API reference
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+    :column: col-12 p-3
+
+    Using AMS for Research?
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+    Please cite our paper [Wang2025]_ if AMS is used in your research for
+    publication.
+
+
+.. [Wang2025] J. Wang et al., "Dynamics-incorporated Modeling Framework for Stability
+       Constrained Scheduling Under High-penetration of Renewable Energy," in IEEE
+       Transactions on Sustainable Energy, doi: 10.1109/TSTE.2025.3528027.
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: AMS Manual
+   :hidden:
+
+   getting_started/index
+   examples/index
+   modeling/index
+   release-notes
+   routineref
+   modelref
+   api

docs/source/modeling/example.rst

@@ -0,0 +1,159 @@
+Examples
+========
+
+One example is provided to demonstrate descriptive scheduling modeling.
+
+DCOPF
+----------
+
+
+DC optimal power flow (DCOPF) is a fundamental routine used in power system analysis.
+In this example, we demonstrate how to implement a DCOPF routine in a descriptive
+manner using AMS. Below is a simplified DCOPF code snippet.
+The full code can be found in :py:mod:`ams.routines.dcopf.DCOPF`.
+
+Data Section
+^^^^^^^^^^^^
+
+.. code-block:: python
+   :linenos:
+
+      class DCOPF(RoutineBase):
+
+          def __init__(self, system, config):
+              RoutineBase.__init__(self, system, config)
+              self.info = 'DC Optimal Power Flow'
+              self.type = 'DCED'
+              # --- Data Section ---
+              # --- generator cost ---
+              self.c1 = RParam(info='Gen cost coefficient 1',
+                               name='c1', tex_name=r'c_{1}', unit=r'$/(p.u.)', 
+                               model='GCost', src='c1',
+                               indexer='gen', imodel='StaticGen',)
+              # --- generator ---
+              self.ug = RParam(info='Gen connection status',
+                               name='ug', tex_name=r'u_{g}',
+                               model='StaticGen', src='u',
+                               no_parse=True)
+              self.ctrl = RParam(info='Gen controllability',
+                                 name='ctrl', tex_name=r'c_{trl}',
+                                 model='StaticGen', src='ctrl',
+                                 no_parse=True)
+              self.ctrle = NumOpDual(info='Effective Gen controllability',
+                                     name='ctrle', tex_name=r'c_{trl, e}',
+                                     u=self.ctrl, u2=self.ug,
+                                     fun=np.multiply, no_parse=True)
+              # --- load ---
+              self.pd = RParam(info='active demand',
+                               name='pd', tex_name=r'p_{d}',
+                               model='StaticLoad', src='p0',
+                               unit='p.u.',)
+              # --- line ---
+              self.rate_a = RParam(info='long-term flow limit',
+                                   name='rate_a', tex_name=r'R_{ATEA}',
+                                   unit='MVA', model='Line',)
+              # --- line angle difference ---
+              self.amax = NumOp(u=self.rate_a, fun=np.ones_like,
+                                rfun=np.dot, rargs=dict(b=np.pi),
+                                name='amax', tex_name=r'\theta_{max}',
+                                info='max line angle difference',
+                                no_parse=True,)
+              # --- connection matrix ---
+              self.Cg = RParam(info='Gen connection matrix',
+                               name='Cg', tex_name=r'C_{g}',
+                               model='mats', src='Cg',
+                               no_parse=True, sparse=True,)
+              # --- system matrix ---
+              self.Bbus = RParam(info='Bus admittance matrix',
+                                 name='Bbus', tex_name=r'B_{bus}',
+                                 model='mats', src='Bbus',
+                                 no_parse=True, sparse=True,)
+
+Lines 1-4: Derive subclass ``DCOPF`` from ``RoutineBase``.
+
+Lines 5-6: Define routine information and type.
+
+Lines 9-12: Define linear generator cost coefficients ``c1``, where it
+sources from ``GCost.c1`` and sorted by ``StaticGen.gen``.
+
+Lines 22-24: Define effective controllability as service ``ctrle``,
+where it multiplies ``ctrl`` and ``ug``.
+
+Lines 42-45: Define generator connection matrix ``Cg``, where it sources from
+matrix processor ``mats.Cg`` and is sparse.
+
+Model Section
+^^^^^^^^^^^^^
+
+.. code-block:: python
+   :linenos:
+   :lineno-start: 51
+
+              # --- Model Section ---
+              # --- generation ---
+              self.pg = Var(info='Gen active power',
+                            unit='p.u.',
+                            name='pg', tex_name=r'p_g',
+                            model='StaticGen', src='p',
+                            v0=self.pg0)
+              # --- bus ---
+              self.aBus = Var(info='Bus voltage angle',
+                              unit='rad',
+                              name='aBus', tex_name=r'\theta_{bus}',
+                              model='Bus', src='a',)
+              # --- power balance ---
+              pb = 'Bbus@aBus + Pbusinj + Cl@pd + Csh@gsh - Cg@pg'
+              self.pb = Constraint(name='pb', info='power balance',
+                                   e_str=pb, is_eq=True,)
+              # --- line flow ---
+              self.plf = Var(info='Line flow',
+                             unit='p.u.',
+                             name='plf', tex_name=r'p_{lf}',
+                             model='Line',)
+              self.plflb = Constraint(info='line flow lower bound',
+                                      name='plflb', type='uq',
+                                      e_str='-Bf@aBus - Pfinj - rate_a',)
+              self.plfub = Constraint(info='line flow upper bound',
+                                      name='plfub', type='uq',
+                                      e_str='Bf@aBus + Pfinj - rate_a',)
+              # --- objective ---
+              obj = 'sum(mul(c2, power(pg, 2)))'
+              obj += '+ sum(mul(c1, pg))'
+              obj += '+ sum(mul(ug, c0))'
+              self.obj = Objective(name='obj',
+                                   info='total cost', unit='$',
+                                   sense='min', e_str=obj,)
+
+Continued from the above code.
+
+Lines 53-57: Define variable ``pg``, where it links to ``StaticGen.p``
+and initial value ``pg0``.
+
+Lines 68-71: Define variable ``plf``, where it links to ``Line`` with
+no target source variable nor initial value.
+
+Lines 72-77: Define inequality constraints ``plflb`` and ``plfub``
+for line flow limits.
+
+Lines 79-84: Define objective function ``obj`` for minimizing total cost.
+
+Finalize
+^^^^^^^^
+
+Lastly, similar to finalize a device model, we need to finalize the routine
+by adding the ``RTED`` to the routine list in ``$HOME/ams/ams/routines/__init__.py``,
+where 'rted' is the file name, and 'RTED' is the routine name.
+
+.. code-block:: python
+
+      all_routines = OrderedDict([
+            ... ...
+            ('dcopf', ['DCOPF']),
+            ('ed', ['ED', 'EDDG', 'EDES']),
+            ('rted', ['RTED', 'RTEDDG', 'RTEDES', 'RTEDVIS']),
+            ... ...
+      ])
+
+.. note::
+      Refer to the documentation "Example - Customize Formulation"
+      for API customization that does not require modification of the source code.

docs/source/modeling/index.rst

@@ -0,0 +1,17 @@
+.. _development:
+
+===========
+Development
+===========
+
+This chapter introduces advanced topics on modeling with AMS.
+It aims to give an in-depth explanation of flexible dispatch mdoeling
+framework and the interoperation with dynamic simulation.
+
+.. toctree::
+    :maxdepth: 2
+
+    system
+    model
+    routine
+    example

docs/source/modeling/model.rst

@@ -0,0 +1,210 @@
+Device
+=========
+
+This section introduces the modeling of power system devices. Here the term
+"model" refers to the descriptive model of a device, which is used to
+hold the device-level data and variables, such as ``Bus``, ``Line``, and ``PQ``.
+
+AMS employs a similar model organization manner as ANDES, where the class
+``model`` is used to hold the device-level parameters and variables.
+
+.. note::
+
+   One major difference here is, in ANDES, two classes, ``ModelData`` and
+   ``Model``, are used to hold the device-level parameters and equations.
+
+Parameters
+------------
+Parameter is an atom element in building a power system model. Most parameters
+are read from an input file, and other parameters are calculated from the existing
+parameters.
+
+AMS leverages the parameter definition in ANDES, where four classes,
+``DataParam``, ``IdxParam``, ``NumParam``, and ``ExtParam`` are used.
+More details can be found in ANDES documentation
+`Development - Parameters <https://docs.andes.app/en/latest/modeling/parameters.html>`_.
+
+Variables
+-----------
+
+In AMS, the definition of variables ``Algeb`` is simplified from ANDES. The
+``Algeb`` class is used to define algebraic variables in the model level, which are used to
+exchange data with dynamic simulator.
+
+.. autoclass:: ams.core.var.Algeb
+    :noindex:
+
+      Algeb
+
+.. note::
+
+    The ``Algeb`` class here is not directly used for optimization purpose, we will discuss
+    its role further in the Routine section.
+
+Model
+--------------
+
+Encapsulating the parameters and variables, the ``Model`` class is used to define the
+device model.
+
+.. autoclass:: ams.core.model.Model
+    :noindex:
+
+      Model
+
+Examples
+------------
+
+The following two examples demonstrate how to define a device model in AMS.
+
+
+PV model
+^^^^^^^^^^^^^^
+
+In this example, we define a PV generator model ``PV`` in three steps, data
+definition, model definition, and manufacturing.
+
+First, we need to define the parameters needed in a ``PV``.
+not included in ANDES ``PVData``. In this example, we hold the parameters in
+a separate class ``GenParam``.
+
+.. code-block:: python
+
+    from andes.core.param import NumParam, ExtParam
+
+    class GenParam:
+        def __init__(self) -> None:
+            self.ctrl = NumParam(default=1,
+                                info="generator controllability",
+                                tex_name=r'c_{trl}',)
+            self.Pc1 = NumParam(default=0.0,
+                                info="lower real power output of PQ capability curve",
+                                tex_name=r'P_{c1}',
+                                unit='p.u.')
+            self.Pc2 = NumParam(default=0.0,
+                                info="upper real power output of PQ capability curve",
+                                tex_name=r'P_{c2}',
+                                unit='p.u.')
+
+            ......
+
+            self.pg0 = NumParam(default=0.0,
+                                info='real power start point',
+                                tex_name=r'p_{g0}',
+                                unit='p.u.',
+                                )
+
+Second, we define the ``PVModel`` model with two algebraic variables and an external parameter.
+
+.. code-block:: python
+
+    from ams.core.model import Model
+    from ams.core.var import Algeb
+
+    class PVModel(Model):
+
+        def __init__(self, system=None, config=None):
+            super().__init__(system, config)
+            self.group = 'StaticGen'
+
+            self.zone = ExtParam(model='Bus', src='zone', indexer=self.bus, export=False,
+                                info='Retrieved zone idx', vtype=str, default=None,
+                                )
+            self.p = Algeb(info='actual active power generation',
+                          unit='p.u.',
+                          tex_name='p',
+                          name='p',
+                          )
+            self.q = Algeb(info='actual reactive power generation',
+                          unit='p.u.',
+                          tex_name='q',
+                          name='q',
+                          )
+
+.. note::
+
+    The external parameter ``zone`` is added here to enable the zonal reserve dispatch,
+    but it is not included in ANDES ``PV``.
+
+Third, we manufacture these classes together as the ``PV`` model.
+
+.. code-block:: python
+
+    from andes.models.static.pv import PVData  # NOQA
+
+    class PV(PVData, GenParam, PVModel):
+        """
+        PV generator model.
+        """
+
+        def __init__(self, system, config):
+            PVData.__init__(self)
+            GenParam.__init__(self)
+            PVModel.__init__(self, system, config)
+
+Lastly, we need to finalize the model by adding the ``PV`` model to the model list in
+``$HOME/ams/ams/models/__init__.py``, where 'static' is the file name, and 'PV' is the
+model name.
+
+.. code-block:: python
+
+    ams_file_classes = list([
+        ('info', ['Summary']),
+        ('bus', ['Bus']),
+        ('static', ['PQ', 'PV', 'Slack']),
+        ... ...
+    ])
+
+.. note::
+
+    The device-level model development procedures is similar to ANDES.
+    The only difference is that a device-level model for dispatch is much simpler
+    than that for dynamic simulation.
+    In AMS, we only defines the data and small amount of variables.
+    In contrast, ANDES defines the data, variables, and equations for dynamic simulation.
+    Mode details for device-level model development can be found in ANDES documentation
+    `Development - Examples <https://docs.andes.app/en/latest/modeling/examples.html>`_.
+
+Line model
+^^^^^^^^^^^^^^
+
+In this example, we define a ``Line`` model, where the data is extended from existing
+ANDES ``LineData`` by including two extra parameters ``amin`` and ``amax``.
+
+.. code-block:: python
+
+    from andes.models.line.line import LineData
+    from andes.core.param import NumParam
+    from andes.shared import deg2rad
+
+    from ams.core.model import Model
+
+
+    class Line(LineData, Model):
+        """
+        AC transmission line model.
+
+        The model is also used for two-winding transformer. Transformers can set the
+        tap ratio in ``tap`` and/or phase shift angle ``phi``.
+
+        Notes
+        -----
+        There is a known issue that adding Algeb ``ud`` will cause Line.algebs run into
+        AttributeError: 'NoneType' object has no attribute 'n'. Not figured out why yet.
+        """
+
+        def __init__(self, system=None, config=None) -> None:
+            LineData.__init__(self)
+            Model.__init__(self, system, config)
+            self.group = 'ACLine'
+
+            self.amin = NumParam(default=-360 * deg2rad,
+                                info="minimum angle difference, from bus - to bus",
+                                unit='rad',
+                                tex_name=r'a_{min}',
+                                )
+            self.amax = NumParam(default=360 * deg2rad,
+                                info="maximum angle difference, from bus - to bus",
+                                unit='rad',
+                                tex_name=r'a_{max}',
+                                )

docs/source/modeling/routine.rst

@@ -0,0 +1,122 @@
+Routine
+===========
+
+Routine refers to scheduling-level model, and it includes two sectinos, namely,
+Data Section and Model Section.
+
+Data Section
+------------------
+
+A simplified code snippet for RTED is shown below as an example.
+
+.. code-block:: python
+
+    class RTED:
+
+        def __init__(self):
+            ... ...
+            self.R10 = RParam(info='10-min ramp rate',
+                              name='R10', tex_name=r'R_{10}',
+                              model='StaticGen', src='R10',
+                              unit='p.u./h',)
+            self.gs = ZonalSum(u=self.zg, zone='Zone',
+                               name='gs', tex_name=r'S_{g}',
+                               info='Sum Gen vars vector in shape of zone',
+                               no_parse=True, sparse=True)
+            ... ...
+            self.rbu = Constraint(name='rbu', is_eq=True,
+                                  info='RegUp reserve balance',
+                                  e_str = 'gs @ mul(ug, pru) - dud')
+            ... ...
+
+Routine Parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As discussed in previous section, actual data parameters are stored in the device-level models.
+Thus, in routines, parameters are retrieved from target devices given the device
+name and the parameter name.
+In the example above, ``R10`` is a 10-min ramp rate parameter for the static generator.
+The parameter is retrieved from the devices ``StaticGen`` with the parameter name ``R10``.
+
+Service
+^^^^^^^^^^^^
+
+Services are developed to assit the formulations.
+In the example above, ``ZonalSum`` is a service to sum the generator variables in a zone.
+Later, in the constraint, ``gs`` is multiplied to the reserve variable ``pru``.
+
+Model Section
+-----------------
+
+Descriptive Formulation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scheduling routine is the descriptive model of the optimization problem.
+
+Further, to facilitate the routine definition, AMS developed a class
+:py:mod:`ams.core.param.RParam` to pass the model data to multiple routine modeling.
+
+.. autoclass:: ams.core.param.RParam
+    :noindex:
+
+Numerical Optimization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Optimization model is the optimization problem. ``Var``, ``Constraint``, and
+``Objective`` are the basic building blocks of the optimization model. ``OModel``
+is the container of the optimization model.
+A summary table is shown below.
+
+.. currentmodule:: ams.opt
+.. autosummary::
+      :recursive:
+      :toctree: _generated
+
+      Var
+      Constraint
+      Objective
+      OModel
+
+Interoperation with ANDES
+-----------------------------------
+
+The interoperation with dynamic simulator invovles both file conversion and data exchange.
+In AMS, the built-in interface with ANDES is implemented in :py:mod:`ams.interface`.
+
+
+File Format Converter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Power flow data is the bridge between scheduling study and dynamics study,
+where it defines grid topology and power flow.
+An AMS case can be converted to an ANDES case, with the option to supply additional dynamic
+data.
+
+.. autofunction:: ams.interface.to_andes
+    :noindex:
+
+
+Data Exchange in Simulation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To achieve scheduling-dynamics cosimulation, it requires bi-directional data exchange between
+scheduling and dynamics study.
+From the perspective of AMS, two functions, ``send`` and ``receive``, are developed.
+The maping relationship for a specific routine is defined in the routine class as ``map1`` and
+``map2``.
+Additionally, a link table for the ANDES case is used for the controller connections.
+
+Module :py:mod:`ams.interface.Dynamic`, contains the necessary functions and classes for
+file conversion and data exchange.
+
+.. autoclass:: ams.interface.Dynamic
+    :noindex:
+    :members: send, receive
+
+When you use this interface, it automatically picks either the dynamic or static model based on the TDS initialization status.
+If the TDS is running, it selects the dynamic model; otherwise, it goes for the static model.
+For more details, check out the full API reference or take a look at the source code.
+
+.. note::
+      Check ANDES documentation
+      `StaticGen <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_
+      for more details about substituting static generators with dynamic generators.

docs/source/modeling/system.rst

@@ -0,0 +1,51 @@
+System
+======
+
+
+Overview
+--------
+System is the top-level class for organizing power system dispatch models
+and routines. The full API reference of System is found at
+:py:mod:`ams.system.System`.
+
+Dynamic Imports
+```````````````
+System dynamically imports groups, models, and routines at creation. To add new
+models, groups or routines, edit the corresponding file by adding entries
+following examples.
+
+.. autofunction:: ams.system.System.import_models
+    :noindex:
+
+.. autofunction:: ams.system.System.import_groups
+    :noindex:
+
+.. autofunction:: ams.system.System.import_routines
+    :noindex:
+
+.. autofunction:: ams.system.System.import_types
+    :noindex:
+
+
+Device-level Models
+------------------------
+AMS follows a similar device-level model organization of ANDES with a few differences.
+
+
+Routine-level Models
+------------------------
+In AMS, routines are responsible for collecting data, defining optimization
+problems, and solving them.
+
+
+Optimization
+--------------------------------------------
+
+Within the ``Routine``, the descriptive formulation are translated into
+`CVXPY <https://www.cvxpy.org/>`_ optimization problem with
+``Vars``, ``Constraints``, and ``Objective``.
+The full API reference of them can be found in :py:mod:`ams.opt.Var`,
+:py:mod:`ams.opt.Constraint`, and :py:mod:`ams.opt.Objective`.
+
+.. autoclass:: ams.opt.omodel.OModel
+    :noindex: