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

docs/source/conf.py

@@ -0,0 +1,203 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+import os
+import ams
+import shutil
+
+
+# Set canonical URL from the Read the Docs Domain
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinx_panels',
+    'IPython.sphinxext.ipython_directive',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'matplotlib.sphinxext.plot_directive',
+    'numpydoc',
+    'sphinx_copybutton',
+    "nbsphinx",
+]
+
+mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
+
+# Configuration options for plot_directive. See:
+# https://github.com/matplotlib/matplotlib/blob/f3ed922d935751e08494e5fb5311d3050a3b637b/lib/matplotlib/sphinxext/plot_directive.py#L81
+plot_html_show_source_link = False
+plot_html_show_formats = False
+
+# Generate the API documentation when building
+autosummary_generate = True
+numpydoc_show_class_members = False
+
+templates_path = ['_templates']
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+exclude_patterns = []
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# General information about the project.
+project = 'AMS'
+copyright = '2023-2024, Jinning Wang'
+author = 'Jinning Wang'
+
+version = ams.__version__
+release = ams.__version__
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# Use a different latex engine due to possible Unicode characters in the documentation:
+# https://docs.readthedocs.io/en/stable/guides/pdf-non-ascii-languages.html
+latex_engine = "xelatex"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    "use_edit_page_button": True,
+    # "footer_items": ["copyright", "sphinx-version", "theme-version"],
+}
+
+html_context = {
+    "github_url": "https://github.com",
+    "github_user": "CURENT",
+    "github_repo": "ams",
+    "github_version": "master",
+    "doc_path": "docs/source",
+}
+
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ams'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'preamble': r'\DeclareUnicodeCharacter{2588}{-}',
+    'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    'pointsize': '11pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'ams.tex', 'AMS Manual',
+     'Jinning Wang', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'ams', 'AMS Manual',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'ams', 'AMS Manual',
+     author, 'ams', 'Python Software for Scheduling Modeling and Co-Simulation with Dynanics',
+     'Miscellaneous'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),  # Updated URL for numpy
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),  # Updated URL for matplotlib
+}
+
+# --- Options for primary sidebar ------------------------------------------
+# REF: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#layout-sidebar-primary
+html_sidebars = {
+    # "<page_pattern>": ["list", "of", "templates"]
+}
+
+# Favorite icon
+html_favicon = 'images/curent.ico'
+
+# Disable smartquotes to display double dashes correctly
+smartquotes = False
+
+# import and execute model reference generation script
+exec(open("genmodelref.py").read())
+exec(open("genroutineref.py").read())
+
+shutil.rmtree("_examples", ignore_errors=True)
+shutil.copytree("../../examples", "_examples", )
+shutil.rmtree("_examples/demonstration")
+shutil.copytree("../../examples/demonstration", "_examples/demo", )
+
+# sphinx-panels shouldn't add bootstrap css since the pydata-sphinx-theme
+# already loads it
+panels_add_bootstrap_css = False

docs/source/examples/index.rst

@@ -0,0 +1,34 @@
+.. _scripting_examples:
+
+Examples
+========
+
+.. _`development demos`: https://github.com/CURENT/ams/tree/master/dev/demo
+
+Refer to the development `development demos`_ for examples prior to preparing this section.
+
+A collection of examples are presented to supplement the tutorial. The
+examples below are identical to the Jupyter Notebook in the ``examples``
+folder of the repository
+`here <https://github.com/CURENT/ams/tree/master/examples>`__.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Scripting
+
+   ../_examples/ex1.ipynb
+   ../_examples/ex2.ipynb
+   ../_examples/ex3.ipynb
+   ../_examples/ex4.ipynb
+   ../_examples/ex5.ipynb
+   ../_examples/ex6.ipynb
+   ../_examples/ex7.ipynb
+   ../_examples/ex8.ipynb
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Demonstration
+
+   ../_examples/demo/demo_ESD1.ipynb
+   ../_examples/demo/demo_AGC.ipynb
+   ../_examples/demo/demo_debug.ipynb

docs/source/genmodelref.py

@@ -0,0 +1,61 @@
+"""
+This file is used to generate reStructuredText tables for Model and Routine references.
+"""
+
+import os
+import ams
+
+if not (os.path.isfile('modelref.rst') and os.path.isfile('configref.rst')):
+
+    ss = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'))
+
+    # write the top-level index file
+
+    out = """.. _modelref:
+
+***************
+Model reference
+***************
+
+Use the left navigation pane to locate the group and model
+and view details.
+
+"""
+
+    out += ss.supported_models(export='rest')
+
+    out += '\n'
+    out += '.. toctree ::\n'
+    out += '    :maxdepth: 2\n'
+    out += '    :hidden:\n'
+    out += '\n'
+
+    file_tpl = '    groupdoc/{}\n'
+
+    for group in ss.groups.values():
+        out += file_tpl.format(group.class_name)
+
+    with open('modelref.rst', 'w') as f:
+        f.write(out)
+
+    # write individual files
+
+    os.makedirs('groupdoc', exist_ok=True)
+
+    for group in ss.groups.values():
+        with open(f'groupdoc/{group.class_name}.rst', 'w') as f:
+            f.write(group.doc_all(export='rest'))
+
+    # # Config Reference Section
+
+    # out = ''
+    # out += '.. _configref:\n\n'
+    # out += '****************\n'
+    # out += 'Config reference\n'
+    # out += '****************\n'
+    # out += '\n'
+
+    # out += ss.config.doc(export='rest', target=True, symbol=False)
+
+    # for r in ss.routines.values():
+    #     out += r.config.doc(export='rest', target=True, symbol=False)

docs/source/genroutineref.py

@@ -0,0 +1,47 @@
+"""
+This file is used to generate reStructuredText tables for Model and Routine references.
+"""
+
+import os
+import ams
+
+if not (os.path.isfile('routineref.rst') and os.path.isfile('configref.rst')):
+
+    ss = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'))
+
+    # write the top-level index file
+
+    out = """.. _routineref:
+
+*******************
+Routine reference
+*******************
+
+Use the left navigation pane to locate the group and model
+and view details.
+
+"""
+
+    out += ss.supported_routines(export='rest')
+
+    out += '\n'
+    out += '.. toctree ::\n'
+    out += '    :maxdepth: 2\n'
+    out += '    :hidden:\n'
+    out += '\n'
+
+    file_tpl = '    typedoc/{}\n'
+
+    for rtn_type in ss.types.values():
+        out += file_tpl.format(rtn_type.class_name)
+
+    with open('routineref.rst', 'w') as f:
+        f.write(out)
+
+    # write individual files
+
+    os.makedirs('typedoc', exist_ok=True)
+
+    for rtn_type in ss.types.values():
+        with open(f'typedoc/{rtn_type.class_name}.rst', 'w') as f:
+            f.write(rtn_type.doc_all(export='rest'))

docs/source/getting_started/copyright.rst

@@ -0,0 +1,20 @@
+.. role:: raw-html(raw)
+    :format: html
+
+*******
+License
+*******
+
+GNU Public License v3
+*********************
+| Copyright :raw-html:`©` 2023-2024 Jinning Wang.
+
+AMS is free software; you can redistribute it and/or modify it under the terms
+of the `GNU General Public License <http://www.gnu.org/licenses/gpl-3.0.html>`_
+as published by the Free Software Foundation; either version 3 of the License,
+or (at your option) any later version.
+
+AMS is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the `GNU General Public License
+<http://www.gnu.org/licenses/gpl-3.0.html>`_ for more details.

docs/source/getting_started/formats/index.rst

@@ -0,0 +1,20 @@
+.. _input-formats:
+
+=============
+Input formats
+=============
+
+AMS currently supports the following input formats:
+
+- ``.xlsx``: Excel spreadsheet file with AMS data
+- ``.raw``: PSS/E RAW format
+- ``.m``: MATPOWER format
+- ``.py``: PYPOWER format
+
+.. toctree::
+   :maxdepth: 3
+
+   xlsx
+   psse
+   matpower
+   pypower

docs/source/getting_started/formats/matpower.rst

