Add comments

src/holeg/GridSolverResult.java

@@ -1,5 +1,20 @@
 package holeg;
 
 public enum GridSolverResult {
-    Error, PartialFailure, Solved, Interrupted
+    /**
+     * An error occurred during the solving.
+     */
+    Error,
+    /**
+     * Any subgrid was not solved successfully.
+     */
+    PartialFailure,
+    /**
+     * All subgrids were solved successfully.
+     */
+    Solved,
+    /**
+     * The solving was interrupted (stopped). No solution was produced.
+     */
+    Interrupted
 }

src/holeg/HolegGateway.java

@@ -23,12 +23,15 @@ public class HolegGateway {
         for (HolonObject object : network.getHolonObjectList()) {
             double power = object.getEnergyAtTimeStep(iteration);
             SimpleGridNode node;
+
+            // Create house or generator
             if (power <= 0)
                 node = gridBuilder.addHouse(new ComplexNumber(-power, 0));
             else
                 node = gridBuilder.addGenerator(new ComplexNumber(power, 0));
             node.tag = object;
 
+            // Find type by design
             if (object.getElements().stream().anyMatch(e -> e.getEleName().equalsIgnoreCase("SLACK")))
                 node.typeByDesign = NodeType.Slack;
             else if (object.getElements().stream().anyMatch(e -> e.getEleName().equalsIgnoreCase("TRANSFORMER")))
@@ -37,12 +40,15 @@ public class HolegGateway {
                 node.typeByDesign = NodeType.Bus;
             canvasToGrid.put(object, node);
         }
+        // Add all switches and nodes
         for (AbstractCanvasObject object : network.getNodeAndSwitches()) {
             SimpleGridNode node = gridBuilder.addHouse(new ComplexNumber(0, 0));
             node.tag = object;
             node.typeByDesign = NodeType.Bus;
             canvasToGrid.put(object, node);
         }
+
+        // Add all cables
         for (IntermediateCableWithState cable : network.getEdgeList()) {
             SimpleGridNode a = canvasToGrid.get(cable.getModel().getA());
             SimpleGridNode b = canvasToGrid.get(cable.getModel().getB());
@@ -59,8 +65,12 @@ public class HolegGateway {
     private static void decorateNetwork(MinimumNetwork network, int iteration, FlexManager flexManager, DecoratedNetwork decoratedNetwork, Grid grid) {
         synchronized (decoratedNetwork.getLockObject()) {
             decoratedNetwork.clear();
+
+            // Convert all nodes
             for (GridNode node : grid.getNodes()) {
                 SimpleGridNode simpleNode = (SimpleGridNode) node;
+
+                // Create supplier, consumer or passiv object
                 if (node.getPowerGeneration().lenSquared() > 0)
                     decoratedNetwork.getSupplierList().add(new Supplier((HolonObject) simpleNode.tag, (float) node.getPowerGeneration().real, 0, simpleNode.voltage, simpleNode.phaseDegrees, simpleNode.typeSolved == NodeType.Slack));
                 else if (node.getPowerConsumption().lenSquared() > 0)
@@ -68,6 +78,8 @@ public class HolegGateway {
                 else if (simpleNode.tag instanceof HolonObject)
                     decoratedNetwork.getPassivNoEnergyList().add(new Passiv((HolonObject) simpleNode.tag));
             }
+
+            // Convert all edges
             for (GridEdge edge : grid.getEdges()) {
                 SimpleGridEdge simpleGridEdge = (SimpleGridEdge) edge;
                 decoratedNetwork.getDecoratedCableList().add(
@@ -85,7 +97,7 @@ public class HolegGateway {
         boolean solve = !PowerFlowAnalysisMenu.getInstance().areUpdatesDisabled();
         Grid grid = convert(minimumNetwork, iteration, flexManager);
 
-        // Check if the grid is equal to the one already solved
+        // Check if the grid is equal to one already solved
         if (context != null) {
             for (Grid lastSolved : context.lastSolvedGrids) {
                 if (GridComparator.isEqual(lastSolved, grid)) {
@@ -109,6 +121,7 @@ public class HolegGateway {
         if (context != null && context.solverJob != null) {
             try {
                 context.solverJob.interrupt();
+                // wait till old solver job has finished or is interrupted
                 context.solverJob.join(200);
             }
             catch(InterruptedException ignored) {
@@ -121,6 +134,8 @@ public class HolegGateway {
         Thread solverJob = new Thread(() -> {
             long start = System.nanoTime();
             GridSolverResult result = null;
+
+            // Starting solving when requested
             if (solve) {
                 HolegPowerFlow powerFlow = new HolegPowerFlow();
                 result = powerFlow.solve(grid, PowerFlowSettings.getDefault());
@@ -130,9 +145,11 @@ public class HolegGateway {
             decorateNetwork(minimumNetwork, iteration, flexManager, network, grid);
             if (context != null)
                 context.solverTimeMilliseconds = (System.nanoTime() - start) / 1e6f;
+
+            // Update canvas and other visuals
             SingletonControl.getInstance().getControl().calculateVisual();
 
-            // Show result
+            // Show result message box
             if (result != null && PowerFlowAnalysisMenu.getInstance().shouldShowResult())
                 SolveResultMessageBox.show(result);
         });
@@ -141,10 +158,12 @@ public class HolegGateway {
         // Wait or save solver job
         try {
             if (context == null || context.settings.waitForSolverJob) {
+                // Start and wait till solver job is finished
                 solverJob.start();
                 solverJob.join();
             }
             else {
+                // Render the non-solved grid and start the real solver job
                 decorateNetwork(minimumNetwork, iteration, flexManager, network, grid);
                 context.solverJob = solverJob;
                 solverJob.start();

src/holeg/PowerFlowSettings.java

@@ -3,13 +3,39 @@ package holeg;
 import holeg.power_flow.SolverSettings;
 
 public class PowerFlowSettings {
+    /**
+     * The solver settings to use.
+     */
     public SolverSettings solverSettings;
+    /**
+     * When true the solver is only used when the grid has changed to any last solved grid.
+     */
     public boolean onlyUpdateGridWhenChanged;
+    /**
+     * When true the solving is done synchronous with the main update. This will lead to the main thread waiting.
+     */
     public boolean waitForSolverJob;
+    /**
+     * When true grids which have no producers are not solved.
+     */
     public boolean skipGridsWithNoProducers;
+    /**
+     * When true the solver changes one node to the slack node when no slack node is given by the grid design.
+     */
     public boolean replaceNodeWithSlackNode;
+    /**
+     * Sets the slack node placement strategy which is used to create and solve the grid.
+     */
     public SlackNodePlacementStrategy slackNodePlacementStrategy;
+    /**
+     * Sets the maximum power the slack node should consume or produce. When the power is exceeded the grid
+     * is returned as an invalid grid.
+     */
     public double maxSlackPowerUntilInvalid;
+    /**
+     * Sets the minimum voltage any node can have. When the voltage is lower of any node the grid is returned
+     * as an invalid grid.
+     */
     public double minVoltageUntilInvalid;
 
     public PowerFlowSettings() {
@@ -23,6 +49,10 @@ public class PowerFlowSettings {
         minVoltageUntilInvalid = 0.3;
     }
 
+    /**
+     * Returns default settings.
+     * @return The default settings.
+     */
     public static PowerFlowSettings getDefault() {
         return new PowerFlowSettings();
     }

src/holeg/SlackNodePlacementStrategy.java

@@ -1,10 +1,29 @@
 package holeg;
 
 public enum SlackNodePlacementStrategy {
+    /**
+     * The first node is always replaced as a slack node. The grid is only solved once.
+     */
     FirstNode,
+    /**
+     * A random node is chosen as the slack node. The grid is only solved once.
+     */
     RandomNode,
+    /**
+     * A random producer is chosen as the slack node. The grid is only solved once.
+     */
     RandomProducer,
+    /**
+     * The largest producer is chosen as the slack node. The grid is only solved once.
+     */
     LargestProducer,
+    /**
+     * The largest consumer is chosen as the slack node. The grid is only solved once.
+     */
     LargestConsumer,
+    /**
+     * The grid is solved multiple times. For each try another node is the slack node. The minimum solution to
+     * the problem in terms of the slack power is chosen as the final solved grid.
+     */
     MinimizeSlack
 }

src/holeg/model/Grid.java

@@ -2,23 +2,39 @@ package holeg.model;
 
 import java.util.*;
 
+/**
+ * Abstracts the electrical grid.
+ */
 public class Grid {
     private List<GridNode> nodes = new ArrayList<>();
     private Set<GridEdge> edges = new HashSet<>();
     private HashMap<GridNode, List<GridEdge>> edgesPerNode = new HashMap<>();
 
+    /**
+     * Adds a node to the grid.
+     * @param node The node to be added.
+     */
     public void addNode(GridNode node) {
         if (node == null)
             throw new IllegalArgumentException("node is null");
         nodes.add(node);
     }
 
+    /**
+     * Adds edge to the edgesPerNode map.
+     * @param node The node to use.
+     * @param edge The edge to add.
+     */
     private void addEdgeToMap(GridNode node, GridEdge edge) {
         List<GridEdge> edges = edgesPerNode.getOrDefault(node, new ArrayList<>());
         edges.add(edge);
         edgesPerNode.put(node, edges);
     }
 
+    /**
+     * Adds an edge to the grid.
+     * @param edge The edge to add.
+     */
     public void addEdge(GridEdge edge) {
         if (edge == null)
             throw new IllegalArgumentException("edge is null");

src/holeg/model/GridComparator.java

@@ -4,8 +4,18 @@ import holeg.power_flow.ComplexNumber;
 
 import java.util.HashSet;
 
+/**
+ * Compares two grids and checks if they are equal.
+ */
 public class GridComparator {
+    /**
+     * Compare the two grids a and b.
+     * @param a The first grid to compare to.
+     * @param b The second grid to compare to.
+     * @return True when the grid a and b are equal or false otherwise.
+     */
     public static boolean isEqual(Grid a, Grid b) {
+        // Trival checks
         if (a == b)
             return true;
         if (a == null || b == null)

src/holeg/model/NodeType.java

@@ -1,7 +1,16 @@
 package holeg.model;
 
 public enum NodeType {
+    /**
+     * The node is a bus (supplier, consumer)
+     */
     Bus,
+    /**
+     * The node is a slack node.
+     */
     Slack,
+    /**
+     * The node is a transformer.
+     */
     Transformer
 }

src/holeg/power_flow/SolverError.java

@@ -1,9 +1,24 @@
 package holeg.power_flow;
 
 public enum SolverError {
+    /**
+     * No error occurred.
+     */
     None,
+    /**
+     * An internal error occurred.
+     */
     Internal,
+    /**
+     * The problem data is invalid.
+     */
     InvalidData,
+    /**
+     * The problem did not converge.
+     */
     ConvergenceError,
+    /**
+     * The solver thread was interrupted.
+     */
     Interrupted
 }

src/holeg/ui/PowerFlowAnalysisMenu.java

@@ -37,7 +37,7 @@ public class PowerFlowAnalysisMenu extends JMenu {
         showDebugMessageBox = (JCheckBoxMenuItem) add(new JCheckBoxMenuItem("Show debug message"));
 
         clearCache.addActionListener((e) -> {
-            SingletonControl.getInstance().getControl().getSimManager().getHolegPowerFlowContext().clearCache();
+            clearCache();
         });
 
         solve.addActionListener((e) -> {
@@ -51,10 +51,16 @@ public class PowerFlowAnalysisMenu extends JMenu {
         instance = this;
     }
 
+    private void clearCache() {
+        SingletonControl.getInstance().getControl().getSimManager().getHolegPowerFlowContext().clearCache();
+    }
+
     private void solve(boolean clearCache) {
+        // This is needed otherwise the calculateStateAndVisualForCurrentTimeStep() function would not do anything
+        // when updates are disabled (same execution path)
         overwriteDisableUpdatesToForceUpdates = true;
         if (clearCache)
-            SingletonControl.getInstance().getControl().getSimManager().getHolegPowerFlowContext().clearCache();
+            clearCache();
         SingletonControl.getInstance().getControl().calculateStateAndVisualForCurrentTimeStep();
         overwriteDisableUpdatesToForceUpdates = false;
     }

src/holeg/ui/SolveResultMessageBox.java

@@ -8,6 +8,7 @@ public class SolveResultMessageBox {
     public static void show(GridSolverResult result) {
         switch(result) {
             case Error:
+            default:
                 JOptionPane.showMessageDialog(null,"Could not solve grid.","Error while solving.", JOptionPane.ERROR_MESSAGE);
                 break;
             case PartialFailure: