Using CLI from Notebook#
This example notebook is a supplement to the ANDES tutorial. Make sure you have read the tutorial on using the CLI first.
A brief version can be found at https://github.com/cuihantao/andes/blob/master/README.md#run-simulations
The !
magic in iPython#
This example shows how to use the ANDES CLI from Jupyter Notebook.
It is based on the iPython magic !
.
To run a command from within IPython or Jupyter, place a !
immediately before the command.
Conversely, all commands demonstrated in this notebook can be used in a terminal/shell by removing the preceeding !
sign.
Set up on Windows#
Windows users will need to install MSYS2 to support most of the Linux shell commands.
To install MSYS2-base, uncomment the following line and run it:
# !conda install -c msys2 -n base --yes m2-base
Running Shell Commands#
For example, to list the directory , use !ls
. This is equivalent to executing ls
from the terminal.
!ls
demonstration ex1.ipynb ex3.ipynb ex5.ipynb ex7.ipynb ex9.ipynb
ex10.ipynb ex2.ipynb ex4.ipynb ex6.ipynb ex8.ipynb verification
Likewise, to run andes
, use !andes
. Addition arguments can be passed as usual.
!andes
_ _ | Version 1.6.4.post10.dev0+gd1a4589d
/_\ _ _ __| |___ ___ | Python 3.9.10 on Linux, 04/19/2022 08:30:40 PM
/ _ \| ' \/ _` / -_|_-< |
/_/ \_\_||_\__,_\___/__/ | This program comes with ABSOLUTELY NO WARRANTY.
usage: andes [-h] [-v {1,10,20,30,40}]
{run,plot,doc,misc,prepare,prep,selftest,st,demo} ...
positional arguments:
{run,plot,doc,misc,prepare,prep,selftest,st,demo}
[run] run simulation routine; [plot] plot results;
[doc] quick documentation; [misc] misc. functions;
[prepare] prepare the numerical code; [selftest] run
self test;
optional arguments:
-h, --help show this help message and exit
-v {1,10,20,30,40}, --verbose {1,10,20,30,40}
Verbosity level in 10-DEBUG, 20-INFO, 30-WARNING, or
40-ERROR.
Run a simulation#
Pass the path to the case file and other arguments to andes from the command line as follows.
!andes run ../andes/cases/kundur/kundur_full.xlsx -r tds
_ _ | Version 1.6.4.post10.dev0+gd1a4589d
/_\ _ _ __| |___ ___ | Python 3.9.10 on Linux, 04/19/2022 08:30:41 PM
/ _ \| ' \/ _` / -_|_-< |
/_/ \_\_||_\__,_\___/__/ | This program comes with ABSOLUTELY NO WARRANTY.
Working directory: "/home/hacui/repos/andes/examples"
> Loaded config from file "/home/hacui/.andes/andes.rc"
> Loaded generated Python code in "/home/hacui/.andes/pycode".
Parsing input file "../andes/cases/kundur/kundur_full.xlsx"...
Input file parsed in 0.2502 seconds.
System internal structure set up in 0.0306 seconds.
-> System connectivity check results:
No islanded bus detected.
System is interconnected.
Each island has a slack bus correctly defined and enabled.
-> Power flow calculation
Numba: Off
Sparse solver: KLU
Solution method: NR method
Power flow initialized in 0.0029 seconds.
0: |F(x)| = 14.9282832
1: |F(x)| = 3.608627841
2: |F(x)| = 0.1701107882
3: |F(x)| = 0.002038626956
4: |F(x)| = 3.745104027e-07
Converged in 5 iterations in 0.0032 seconds.
Initialization for dynamics completed in 0.0278 seconds.
Initialization was successful.
Report saved to "kundur_full_out.txt" in 0.0016 seconds.
-> Time Domain Simulation Summary:
Sparse Solver: KLU
Simulation time: 0.0-20.0 s.
Fixed step size: h=33.33 ms. Shrink if not converged.
<Toggle 1>: Line.Line_8 status changed to 0 at t=2.0 sec.
100%|########################################| 100.0/100 [00:01<00:00, 86.61%/s]
Simulation completed in 1.1546 seconds.
Outputs to "kundur_full_out.lst" and "kundur_full_out.npz".
Outputs written in 0.0235 seconds.
-> Single process finished in 1.6411 seconds.
Case file names can be separated from the path, which can be passed to -p
. The above command is equivanent to
!andes run kundur_full.xlsx -p "../andes/cases/kundur/" -r tds
_ _ | Version 1.6.4.post10.dev0+gd1a4589d
/_\ _ _ __| |___ ___ | Python 3.9.10 on Linux, 04/19/2022 08:30:43 PM
/ _ \| ' \/ _` / -_|_-< |
/_/ \_\_||_\__,_\___/__/ | This program comes with ABSOLUTELY NO WARRANTY.
Working directory: "/home/hacui/repos/andes/examples"
> Loaded config from file "/home/hacui/.andes/andes.rc"
> Loaded generated Python code in "/home/hacui/.andes/pycode".
Parsing input file "../andes/cases/kundur/kundur_full.xlsx"...
Input file parsed in 0.2501 seconds.
System internal structure set up in 0.0305 seconds.
-> System connectivity check results:
No islanded bus detected.
System is interconnected.
Each island has a slack bus correctly defined and enabled.
-> Power flow calculation
Numba: Off
Sparse solver: KLU
Solution method: NR method
Power flow initialized in 0.0029 seconds.
0: |F(x)| = 14.9282832
1: |F(x)| = 3.608627841
2: |F(x)| = 0.1701107882
3: |F(x)| = 0.002038626956
4: |F(x)| = 3.745104027e-07
Converged in 5 iterations in 0.0032 seconds.
Initialization for dynamics completed in 0.0277 seconds.
Initialization was successful.
Report saved to "kundur_full_out.txt" in 0.0016 seconds.
-> Time Domain Simulation Summary:
Sparse Solver: KLU
Simulation time: 0.0-20.0 s.
Fixed step size: h=33.33 ms. Shrink if not converged.
<Toggle 1>: Line.Line_8 status changed to 0 at t=2.0 sec.
100%|########################################| 100.0/100 [00:01<00:00, 86.32%/s]
Simulation completed in 1.1584 seconds.
Outputs to "kundur_full_out.lst" and "kundur_full_out.npz".
Outputs written in 0.0237 seconds.
-> Single process finished in 1.6446 seconds.
!pwd
/home/hacui/repos/andes/examples
import os
os.path.isfile('../andes/cases/kundur/kundur_full.xlsx')
True
PSS/E RAW and DYR Files#
To run a simulation using PSS/E raw and dyr files, pass the dyr file to argument --addfile
.
For example:
!andes run ../andes/cases/kundur/kundur.raw --addfile ../andes/cases/kundur/kundur_full.dyr -r tds
_ _ | Version 1.6.4.post10.dev0+gd1a4589d
/_\ _ _ __| |___ ___ | Python 3.9.10 on Linux, 04/19/2022 08:30:46 PM
/ _ \| ' \/ _` / -_|_-< |
/_/ \_\_||_\__,_\___/__/ | This program comes with ABSOLUTELY NO WARRANTY.
Working directory: "/home/hacui/repos/andes/examples"
> Loaded config from file "/home/hacui/.andes/andes.rc"
> Loaded generated Python code in "/home/hacui/.andes/pycode".
Parsing input file "../andes/cases/kundur/kundur.raw"...
MODIFIED KUNDUR'S TWO-AREA TEST SYSTEM, DISTRIBUTED WITH ANDES
SEE THE BOOK "POWER SYSTEM STABILITY AND CONTROL" FOR ORIGINAL DATA
Input file parsed in 0.0024 seconds.
Parsing additional file "../andes/cases/kundur/kundur_full.dyr"...
Addfile parsed in 0.2239 seconds.
System internal structure set up in 0.0297 seconds.
-> System connectivity check results:
No islanded bus detected.
System is interconnected.
Each island has a slack bus correctly defined and enabled.
-> Power flow calculation
Numba: Off
Sparse solver: KLU
Solution method: NR method
Power flow initialized in 0.0028 seconds.
0: |F(x)| = 3.175850023
1: |F(x)| = 3.176155228e-08
Converged in 2 iterations in 0.0014 seconds.
Initialization for dynamics completed in 0.0276 seconds.
Initialization was successful.
Report saved to "kundur_out.txt" in 0.0014 seconds.
-> Time Domain Simulation Summary:
Sparse Solver: KLU
Simulation time: 0.0-20.0 s.
Fixed step size: h=33.33 ms. Shrink if not converged.
<Toggle Toggle_1>: Line.Line_8 status changed to 0 at t=2.0 sec.
100%|########################################| 100.0/100 [00:01<00:00, 86.44%/s]
Simulation completed in 1.1569 seconds.
Outputs to "kundur_out.lst" and "kundur_out.npz".
Outputs written in 0.0235 seconds.
-> Single process finished in 1.6165 seconds.
Check the output lst
file#
!cat kundur_full_out.lst
0, Time [s], Time [s]
1, delta GENROU 1, $\delta$ GENROU 1
2, delta GENROU 2, $\delta$ GENROU 2
3, delta GENROU 3, $\delta$ GENROU 3
4, delta GENROU 4, $\delta$ GENROU 4
5, omega GENROU 1, $\omega$ GENROU 1
6, omega GENROU 2, $\omega$ GENROU 2
7, omega GENROU 3, $\omega$ GENROU 3
8, omega GENROU 4, $\omega$ GENROU 4
9, e1q GENROU 1, $e'_q$ GENROU 1
10, e1q GENROU 2, $e'_q$ GENROU 2
11, e1q GENROU 3, $e'_q$ GENROU 3
12, e1q GENROU 4, $e'_q$ GENROU 4
13, e1d GENROU 1, $e'_d$ GENROU 1
14, e1d GENROU 2, $e'_d$ GENROU 2
15, e1d GENROU 3, $e'_d$ GENROU 3
16, e1d GENROU 4, $e'_d$ GENROU 4
17, e2d GENROU 1, $e''_d$ GENROU 1
18, e2d GENROU 2, $e''_d$ GENROU 2
19, e2d GENROU 3, $e''_d$ GENROU 3
20, e2d GENROU 4, $e''_d$ GENROU 4
21, e2q GENROU 1, $e''_q$ GENROU 1
22, e2q GENROU 2, $e''_q$ GENROU 2
23, e2q GENROU 3, $e''_q$ GENROU 3
24, e2q GENROU 4, $e''_q$ GENROU 4
25, LAG_y TGOV1 1, $y_{LAG}$ TGOV1 1
26, LAG_y TGOV1 2, $y_{LAG}$ TGOV1 2
27, LAG_y TGOV1 3, $y_{LAG}$ TGOV1 3
28, LAG_y TGOV1 4, $y_{LAG}$ TGOV1 4
29, LL_x TGOV1 1, $x'_{LL}$ TGOV1 1
30, LL_x TGOV1 2, $x'_{LL}$ TGOV1 2
31, LL_x TGOV1 3, $x'_{LL}$ TGOV1 3
32, LL_x TGOV1 4, $x'_{LL}$ TGOV1 4
33, vp EXDC2 1, $V_p$ EXDC2 1
34, vp EXDC2 2, $V_p$ EXDC2 2
35, vp EXDC2 3, $V_p$ EXDC2 3
36, vp EXDC2 4, $V_p$ EXDC2 4
37, LS_y EXDC2 1, $y_{LS}$ EXDC2 1
38, LS_y EXDC2 2, $y_{LS}$ EXDC2 2
39, LS_y EXDC2 3, $y_{LS}$ EXDC2 3
40, LS_y EXDC2 4, $y_{LS}$ EXDC2 4
41, LL_x EXDC2 1, $x'_{LL}$ EXDC2 1
42, LL_x EXDC2 2, $x'_{LL}$ EXDC2 2
43, LL_x EXDC2 3, $x'_{LL}$ EXDC2 3
44, LL_x EXDC2 4, $x'_{LL}$ EXDC2 4
45, LA_y EXDC2 1, $y_{LA}$ EXDC2 1
46, LA_y EXDC2 2, $y_{LA}$ EXDC2 2
47, LA_y EXDC2 3, $y_{LA}$ EXDC2 3
48, LA_y EXDC2 4, $y_{LA}$ EXDC2 4
49, W_x EXDC2 1, $x'_{W}$ EXDC2 1
50, W_x EXDC2 2, $x'_{W}$ EXDC2 2
51, W_x EXDC2 3, $x'_{W}$ EXDC2 3
52, W_x EXDC2 4, $x'_{W}$ EXDC2 4
53, a Bus 1, $\theta$ Bus 1
54, a Bus 2, $\theta$ Bus 2
55, a Bus 3, $\theta$ Bus 3
56, a Bus 4, $\theta$ Bus 4
57, a Bus 5, $\theta$ Bus 5
58, a Bus 6, $\theta$ Bus 6
59, a Bus 7, $\theta$ Bus 7
60, a Bus 8, $\theta$ Bus 8
61, a Bus 9, $\theta$ Bus 9
62, a Bus 10, $\theta$ Bus 10
63, v Bus 1, $V$ Bus 1
64, v Bus 2, $V$ Bus 2
65, v Bus 3, $V$ Bus 3
66, v Bus 4, $V$ Bus 4
67, v Bus 5, $V$ Bus 5
68, v Bus 6, $V$ Bus 6
69, v Bus 7, $V$ Bus 7
70, v Bus 8, $V$ Bus 8
71, v Bus 9, $V$ Bus 9
72, v Bus 10, $V$ Bus 10
73, q PV 2, $q$ PV 2
74, q PV 3, $q$ PV 3
75, q PV 4, $q$ PV 4
76, q Slack 1, $q$ Slack 1
77, p Slack 1, $p$ Slack 1
78, Id GENROU 1, $I_d$ GENROU 1
79, Id GENROU 2, $I_d$ GENROU 2
80, Id GENROU 3, $I_d$ GENROU 3
81, Id GENROU 4, $I_d$ GENROU 4
82, Iq GENROU 1, $I_q$ GENROU 1
83, Iq GENROU 2, $I_q$ GENROU 2
84, Iq GENROU 3, $I_q$ GENROU 3
85, Iq GENROU 4, $I_q$ GENROU 4
86, vd GENROU 1, $V_d$ GENROU 1
87, vd GENROU 2, $V_d$ GENROU 2
88, vd GENROU 3, $V_d$ GENROU 3
89, vd GENROU 4, $V_d$ GENROU 4
90, vq GENROU 1, $V_q$ GENROU 1
91, vq GENROU 2, $V_q$ GENROU 2
92, vq GENROU 3, $V_q$ GENROU 3
93, vq GENROU 4, $V_q$ GENROU 4
94, tm GENROU 1, $\tau_m$ GENROU 1
95, tm GENROU 2, $\tau_m$ GENROU 2
96, tm GENROU 3, $\tau_m$ GENROU 3
97, tm GENROU 4, $\tau_m$ GENROU 4
98, te GENROU 1, $\tau_e$ GENROU 1
99, te GENROU 2, $\tau_e$ GENROU 2
100, te GENROU 3, $\tau_e$ GENROU 3
101, te GENROU 4, $\tau_e$ GENROU 4
102, vf GENROU 1, $v_f$ GENROU 1
103, vf GENROU 2, $v_f$ GENROU 2
104, vf GENROU 3, $v_f$ GENROU 3
105, vf GENROU 4, $v_f$ GENROU 4
106, XadIfd GENROU 1, $X_{ad}I_{fd}$ GENROU 1
107, XadIfd GENROU 2, $X_{ad}I_{fd}$ GENROU 2
108, XadIfd GENROU 3, $X_{ad}I_{fd}$ GENROU 3
109, XadIfd GENROU 4, $X_{ad}I_{fd}$ GENROU 4
110, Pe GENROU 1, $P_e$ GENROU 1
111, Pe GENROU 2, $P_e$ GENROU 2
112, Pe GENROU 3, $P_e$ GENROU 3
113, Pe GENROU 4, $P_e$ GENROU 4
114, Qe GENROU 1, $Q_e$ GENROU 1
115, Qe GENROU 2, $Q_e$ GENROU 2
116, Qe GENROU 3, $Q_e$ GENROU 3
117, Qe GENROU 4, $Q_e$ GENROU 4
118, psid GENROU 1, $\psi_d$ GENROU 1
119, psid GENROU 2, $\psi_d$ GENROU 2
120, psid GENROU 3, $\psi_d$ GENROU 3
121, psid GENROU 4, $\psi_d$ GENROU 4
122, psiq GENROU 1, $\psi_q$ GENROU 1
123, psiq GENROU 2, $\psi_q$ GENROU 2
124, psiq GENROU 3, $\psi_q$ GENROU 3
125, psiq GENROU 4, $\psi_q$ GENROU 4
126, psi2q GENROU 1, $\psi_{aq}$ GENROU 1
127, psi2q GENROU 2, $\psi_{aq}$ GENROU 2
128, psi2q GENROU 3, $\psi_{aq}$ GENROU 3
129, psi2q GENROU 4, $\psi_{aq}$ GENROU 4
130, psi2d GENROU 1, $\psi_{ad}$ GENROU 1
131, psi2d GENROU 2, $\psi_{ad}$ GENROU 2
132, psi2d GENROU 3, $\psi_{ad}$ GENROU 3
133, psi2d GENROU 4, $\psi_{ad}$ GENROU 4
134, psi2 GENROU 1, $\psi_a$ GENROU 1
135, psi2 GENROU 2, $\psi_a$ GENROU 2
136, psi2 GENROU 3, $\psi_a$ GENROU 3
137, psi2 GENROU 4, $\psi_a$ GENROU 4
138, Se GENROU 1, $S_e(|\psi_{a}|)$ GENROU 1
139, Se GENROU 2, $S_e(|\psi_{a}|)$ GENROU 2
140, Se GENROU 3, $S_e(|\psi_{a}|)$ GENROU 3
141, Se GENROU 4, $S_e(|\psi_{a}|)$ GENROU 4
142, XaqI1q GENROU 1, $X_{aq}I_{1q}$ GENROU 1
143, XaqI1q GENROU 2, $X_{aq}I_{1q}$ GENROU 2
144, XaqI1q GENROU 3, $X_{aq}I_{1q}$ GENROU 3
145, XaqI1q GENROU 4, $X_{aq}I_{1q}$ GENROU 4
146, paux TGOV1 1, $P_{aux}$ TGOV1 1
147, paux TGOV1 2, $P_{aux}$ TGOV1 2
148, paux TGOV1 3, $P_{aux}$ TGOV1 3
149, paux TGOV1 4, $P_{aux}$ TGOV1 4
150, pout TGOV1 1, $P_{out}$ TGOV1 1
151, pout TGOV1 2, $P_{out}$ TGOV1 2
152, pout TGOV1 3, $P_{out}$ TGOV1 3
153, pout TGOV1 4, $P_{out}$ TGOV1 4
154, wref TGOV1 1, $\omega_{ref}$ TGOV1 1
155, wref TGOV1 2, $\omega_{ref}$ TGOV1 2
156, wref TGOV1 3, $\omega_{ref}$ TGOV1 3
157, wref TGOV1 4, $\omega_{ref}$ TGOV1 4
158, pref TGOV1 1, $P_{ref}$ TGOV1 1
159, pref TGOV1 2, $P_{ref}$ TGOV1 2
160, pref TGOV1 3, $P_{ref}$ TGOV1 3
161, pref TGOV1 4, $P_{ref}$ TGOV1 4
162, wd TGOV1 1, $\omega_{dev}$ TGOV1 1
163, wd TGOV1 2, $\omega_{dev}$ TGOV1 2
164, wd TGOV1 3, $\omega_{dev}$ TGOV1 3
165, wd TGOV1 4, $\omega_{dev}$ TGOV1 4
166, pd TGOV1 1, $P_d$ TGOV1 1
167, pd TGOV1 2, $P_d$ TGOV1 2
168, pd TGOV1 3, $P_d$ TGOV1 3
169, pd TGOV1 4, $P_d$ TGOV1 4
170, LL_y TGOV1 1, $y_{LL}$ TGOV1 1
171, LL_y TGOV1 2, $y_{LL}$ TGOV1 2
172, LL_y TGOV1 3, $y_{LL}$ TGOV1 3
173, LL_y TGOV1 4, $y_{LL}$ TGOV1 4
174, v EXDC2 1, $E_{term}$ EXDC2 1
175, v EXDC2 2, $E_{term}$ EXDC2 2
176, v EXDC2 3, $E_{term}$ EXDC2 3
177, v EXDC2 4, $E_{term}$ EXDC2 4
178, vout EXDC2 1, $v_{out}$ EXDC2 1
179, vout EXDC2 2, $v_{out}$ EXDC2 2
180, vout EXDC2 3, $v_{out}$ EXDC2 3
181, vout EXDC2 4, $v_{out}$ EXDC2 4
182, vref EXDC2 1, $V_{ref}$ EXDC2 1
183, vref EXDC2 2, $V_{ref}$ EXDC2 2
184, vref EXDC2 3, $V_{ref}$ EXDC2 3
185, vref EXDC2 4, $V_{ref}$ EXDC2 4
186, Se EXDC2 1, $S_e(|V_{out}|)$ EXDC2 1
187, Se EXDC2 2, $S_e(|V_{out}|)$ EXDC2 2
188, Se EXDC2 3, $S_e(|V_{out}|)$ EXDC2 3
189, Se EXDC2 4, $S_e(|V_{out}|)$ EXDC2 4
190, vi EXDC2 1, $V_i$ EXDC2 1
191, vi EXDC2 2, $V_i$ EXDC2 2
192, vi EXDC2 3, $V_i$ EXDC2 3
193, vi EXDC2 4, $V_i$ EXDC2 4
194, LL_y EXDC2 1, $y_{LL}$ EXDC2 1
195, LL_y EXDC2 2, $y_{LL}$ EXDC2 2
196, LL_y EXDC2 3, $y_{LL}$ EXDC2 3
197, LL_y EXDC2 4, $y_{LL}$ EXDC2 4
198, W_y EXDC2 1, $y_{W}$ EXDC2 1
199, W_y EXDC2 2, $y_{W}$ EXDC2 2
200, W_y EXDC2 3, $y_{W}$ EXDC2 3
201, W_y EXDC2 4, $y_{W}$ EXDC2 4
Plot and save to file#
We found a limitation of using andes plot
from within Notebook/iPython. The figure won't be displayed correctly. The workaround is to save the image as a file and display it from the notebook.
Please let us know if you have better solutions.
!andes plot kundur_full_out.lst 0 5 6 --save
Figure saved to "kundur_full_out_1.png".
Figure(640x480)
Display image#
from IPython.display import Image
Image("kundur_full_out_1.png")