@@ -0,0 +1,183 @@
+.. _input-matpower:
+
+MATPOWER
+--------
+The data file format of MATPOWER is excerpted below for quick reference. For more information, see
+the `MATPOWER User’s Manual <https://matpower.org/docs/MATPOWER-manual.pdf>`_.
+
+Bus Data
+~~~~~~~~~
++----------------+--------+-----------------------------------------------------------------+
+|      name      | column | description                                                     |
++================+========+=================================================================+
+|     BUS_I      |   1    | bus number (positive integer)                                   |
++----------------+--------+-----------------------------------------------------------------+
+|    BUS_TYPE    |   2    | bus type (1 = PQ, 2 = PV, 3 = ref, 4 = isolated)                |
++----------------+--------+-----------------------------------------------------------------+
+|      PD        |   3    | real power demand (MW)                                          |
++----------------+--------+-----------------------------------------------------------------+
+|      QD        |   4    | reactive power demand (MVAr)                                    |
++----------------+--------+-----------------------------------------------------------------+
+|      GS        |   5    | shunt conductance (MW demanded at V = 1.0 p.u.)                 |
++----------------+--------+-----------------------------------------------------------------+
+|      BS        |   6    | shunt susceptance (MVAr injected at V = 1.0 p.u.)               |
++----------------+--------+-----------------------------------------------------------------+
+|   BUS AREA     |   7    | area number (positive integer)                                  |
++----------------+--------+-----------------------------------------------------------------+
+|      VM        |   8    | voltage magnitude (p.u.)                                        |
++----------------+--------+-----------------------------------------------------------------+
+|      VA        |   9    | voltage angle (degrees)                                         |
++----------------+--------+-----------------------------------------------------------------+
+|    BASE_KV     |   10   | base voltage (kV)                                               |
++----------------+--------+-----------------------------------------------------------------+
+|     ZONE       |   11   | loss zone (positive integer)                                    |
++----------------+--------+-----------------------------------------------------------------+
+|     VMAX       |   12   | maximum voltage magnitude (p.u.)                                |
++----------------+--------+-----------------------------------------------------------------+
+|     VMIN       |   13   | minimum voltage magnitude (p.u.)                                |
++----------------+--------+-----------------------------------------------------------------+
+|   LAM_P [1]    |   14   | Lagrange multiplier on real power mismatch (:math:`u`/MW)       |
++----------------+--------+-----------------------------------------------------------------+
+|   LAM_Q [1]    |   15   | Lagrange multiplier on reactive power mismatch (:math:`u`/MVar) |
++----------------+--------+-----------------------------------------------------------------+
+| MU_VMAX [1]    |   16   | Kuhn-Tucker multiplier on upper voltage limit (:math:`u`/p.u.)  |
++----------------+--------+-----------------------------------------------------------------+
+| MU_VMIN [1]    |   17   | Kuhn-Tucker multiplier on lower voltage limit (:math:`u`/p.u.)  |
++----------------+--------+-----------------------------------------------------------------+
+
+
+#. Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objective function has units :math:`u`.
+
+Generator Data
+~~~~~~~~~~~~~~
++------------------------+--------+--------------------------------------------------------------+
+| name                   | column | description                                                  |
++------------------------+--------+--------------------------------------------------------------+
+| GEN_BUS                | 1      | bus number                                                   |
++------------------------+--------+--------------------------------------------------------------+
+| PG                     | 2      | real power output (MW)                                       |
++------------------------+--------+--------------------------------------------------------------+
+| QG                     | 3      | reactive power output (MVAr)                                 |
++------------------------+--------+--------------------------------------------------------------+
+| QMAX                   | 4      | maximum reactive power output (MVAr)                         |
++------------------------+--------+--------------------------------------------------------------+
+| QMIN                   | 5      | minimum reactive power output (MVAr)                         |
++------------------------+--------+--------------------------------------------------------------+
+| VG [3]                 | 6      | voltage magnitude setpoint (p.u.)                            |
++------------------------+--------+--------------------------------------------------------------+
+| MBASE                  | 7      | total MVA base of machine, defaults to baseMVA               |
++------------------------+--------+--------------------------------------------------------------+
+| GEN_STATUS             | 8      | machine status, > 0 for in-service , <= 0 for out-of-service |
++------------------------+--------+--------------------------------------------------------------+
+| PMAX                   | 9      | maximum real power output (MW)                               |
++------------------------+--------+--------------------------------------------------------------+
+| PMIN                   | 10     | minimum real power output (MW)                               |
++------------------------+--------+--------------------------------------------------------------+
+| PC1 [1]                | 11     | lower real power output of PQ capability curve (MW)          |
++------------------------+--------+--------------------------------------------------------------+
+| PC2 [1]                | 12     | upper real power output of PQ capability curve (MW)          |
++------------------------+--------+--------------------------------------------------------------+
+| QC1MIN [1]             | 13     | minimum reactive power output at PC1 (MVAr)                  |
++------------------------+--------+--------------------------------------------------------------+
+| QC1MAX [1]             | 14     | maximum reactive power output at PC1 (MVAr)                  |
++------------------------+--------+--------------------------------------------------------------+
+| QC2MIN [1]             | 15     | minimum reactive power output at PC2 (MVAr)                  |
++------------------------+--------+--------------------------------------------------------------+
+| QC2MAX [1]             | 16     | maximum reactive power output at PC2 (MVAr)                  |
++------------------------+--------+--------------------------------------------------------------+
+| RAMP_AGC [1]           | 17     | ramp rate for load following/AGC (MW/min)                    |
++------------------------+--------+--------------------------------------------------------------+
+| RAMP_10 [1]            | 18     | ramp rate for 10 minute reserves (MW)                        |
++------------------------+--------+--------------------------------------------------------------+
+| RAMP_30 [1]            | 19     | ramp rate for 30 minute reserves (MW)                        |
++------------------------+--------+--------------------------------------------------------------+
+| RAMP_Q [1]             | 20     | ramp rate for reactive power (2 sec timescale) (MVAr/min)    |
++------------------------+--------+--------------------------------------------------------------+
+| APF [1]                | 21     | area participation factor                                    |
++------------------------+--------+--------------------------------------------------------------+
+| MU_PMAX [2]            | 22     | Kuhn-Tucker multiplier on upper Pg limit (:math:`u`/MW)      |
++------------------------+--------+--------------------------------------------------------------+
+| MU_PMIN [2]            | 23     | Kuhn-Tucker multiplier on lower Pg                           |
++------------------------+--------+--------------------------------------------------------------+
+
+#. Not included in version 1 case format.
+
+#.  Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objective function has units :math:`u`.
+
+#. Used to determine voltage setpoint for optimal power flow only if ``opf.use_vg`` option is non-zero (0 by default). Otherwise generator voltage range is determined by limits set for corresponding bus in bus matrix.
+
+Branch Data
+~~~~~~~~~~~~
++--------------------------+--------+------------------------------------------------------------------------------+
+| name                     | column | description                                                                  |
++--------------------------+--------+------------------------------------------------------------------------------+
+| F_BUS                    | 1      | "from" bus number                                                            |
++--------------------------+--------+------------------------------------------------------------------------------+
+| T_BUS                    | 2      | "to" bus number                                                              |
++--------------------------+--------+------------------------------------------------------------------------------+
+| BR_R                     | 3      | resistance (p.u.)                                                            |
++--------------------------+--------+------------------------------------------------------------------------------+
+| BR_X                     | 4      | reactance (p.u.)                                                             |
++--------------------------+--------+------------------------------------------------------------------------------+
+| BR_B                     | 5      | total line charging susceptance (p.u.)                                       |
++--------------------------+--------+------------------------------------------------------------------------------+
+| RATE_A [1]               | 6      | MVA rating A (long term rating), set to 0 for unlimited                      |
++--------------------------+--------+------------------------------------------------------------------------------+
+| RATE_B [1]               | 7      | MVA rating B (short term rating), set to 0 for unlimited                     |
++--------------------------+--------+------------------------------------------------------------------------------+
+| RATE_C [1]               | 8      | MVA rating C (emergency rating), set to 0 for unlimited                      |
++--------------------------+--------+------------------------------------------------------------------------------+
+| TAP                      | 9      | transformer off nominal turns ratio                                          |
++--------------------------+--------+------------------------------------------------------------------------------+
+| SHIFT                    | 10     | transformer phase shift angle (degrees), positive => delay                   |
++--------------------------+--------+------------------------------------------------------------------------------+
+| BR_STATUS                | 11     | initial branch status, 1 = in-service, 0 = out-of-service                    |
++--------------------------+--------+------------------------------------------------------------------------------+
+| ANGMIN [2]               | 12     | minimum angle difference, Of - Ot (degrees)                                  |
++--------------------------+--------+------------------------------------------------------------------------------+
+| ANGMAX [2]               | 13     | maximum angle difference, 0,-0 - (degrees)                                   |
++--------------------------+--------+------------------------------------------------------------------------------+
+| PF [3]                   | 14     | real power injected at "from" bus end (MW)                                   |
++--------------------------+--------+------------------------------------------------------------------------------+
+| QF [3]                   | 15     | reactive power injected at "from" bus end (MVAr)                             |
++--------------------------+--------+------------------------------------------------------------------------------+
+| PT [3]                   | 16     | real power injected at "to" bus end (MW)                                     |
++--------------------------+--------+------------------------------------------------------------------------------+
+| QT [3]                   | 17     | reactive power injected at "to" bus end (MVAr)                               |
++--------------------------+--------+------------------------------------------------------------------------------+
+| MU_SF [4]                | 18     | Kuhn-Tucker multiplier on MVA limit at "from" bus (:math:`u`/MVA)            |
++--------------------------+--------+------------------------------------------------------------------------------+
+| MU_ST [4]                | 19     | Kuhn-Tucker multiplier on MVA limit at "to" bus (:math:`u`/MVA)              |
++--------------------------+--------+------------------------------------------------------------------------------+
+| MU_ANGMIN [4]            | 20     | Kuhn-Tucker multiplier lower angle difference limit (:math:`u`/degree)       |
++--------------------------+--------+------------------------------------------------------------------------------+
+| MU_ANGMAX [4]            | 21     | Kuhn                                                                         |
++--------------------------+--------+------------------------------------------------------------------------------+
+
+#. Used to specify branch flow limits. By default these are limits on apparent power with units in MVA. However, the 'opf.flow lim' option can be used to specify that the limits are active power or current, in which case the ratings are specified in MW or :math:`kA·V_{basekV}`, respectively. For current this is equivalent to an MVA value at a 1 p.u. voltage.
+
+#. Not included in version 1 case format. The voltage angle difference is taken to be unbounded below if :math:`ANGMIN ≤ −360` and unbounded above if :math:`ANGMAX ≥ 360`. If both parameters are zero, the voltage angle difference is unconstrained.
+
+#. Included in power flow and OPF output, ignored on input.
+
+#. Included in OPF output, typically not included (or ignored) in input matrix. Here we assume the objective function has units :math:`u`.
+
+
+Generator Cost Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| name     | column | description                                                                                                               |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| MODEL    | 1      | cost model, 1 = piecewise linear, 2 = polynomial                                                                          |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| STARTUP  | 2      | startup cost in US dollars [1]                                                                                            |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| SHUTDOWN | 3      | shutdown cost in US dollars [1]                                                                                           |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| NCOST    | 4      | number of points of an n-segment piecewise linear cost function or coefficients of an n-th order polynomial cost function |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+| COST [2] | 5      | parameters defining total cost function :math:`f(p)`                                                                      |
++----------+--------+---------------------------------------------------------------------------------------------------------------------------+
+
+#. Not currently used by any Matpower functions.
+#. MODEL = 1, :math:`f(p)` is defined by the coordinates :math:`(p_1, f_1), (p_2, f_2), . . . , (p_N , f_N)`; MODEL = 2, :math:`f(p) = c_{n}p^{n} + ... + c_{1}p^{1} + c_{0}`.

