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

docs/source/modelref.rst

@@ -0,0 +1,66 @@
+.. _modelref:
+
+***************
+Model reference
+***************
+
+Use the left navigation pane to locate the group and model
+and view details.
+
+Supported Groups and Models
+
++---------------------+------------------------------------------------------+
+|        Group        |                        Models                        |
++=====================+======================================================+
+|  :ref:`ACLine`      | :ref:`Line`                                          |
++---------------------+------------------------------------------------------+
+|  :ref:`ACShort`     | :ref:`Jumper`                                        |
++---------------------+------------------------------------------------------+
+|  :ref:`ACTopology`  | :ref:`Bus`                                           |
++---------------------+------------------------------------------------------+
+|  :ref:`Collection`  | :ref:`Area`, :ref:`Zone`                             |
++---------------------+------------------------------------------------------+
+|  :ref:`Cost`        | :ref:`GCost`, :ref:`SFRCost`, :ref:`VSGCost`,        |
+|                     | :ref:`DCost`                                         |
++---------------------+------------------------------------------------------+
+|  :ref:`DG`          | :ref:`PVD1`, :ref:`ESD1`, :ref:`EV1`, :ref:`EV2`     |
++---------------------+------------------------------------------------------+
+|  :ref:`Horizon`     | :ref:`TimeSlot`, :ref:`EDTSlot`, :ref:`UCTSlot`      |
++---------------------+------------------------------------------------------+
+|  :ref:`Information` | :ref:`Summary`                                       |
++---------------------+------------------------------------------------------+
+|  :ref:`RenGen`      | :ref:`REGCA1`                                        |
++---------------------+------------------------------------------------------+
+|  :ref:`Reserve`     | :ref:`SFR`, :ref:`SR`, :ref:`NSR`, :ref:`VSGR`       |
++---------------------+------------------------------------------------------+
+|  :ref:`StaticGen`   | :ref:`Slack`, :ref:`PV`                              |
++---------------------+------------------------------------------------------+
+|  :ref:`StaticLoad`  | :ref:`PQ`                                            |
++---------------------+------------------------------------------------------+
+|  :ref:`StaticShunt` | :ref:`Shunt`                                         |
++---------------------+------------------------------------------------------+
+|  :ref:`Undefined`   | :ref:`SRCost`, :ref:`NSRCost`                        |
++---------------------+------------------------------------------------------+
+|  :ref:`VSG`         | :ref:`REGCV1`, :ref:`REGCV2`                         |
++---------------------+------------------------------------------------------+
+
+
+.. toctree ::
+    :maxdepth: 2
+    :hidden:
+
+    groupdoc/ACLine
+    groupdoc/ACShort
+    groupdoc/ACTopology
+    groupdoc/Collection
+    groupdoc/Cost
+    groupdoc/DG
+    groupdoc/Horizon
+    groupdoc/Information
+    groupdoc/RenGen
+    groupdoc/Reserve
+    groupdoc/StaticGen
+    groupdoc/StaticLoad
+    groupdoc/StaticShunt
+    groupdoc/Undefined
+    groupdoc/VSG

docs/source/release-notes.rst

