From 7cf0e271d0a2f10a339126bdb018b2efa15f0ad0 Mon Sep 17 00:00:00 2001
From: Slaven Peles <peless@ornl.gov>
Date: Wed, 7 May 2025 16:05:51 -0400
Subject: [PATCH 1/2] Reorganize examples.

---
 examples/CMakeLists.txt                       | 22 ++++++-------------
 .../AdjointSensitivity/AdjointSensitivity.cpp |  0
 .../AdjointSensitivity/CMakeLists.txt         |  0
 examples/Experimental/CMakeLists.txt          | 14 ++++++++++++
 .../DynamicConstrainedOpt/CMakeLists.txt      |  0
 .../DynamicConstrainedOpt.cpp                 |  0
 .../GenConstLoad/CMakeLists.txt               |  0
 .../GenConstLoad/GenConstLoad.cpp             |  0
 .../GenInfiniteBus/CMakeLists.txt             |  0
 .../GenInfiniteBus/GenInfiniteBus.cpp         |  0
 .../ParameterEstimation/CMakeLists.txt        |  0
 .../ParameterEstimation.cpp                   |  0
 .../ParameterEstimation/lookup_table.hpp      |  0
 examples/PowerElectronics/CMakeLists.txt      | 12 ++++++++++
 .../DistributedGeneratorTest/CMakeLists.txt   |  0
 .../DistributedGeneratorTest/DGTest.cpp       |  0
 .../Microgrid/CMakeLists.txt                  |  0
 .../Microgrid/Microgrid.cpp                   |  0
 .../RLCircuit/CMakeLists.txt                  |  0
 .../RLCircuit/RLCircuit.cpp                   |  0
 .../ScaleMicrogrid/CMakeLists.txt             |  0
 .../ScaleMicrogrid/ScaleMicrogrid.cpp         |  0
 .../ScaleMicrogrid/SolutionKeys.hpp           |  0
 examples/PowerFlow/CMakeLists.txt             |  8 +++++++
 examples/{ => PowerFlow}/Grid3Bus/3bus.mat    |  0
 .../{ => PowerFlow}/Grid3Bus/CMakeLists.txt   |  0
 .../{ => PowerFlow}/Grid3Bus/Grid3BusSys.cpp  |  0
 examples/{ => PowerFlow}/Grid3Bus/README.md   |  0
 28 files changed, 41 insertions(+), 15 deletions(-)
 rename examples/{ => Experimental}/AdjointSensitivity/AdjointSensitivity.cpp (100%)
 rename examples/{ => Experimental}/AdjointSensitivity/CMakeLists.txt (100%)
 create mode 100644 examples/Experimental/CMakeLists.txt
 rename examples/{ => Experimental}/DynamicConstrainedOpt/CMakeLists.txt (100%)
 rename examples/{ => Experimental}/DynamicConstrainedOpt/DynamicConstrainedOpt.cpp (100%)
 rename examples/{ => Experimental}/GenConstLoad/CMakeLists.txt (100%)
 rename examples/{ => Experimental}/GenConstLoad/GenConstLoad.cpp (100%)
 rename examples/{ => Experimental}/GenInfiniteBus/CMakeLists.txt (100%)
 rename examples/{ => Experimental}/GenInfiniteBus/GenInfiniteBus.cpp (100%)
 rename examples/{ => Experimental}/ParameterEstimation/CMakeLists.txt (100%)
 rename examples/{ => Experimental}/ParameterEstimation/ParameterEstimation.cpp (100%)
 rename examples/{ => Experimental}/ParameterEstimation/lookup_table.hpp (100%)
 create mode 100644 examples/PowerElectronics/CMakeLists.txt
 rename examples/{ => PowerElectronics}/DistributedGeneratorTest/CMakeLists.txt (100%)
 rename examples/{ => PowerElectronics}/DistributedGeneratorTest/DGTest.cpp (100%)
 rename examples/{ => PowerElectronics}/Microgrid/CMakeLists.txt (100%)
 rename examples/{ => PowerElectronics}/Microgrid/Microgrid.cpp (100%)
 rename examples/{ => PowerElectronics}/RLCircuit/CMakeLists.txt (100%)
 rename examples/{ => PowerElectronics}/RLCircuit/RLCircuit.cpp (100%)
 rename examples/{ => PowerElectronics}/ScaleMicrogrid/CMakeLists.txt (100%)
 rename examples/{ => PowerElectronics}/ScaleMicrogrid/ScaleMicrogrid.cpp (100%)
 rename examples/{ => PowerElectronics}/ScaleMicrogrid/SolutionKeys.hpp (100%)
 create mode 100644 examples/PowerFlow/CMakeLists.txt
 rename examples/{ => PowerFlow}/Grid3Bus/3bus.mat (100%)
 rename examples/{ => PowerFlow}/Grid3Bus/CMakeLists.txt (100%)
 rename examples/{ => PowerFlow}/Grid3Bus/Grid3BusSys.cpp (100%)
 rename examples/{ => PowerFlow}/Grid3Bus/README.md (100%)

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 6e0382b7..cb154a7e 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -1,25 +1,17 @@
-#
+# [[
+#  Author(s):
+#    - Slaven Peles <peless@ornl.gov>
+#]]
 
 add_subdirectory(MatPowerTesting)
 add_subdirectory(LinearAlgebra)