docs/source/getting_started/formats/psse.rst

@@ -0,0 +1,46 @@
+
+.. _psse:
+
+PSS/E RAW
+-----------------
+
+The Siemens PSS/E data format is a widely used for power system simulation.
+PSS/E uses a variety of plain-text files to store data for different actions.
+The RAW format (with file extension ``.raw``) is used to store the steady-state
+data for power flow analysis.
+Leveraging ANDES PSS/E parser, one can load PSS/E RAW files into AMS for power
+flow study.
+
+RAW Compatibility
+.................
+AMS supports PSS/E RAW in versions 32 and 33. Newer versions of
+``raw`` files can store PSS/E settings along with the system data, but such
+feature is not yet supported in AMS. Also, manually edited ``raw`` files can
+confuse the parser in AMS. Following manual edits, it is strongly recommended
+to load the data into PSS/E and save the case as a v33 RAW file.
+
+AMS supports most power flow models in PSS/E. It needs to be recognized that
+the power flow models in PSS/E is is a larger set compared with those in AMS.
+For example, switched shunts in PSS/E are converted to fixed ones, not all
+three-winding transformer flags are supported, and HVDC devices are not yet
+converted. This is not an exhaustive list, but all of them are advanced models.
+
+We welcome contributions but please also reach out to us if you need
+to arrange the development of such models.
+
+Loading files
+.............
+
+In the command line, PSS/E files can be loaded with
+
+.. code-block:: bash
+
+    ams run kundur.raw
+
+Likewise, one can convert PSS/E files to AMS xlsx:
+
+.. code-block:: bash
+
+    ams run kundur.raw -c
+
+This will convert all models in the RAW files.