@@ -0,0 +1,385 @@
+.. _ReleaseNotes:
+
+=============
+Release notes
+=============
+
+The APIs before v3.0.0 are in beta and may change without prior notice.
+
+Pre-v1.0.0
+==========
+
+v1.0.0 (2024-01-24)
+--------------------
+
+- **Breaking Change**: rename model ``Region`` to ``Zone`` for clarity. Prior case
+  files without modification can run into error.
+- Fix bugs in ``RTED.dc2ac``
+- Minor refacotr ``OptzBase.get_idx`` to reduce duplication
+- Rename module ``OptBase`` to ``OptzBase`` for clarity
+- Update benchamrk figure in README
+- Set ANDES requirement to v1.9.3
+- Deprecate method ``get_idx`` and suggest using ``get_all_idxes`` instead
+- Remove module ``benchmarks.py`` and its tests for simplicity
+
+v0.9.13 (2024-12-05)
+--------------------
+
+- Add a step to report in ``RoutineBase.run``
+- Add more tests to cover DG and ES related routines
+- Improve formulation for DG and ESD involved routines
+- Improve module ``Report`` and method ``RoutineBase.export_csv``
+- Support ``TimedEvent`` in ANDES case conversion
+- Add Var ``vBus`` in ``DCOPF`` for placeholder
+
+v0.9.12 (2024-11-23)
+--------------------
+
+- Refactor ``OModel.initialized`` as a property method
+- Add a demo to show using ``Constraint.e`` for debugging
+- Fix ``ams.opt.omodel.Param.evaluate`` when its value is a number
+- Improve ``ams.opt.omodel.ExpressionCalc`` for better performance
+- Refactor module ``ams.opt``
+- Add class ``ams.opt.Expression``
+- Switch from PYPOWER to ANDES in routine ``PFlow``
+- Switch from PYPOWER to regular formulation in routine ``DCPF``
+- Refactor routines ``DCPF`` and ``DCOPF``
+- In ``RDocumenter``, set Srouce to be owner if there is no src
+- Specify ``multiprocess<=0.70.16`` in requirements as 0.70.17 does not support Linux
+
+RC1
+~~~~
+- Reset setup.py to ensure compatibility
+
+v0.9.11 (2024-11-14)
+--------------------
+
+- Add pyproject.toml for PEP 517 and PEP 518 compliance
+- Add model ``Jumper``
+- Fix deprecation warning related to ``pandas.fillna`` and ``newshape`` in NumPy
+- Minor refactor on solvers information in the module ``shared``
+- Change default values of minimum ON/OFF duration time of generators to be 1 and 0.5 hours
+- Add parameter ``uf`` for enforced generator on/off status
+- In servicee ``LoadScale``, consider load online status
+- Consider line online status in routine ``ED``
+- Add methods ``evaluate`` and ``finalize`` in the class ``OModel`` to handle optimization 
+  elements generation and assembling
+- Refactor ``OModel.init`` and ``Routine.init``
+- Add ANDES paper as the citation file for now
+- Add more routine tests for generator trip, line trip, and load trip
+- Add a README to overview built-in cases
+- Rename methods ``v2`` as ``e`` for classes ``Constraint`` and ``Objective``
+- Add benchmark functions
+- Improve the usage of ``eval`` in module ``omodel``
+- Refactor module ``interop.andes`` as module ``interface`` for simplicity
+
+v0.9.10 (2024-09-03)
+--------------------
+
+Hotfix of import issue in ``v0.9.9``.
+
+- In module ``MatProcessor``, add two parameters ``permc_spec`` and ``use_umfpack`` in function ``build_ptdf``
+- Follow RTD's deprecation of Sphinx context injection at build time
+- In MATPOWER conversion, set devices name as None
+- Skip macOS tests in azure-pipelines due to failure in fixing its configuration
+- Prepare to support NumPy v2.0.0, but solvers have unexpected behavior
+- Improve the logic of setting ``Optz`` value
+- Support NumPy v2.0.0
+
+v0.9.9 (2024-09-02)
+-------------------
+
+**NOTICE: This version has known issues and has been yanked on PyPI.**
+
+v0.9.8 (2024-06-18)
+-------------------
+
+- Assign ``MParam.owner`` when declaring
+- In ``MatProcessor``, improve ``build_ptdf`` and ``build_lodf`` to allow partial building and
+  incremental building
+- Add file ``cases/matpower/Benchmark.json`` for benchmark with MATPOWER
+- Improve known good results test
+- Minor fix in ``main.py`` selftest part
+- Set dependency NumPy version to be <2.0.0 to avoid CVXPY compatibility issues
+
+v0.9.7 (2024-05-24)
+-------------------
+
+This patch release add the Roadmap section in the release notes, to list out some potential features.
+It also drafts the EV Aggregation model based on the state space modelg, but the finish date remains unknown.
+
+References:
+
+[1] J. Wang et al., "Electric Vehicles Charging Time Constrained Deliverable Provision of Secondary
+Frequency Regulation," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3356948.
+
+- Fix OTDF calculation
+- Add parameter ``dtype='float64'`` and ``no_store=False`` in ``MatProcessor`` PTDF, LODF, and OTDF
+  calculation, to save memory
+- Add placeholder parameter ``Bus.type``
+
+v0.9.6 (2024-04-21)
+-------------------
+
+This patch release refactor and improve ``MatProcessor``, where it support PTDF, LODF,
+and OTDF for static analysis.
+
+The reference can be found online "PowerWorld > Web Help > Sensitivities > Line
+Outage Distribution Factors".
+
+- Refactor DCPF, PFlow, and ACOPF
+- Add a loss factor in ``RTED.dc2ac``
+- Add ``DCOPF.dc2ac``
+- Fix OModel parse status to ensure no_parsed params can be updated
+- Fix and rerun ``ex2``
+- Format ``Routine.get`` return type to be consistent with input idx type
+- Remove unused ``Routine.prepare``
+- Refactor ``MatProcessor`` to separate matrix building
+- Add Var ``plf`` in ``DCPF``, ``PFlow``, and ``ACOPF`` to store the line flow
+- Add ``build_ptdf``, ``build_lodf``, and ``build_otdf``
+- Fix ``Routine.get`` to support pd.Series type idx input
+- Reserve ``exec_time`` after ``dc2ac``
+- Adjust kloss to fix ``ex2``
+
+v0.9.5 (2024-03-25)
+-------------------
+
+- Add more plots in ``demo_AGC``
+- Improve line rating adjustment
+- Adjust static import sequence in ``models.__init__.py``
+- Adjust pjm5bus case line rate_a
+- Fix formulation of constraint line angle diff
+- Align slack bus angle to zero in ``DCOPF``
+- Align StaticGen idx sequence with converted MATPOWER case
+- Fix several issues in MATPOWER converter
+
+v0.9.4 (2024-03-16)
+-------------------
+
+- Add Var ``pi`` and ExpressionCalc ``pic`` to store the dual of constraint power balance
+- Add Param ``M`` and ``D`` to model ``REGCV1``
+- Add CPS1 score calculation in ``demo_AGC``
+
+v0.9.3 (2024-03-06)
+-------------------
+
+- Major improvemets on ``demo_AGC``
+- Bug fix in ``RTED.dc2ac``
+
+v0.9.2 (2024-03-04)
+-------------------
+
+- Add ``demo_AGC`` to demonstrate detailed secondary frequency regulation study
+- Add ``ExpressionCalc`` to handle post-solving calculation
+- Rename ``type='eq'`` to ``is_eq=False`` in ``Constraint`` to avoid overriding built-in attribute
+- Several formatting improvements
+
+v0.9.1 (2024-03-02)
+-------------------
+
+- Change sphinx extension myst_nb to nbsphinx for math rendering in ``ex8``
+- Improve ``symprocessor`` to include routine config
+- Add config to Routine reference
+- Fix symbol processor issue with power operator
+
+v0.9.0 (2024-02-27)
+-------------------
+
+- Add ``ex8`` for formulation customization via API
+- Improve Development documentation
+- Fix ``addService``, ``addVars``
+- Rename ``RoutineModel`` to ``RoutineBase`` for better naming
+- Fix ANDES file converter issue
+- Initial release on conda-forge
+
+v0.8.5 (2024-01-31)
+-------------------
+
+- Improve quality of coverage and format
+- Fix dependency issue
+
+v0.8.4 (2024-01-30)
+-------------------
+
+- Version cleanup
+
+v0.8.3 (2024-01-30)
+-------------------
+
+- Initial release on PyPI
+
+v0.8.2 (2024-01-30)
+-------------------
+
+- Improve examples
+- Add module ``report`` and func ``RoutineBase.export_csv`` for results export
+
+v0.8.1 (2024-01-20)
+-------------------
+
+- Improve ``MatProcessor``
+- Add more examples
+- Improve ANDES interface
+
+v0.8.0 (2024-01-09)
+-------------------
+
+- Refactor ``DCED`` routines to improve performance
+
+v0.7.5 (2023-12-28)
+-------------------
+
+- Refactor ``MatProcessor`` and ``DCED`` routines to improve performance
+- Integrate sparsity pattern in ``RParam``
+- Rename energy storage routines ``RTED2``, ``ED2`` and ``UC2`` to ``RTEDES``, ``EDES`` and ``UCES``
+
+v0.7.4 (2023-11-29)
+-------------------
+
+- Refactor routins and optimization models to improve performance
+- Fix routines modeling
+- Add examples
+- Fix built-in cases
+
+v0.7.3 (2023-11-03)
+-------------------
+
+- Add tests
+
+v0.7.2 (2023-10-26)
+-------------------
+
+- Add routines ``ED2`` and ``UC2``
+- Minor fix on ``SymProcessor`` and ``Documenter``
+
+v0.7.1 (2023-10-12)
+-------------------
+
+- Add function ``_initial_guess`` to routine ``UC``
+- Refactor PYPOWER
+
+v0.7.0 (2023-09-22)
+-------------------
+
+- Add interfaces for customizing optimization
+- Add models ``REGCV1`` and ``REGCV1Cost`` for virtual inertia scheduling
+- Add cost models: ``SRCost``, ``NSRCost``, ``DCost``
+- Add reserve models: ``SR``, ``NSR``
+- Add routine ``UC``
+- Add routine ``RTED2`` to include energy storage model
+
+v0.6.7 (2023-08-02)
+-------------------
+
+- Version cleanup
+
+v0.6.6 (2023-07-27)
+-------------------
+
+- Improve routine reference
+- Add routine ED, LDOPF
+
+v0.6.5 (2023-06-27)
+-------------------
+
+- Update documentation with auto-generated model and routine reference
+- Add interface with ANDES ``ams.interop.andes``
+- Add routine RTED and example of RTED-TDS co-simulation
+- Draft development documentation
+
+v0.6.4 (2023-05-23)
+-------------------
+
+- Setup PFlow and DCPF using PYPOWER
+
+v0.6.3 (2023-05-22)
+-------------------
+
+- Using CVXPY for draft implementation
+- Improve ``model``, ``group``, ``param`` and ``var`` in ``core``
+- Refactor ``routines`` and ``opt``
+- Improve PYPOWER interface ``io.pypower.system2ppc``
+- Fix PYPOWER function ``solver.pypower.makePTDF``
+
+v0.6.2 (2023-04-23)
+-------------------
+
+- Enhance docstring
+- Remove unused module ``utils.LazyImport``
+- Remove unused module ``shared``
+
+v0.6.1 (2023-03-05)
+-------------------
+
+- Fix incompatiability of NumPy attribute ``object`` in  ``io.matpower._get_bus_id_caller``
+- Add file parser ``io.pypower`` for PYPOWER case file
+- Deprecate PYPOWER interface ``solvers.ipp``
+
+v0.6.0 (2023-03-04)
+-------------------
+
+- Set up PYPOWER for power flow calculation
+- Add PYPOWER interface ``solvers.ipp``
+- Develop module ``routines`` for routine analysis
+- Revise module ``system``, ``core.var``, ``core.model`` for routine analysis
+- Set up routine ``PFlow`` for power flow calculation
+- Add file parser ``io.matpower`` and ``io.raw`` for MATPOWER file and RAW file
+- Documentation of APIs
+
+v0.5 (2023-02-17)
+-------------------
+
+- Develop module ``system``, ``main``, ``cli``
+- Development preparation: versioneer, documentation, etc.
+
+v0.4 (2023-01)
+-------------------
+
+This release outlines the package.
+
+Known Limitations
+=================
+
+- For builit-in PYPOWER-based ACOPF, the known largest solvable case is "pglib_opf_case1354_pegase.m"
+- Batch processing is not supported yet
+- Routine ``DCOPF`` has been extensively benchmarked with pandapower and MATPOWER.
+- Routines besides above mentioned are not fully benchmarked yet.
+
+Roadmap
+=======
+
+This section lists out some potential features that may be added in the future.
+Note that the proposed features are not guaranteed to be implemented and subject to change.
+
+Electric Vehicle for Grid Service
+------------------------------------------
+
+A charging-time-constrained EV aggregation based on the state-space model
+
+References:
+
+[1] J. Wang et al., "Electric Vehicles Charging Time Constrained Deliverable Provision of Secondary
+Frequency Regulation," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3356948.
+
+[2] M. Wang et al., "State Space Model of Aggregated Electric Vehicles for Frequency Regulation," in
+IEEE Transactions on Smart Grid, vol. 11, no. 2, pp. 981-994, March 2020, doi: 10.1109/TSG.2019.2929052.
+
+Distribution OPF
+--------------------------
+
+- Distribution networks OPF and its LMP
+- DG siting and sizing considering energy equity
+
+References:
+
+[1] H. Yuan, F. Li, Y. Wei and J. Zhu, "Novel Linearized Power Flow and Linearized OPF Models for
+Active Distribution Networks With Application in Distribution LMP," in IEEE Transactions on Smart Grid,
+vol. 9, no. 1, pp. 438-448, Jan. 2018, doi: 10.1109/TSG.2016.2594814.
+
+[2] C. Li, F. Li, S. Jiang, X. Wang and J. Wang, "Siting and Sizing of DG Units Considering Energy
+Equity: Model, Solution, and Guidelines," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3350914.
+
+Planning
+--------------------------
+
+- Transmission expansion planning

docs/source/routineref.rst

@@ -0,0 +1,38 @@
+.. _routineref:
+
+*******************
+Routine reference
+*******************
+
+Use the left navigation pane to locate the group and model
+and view details.
+
+Supported Types and Routines
+
++--------------+-------------------------------------------------------------+
+|     Type     |                          Routines                           |
++==============+=============================================================+
+|  :ref:`ACED` | :ref:`ACOPF`                                                |
++--------------+-------------------------------------------------------------+
+|  :ref:`DCED` | :ref:`DCOPF`, :ref:`ED`, :ref:`EDDG`, :ref:`EDES`,          |
+|              | :ref:`RTED`, :ref:`RTEDDG`, :ref:`RTEDES`, :ref:`RTEDVIS`   |
++--------------+-------------------------------------------------------------+
+|  :ref:`DCUC` | :ref:`UC`, :ref:`UCDG`, :ref:`UCES`                         |
++--------------+-------------------------------------------------------------+
+|  :ref:`DED`  | :ref:`DOPF`, :ref:`DOPFVIS`                                 |
++--------------+-------------------------------------------------------------+
+|  :ref:`PF`   | :ref:`DCPF`, :ref:`PFlow`, :ref:`CPF`, :ref:`PFlow0`,       |
+|              | :ref:`DCPF0`                                                |
++--------------+-------------------------------------------------------------+
+
+
+.. toctree ::
+    :maxdepth: 2
+    :hidden:
+
+    typedoc/ACED
+    typedoc/DCED
+    typedoc/DCUC
+    typedoc/DED
+    typedoc/PF
+    typedoc/UndefinedType

docs/source/typedoc/ACED.rst

@@ -0,0 +1,91 @@
+.. _ACED:
+
+================================================================================
+ACED
+================================================================================
+Type for AC-based economic dispatch.
+
+Common Parameters: c2, c1, c0, pmax, pmin, pd, ptdf, rate_a, qd
+
+Common Vars: pg, aBus, vBus, qg
+
+Common Constraints: pb, lub, llb
+
+Available routines:
+ACOPF_
+
+.. _ACOPF:
+
+--------------------------------------------------------------------------------
+ACOPF
+--------------------------------------------------------------------------------
+Standard AC optimal power flow.
+
+Notes
+-----
+1. ACOPF is solved with PYPOWER ``runopf`` function.
+2. ACOPF formulation in AMS style is NOT DONE YET,
+   but this does not affect the results
+   because the data are passed to PYPOWER for solving.
+
+Objective
+----------------------------------
+
++------+--------------------------------------------------------------+
+| Unit |                          Expression                          |
++======+==============================================================+
+|      | :math:`min. \sum(c_{2}   p_{g}^{2} + c_{1}   p_{g} + c_{0})` |
++------+--------------------------------------------------------------+
+
+Constraints
+----------------------------------
+
++------+---------------+---------------------------------------+
+| Name |  Description  |              Expression               |
++======+===============+=======================================+
+|  pb  | power balance | :math:`\sum(p_{d}) - \sum(p_{g}) = 0` |
++------+---------------+---------------------------------------+
+
+Vars
+----------------------------------
+
++-------+-----------------+-----------------------+--------+-------------+------------+
+| Name  |     Symbol      |      Description      |  Unit  |   Source    | Properties |
++=======+=================+=======================+========+=============+============+
+|  pg   | :math:`p_{g}`   | Gen active power      | *p.u.* | StaticGen.p |            |
++-------+-----------------+-----------------------+--------+-------------+------------+
+|  aBus | :math:`a_{Bus}` | bus voltage angle     | *rad*  | Bus.a       |            |
++-------+-----------------+-----------------------+--------+-------------+------------+
+|  plf  | :math:`p_{lf}`  | Line flow             | *p.u.* | Line        |            |
++-------+-----------------+-----------------------+--------+-------------+------------+
+|  vBus | :math:`v_{Bus}` | Bus voltage magnitude | *p.u.* | Bus.v       |            |
++-------+-----------------+-----------------------+--------+-------------+------------+
+|  qg   | :math:`q_{g}`   | Gen reactive power    | *p.u.* | StaticGen.q |            |
++-------+-----------------+-----------------------+--------+-------------+------------+
+
+Parameters
+----------------------------------
+
++------+----------------+---------------------------------------+--------------+---------------+
+| Name |     Symbol     |              Description              |     Unit     |    Source     |
++======+================+=======================================+==============+===============+
+|  ug  | :math:`u_{g}`  | Gen connection status                 |              | StaticGen.u   |
++------+----------------+---------------------------------------+--------------+---------------+
+|  x   | :math:`x`      | line reactance                        | *p.u.*       | Line.x        |
++------+----------------+---------------------------------------+--------------+---------------+
+|  tap | :math:`t_{ap}` | transformer branch tap ratio          | *float*      | Line.tap      |
++------+----------------+---------------------------------------+--------------+---------------+
+|  phi | :math:`\phi`   | transformer branch phase shift in rad | *radian*     | Line.phi      |
++------+----------------+---------------------------------------+--------------+---------------+
+|  pd  | :math:`p_{d}`  | active deman                          | *p.u.*       | StaticLoad.p0 |
++------+----------------+---------------------------------------+--------------+---------------+
+|  c2  | :math:`c_{2}`  | Gen cost coefficient 2                | *$/(p.u.^2)* | GCost.c2      |
++------+----------------+---------------------------------------+--------------+---------------+
+|  c1  | :math:`c_{1}`  | Gen cost coefficient 1                | *$/(p.u.)*   | GCost.c1      |
++------+----------------+---------------------------------------+--------------+---------------+
+|  c0  | :math:`c_{0}`  | Gen cost coefficient 0                | *$*          | GCost.c0      |
++------+----------------+---------------------------------------+--------------+---------------+
+|  qd  | :math:`q_{d}`  | reactive demand                       | *p.u.*       | StaticLoad.q0 |
++------+----------------+---------------------------------------+--------------+---------------+
+
+