Initial commit for GenSAS

Author: Feng Qiu

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright © 2022, UChicago Argonne, LLC
+All Rights Reserved
+Software Name: GenSAS
+By: Argonne National Laboratory
+
+OPEN SOURCE LICENSE
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+
+******************************************************************************************************
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+***************************************************************************************************

README.md

@@ -0,0 +1,25 @@
+# GenSAS
+
+**GenSAS** is a C++ based generalized simulation tool based on semi-analytical solutions (SAS) technology. It provides two modules:
+
+1. **ModelicaSAS** is a SAS-based simulation tool that supports Modelica modeling language. Currently it supports simulation of single Modelica model.
+
+2. **PowerSAS** is a robust, efficient and scalable power grid analysis framework based on semi-analytical solutions (SAS) technology. This is the version for C++ users. It currently provides AC power flow functionality.
+
+Backed by the SAS approach, the GenSAS tool provides much better convergence than the tools using traditional Newton-type equation solvers. Moreover, due to the analytical nature, GenSAS provides model-adaptive high-accuracy approximation, which brings significantly extended effective range for power grid analysis. PowerSAS has been used to solve large-scale system cases with 200,000+ buses.
+
+### Companion Project
+PowerSAS.m -- SAS-based power grid analysis toolbox for Matlab/GNU Octave users. 
+
+### Acknowledgement
+This work is supported by the Laboratory Directed Research and Development (LDRD) program of Argonne National Laboratory, provided by the U.S. Department of Energy Office of Science under Contract No. DE-AC02-06CH11357, and the U.S. Department of Energy Office of Electricity, Advanced Grid Modeling program under Grant DE-OE0000875.
+
+### Publications
+* Rui Yao, Kai Sun, Feng Qiu, “Vectorized Efficient Computation of Padé Approximation for Semi-Analytical Simulation of Large-Scale Power Systems,” IEEE Transactions on Power Systems, 34 (5), 3957-3959, 2019.
+* Rui Yao, Yang Liu, Kai Sun, Feng Qiu, Jianhui Wang,"Efficient and Robust Dynamic Simulation of Power Systems with Holomorphic Embedding", IEEE Transactions on Power Systems, 35 (2), 938 - 949, 2020.
+* Rui Yao, Feng Qiu, "Novel AC Distribution Factor for Efficient Outage Analysis", IEEE Transactions on Power Systems, 35 (6), 4960-4963, 2020.
+* Xin Xu, Rui Yao, Kai Sun, Feng Qiu, "A Semi-Analytical Solution Approach for Solving Constant-Coefficient First-Order Partial Differential Equations", IEEE Control Systems Letters, 6, 704-709, 2021.
+* Rui Yao, Feng Qiu, Kai Sun, “Contingency Analysis Based on Partitioned and Parallel Holomorphic Embedding”, IEEE Transactions on Power Systems, in press.
+
+### License
+This software is under 3-clause BSD license. Please refer to LICENSE.md for details.

doc/Installation.md