-add_subdirectory(DistributedGeneratorTest)
 
-if(TARGET SUNDIALS::kinsol)
-  add_subdirectory(Grid3Bus)
-endif()
+add_subdirectory(PowerFlow)
+add_subdirectory(PowerElectronics)
+add_subdirectory(Experimental)
 
 if(TARGET SUNDIALS::idas)
-  add_subdirectory(AdjointSensitivity)
-  add_subdirectory(RLCircuit)
-  add_subdirectory(Microgrid)
-  add_subdirectory(ScaleMicrogrid)
   add_subdirectory(PhasorDynamics)
-  if(GRIDKIT_ENABLE_IPOPT)
-    add_subdirectory(DynamicConstrainedOpt)
-    add_subdirectory(GenConstLoad)
-    add_subdirectory(GenInfiniteBus)
-    add_subdirectory(ParameterEstimation)
-  endif()
 endif()
 
 if(GRIDKIT_ENABLE_ENZYME)
diff --git a/examples/AdjointSensitivity/AdjointSensitivity.cpp b/examples/Experimental/AdjointSensitivity/AdjointSensitivity.cpp
similarity index 100%
rename from examples/AdjointSensitivity/AdjointSensitivity.cpp
rename to examples/Experimental/AdjointSensitivity/AdjointSensitivity.cpp
diff --git a/examples/AdjointSensitivity/CMakeLists.txt b/examples/Experimental/AdjointSensitivity/CMakeLists.txt
similarity index 100%
rename from examples/AdjointSensitivity/CMakeLists.txt
rename to examples/Experimental/AdjointSensitivity/CMakeLists.txt
diff --git a/examples/Experimental/CMakeLists.txt b/examples/Experimental/CMakeLists.txt
new file mode 100644
index 00000000..767767ff
--- /dev/null
+++ b/examples/Experimental/CMakeLists.txt
@@ -0,0 +1,14 @@
+# [[
+#  Author(s):
+#    - Slaven Peles <peless@ornl.gov>
+#]]
+
+if(TARGET SUNDIALS::idas)
+  add_subdirectory(AdjointSensitivity)
+  if(GRIDKIT_ENABLE_IPOPT)
+    add_subdirectory(DynamicConstrainedOpt)
+    add_subdirectory(GenConstLoad)
+    add_subdirectory(GenInfiniteBus)
+    add_subdirectory(ParameterEstimation)
+  endif()
+endif()
diff --git a/examples/DynamicConstrainedOpt/CMakeLists.txt b/examples/Experimental/DynamicConstrainedOpt/CMakeLists.txt
similarity index 100%
rename from examples/DynamicConstrainedOpt/CMakeLists.txt
rename to examples/Experimental/DynamicConstrainedOpt/CMakeLists.txt
diff --git a/examples/DynamicConstrainedOpt/DynamicConstrainedOpt.cpp b/examples/Experimental/DynamicConstrainedOpt/DynamicConstrainedOpt.cpp
similarity index 100%
rename from examples/DynamicConstrainedOpt/DynamicConstrainedOpt.cpp
rename to examples/Experimental/DynamicConstrainedOpt/DynamicConstrainedOpt.cpp
diff --git a/examples/GenConstLoad/CMakeLists.txt b/examples/Experimental/GenConstLoad/CMakeLists.txt
similarity index 100%
rename from examples/GenConstLoad/CMakeLists.txt
rename to examples/Experimental/GenConstLoad/CMakeLists.txt
diff --git a/examples/GenConstLoad/GenConstLoad.cpp b/examples/Experimental/GenConstLoad/GenConstLoad.cpp
similarity index 100%
rename from examples/GenConstLoad/GenConstLoad.cpp
rename to examples/Experimental/GenConstLoad/GenConstLoad.cpp
diff --git a/examples/GenInfiniteBus/CMakeLists.txt b/examples/Experimental/GenInfiniteBus/CMakeLists.txt
similarity index 100%
rename from examples/GenInfiniteBus/CMakeLists.txt
rename to examples/Experimental/GenInfiniteBus/CMakeLists.txt
diff --git a/examples/GenInfiniteBus/GenInfiniteBus.cpp b/examples/Experimental/GenInfiniteBus/GenInfiniteBus.cpp
similarity index 100%
rename from examples/GenInfiniteBus/GenInfiniteBus.cpp
rename to examples/Experimental/GenInfiniteBus/GenInfiniteBus.cpp
diff --git a/examples/ParameterEstimation/CMakeLists.txt b/examples/Experimental/ParameterEstimation/CMakeLists.txt
similarity index 100%
rename from examples/ParameterEstimation/CMakeLists.txt
rename to examples/Experimental/ParameterEstimation/CMakeLists.txt
diff --git a/examples/ParameterEstimation/ParameterEstimation.cpp b/examples/Experimental/ParameterEstimation/ParameterEstimation.cpp
similarity index 100%
rename from examples/ParameterEstimation/ParameterEstimation.cpp
rename to examples/Experimental/ParameterEstimation/ParameterEstimation.cpp
diff --git a/examples/ParameterEstimation/lookup_table.hpp b/examples/Experimental/ParameterEstimation/lookup_table.hpp
similarity index 100%
rename from examples/ParameterEstimation/lookup_table.hpp
rename to examples/Experimental/ParameterEstimation/lookup_table.hpp
diff --git a/examples/PowerElectronics/CMakeLists.txt b/examples/PowerElectronics/CMakeLists.txt
new file mode 100644
index 00000000..a362bbe4
--- /dev/null
+++ b/examples/PowerElectronics/CMakeLists.txt
@@ -0,0 +1,12 @@
+# [[
+#  Author(s):
+#    - Slaven Peles <peless@ornl.gov>
+#]]
+
+add_subdirectory(DistributedGeneratorTest)
+
+if(TARGET SUNDIALS::idas)
+  add_subdirectory(RLCircuit)
+  add_subdirectory(Microgrid)
+  add_subdirectory(ScaleMicrogrid)
+endif()
diff --git a/examples/DistributedGeneratorTest/CMakeLists.txt b/examples/PowerElectronics/DistributedGeneratorTest/CMakeLists.txt
similarity index 100%
rename from examples/DistributedGeneratorTest/CMakeLists.txt
rename to examples/PowerElectronics/DistributedGeneratorTest/CMakeLists.txt
diff --git a/examples/DistributedGeneratorTest/DGTest.cpp b/examples/PowerElectronics/DistributedGeneratorTest/DGTest.cpp
similarity index 100%
rename from examples/DistributedGeneratorTest/DGTest.cpp
rename to examples/PowerElectronics/DistributedGeneratorTest/DGTest.cpp
diff --git a/examples/Microgrid/CMakeLists.txt b/examples/PowerElectronics/Microgrid/CMakeLists.txt
similarity index 100%
rename from examples/Microgrid/CMakeLists.txt
rename to examples/PowerElectronics/Microgrid/CMakeLists.txt
diff --git a/examples/Microgrid/Microgrid.cpp b/examples/PowerElectronics/Microgrid/Microgrid.cpp
similarity index 100%
rename from examples/Microgrid/Microgrid.cpp
rename to examples/PowerElectronics/Microgrid/Microgrid.cpp
diff --git a/examples/RLCircuit/CMakeLists.txt b/examples/PowerElectronics/RLCircuit/CMakeLists.txt
similarity index 100%
rename from examples/RLCircuit/CMakeLists.txt
rename to examples/PowerElectronics/RLCircuit/CMakeLists.txt
diff --git a/examples/RLCircuit/RLCircuit.cpp b/examples/PowerElectronics/RLCircuit/RLCircuit.cpp
similarity index 100%
rename from examples/RLCircuit/RLCircuit.cpp
rename to examples/PowerElectronics/RLCircuit/RLCircuit.cpp
diff --git a/examples/ScaleMicrogrid/CMakeLists.txt b/examples/PowerElectronics/ScaleMicrogrid/CMakeLists.txt
similarity index 100%
rename from examples/ScaleMicrogrid/CMakeLists.txt
rename to examples/PowerElectronics/ScaleMicrogrid/CMakeLists.txt
diff --git a/examples/ScaleMicrogrid/ScaleMicrogrid.cpp b/examples/PowerElectronics/ScaleMicrogrid/ScaleMicrogrid.cpp
similarity index 100%
rename from examples/ScaleMicrogrid/ScaleMicrogrid.cpp
rename to examples/PowerElectronics/ScaleMicrogrid/ScaleMicrogrid.cpp
diff --git a/examples/ScaleMicrogrid/SolutionKeys.hpp b/examples/PowerElectronics/ScaleMicrogrid/SolutionKeys.hpp
similarity index 100%
rename from examples/ScaleMicrogrid/SolutionKeys.hpp
rename to examples/PowerElectronics/ScaleMicrogrid/SolutionKeys.hpp
diff --git a/examples/PowerFlow/CMakeLists.txt b/examples/PowerFlow/CMakeLists.txt
new file mode 100644
index 00000000..473d79af
--- /dev/null
+++ b/examples/PowerFlow/CMakeLists.txt
@@ -0,0 +1,8 @@
+# [[
+#  Author(s):
+#    - Slaven Peles <peless@ornl.gov>
+#]]
+
+if(TARGET SUNDIALS::kinsol)
+  add_subdirectory(Grid3Bus)
+endif()
diff --git a/examples/Grid3Bus/3bus.mat b/examples/PowerFlow/Grid3Bus/3bus.mat
similarity index 100%
rename from examples/Grid3Bus/3bus.mat
rename to examples/PowerFlow/Grid3Bus/3bus.mat
diff --git a/examples/Grid3Bus/CMakeLists.txt b/examples/PowerFlow/Grid3Bus/CMakeLists.txt
similarity index 100%
rename from examples/Grid3Bus/CMakeLists.txt
rename to examples/PowerFlow/Grid3Bus/CMakeLists.txt
diff --git a/examples/Grid3Bus/Grid3BusSys.cpp b/examples/PowerFlow/Grid3Bus/Grid3BusSys.cpp
similarity index 100%
rename from examples/Grid3Bus/Grid3BusSys.cpp
rename to examples/PowerFlow/Grid3Bus/Grid3BusSys.cpp
diff --git a/examples/Grid3Bus/README.md b/examples/PowerFlow/Grid3Bus/README.md
similarity index 100%
rename from examples/Grid3Bus/README.md
rename to examples/PowerFlow/Grid3Bus/README.md

From 3107af7c487efb99eadf3117d8665fefced3177d Mon Sep 17 00:00:00 2001
From: Slaven Peles <peless@ornl.gov>
Date: Thu, 8 May 2025 11:09:01 -0400
Subject: [PATCH 2/2] Move Matpower parser tests to PowerFlow examples.

---
 examples/CMakeLists.txt                         |  1 -
 examples/PowerFlow/CMakeLists.txt               |  2 ++
 .../MatPowerTesting/CMakeLists.txt              |  0
 .../MatPowerTesting/test_parse_branch_row.cpp   |  0
 .../MatPowerTesting/test_parse_bus_row.cpp      |  0
 .../MatPowerTesting/test_parse_gen_row.cpp      |  0
 .../MatPowerTesting/test_parse_gencost_row.cpp  |  0
 .../MatPowerTesting/test_parse_matpower.cpp     |  0
 examples/README.md                              | 17 +++++++++++++++++
 9 files changed, 19 insertions(+), 1 deletion(-)
 rename examples/{ => PowerFlow}/MatPowerTesting/CMakeLists.txt (100%)
 rename examples/{ => PowerFlow}/MatPowerTesting/test_parse_branch_row.cpp (100%)
 rename examples/{ => PowerFlow}/MatPowerTesting/test_parse_bus_row.cpp (100%)
 rename examples/{ => PowerFlow}/MatPowerTesting/test_parse_gen_row.cpp (100%)
 rename examples/{ => PowerFlow}/MatPowerTesting/test_parse_gencost_row.cpp (100%)
 rename examples/{ => PowerFlow}/MatPowerTesting/test_parse_matpower.cpp (100%)
 create mode 100644 examples/README.md

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index cb154a7e..c242976a 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -3,7 +3,6 @@
 #    - Slaven Peles <peless@ornl.gov>
 #]]
 
