Merge pull request #137 from CURENT/develop

Prep v1.0.8

Author: jinningwang

.github/workflows/publish-pypi.yml

@@ -1,6 +1,9 @@
 name: Publish
 
-on: [push, pull_request]
+on:
+  push:
+    tags:
+      - '*'
 
 jobs:
   func:

ams/cases/README.md

@@ -64,6 +64,13 @@ Western Electricity Coordinating Council system [SciData](#references)
 - `wecc.m`: Matpower case for the WECC system.
 - `wecc_uced.xlsx`: UCED case for the WECC system.
 
+## hawaii
+
+Hawaii Synthetic Grid – 37 Buses [synthetic](#references), source from [Hawaii Synthetic Grid – 37 Buses](https://electricgrids.engr.tamu.edu/hawaii40/)
+
+- `Hawaii40.m`: Matpower case for the synthetic Hawaii system.
+- `Hawaii40.AUX`: [Auxiliary File Format](https://www.powerworld.com/knowledge-base/auxiliary-file-format-10), can contain power flow, dynamics, contingencies, economic studies, etc. data.
+
 ## pglib
 
 Cases from the Power Grid Lib - Optimal Power Flow [pglib](#references)
@@ -82,4 +89,6 @@ Cases from the Power Grid Lib - Optimal Power Flow [pglib](#references)
 
 [SciData]: Q. Zhang and F. Li, “A Dataset for Electricity Market Studies on Western and Northeastern Power Grids in the United States,” Scientific Data, vol. 10, no. 1, p. 646, Sep. 2023, doi: 10.1038/s41597-023-02448-w.
 
-[pglib]: S. Babaeinejadsarookolaee et al., “The Power Grid Library for Benchmarking AC Optimal Power Flow Algorithms,” arXiv.org, 2019. https://arxiv.org/abs/1908.02788
+[pglib]: S. Babaeinejadsarookolaee et al., “The Power Grid Library for Benchmarking AC Optimal Power Flow Algorithms,” arXiv.org, 2019. https://arxiv.org/abs/1908.02788
+
+[synthetic] A. B. Birchfield, T. Xu, K. M. Gegner, K. S. Shetye and T. J. Overbye, "Grid Structural Characteristics as Validation Criteria for Synthetic Networks," in IEEE Transactions on Power Systems, vol. 32, no. 4, pp. 3258-3265, July 2017, doi: 10.1109/TPWRS.2016.2616385.

ams/cases/hawaii40/Hawaii40.AUX

@@ -8,6 +8,7 @@
 
 %   Created by Rui Bo in 2006, modified in 2010, 2014.
 %   Distributed with permission.
+%   Make up two sections gentype, genfuel, and bus_name for testing purposes.
 
 %   MATPOWER
 
@@ -60,3 +61,27 @@
 	2	0	0	2	40	0;
 	2	0	0	2	10	0;
 ];
+
+mpc.gentype = {
+	'ST';
+	'ST';
+	'ST';
+	'ST';
+	'ST';
+};
+
+mpc.genfuel = {
+	'coal';
+	'coal';
+	'coal';
+	'coal';
+	'coal';
+};
+
+mpc.bus_name = {
+	'A';
+	'B';
+	'C';
+	'D';
+	'E';
+};

ams/cases/hawaii40/Hawaii40.m

@@ -25,6 +25,7 @@
     'matpower': ('m', ),
     'psse': ('raw', 'dyr'),
     'pypower': ('py',),
+    'powerworld': ('aux',),
 }
 
 # Output formats is a dictionary of supported output formats and their extensions

ams/cases/matpower/case5.m

@@ -2,9 +2,10 @@
 MATPOWER parser.
 """
 import logging
+import re
 import numpy as np
 
-from andes.io.matpower import m2mpc
+from andes.io import read_file_like
 from andes.shared import deg2rad, rad2deg
 
 logger = logging.getLogger(__name__)
@@ -29,6 +30,151 @@ def read(system, file):
     return mpc2system(mpc, system)
 
 
+def m2mpc(infile: str) -> dict:
+    """
+    Parse a MATPOWER file and return a dictionary containing the parsed data.
+
+    This function processes MATPOWER case files and extracts relevant fields
+    into a structured dictionary. It is revised from ``andes.io.matpower.m2mpc``.
+
+    Supported fields include:
+    - `baseMVA`: The system base power in MVA.
+    - `bus`: Bus data, including voltage, load, and generation information.
+    - `bus_name`: Names of the buses (if available).
+    - `gen`: Generator data, including power limits and voltage setpoints.
+    - `branch`: Branch data, including line impedances and ratings.
+    - `gencost`: Generator cost data (parsed but not used in this implementation).
+    - `areas`: Area data (parsed but not used in this implementation).
+    - `gentype`: Generator type information (if available).
+    - `genfuel`: Generator fuel type information (if available).
+
+    Parameters
+    ----------
+    infile : str
+        Path to the MATPOWER file to be parsed.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the parsed MATPOWER data, where keys correspond
+        to MATPOWER struct names and values are numpy arrays or lists.
+    """
+
+    func = re.compile(r'function\s')
+    mva = re.compile(r'\s*mpc.baseMVA\s*=\s*')
+    bus = re.compile(r'\s*mpc.bus\s*=\s*\[?')
+    gen = re.compile(r'\s*mpc.gen\s*=\s*\[')
+    branch = re.compile(r'\s*mpc.branch\s*=\s*\[')
+    area = re.compile(r'\s*mpc.areas\s*=\s*\[')
+    gencost = re.compile(r'\s*mpc.gencost\s*=\s*\[')
+    bus_name = re.compile(r'\s*mpc.bus_name\s*=\s*{')
+    gentype = re.compile(r'\s*mpc.gentype\s*=\s*{')
+    genfuel = re.compile(r'\s*mpc.genfuel\s*=\s*{')
+    end = re.compile(r'\s*[\];}]')
+    has_digit = re.compile(r'.*\d+\s*]?;?')
+
+    field = None
+    info = True
+
+    mpc = {
+        'version': 2,  # not in use
+        'baseMVA': 100,
+        'bus': [],
+        'gen': [],
+        'branch': [],
+        'area': [],
+        'gencost': [],
+        'bus_name': [],
+        'gentype': [],
+        'genfuel': [],
+    }
+
+    input_list = read_file_like(infile)
+
+    for line in input_list:
+        line = line.strip().rstrip(';')
+        if not line:
+            continue
+        elif func.search(line):  # skip function declaration
+            continue
+        elif len(line.split('%')[0]) == 0:
+            if info is True:
+                logger.info(line[1:])
+                info = False
+            else:
+                continue
+        elif mva.search(line):
+            mpc["baseMVA"] = float(line.split('=')[1])
+
+        if not field:
+            if bus.search(line):
+                field = 'bus'
+            elif gen.search(line):
+                field = 'gen'
+            elif branch.search(line):
+                field = 'branch'
+            elif area.search(line):
+                field = 'area'
+            elif gencost.search(line):
+                field = 'gencost'
+            elif bus_name.search(line):
+                field = 'bus_name'
+            elif gentype.search(line):
+                field = 'gentype'
+            elif genfuel.search(line):
+                field = 'genfuel'
+            else:
+                continue
+        elif end.search(line):
+            field = None
+            continue
+
+        # parse mpc sections
+        if field:
+            if line.find('=') >= 0:
+                line = line.split('=')[1]
+            if line.find('[') >= 0:
+                line = re.sub(r'\[', '', line)
+            elif line.find('{') >= 0:
+                line = re.sub(r'{', '', line)
+
+            if field in ['bus_name', 'gentype', 'genfuel']:
+                # Handle string-based fields
+                line = line.split(';')
+                data = [i.strip('\'').strip() for i in line if i.strip()]
+                mpc[field].extend(data)
+            else:
+                if not has_digit.search(line):
+                    continue
+                line = line.split('%')[0].strip()
+                line = line.split(';')
+                for item in line:
+                    if not has_digit.search(item):
+                        continue
+                    try:
+                        data = np.array([float(val) for val in item.split()])
+                    except Exception as e:
+                        logger.error('Error parsing "%s"', infile)
+                        raise e
+                    mpc[field].append(data)
+
+    # convert mpc to np array
+    mpc_array = dict()
+    for key, val in mpc.items():
+        if isinstance(val, (float, int)):
+            mpc_array[key] = val
+        elif isinstance(val, list):
+            if len(val) == 0:
+                continue
+            if key in ['bus_name', 'gentype', 'genfuel']:
+                mpc_array[key] = np.array(val, dtype=object)
+            else:
+                mpc_array[key] = np.array(val)
+        else:
+            raise NotImplementedError("Unknown type for mpc, ", type(val))
+    return mpc_array
+
+
 def mpc2system(mpc: dict, system) -> bool:
     """
     Load an mpc dict into an empty AMS system.
@@ -97,7 +243,20 @@ def mpc2system(mpc: dict, system) -> bool:
         mpc_gen[:, 19] = system.PV.Rq.default * base_mva / 60
     else:
         mpc_gen = mpc['gen']
-    for data in mpc_gen:
+
+    # Ensure 'gentype' and 'genfuel' keys exist in mpc, with default values if missing
+    gentype = mpc.get('gentype', [''] * mpc_gen.shape[0])
+    genfuel = mpc.get('genfuel', [''] * mpc_gen.shape[0])
+
+    # Validate lengths of 'gentype' and 'genfuel' against the number of generators
+    if len(gentype) != mpc_gen.shape[0]:
+        raise ValueError(
+            f"'gentype' length ({len(gentype)}) does not match the number of generators ({mpc_gen.shape[0]})")
+    if len(genfuel) != mpc_gen.shape[0]:
+        raise ValueError(
+            f"'genfuel' length ({len(genfuel)}) does not match the number of generators ({mpc_gen.shape[0]})")
+
+    for data, gt, gf in zip(mpc_gen, gentype, genfuel):
         # bus  pg  qg  qmax  qmin  vg  mbase  status  pmax  pmin
         # 0    1   2   3     4     5   6      7       8     9
         # pc1  pc2  qc1min  qc1max  qc2min  qc2max  ramp_agc  ramp_10
@@ -142,7 +301,7 @@ def mpc2system(mpc: dict, system) -> bool:
                        Qc2min=qc2min, Qc2max=qc2max,
                        Ragc=ramp_agc, R10=ramp_10,
                        R30=ramp_30, Rq=ramp_q,
-                       apf=apf)
+                       apf=apf, gentype=gt, genfuel=gf)
         else:
             system.add('PV', idx=gen_idx, bus=bus_idx, busr=bus_idx,
                        name=None,
@@ -155,7 +314,7 @@ def mpc2system(mpc: dict, system) -> bool:
                        Qc2min=qc2min, Qc2max=qc2max,
                        Ragc=ramp_agc, R10=ramp_10,
                        R30=ramp_30, Rq=ramp_q,
-                       apf=apf)
+                       apf=apf, gentype=gt, genfuel=gf)
 
     for data in mpc['branch']:
         # fbus	tbus	r	x	b	rateA	rateB	rateC	ratio	angle
