Merge pull request #40 from jinningwang/doc

Doc

.codecov.yml

@@ -12,8 +12,6 @@ cli:
     pycoverage:
       report_type: "xml"
 
-codecov: 
-  token: 5fc2d41f-bcba-455d-a843-f85beb76d28f
 ignore:
   - "ams/_version.py"
   - "ams/pypower/**"

.github/workflows/codecov.yml

@@ -0,0 +1,50 @@
+name: Code coverage
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: Report coverage
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: conda-incubator/setup-miniconda@v3
+      with:
+        python-version: 3.11
+        mamba-version: "*"
+        miniforge-version: "latest"
+        channels: conda-forge,defaults
+        channel-priority: true
+        activate-environment: anaconda-client-env
+    - shell: bash -el {0}
+      name: Install dependencies
+      run: |
+        mamba install -y nbmake pytest-xdist line_profiler  # add'l packages for notebook tests.
+        mamba install --file requirements.txt --file requirements-extra.txt
+        python -m pip install -e .
+    - shell: bash -el {0}
+      name: Test with pytest and collect coverage
+      run: |
+        pytest --cov=./ --cov-report=xml
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+    - name: Check secret presence
+      id: check_secret
+      run: |
+        echo "is_set=false" >> $GITHUB_OUTPUT
+        if [ ! -z "${{ secrets.CODACY_PROJECT_TOKEN }}" ]; then
+          echo "is_set=true" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Upload coverage to Codacy
+      if: steps.check_secret.outputs.is_set == 'true'
+      uses: codacy/codacy-coverage-reporter-action@v1.3.0
+      with:
+        project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+        coverage-reports: coverage.xml
+      env:
+        CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}

.github/workflows/pythonapp.yml

@@ -38,19 +38,6 @@ jobs:
       name: Test notebooks.
       run: |
         pytest --nbmake examples --ignore=examples/demonstration
-    - shell: bash -el {0}
-      name: Test with pytest and collect coverage
-      run: |
-        pytest --cov=./ --cov-report=xml
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-    - name: Upload coverage to Codacy
-      run: |
-        bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r coverage.xml
-      env:
-        CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
     - name: Build a distribution if tagged
       if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.9'
       run: |

.gitignore

@@ -38,4 +38,8 @@ icebar
 ~$*.xlsx
 
 # conda