Using xargs
for index lookup#
A convenient tool in Linux/macOS is xargs
, which turns the standard output of one program into arguments for another.
andes plot --xargs
accepts an input of search pattern for variable names and returns a list of arguments, including the matched indices, that can be understood by andes plot
.
To illustrate, let's look at an example output of andes plot --xargs
.
!andes plot kundur_full_out.lst --xargs "omega GENROU"
kundur_full_out.lst 0 5 6 7 8
The output consists of the lst file name, the default x-axis index 0
, and the indices for the found variables. The full output can be passed to andes plot
without modification.
We use the following command to pass the arguments:
!andes plot kundur_full_out.lst --xargs "omega GENROU" | xargs andes plot
Figure(640x480)
where |
is the pipe operator in shell for piping the standard output of the left-hand side to the right-hand side, xargs
captures the pipe-in and appends it to andes plot
.
The command is equivalent to manually running
!andes plot kundur_full_out.lst 5 6 7 8
Figure(640x480)
Cleanup#
Remove the saved png
image files.
!rm -v *.png
removed 'kundur_full_out_1.png'
!andes misc -C
"/home/hacui/repos/andes/examples/kundur_full_out.npz" removed.
"/home/hacui/repos/andes/examples/kundur_full_out.txt" removed.
"/home/hacui/repos/andes/examples/kundur_out.lst" removed.
"/home/hacui/repos/andes/examples/kundur_out.npz" removed.
"/home/hacui/repos/andes/examples/kundur_full_out.lst" removed.
"/home/hacui/repos/andes/examples/kundur_out.txt" removed.