Added MkDocs

EnergyNode · Mar 23, 2024 · 31f2ed4 · 31f2ed4
1 parent b22b36b
commit 31f2ed4
Show file tree

Hide file tree

Showing 35 changed files with 441 additions and 805 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.github/workflows/docs_ci.yml b/.github/workflows/docs_ci.yml
@@ -0,0 +1,17 @@
+name: Make Docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/feedback.md b/docs/feedback.md
@@ -0,0 +1,3 @@
+Please create a [new issue](https://github.com/EnergyNode/sisa_public/issues) to give us feedback, report a bug, or request a new feature.
+
+You are welcome to email us: <leiwuinfo@gmail.com>.
diff --git a/docs/fig/flowchart-get_z_pscad.svg b/docs/fig/flowchart-get_z_pscad.svg
diff --git a/docs/fig/flowchart-z_f_scan.svg b/docs/fig/flowchart-z_f_scan.svg
diff --git a/docs/fig/impedance_scan_page.png b/docs/fig/impedance_scan_page.png
diff --git a/docs/fig/pscad_folder.png b/docs/fig/pscad_folder.png
diff --git a/docs/fig/pscad_output.png b/docs/fig/pscad_output.png
diff --git a/docs/fig/pscad_output_folder.png b/docs/fig/pscad_output_folder.png
diff --git a/docs/fig/sisa_file.png b/docs/fig/sisa_file.png
diff --git a/docs/fig/sisa_find_oscillation_frequency.png b/docs/fig/sisa_find_oscillation_frequency.png
diff --git a/docs/fig/sisa_find_oscillation_frequency_zoomed_in.png b/docs/fig/sisa_find_oscillation_frequency_zoomed_in.png
diff --git a/docs/fig/sisa_home_page.png b/docs/fig/sisa_home_page.png
diff --git a/docs/fig/sisa_oscillation_frequency_adjusted.png b/docs/fig/sisa_oscillation_frequency_adjusted.png
diff --git a/docs/fig/sisa_plot_participation_factor.png b/docs/fig/sisa_plot_participation_factor.png
diff --git a/docs/fig/sisa_plot_shaping_ha.png b/docs/fig/sisa_plot_shaping_ha.png
diff --git a/docs/fig/stability_analysis_page.png b/docs/fig/stability_analysis_page.png
diff --git a/docs/fig/user_page.png b/docs/fig/user_page.png
diff --git a/docs/how_to_use/download.md b/docs/how_to_use/download.md
@@ -0,0 +1,14 @@
+To use `SISA`, you have to agree with our license.
+
+Visit our [release page](https://github.com/EnergyNode/sisa_public/releases) to download the app, as well as examples. It is always recommended to download the latest release.
+
+Download the `sisa_<release version>.zip` from our website. Unzip the file and double-click the `sisa.exe` file and start to use. That's it! No need of installation/setup.
+
+Figure: SISA file. {#fig_sisa_file}
+
+![](../fig/sisa_file.png){ width="800" }
+
+
+Figure: SISA home page. {#fig_sisa_file}
+
+![](../fig/sisa_home_page.png){ width="800" }
diff --git a/docs/how_to_use/impedance_scan.md b/docs/how_to_use/impedance_scan.md
@@ -0,0 +1,89 @@
+The `Impdance Scan` page allows the user to perform impedance scan with external third party software. Currently, only `PSCAD` is supported. And we are busy with implementing `MATLAB` support. Please contact us if you need the support for other software.
+
+Figure: SISA impedance scan page. {#fig_impedance_scan_page}
+
+![](../fig/impedance_scan_page.png){ width="800" }
+
+
+## F-Scan
+Please provide the input data for frequency-domain related parameters. The `Number of Frequency Points` tells `SISA` how many frequencies between `Start Frequency` and `End Frequency` should be generated, while `Scale` specifies the style of the frequency step.
+
+The perturbation signal can be defined by `Perturbation Up [kV]` for voltage or `Perturbation Ip [kA]` for current.
+
+## Simulation
+It instructs how an external third-party software should run the time-domain simulation. For EMT simulations, the system in the simulation starts from zero and gradually establishes a steady state, after which EMT events (e.g., closing a circuit breaker) can occur. For many rounds of simulation based on the same system, running every simulation from zero is a massive waste of time. Instead, we can let the first simulation run from zero to a steady state and stop. The system's status at the stop moment is called a `snapshot`. All the remaining simulation rounds start directly from the snapshot instead of zero.
+
+## PSCAD
+The user can provide input data specifically related to `PSCAD` software. Only the `PSCAD Version` of `PSCAD 4.6.3 (x64)` is currently supported.
+
+The `Working Folder` must contain these files:
+
+. A workspace file `.pswx`. The file name (without file extension `.pswx`) should be entered in the `Workspace Name` field.
+. A project file `.pscx`. The file name (without file extension `.pscx`) should be entered in the `Project Name` field.
+. The two library files `MyLib.pslx` and `Toolbox.pslx` can download for free on our website.
+
+The user can use the `Choose Folder` button to enter the full path.
+
+Figure: PSCAD folder. {#fig_pscad_folder}
+
+![](../fig/pscad_folder.png){ width="800" }
+
+You need to add an instance of the toolbox from the library file to your project file at a place in `PSCAD` based on your needs. Then `PSCAD` will automatically assign a component ID for this toolbox, and you need to provide the ID to the `Toolbox ID` field.
+
+## Run and Stop
+After providing the input data, the user can click the `Run` button to start. The following steps will happen automatically:
+
+* Launch a new instance of `PSCAD`. Note that `PSCAD 4` does not allow an already-launched `PSCAD` instance to be connected.
+* Create a snapshot.
+* Run a steady-state simulation to have a reference status.
+* Run through all frequencies described by the user with the perturbation signal.
+* Perform `FFT` analysis and output results.
+
+When the application is running, the `Run` button will be disabled and `Stop` button will be enabled. The user can click the `Stop` button to terminate the simulation at any time.
+
+## Output
+After the run is finished, `SISA` will create an `output` folder right in the `Working Folder` and put all the results there.
+
+* The file `impedance.csv` contains the impedances of all frequencies.
+* The file `impedance.html` visualizes the data stored in `impedance.csv` file in an interactive way powered by the open-source tool `bokeh`.
+
+Figure: PSCAD output folder. {#fig_pscad_output_folder}
+
+![](../fig/pscad_output_folder.png){ width="800" }
+
+
+Figure: PSCAD output. {#fig_pscad_output}
+
+![](../fig/pscad_output.png){ width="800" }
+
+## PSCAD Installation Path
+When `SISA` tries to launch `PSCAD`, it first uses a common path that `PSCAD 4` is installed on a computer. However, if your `PSCAD` is installed at a different path, please visit `UserPage` to let `SISA` know.
+
+Figure: SISA user page. {#fig_user_page}
+
+![](../fig/user_page.png){ width="800" }
+
+
+!!! quote "PSCAD"
+
+    There are different scenarios for the program folder naming convention:
+
+    1. When the MyUpdater utility is used to install PSCAD, the program file format has that “…Testing” folder, as shown:
+        `C:\Program Files (x86)\PSCAD463 x64 Testing\bin\win64\Pscad.exe.`
+
+    2. When the InstallShield Wizard is used to install PSCAD on a new machine (no other PSCAD patches installed):
+
+        * the default installation folder would be: `C:\Program Files (x86)\PSCAD50\`
+
+        * the default application folder would be: `C:\Program Files (x86)\PSCAD50\bin\`
+
+    3. When the InstallShield Wizard is used to install a higher patch of PSCAD 5.0.x (e.g. v5.0.2) on a machine that already has an earlier patch (e.g. v5.0.1), the installer will ask if you if you want to either:
+
+        * Update the existing PSCAD 5.0.1 installation, then the same default folders as per Step 2 above would be used,
+        * Or, perform a side-by-side installation of both patches, then 
+
+            * the default installation path for the new patch would be: `C:\Program Files (x86)\PSCAD503\`
+
+            * the default application path for the new patch would be: `C:\Program Files (x86)\PSCAD503\bin\win64`
+
+    4. When performing a silent installation, you can specify any installation folder via command line arguments.
diff --git a/docs/how_to_use/license.md b/docs/how_to_use/license.md
@@ -0,0 +1,6 @@
+Copyright (c) 2021-2023, EnergyNode B.V.
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to use the Software, subject to the following terms.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/docs/how_to_use/operating_system.md b/docs/how_to_use/operating_system.md
@@ -0,0 +1 @@
+`SISA` has a builtin feature to communicate with external third-party software like `PSCAD` for the Impedance Scan function. `PSCAD` can only be installed on Windows, and thus `SISA` can only be used on Windows.
diff --git a/docs/how_to_use/stability_analysis.md b/docs/how_to_use/stability_analysis.md
@@ -0,0 +1,173 @@
+The `Stability Analysis` page allows the user to perform stability analysis based on the frequency-spectra of impedances, which are essentially CSV-files. These files can be generated by the `Impedance Scan` function of this tool, or by any other simulation software, or by actual measurements.
+
+Here is focused on _how to use_. Please refer the publication [[@yang2022siso]] for detailed domain-knowledge.
+
+## Steps
+You can follow these steps to use this tool.
+
+1. System Partition: split the system into 2 subsystems: $A$ and $B$.
+1. Frequency scan: map the multi-input multi-output (MIMO) of all the connection ports between subsystem $A$ and $B$, i.e. $H_a$ and $H_b$ respectively.
+
+    !!! Note
+        You can use different ways to obtain the frequency scan CSV files:
+
+        - the `Impedance Scan` function of this tool,
+        - or by any other simulation software,
+        - or by actual measurements.
+
+1. Use the `Stability Analysis` feature of `SISA`.
+
+## System Partition
+<!-- TODO: check if subsystem B cannot contain active components.-->
+The first step you need is to split the whole system into 2 subsystems. According to the Right Half Plane (RHP) pole-free partition rule the subsystem $A$ has all the active components, and the subsystem $B$ contains only the passive components. 
+
+## Frequency Scan
+The aim is to get the transfer-function matrices $H_a$ and $H_b$ in frequency-domain. It is usually very difficult to directly obtain them. A common practice is to run a frequency scan for each port in a subsystem resulting one CSV file per port per subsystem. And then, use these files as building blocks to construct $H_a$ and $H_b$. This is the way adopted by `SISA`.
+
+### Frequency Scan File
+A frequency scan file is a CSV file. The file name follows this convention `<ZorY>_xxx.csv`. The first character must be the letter `Z` or `Y`. The choice depends on the nature of the frequency-scan, use `Z` for impedance and `Y` for admittance. The second character must be an underscore `_`. The rest characters are left to the user's discretion. The file extension must be `.csv`.
+
+The file content is comma separated tabular data. The impedance or admittance is represented in the $d$-$q$ system over different frequencies. Thus, the impedance or admittance at each frequency is a 2-by-2 matrix of complex values, indicated by an underline `_`. See the matrix below where $\underline{X}$ represents $\underline{Z}$ or $\underline{Y}$.
+
+$$
+\left[\begin{array}{cc}
+    \underline{X}_{dd} & \underline{X}_{dq} \\
+    \underline{X}_{qd} & \underline{X}_{qq} \\
+\end{array}\right]
+$$
+
+The data in the file starts directly from the first row, thus no column headers are allowed. The column sequence is:
+
+| frequencies | x_dd_mag | x_dd_ang | x_dq_mag | x_dq_ang | x_qd_mag | x_qd_ang | x_qq_mag | x_qq_ang |
+| ----------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
+
+!!! note
+    - `mag` means the magnitidue of a complex value. The unit is $[\mathrm{dB}]$.
+    - `ang` means the phase angle of a complex value. The unit is $[\mathrm{degree}]$.
+
+The user has the flexibility to obtain these files through various means, including computer simulations or actual measurements. For example, you can build the system in a `SISA`-supported simulation software and use the provided `Impedance Scan` feature of `SISA` to get them.
+
+!!! info
+    All frequency scan files must have exactly the same frequency points.
+
+
+### H Config File
+After obtaining the impedance/admittance scan files of all the connection ports between subsystem $A$ and $B$, you can construct $H_a$ and $H_b$ by appropriately positioning those $\underline{Z}$ and $\underline{Y}$ matrices into a larger matrix. You need to create two CSV file to config $H_a$ and $H_b$ matrices, respectively. The file names must be `ha_config.csv` and `hb_config.csv`.
+
+Suppose the $\mathbf{H_a}$ matrix is mathematically 
+
+$$
+\mathbf{H_a} = 
+\left[\begin{array}{cc}
+    \mathbf{Y}_{\mathrm{type3}} & \mathbf{O} & \mathbf{O} & \mathbf{O} & \mathbf{O} \\
+    \mathbf{O} & \mathbf{Y}_{\mathrm{type4}} & \mathbf{O} & \mathbf{O} & \mathbf{O} \\
+    \mathbf{O} & \mathbf{O} & \mathbf{Y}_{\mathrm{type4}} & \mathbf{O} & \mathbf{O} \\
+    \mathbf{O} & \mathbf{O} & \mathbf{O} & \mathbf{Y}_{\mathrm{type4}} & \mathbf{O} \\
+    \mathbf{O} & \mathbf{O} & \mathbf{O} & \mathbf{O} & \mathbf{Z}_{\mathrm{grid}} \\
+\end{array}\right]
+$$
+
+where 
+
+- $\mathbf{Y}_{\mathrm{type3}}$, $\mathbf{Y}_{\mathrm{type4}}$, and $\mathbf{Z}_{\mathrm{grid}}$ are $2\times2$ matrices. And you have already obtained the frequency scan files of them as in section [Frequency Scan File](#frequency-scan-file), and their file names are `Y_type3.csv`, `Y_type4.csv`, and `Z_grid.csv`, respectively.
+- $\mathbf{O}$ is a $2\times2$ null matrix. You don't need a frequency scan file for $\mathbf{O}$.
+
+Then your `ha_config.csv` file content should be
+
+```csv
+Y_type3,,,,
+,Y_type4,,,
+,,Y_type4,,
+,,,Y_type4,
+,,,,Z_grid
+```
+
+!!! Note
+    The position of each null-matrix is empty.
+
+
+## SISA Stability Analysis Page
+
+After preparing the `frequency-scan` files and `h-config` files, you are ready to use the SISA `Statbilty Analysis Page`, see [](#fig_stability_analysis_page).
+
+Figure: SISA Stability Analysis Page. {#fig_stability_analysis_page}
+
+![](../fig/stability_analysis_page.png){ width="800" }
+
+You need to follow 3 separate steps, one by one.
+
+1. Run without Adjust - Assess the stability of the system in its current state without applying any mitigation measures.
+1. Calculate Participation Factor - Analyse the most contributive component for an oscillation.
+1. Run with Adjust - Assess the stability of the system after applying the implemented impedance shaping method.
+
+### Run without Adjust
+All the frequency scan (impedance/admittance) files and the h-config files (`ha_config.csv` and `hb_config.csv`) must be placed in the same folder as the `Input Folder`. You need to simply provide it by clicking the `Choose folder`, and then click the button of `Run without Adjust`.
+
+The frequency spectra of all eigen values ($\Lambda$) of the tranfer function matrix $\mathbf{H}$, where $\mathbf{H} = \mathbf{H_a} \mathbf{H_b}$, are plotted with interactive figures in one HTML file. It will be opened automatically with your default browser (e.g. Google Chrome). These figures can help you to find out the oscillication frequency and which eigen value contributes the most.
+
+The default view of a figure contains two subplots: amplitude and phase angle, see [](#fig_sisa_find_oscillation_frequency) as an example. The frequency points are directly from the input frequency scan files. Each frequency has a blue dot. Since they are discrete values, the exact crossing frequency at the reference level (marked by an horitonal red line) is interpolated and indicated by a vertical line, and you can use the nearest blue dot on each side of the vertical line comparing with the reference line to determine the crossing direction. [](#fig_sisa_find_oscillation_frequency_zoomed_in) shows that somewhere after 26.5 Hz, the amplitude crosses from below to above, while the phase angle crosses from above to below. And the amplitude crosses at a smaller frequency that the phase angle. Therefore, you know the eigen value $\Lambda9$ contributes the most at the oscillation frequency near 26.5 Hz.
+
+Figure: Exemplary figure of an eigen value (default view). {#fig_sisa_find_oscillation_frequency}
+
+![](../fig/sisa_find_oscillation_frequency.png){ width="800" }
+
+Figure: Exemplary figure of an eigen value (zoomed-in view around the oscillation frequency near 26.5 Hz). {#fig_sisa_find_oscillation_frequency_zoomed_in}
+
+![](../fig/sisa_find_oscillation_frequency_zoomed_in.png){ width="800" }
+
+
+### Calculate Participagion Factor
+After visually identifying the most contributive eigen value and the oscillation frequency, you can calculate the participation factor.
+
+- Decide which subsystem you want to adjust (`A` or `B`).
+- The index of the eigen value.
+
+    !!! note
+        It should be an integer. Just use the number of the $\Lambda$ in the corresponding figure. E.g. use the number `9` for $\Lambda9$ for the example of [](#fig_sisa_find_oscillation_frequency_zoomed_in).
+
+- The oscillation frequency.
+
+    !!! note
+        Since the frequency points are discrete, the exactly oscillation frequency is usually not available from the frequency scan files, you need to use the nearest available value. In the example of [](#fig_sisa_find_oscillation_frequency_zoomed_in), you need to use 26.5 Hz.  
+
+Click the button `Calculate` will result in a new HTML file with a figure of participation factor, see [](#fig_sisa_plot_participation_factor) as an example.
+
+Figure: Exemplary figure of a participation factor. {#fig_sisa_plot_participation_factor}
+
+![](../fig/sisa_plot_participation_factor.png){ width="800" }
+
+Here you can clearly see the `dd component` of `Port Number` `3` and `4` has the highest value, indicating that they both are the dominant contributors. You can shape them to damp the oscillation most effectively. Suppose you want to choose port number `3` for the next step.
+
+### Run with Adjust
+After identifying the component to adjust by the participation factor figure, you can proceed with finding a proper adjudtment to damp the oscillation using the following input.
+
+- The index of the port, which is the Port Number in [](#fig_sisa_plot_participation_factor).
+
+    !!! note 
+        It should be an integer. E.g. use the number `3` from the example of [](#fig_sisa_plot_participation_factor).
+
+- The axis: `d` or `q`. Based on the example of [](#fig_sisa_plot_participation_factor), you choose `d`.
+- Delta phase angle - This is the increment of phase margin $\Delta \mathrm{PM}$ in equation (26) in [[@yang2022siso]]. 
+- Quality factor ratio - This is the ratio to calculate the quality factor.
+
+    $$
+        \omega_i = \mathrm{ratio} \times 2\pi f_c
+    $$
+
+    where $f_c$ is the oscillation frequency, and $\omega_i$ is the quality factor from equation (28) in [[@yang2022siso]].
+
+Click the button `Run with Adjust` will result in two HTML files.
+
+- Frequency reponse of the shaping function shown in equation (28) in [[@yang2022siso]].
+
+    Figure: Exemplary figure of the frequency response of the shaping function. {#fig_sisa_plot_shaping_ha}
+
+    ![](../fig/sisa_plot_shaping_ha.png){ width="800" }
+
+- Frequency spectra of all the eigen values ($\Lambda$) of the adjusted transfer function $\mathbf{H}$.
+
+    Figure: Exemplary figure of an eigen value of the adjust transfer function. {#fig_sisa_oscillation_frequency_adjusted}
+
+    ![](../fig/sisa_oscillation_frequency_adjusted.png){ width="800" }
+
+[](#fig_sisa_oscillation_frequency_adjusted) shows that the crossing frequency of the amplitude becomes larger than the crossing of frequency of the phase angle, comparing to [](#fig_sisa_find_oscillation_frequency). This is the effect of the adjustment.
diff --git a/docs/how_to_use/user_page.md b/docs/how_to_use/user_page.md
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,6 @@
+# Introduction
+SISA, which stands for SISO Impedance-Based Stability Analysis, is a desktop application to address dynamic issues in the power-electronics-based power system. It translates the dynamic interactions at selected multiple ports of the system to single-input single-output (SISO) minor loops in the freequency domain, of which the stability can be readily assessed by the SISO Nyquist stability criteria. It calculates the frequency-domain participation factor for the user to identify the most contributive components for the oscillation, and uses impedance shaping solution for the user to explore system stability enhancement solutions. In addition, it has the Impedance Scan function for various impedance-based analyses, including the above-mentioned stability analysis.
+
+The scientific background of SISA can be found at [[@yang2022siso]].
+
+\bibliography
diff --git a/docs/pages/.DS_Store b/docs/pages/.DS_Store
diff --git a/docs/physics/impedance_scan.md b/docs/physics/impedance_scan.md
diff --git a/docs/physics/stability_analysis.md b/docs/physics/stability_analysis.md
@@ -0,0 +1,13 @@
+## Subsystems
+The whole system is splitted into 2 subsystems: `A` and `B`.
+
+## Eigen 
+
+
+
+
+## Publication
+The detailed scientific background of SISA can be found at [[@yang2022siso]].
+
+
+##