-.conda/*
+.conda/*
+
+# coverage
+.coverage
+coverage.xml

README.md

@@ -13,7 +13,7 @@ Python Software for Power System Dispatch Modeling and Co-Simulation with Dynani
 |---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Downloads     | [![PyPI Version](https://img.shields.io/pypi/v/ltbams.svg)](https://pypi.python.org/pypi/ltbams)                                                                
 | Try on Binder | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/curent/ams/master)                                                                                                                                                 |                                                                                                                                                                                                            |
-| Code Quality  |[![Codacy Badge](https://app.codacy.com/project/badge/Grade/69456da1b8634f2f984bd769e35f0050)](https://app.codacy.com/gh/CURENT/ams/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)| [![codecov](https://codecov.io/gh/CURENT/ams/graph/badge.svg?token=RZI5GLLBQH)](https://codecov.io/gh/CURENT/ams)                                                                          |
+| Code Quality  |[![Codacy Badge](https://app.codacy.com/project/badge/Grade/69456da1b8634f2f984bd769e35f0050)](https://app.codacy.com/gh/CURENT/ams/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)| [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/69456da1b8634f2f984bd769e35f0050)](https://app.codacy.com/gh/CURENT/ams/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)                                                                          |
 | Build Status  | [![GitHub Action Status](https://github.com/CURENT/ams/workflows/Python%20application/badge.svg)](https://github.com/curent/ams/actions)  |
 | Structure   | [![Structure](https://img.shields.io/badge/code_base-visualize-blue)](https://mango-dune-07a8b7110.1.azurestaticapps.net/?repo=CURENT%2Fams)
 
@@ -48,6 +48,14 @@ Use the following resources to get involved.
 -  Try in Jupyter Notebook on [Binder][Binder]
 <!-- + Check out and and cite our [paper][arxiv paper] -->
 
+# Installation
+
+AMS is released as ``ltbams`` on PyPI. To install the latest release, use pip as follows:
+
+```bash
+pip install ltbams
+```
+
 # Sponsors and Contributors
 AMS is the dispatch simulation engine for the CURENT Largescale Testbed (LTB).
 More information about CURENT LTB can be found at the [LTB Repository][LTB Repository].
@@ -63,12 +71,9 @@ See [GitHub contributors][GitHub contributors] for the contributor list.
 AMS is licensed under the [GPL v3 License](./LICENSE).
 
 # Related Projects
--  [CVXPY](https://github.com/cvxpy/cvxpy)
--  [Visualizations of Mittelmann benchmarks](https://mattmilten.github.io/mittelmann-plots/)
--  [CBC Solver](https://github.com/coin-or/Cbc)
--  [MATPOWER](https://github.com/MATPOWER/matpower)
--  [PYPOWER](https://github.com/rwl/PYPOWER)
--  [pandapower](https://github.com/e2nIEE/pandapower)
+- [Popular Open Source Libraries for Power System Analysis](https://github.com/jinningwang/best-of-ps)
+- [G-PST Tools Portal](https://g-pst.github.io/tools/): An open tools portal with a classification approach
+- [Open Source Software (OSS) for Electricity Market Research, Teaching, and Training](https://www2.econ.iastate.edu/tesfatsi/ElectricOSS.htm)
 
 Some commercial solvers provide academic licenses, such as COPT, GUROBI, CPLEX, and MOSEK.
 

ams/interop/andes.py

@@ -96,9 +96,9 @@ def to_andes(system, setup=False, addfile=None,
     --------
     >>> import ams
     >>> import andes
-    >>> sp = ams.load(ams.get_case('ieee14/ieee14_rted.xlsx'), setup=True)
+    >>> sp = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'), setup=True)
     >>> sa = sp.to_andes(setup=False,
-    ...                  addfile=andes.get_case('ieee14/ieee14_wt3.xlsx'),
+    ...                  addfile=andes.get_case('ieee14/ieee14_full.xlsx'),
     ...                  overwrite=True, no_output=True)
 
     Notes
@@ -279,9 +279,10 @@ def parse_addfile(adsys, amsys, addfile):
     # add dynamic models
     for name, df in df_models.items():
         # drop rows that all nan
+        df.replace(['', ' '], np.NaN, inplace=True)  # replace empty string with nan
         df.dropna(axis=0, how='all', inplace=True)
         # if the dynamic model also exists in AMS, use AMS parameters for overlap
-        if name in amsys.models.keys():
+        if (name in amsys.models.keys()) and amsys.models[name].n > 0:
             if df.shape[0] != amsys.models[name].n:
                 msg = f'<{name}> has different number of rows in addfile.'
                 logger.warning(msg)
@@ -903,7 +904,6 @@ def make_link_table(adsys):
     ssa_key0 = pd.merge(left=ssa_key0, how='left', on='stg_idx',
                         right=ssa_rg[['stg_idx', 'rg_idx']])
 
-    pd.set_option('future.no_silent_downcasting', True)
     ssa_key0 = ssa_key0.fillna(value=False)
     dyr = ssa_key0['syg_idx'].astype(bool) + ssa_key0['dg_idx'].astype(bool) + ssa_key0['rg_idx'].astype(bool)
     non_dyr = np.logical_not(dyr)

ams/routines/routine.py

@@ -693,9 +693,14 @@ def _post_add_check(self):
         """
         Post-addition check.
         """
+        # --- reset routine status ---
         self.initialized = False
         self.exec_time = 0.0
         self.exit_code = 0
+        # --- reset symprocessor status ---
+        self._syms = False
+        # --- reset optimization model status ---
+        self.om.initialized = False
 
     def addRParam(self,
                   name: str,
@@ -786,8 +791,9 @@ def addService(self,
         model : str, optional
             Model name.
         """
-        item = ValueService(name=name, value=value, tex_name=tex_name, unit=unit,
-                            info=info, vtype=vtype, model=model)
+        item = ValueService(name=name, tex_name=tex_name,
+                            unit=unit, info=info,
+                            vtype=vtype, value=value)
         # add the service as an routine attribute
         setattr(self, name, item)
 

docs/source/examples/index.rst

@@ -23,3 +23,4 @@ folder of the repository
    ../_examples/ex5.ipynb
    ../_examples/ex6.ipynb
    ../_examples/ex7.ipynb
+   ../_examples/ex8.ipynb

docs/source/getting_started/formats/xlsx.rst

@@ -3,14 +3,23 @@
 AMS xlsx
 ----------
 
-The AMS xlsx format allows one to use Excel for convenient viewing and
-editing. If you do not use Excel, there are alternatives such as the free and
-open-source `LibreOffice <https://www.libreoffice.org>`_.
+AMS sticks to the same XLSX format as ANDES, where each workbook represents a
+model and each row represents a device instance.
 
 Format definition
 .................
 
-The AMS xlsx format contains multiple workbooks (also known as "sheets") shown
-as tabs at the bottom. The name of a workbook is a *model* name, and each
+As indicated in the image below, the AMS xlsx format contains multiple workbooks
+(also known as "sheets") shown as tabs at the bottom.
+The name of a workbook is a *model* name, and each
 workbook contains the parameters of all *devices* that are *instances* of the
 model.
+
+.. image:: xlsx.png
+   :width: 600
+   :alt: Example workbook for Bus
+
+.. note:: Power Flow Data are the bridge between AMS and ANDES cases.
+    More discussion can be found in the Examples - Interoperation with ANDES.
+
+For more XLSX format details, please refer to the `ANDES XLSX format <https://docs.andes.app/en/latest/>`_.

docs/source/index.rst

@@ -9,9 +9,9 @@ AMS documentation
 **Useful Links**: `Source Repository`_ | `Report Issues`_ | `Q&A`_  | `LTB Repository`_
 | `ANDES Repository`_
 
-.. _`Source Repository`: https://github.com/jinningwang/ams
-.. _`Report Issues`: https://github.com/jinningwang/ams/issues
-.. _`Q&A`: https://github.com/jinningwang/ams/discussions
+.. _`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/
 

docs/source/modeling/routine.rst

@@ -15,13 +15,8 @@ Further, to facilitate the routine definition, AMS developed a class
 .. autoclass:: ams.core.param.RParam
     :noindex:
 
-.. currentmodule:: ams.routines
-.. autosummary::
-      :recursive:
-      :toctree: _generated
-
-      RoutineData
-      RoutineModel
+.. autoclass:: ams.routines.RoutineModel
+    :noindex:
 
 Optimization model
 ------------------

docs/source/release-notes.rst

@@ -9,6 +9,12 @@ The APIs before v3.0.0 are in beta and may change without prior notice.
 Pre-v1.0.0
 ==========
 
+v0.8.6 (2024-02-xx)
+
+- Add ex8 to demonstrate how to customize existing formulations
+- Fix ``addService``
+- Fix ANDES file converter issue
+
 v0.8.5 (2024-01-31)
 
 - Improve quality of coverage and format