@@ -204,9 +363,8 @@ def mpc2system(mpc: dict, system) -> bool:
         gen_idx = np.arange(mpc['gen'].shape[0]) + 1
         mpc_cost = mpc['gencost']
         if mpc_cost[0, 0] == 1:
-            logger.warning("Type 1 gencost detected. "
-                           "This is not supported in AMS. "
-                           "Default type 2 cost parameters will be used as a fallback."
+            logger.warning("Type 1 gencost detected, which is not supported in AMS.\n"
+                           "Default type 2 cost parameters will be used as a fallback.\n"
                            "It is recommended to manually convert the gencost data to type 2.")
             mpc_cost = np.repeat(np.array([[2, 0, 0, 3, 0, 0, 0]]),
                                  mpc_cost.shape[0], axis=0)

ams/io/__init__.py

@@ -1,5 +1,5 @@
 """
-Excel reader and writer for AMS.
+PSS/E .raw reader for AMS.
 This module is the existing module in ``andes.io.psse``.
 """
 

ams/io/matpower.py

@@ -175,20 +175,91 @@ def __init__(self):
 
 class StaticGen(GroupBase):
     """
-    Generator group.
+    Static Generator Group.
+
+    The generator types and fuel types are referenced from MATPOWER.
+
+    Generator Types
+    ---------------
+    The following codes represent the types of generators:
+        - BA  : Energy Storage, Battery
+        - CE  : Energy Storage, Compressed Air
+        - CP  : Energy Storage, Concentrated Solar Power
+        - FW  : Energy Storage, Flywheel
+        - PS  : Hydraulic Turbine, Reversible (pumped storage)
+        - ES  : Energy Storage, Other
+        - ST  : Steam Turbine (includes nuclear, geothermal, and solar steam)
+        - GT  : Combustion (Gas) Turbine
+        - IC  : Internal Combustion Engine (diesel, piston, reciprocating)
+        - CA  : Combined Cycle Steam Part
+        - CT  : Combined Cycle Combustion Turbine Part
+        - CS  : Combined Cycle Single Shaft
+        - CC  : Combined Cycle Total Unit
+        - HA  : Hydrokinetic, Axial Flow Turbine
+        - HB  : Hydrokinetic, Wave Buoy
+        - HK  : Hydrokinetic, Other
+        - HY  : Hydroelectric Turbine
+        - BT  : Turbines Used in a Binary Cycle
+        - PV  : Photovoltaic
+        - WT  : Wind Turbine, Onshore
+        - WS  : Wind Turbine, Offshore
+        - FC  : Fuel Cell
+        - OT  : Other
+        - UN  : Unknown
+        - JE  : Jet Engine
+        - NB  : ST - Boiling Water Nuclear Reactor
+        - NG  : ST - Graphite Nuclear Reactor
+        - NH  : ST - High Temperature Gas Nuclear Reactor
+        - NP  : ST - Pressurized Water Nuclear Reactor
+        - IT  : Internal Combustion Turbo Charged
+        - SC  : Synchronous Condenser
+        - DC  : DC ties
+        - MP  : Motor/Pump
+        - W1  : Wind Turbine, Type 1
+        - W2  : Wind Turbine, Type 2
+        - W3  : Wind Turbine, Type 3
+        - W4  : Wind Turbine, Type 4
+        - SV  : Static Var Compensator
+        - DL  : Dispatchable Load
+
+    Fuel Types
+    ----------
+    The following codes represent the fuel types:
+        - biomass     : Biomass
+        - coal        : Coal
+        - dfo         : Distillate Fuel Oil
+        - geothermal  : Geothermal
+        - hydro       : Hydro
+        - hydrops     : Hydro Pumped Storage
+        - jetfuel     : Jet Fuel
+        - lng         : Liquefied Natural Gas
+        - ng          : Natural Gas
+        - nuclear     : Nuclear
+        - oil         : Unspecified Oil
+        - refuse      : Refuse, Municipal Solid Waste
+        - rfo         : Residual Fuel Oil
+        - solar       : Solar
+        - syncgen     : Synchronous Condenser
+        - wasteheat   : Waste Heat
+        - wind        : Wind
+        - wood        : Wood or Wood Waste
+        - other       : Other
+        - unknown     : Unknown
+        - dl          : Dispatchable Load
+        - ess         : Energy Storage System
 
     Notes
     -----
-    For co-simulation with ANDES, check
-    `ANDES StaticGen <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_
-    for replacing static generators with dynamic generators.
+    For co-simulation with ANDES, refer to the `ANDES StaticGen Documentation
+    <https://docs.andes.app/en/latest/groupdoc/StaticGen.html#staticgen>`_ for
+    replacing static generators with dynamic generators.
     """
 
     def __init__(self):
         super().__init__()
         self.common_params.extend(('bus', 'Sn', 'Vn', 'p0', 'q0', 'ra', 'xs', 'subidx',
                                    'pmax', 'pmin', 'pg0', 'ctrl', 'R10', 'td1', 'td2',
-                                   'area', 'zone'))
+                                   'area', 'zone', 'gentype', 'genfuel'))
         self.common_vars.extend(('p', 'q'))