-add_subdirectory(MatPowerTesting)
 add_subdirectory(LinearAlgebra)
 
 add_subdirectory(PowerFlow)
diff --git a/examples/PowerFlow/CMakeLists.txt b/examples/PowerFlow/CMakeLists.txt
index 473d79af..584a6c70 100644
--- a/examples/PowerFlow/CMakeLists.txt
+++ b/examples/PowerFlow/CMakeLists.txt
@@ -3,6 +3,8 @@
 #    - Slaven Peles <peless@ornl.gov>
 #]]
 
+add_subdirectory(MatPowerTesting)
+
 if(TARGET SUNDIALS::kinsol)
   add_subdirectory(Grid3Bus)
 endif()
diff --git a/examples/MatPowerTesting/CMakeLists.txt b/examples/PowerFlow/MatPowerTesting/CMakeLists.txt
similarity index 100%
rename from examples/MatPowerTesting/CMakeLists.txt
rename to examples/PowerFlow/MatPowerTesting/CMakeLists.txt
diff --git a/examples/MatPowerTesting/test_parse_branch_row.cpp b/examples/PowerFlow/MatPowerTesting/test_parse_branch_row.cpp
similarity index 100%
rename from examples/MatPowerTesting/test_parse_branch_row.cpp
rename to examples/PowerFlow/MatPowerTesting/test_parse_branch_row.cpp
diff --git a/examples/MatPowerTesting/test_parse_bus_row.cpp b/examples/PowerFlow/MatPowerTesting/test_parse_bus_row.cpp
similarity index 100%
rename from examples/MatPowerTesting/test_parse_bus_row.cpp
rename to examples/PowerFlow/MatPowerTesting/test_parse_bus_row.cpp
diff --git a/examples/MatPowerTesting/test_parse_gen_row.cpp b/examples/PowerFlow/MatPowerTesting/test_parse_gen_row.cpp
similarity index 100%
rename from examples/MatPowerTesting/test_parse_gen_row.cpp
rename to examples/PowerFlow/MatPowerTesting/test_parse_gen_row.cpp
diff --git a/examples/MatPowerTesting/test_parse_gencost_row.cpp b/examples/PowerFlow/MatPowerTesting/test_parse_gencost_row.cpp
similarity index 100%
rename from examples/MatPowerTesting/test_parse_gencost_row.cpp
rename to examples/PowerFlow/MatPowerTesting/test_parse_gencost_row.cpp
diff --git a/examples/MatPowerTesting/test_parse_matpower.cpp b/examples/PowerFlow/MatPowerTesting/test_parse_matpower.cpp
similarity index 100%
rename from examples/MatPowerTesting/test_parse_matpower.cpp
rename to examples/PowerFlow/MatPowerTesting/test_parse_matpower.cpp
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..cd7ad11e
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,17 @@
+# GridKit™ Usage Examples
+
+GridKit™ usage examples are organized in following way:
+- `Enzyme` directory contains Enzyme automatic differentiation examples.
+- `Experimental` directory contains examples of dynamic-constrained
+optimization.
+- `LinearAlgebra` has examples and tests for dense and sparse matrices in
+GridKit™.
+- `PhasorDynamics` contains examples describing use of GridKit™ for phasor
+domain dynamic simulations.
+- `PowerElectronics` has examples describing microgrid simulations with
+GridKit™.
+- `PowerFlow` contains examples of power flow steady-state simulations with
+GridKit™.
+
+Examples are also used as integration tests for GridKit™ and are run on CI
+pipeline.