update readme and wiki

.gitignore

@@ -5,6 +5,8 @@ python/*.pyd
 python/*.xlsx
 python/*.tex
 python/*.log
+python/*.md
+python/__*
 python/stepspy-current/build/
 python/stepspy-current/dist/
 python/stepspy-current/stepspy.egg-info

README.md

@@ -1,18 +1,19 @@
 # Simulation Toolkit for Electrical Power Systems
 - Maintainer: Changgang Li <[email protected]> from School of Electrical Engineering, Shandong University.
-- Documentation: [N/A]
-- Date of Readme: Feb. 2, 2021
+- Documentation: https://github.com/changgang/steps/wiki/
+- Date of Readme: Feb. 5, 2021
 
 # Reference
-Please cite STEPS with the following paper:
-Changgang Li, Yue Wu, Hengxu Zhang, Hua Ye, Yutian Liu and Yilu Liu, "STEPS: A Portable Numerical Simulation Toolkit for Electrical Power System Dynamic Studies," in IEEE Transactions on Power Systems, doi: 10.1109/TPWRS.2020.3045102.  https://ieeexplore.ieee.org/document/9295409
+Please cite STEPS with the following paper:  
+```Changgang Li, Yue Wu, Hengxu Zhang, Hua Ye, Yutian Liu and Yilu Liu, "STEPS: A Portable Numerical Simulation Toolkit for Electrical Power System Dynamic Studies," in IEEE Transactions on Power Systems, doi: 10.1109/TPWRS.2020.3045102.```  
+See: https://ieeexplore.ieee.org/document/9295409
 
 ## Major functions
 Simulation Toolkit for Electrical Power Systems (STEPS) is an open source power system simulator designed for balanced large-scale AC-DC hybrid power system analysis.  
 Currently, it supports powerflow solution and dynamic simulation. In the future, short circuit analysis and eigenvalue analysis will be supported with no timetable.  
 The data format of STEPS is improved based on PSS/E raw and dyr data format. 
 Though BPA dat format is supported, it will be supported in the future version in stepspy and BPA data importer will be removed.[Sep. 13, 2020]
-You are encourage to join us for further development.
+You are encouraged to join us for further development.
 
 ## Major versions
 - v1.5.1. Add new option export_full to functions of save_network_Y_matrix and APIs. stepspy is also updated. Start to add sequential parameters to STEPS. Released on Feb. 2, 2021.
@@ -29,56 +30,6 @@ You are encourage to join us for further development.
 STEPS depends on CSparse, CXSparse, CppTest, and RapidJSON. The CXSparse is modified to avoid confliction between CSparse and CXSparse by changing prefix cs_ and CS_ to cxs_ and CSX_ .
 Though BLAS, CBLAS, and other SuiteSparse codes are included in the package, they will be removed in future.
 
-## Prerequisite
-1. Install Code::Blocks.
-2. Install C and C++ compiler supprting C++14. GCC>=4.9 is recommended. 
-  - For Unix-like systems, follow guides to install gcc and g++ with the latest version.
-  - For Windows system, MinGW-64 is suggested.
-    - Go to http://mingw-w64.org/ and go to its sourceforge download site for the latest version.
-    - Install 32-bit version or 64-bit version as you like. 64-bit version is recommended.
-3. Start Code::Blocks, and configure its toolchain exectuable.
-4. Install Python if you want to try the stepspy module. 64-bit version is recommended. However, if you want to use 32-bit dynamic library of STEPS, you should install Python of the 32-bit version.
-
-## How to build with Code::Blocks
-1. Compile CSparse
-  1. Open csparse.cbp in the code/ folder with Code::Blocks.
-  2. Go 'Project'-'Properties'-'Build targets'and set type as 'static library'.
-  3. Compile CSparse. You should get a libCSparse.a in folder build/bin/Release/.
-2. Complie CXSparse
-  1. Open cxsparse.cbp in the code/ folder with Code::Blocks
-  2. Go 'Project'-'Properties'-'Build targets'and set type as 'static library'.
-  3. Compile CXSparse. You should get a libCXSparse.a in folder build/bin/Release/.
-3. Compile CppTest.
-  1. Open cpptest.cbp in the code/ folder with Code::Blocks, set build target as 'static library'.
-  2. Compile CppTest. You should get a libCppTest.a in folder build/bin/Release/.
-4. Build STEPS
-  1. Open STEPS.cbp in the code/ folder with Code::Blocks. 
-  2. Go 'Project'-'Build options'-'Linker settings', and add the libCsparse.a, libCXSparse.a, and libCppTest.a library to 'Link libraries'.
-  3. Go 'Project'-'Properties'-'Build Target', and select build target
-    - If you want to compile STEPS as dynamic library, select 'Dynamic library', and set the output file name as 'libsteps.so' for Unix-like systems or 'libsteps.dll' for Windows systems.
-    - If you want to compile STEPS as console application, select 'Console application'.
-  4. If the target is dynamic library, disable 'Link' option for Source files with leading name of 'main'. If the target is console application, enable 'Link' option for only one of Source files with leading name of 'main'.
-  5. Compile the STEPS. You should get the output file in folder build/bin/Release/.
-  6. When compiling in Windows, remove -no-pie and -lgfortran options and remove libKLU.a, libBLAS.a, libUMFPACK.a
-
-Here is a complete procedure of how to build STEPS.  
-1. Compile CSparse as static library. You can find CSparse.cbp in the code/ folder.
-2. Compile CXSparse as static library. You can find CXSparse.cbp in the code/ folder.
-3. Compile CppTest as static library. You can find CppTest.cbp in the code/ folder.
-4. Compile STEPS as dynamic library or exectuable file. Include libCSparse.a, libCXSparse.a, and libCpptest.a.
-
-## How to build in shell mode (Linux)
-To build in Linux shell mode, you can simply run the linux_make.sh. 
-There is the procedure:
-1. Download and install the cbp2make from https://sourceforge.net/projects/cbp2make/. Remember to add x mode to the cbp2make file to make executable.
-2. Add x mode to the linux_make.sh file to make it executable.
-3. Run linux_make.sh.
-
-## How to use stepspy
-stepspy is a Python module of advanced APIs of STEPS. It enables most of STEPS applications. It is recommended to use stepspy in Python 3 of 64-bit version.
-
-stepspy has been uploaded to pypi.org, and can be installed via:
-- pip3 install stepspy 
-- python -m pip install stepspy
-
-Remember to copy the built libSTEPS.dll or libSTEPS.so in release folder to the stepspy folder.
+## How to build
+1. Build STEPS kernel: https://github.com/changgang/steps/wiki/How-to-build-STEPS-kernel
+2. Install stepspy module to Python: https://github.com/changgang/steps/wiki/How-to-install-stepspy-in-Python

python/api_group_seperator.csv

@@ -0,0 +1,13 @@
+starting api name,group long name
+set_encode,Toolkit related APIs
+get_allowed_maximum_bus_number,Capacity related APIs
+add_bus,Device manipulation related APIs
+get_bus_count,Device count related APIs
+is_bus_exist,Device existance related APIs
+bus_name2number,Name2number conversion related APIs
+get_all_buses,Device retrieving related APIs
+get_bus_data,Device data manipulation related APIs
+load_powerflow_data,Powerflow related APIs
+build_network_Y_matrix,Network related APIs
+load_dynamic_data,Dynamic model related APIs
+get_dynamic_simulator_parameter,Dynamic simulation related APIs

python/api_separator.py

@@ -0,0 +1,16 @@
+def load_api_separator():
+    api_separator = dict()
+    with open("api_group_seperator.csv","rt") as fid:
+        fid.readline()
+        while True:
+            line = fid.readline()
+            if len(line)<2:
+                break
+            api_name, group_name = line.strip().split(",")
+            api_name = api_name.strip()
+            group_name = group_name.strip()
+            sep = dict()
+            sep['group name'] = group_name
+            api_separator[api_name] = sep
+    return api_separator
+

python/convert_stepspy_apis_to_markdown.py

@@ -0,0 +1,84 @@
+# program to converte API text file to markdown for wiki.
+all_apis = []
+with open("stepspy_api.txt","rt") as fid_api:
+    api = []
+    line = fid_api.readline().strip()
+    api.append(line)
+    while True:
+        line = fid_api.readline()
+        if len(line)==0:
+            if len(api) != 0:
+                all_apis.append(tuple(api))
+            break
+        else:
+            line = line.strip()
+        if not line.startswith("API "):
+            api.append(line)
+        else:
+            all_apis.append(tuple(api))
+            api = []
+            api.append(line)
+
+with open("stepspy_api.md","wt") as fid_md:
+    for api in all_apis:
+        current_cat = "count"
+        for line in api:
+            if line.startswith("API "):
+                #fid_md.write("# "+line+": ")
+                fid_md.write("# ")
+                current_cat = "format"
+                continue
+            if current_cat == "format":
+                api_name = line.strip("Format:").strip()
+                api_name = api_name[:api_name.find("(")]
+                fid_md.write(api_name+"\n")
+                fid_md.write(line+"  \n")
+                current_cat = "description"
+                continue
+            if current_cat == "description":
+                fid_md.write(line+"  \n")
+                if line.startswith("Args:"):
+                    current_cat = "args"
+                continue
+            if current_cat == "args":
+                if not line.startswith("Rets:"):
+                    fid_md.write("> "+line+"  \n")                
+                else:
+                    fid_md.write("\n"+line+"  \n")
+                    current_cat = "rets"
+                continue
+            if current_cat == "rets":
+                if not line.startswith("Example:") and not line.startswith("Tips:"):
+                    fid_md.write("> "+line+"  \n")                
+                else:
+                    fid_md.write("\n"+line+"  \n")
+                    if line.startswith("Tips:"):
+                        current_cat = "tips"
+                    else:
+                        fid_md.write("```python\n")
+                        current_cat = "example"
+                continue
+            if current_cat == "tips":
+                if not line.startswith("Example:"):
+                    fid_md.write("> "+line+"  \n")                
+                else:
+                    fid_md.write("\n"+line+"  \n")
+                    fid_md.write("```python\n")
+                    current_cat = "example"
+                continue
+            if current_cat == "example":
+                if len(line)!=0:
+                    fid_md.write(line+"  \n")
+                continue
+        if current_cat == "example":
+            fid_md.write("```\n\n")
+        else:
+            fid_md.write("\n\n")
+
+
+
+
+
+
+
+

python/convert_stepspy_apis_to_markdown_glance.py

@@ -0,0 +1,50 @@
+# program to converte API text file to markdown for wiki.
+from api_separator import *
+
+api_separator = load_api_separator()
+
+all_apis = []
+with open("stepspy_api.txt","rt") as fid_api:
+    api = []
+    line = fid_api.readline().strip()
+    api.append(line)
+    while True:
+        line = fid_api.readline()
+        if len(line)==0:
+            if len(api) != 0:
+                all_apis.append(tuple(api))
+            break
+        else:
+            line = line.strip()
+        if not line.startswith("API "):
+            api.append(line)
+        else:
+            all_apis.append(tuple(api))
+            api = []
+            api.append(line)
+
+with open("stepspy_api_glance.md","wt") as fid_md:
+    api_group_name = ""
+    for api in all_apis:
+        current_cat = "count"
+        api_count = 0
+        for line in api:
+            if line.startswith("API "):
+                api_count = int(line.strip("API "))
+                line = line.strip("API ")+". "
+                api_number = line+"["
+                current_cat = "format"
+                continue
+            if current_cat == "format":
+                api_name = line.strip("Format:").strip()
+                api_name = api_name[:api_name.find("(")]
+                if api_name in api_separator:
+                    group_name = api_separator[api_name]["group name"]
+                    api_group_name = group_name.replace(" ","-")
+                    api_group_text_name = group_name
+                    fid_md.write("# "+api_group_text_name+"\n")
+
+                fid_md.write(api_number+api_name+"](https://github.com/changgang/steps/wiki/stepspy:-"+api_group_name+"#"+api_name+")\n")
+                current_cat = "description"
+                break
+