@@ -0,0 +1,22 @@
+# Installation
+
+### Dependencies
+You will need to install the following dependencies first:
+
+1. [SuperLU](https://portal.nersc.gov/project/sparse/superlu/).
+
+2. [Armadillo](http://arma.sourceforge.net/). Armadillo .hpp files need to be included and build together with GenSAS.
+
+3. BLAS and Lapack. For the best performance, [OpenBLAS](https://www.openblas.net/) is recommended.
+
+4. [MatIO](https://github.com/tbeu/matio). 
+
+5. [HDF5](https://www.hdfgroup.org/solutions/hdf5/).
+
+6. [zlib](https://www.zlib.net/).
+
+7. [jsoncpp](https://github.com/open-source-parsers/jsoncpp).
+
+8. [nvwa] (https://github.com/adah1972/nvwa/tree/master/nvwa). Only `_nvwa.h`, `c++11.h`, `debug_new.h`, `fast_mutex.h`, `pctimer.h`, `static_assert.h` are needed to be included.
+
+Then compile and build GenSAS by including or linking the above dependencies.

doc/Usage.md

@@ -0,0 +1,70 @@
+# Usage
+
+### PowerSAS
+Current version only provides AC power flow. Assume the executable is gensas.out, then the power flow computation can be called as follows.
+
+```bash
+gensas.out -p 
+    -f/--file <input-file-name> 
+    -o/--output <output-file-name> 
+    [-l/--level <sas-order>]
+    [-s/--segment <segment-length>]
+    [-a/--alphatol <alpha-tolerance>]
+    [-d/--difftol <error-tolerance>]
+```
+
+Explanations:
+* The first argument `-p` (mandatory, and must be the first argument) means GenSAS runs under PowerSAS mode. For the rest of the arguments, the order does not matter.
+* `-f/--file <input-file-name>` (mandatory) specifies the input data. Currently the input file needs to be .mat file containing PSAT data structure. See `resources/psat_mat/d_014_syn_ind_zip_export.mat` for example.
+* `-o/--output <output-file-name>` (mandatory) specifies the output curve data. Currently the output is a .mat file containing the power flow solution as a vector.
+* `-l/--level <sas-order>` (optional) specifies the order of SAS. If not specified, the order of SAS is 15.
+* `-s/--segment <segment-length>` (optional) specfies the length of a segment of SAS computation. If not specified, the the segment length is 1.0.
+* `-a/--alphatol <alpha-tolerance>` (optional) specifies the tolerance of embedding variable in SAS. If not specified, the tolerance is set as 1e-4.
+* `-d/--difftol <error-tolerance>` (optional) specifies the error tolerance of the equations. If not specified, the error tolerance is set as 1e-6.
+
+Example:
+Try running power flow of the modified synthetic eastern-interconnection (EI) 70,000-bus system:
+```bash
+./gensas.out -p -f resources/psat_mat/d_70k_070.mat -s 0.5 -l 28 -d 1e-5 -o res.mat
+```
+
+### ModelicaSAS
+Currently, ModelicaSAS supports simulation of a single Modelica .mo model without discrete events. The simulation can be called as follows:
+
+```bash
+gensas.out -g 
+    -m/--mode file/string 
+    -i/--input <input> 
+    -o/--output <output-file-name>  
+    [-j/--json <json-output-file-name>]
+    [-l/--level <sas-order>]
+    [-s/--segment <segment-length>]
+    [-a/--aTol <alpha-tolerance>]
+    [-e/--eTol <error-tolerance>]
+    [-t/--outStep <output-step>]
+    [-v/--verbose]
+```
+
+Explanations:
+* The first argument `-g` (mandatory, and must be the first argument) means GenSAS runs under ModelicaSAS mode. For the rest of the arguments, the order does not matter.
+* `-m/--mode file/string` (mandatory) specifies the format of input. If `-m file`, then expect the input file name after `-i`; and if `-m string`, then expect the Modelica model content after `-i`.
+* `-i/--input <input>` (mandatory) specifies the input data. The `<input>` depends on the mode specified after `-m`.
+* `-o/--output <output-file-name>` (mandatory) specifies the output curve data file name. Currently the output is a .mat file containing the output as a matrix.
+* `-j/--json <json-output-file-name>` (optional) specifies the name of the .json file containing output curve. 
+* `-l/--level <sas-order>` (optional) specifies the order of SAS. If not specified, the order of SAS is 15.
+* `-t/--time <max-time>` (optional) specifies the maximum time of simulated process. If not specified, the time is set as 10.0.
+* `-s/--segment <segment-length>` (optional) specfies the length of a segment of SAS computation. If not specified, the the segment length is 1.0.
+* `-a/--atol <alpha-tolerance>` (optional) specifies the tolerance of embedding variable in SAS. If not specified, the tolerance is set as 1e-3.
+* `-e/--etol <error-tolerance>` (optional) specifies the error tolerance of the equations. If not specified, the error tolerance is set as 1e-5.
+* `-k/--step <output-step>` (optional) specifies the time step of the output curves. If not specified, the time step is set as 0.01.
+* `-v/--verbose` (optional) if used, will print intermediate result in SAS computation.
+
+Example:
+Try running simulation of the model in `resources/mofile/test_solve_ode.mo`.
+
+```bash
+ ./gensas.out -g 
+    -m file -i resources/mofile/test_solve_ode.mo 
+    -o resources/mofile/test_solve_ode.mat 
+    -t 15
+```

doc/index.md

@@ -0,0 +1,25 @@
+# GenSAS
+
+**GenSAS** is a C++ based generalized simulation tool based on semi-analytical solutions (SAS) technology. It provides two modules:
+
+1. **ModelicaSAS** is a SAS-based simulation tool that supports Modelica modeling language. Currently it supports simulation of single Modelica model.
+
+2. **PowerSAS** is a robust, efficient and scalable power grid analysis framework based on semi-analytical solutions (SAS) technology. This is the version for C++ users. It currently provides AC power flow functionality.
+
+Backed by the SAS approach, the GenSAS tool provides much better convergence than the tools using traditional Newton-type equation solvers. Moreover, due to the analytical nature, GenSAS provides model-adaptive high-accuracy approximation, which brings significantly extended effective range for power grid analysis. PowerSAS has been used to solve large-scale system cases with 200,000+ buses.
+
+### Companion Project
+PowerSAS.m -- SAS-based power grid analysis toolbox for Matlab/GNU Octave users. 
+
+### Acknowledgement
+This work is supported by the Laboratory Directed Research and Development (LDRD) program of Argonne National Laboratory, provided by the U.S. Department of Energy Office of Science under Contract No. DE-AC02-06CH11357, and the U.S. Department of Energy Office of Electricity, Advanced Grid Modeling program under Grant DE-OE0000875.
+
+### Publications
+* Rui Yao, Kai Sun, Feng Qiu, “Vectorized Efficient Computation of Padé Approximation for Semi-Analytical Simulation of Large-Scale Power Systems,” IEEE Transactions on Power Systems, 34 (5), 3957-3959, 2019.
+* Rui Yao, Yang Liu, Kai Sun, Feng Qiu, Jianhui Wang,"Efficient and Robust Dynamic Simulation of Power Systems with Holomorphic Embedding", IEEE Transactions on Power Systems, 35 (2), 938 - 949, 2020.
+* Rui Yao, Feng Qiu, "Novel AC Distribution Factor for Efficient Outage Analysis", IEEE Transactions on Power Systems, 35 (6), 4960-4963, 2020.
+* Xin Xu, Rui Yao, Kai Sun, Feng Qiu, "A Semi-Analytical Solution Approach for Solving Constant-Coefficient First-Order Partial Differential Equations", IEEE Control Systems Letters, 6, 704-709, 2021.
+* Rui Yao, Feng Qiu, Kai Sun, “Contingency Analysis Based on Partitioned and Parallel Holomorphic Embedding”, IEEE Transactions on Power Systems, in press.
+
+### License
+This software is under 3-clause BSD license. Please refer to LICENSE.md for details.

include/envdependent.h

@@ -0,0 +1,6 @@
+#ifndef ENVDEPENDENT_H
+#define ENVDEPENDENT_H
+
+#define CHE_NUM_THREAD 4
+
+#endif

io/CheDataFormat.cpp

@@ -0,0 +1,35 @@
+//
+// Copyright (C) 2022, UChicago Argonne, LLC. All rights reserved.
+//
+// OPEN SOURCE LICENSE
+// 
+// Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+// 
+// 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+// 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+// 
+// 
+// ******************************************************************************************************
+// DISCLAIMER
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+// PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY 
+// DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
+// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// ***************************************************************************************************
+// 
+#include "CheDataFormat.h"
+
+namespace che {
+	namespace io {
+		namespace chedata {
+
+			int CheComponent::counter = 0;
+
+		}
+	}
+}