[Short-circuit API] Add some javadoc (#3096)

Signed-off-by: Coline PILOQUET <[email protected]>

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BranchFault.java

@@ -8,14 +8,12 @@
 package com.powsybl.shortcircuit;
 
 /**
- * Class to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
+ * Class to describe the characteristics of a fault that occurs on a branch and that is to be simulated.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */
 public class BranchFault extends AbstractFault {
 
-    // Location of the fault in % of the branch length (with side ONE as reference).
     private final double proportionalLocation;
 
     public BranchFault(String id, String elementId, double r, double x, ConnectionType connection, FaultType faultType, double proportionalLocation) {
@@ -25,12 +23,12 @@ public BranchFault(String id, String elementId, double r, double x, ConnectionTy
     }
 
     public BranchFault(String id, String elementId, double r, double x, double proportionalLocation) {
-        // Here the elementId is the id of a bus from the bus view.
+        // Here the elementId is the id of a branch.
         this(id, elementId, r, x, ConnectionType.SERIES, FaultType.THREE_PHASE, proportionalLocation);
     }
 
     public BranchFault(String id, String elementId, double proportionalLocation) {
-        // Here the elementId is the id of a bus from the bus view.
+        // Here the elementId is the id of a branch.
         this(id, elementId, 0.0, 0.0, ConnectionType.SERIES, FaultType.THREE_PHASE, proportionalLocation);
     }
 
@@ -39,6 +37,10 @@ public Type getType() {
         return Type.BRANCH;
     }
 
+    /**
+     * Get the location of the fault on the branch
+     * @return the location of the fault in % of the branch length (with side ONE as reference).
+     */
     public double getProportionalLocation() {
         return this.proportionalLocation;
     }

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BusFault.java

@@ -8,8 +8,7 @@
 package com.powsybl.shortcircuit;
 
 /**
- * Class to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
+ * Class to describe the characteristics of a fault that occurs on a bus and that is to be simulated.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FailedFaultResult.java

@@ -8,6 +8,8 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * A class to represent the result if the analysis has failed.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FailedFaultResult extends AbstractFaultResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java

@@ -21,53 +21,81 @@
 
 /**
  * Interface to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */
 public interface Fault {
 
-    // Type of fault (use for downcast & serialize/deserialize)
+    /**
+     * Type of fault (use for downcast & serialize/deserialize).
+     */
     enum Type {
         BUS,
         BRANCH
     }
 
-    // How the fault impedance and resistance are associated.
+    /**
+     * How the fault impedance and resistance are connected to the ground.
+     */
     enum ConnectionType {
         SERIES,
         PARALLEL,
     }
 
-    // What kind of fault is simulated
+    /**
+     * The type of fault being simulated.
+     */
     enum FaultType {
         THREE_PHASE,
         SINGLE_PHASE,
     }
 
     //TODO : add the numbers of the phase for two and single phase
 
-    // The fault id.
+    /**
+     * The ID of the fault.
+     */
     String getId();
 
-    // The equipment or bus id where the fault is simulated.
+    /**
+     * The ID of the equipment or bus associated to this fault.
+     */
     String getElementId();
 
-    // Characteristics of the short circuit to ground.
+    /**
+     * The resistance of the fault to the ground. The default is zero Ohms.
+     */
     double getRToGround();
 
+    /**
+     * The reactance of the fault to the ground. The default is zero Ohms.
+     */
     double getXToGround();
 
+    /**
+     * The type of the element associated to the fault: can be BUS or BRANCH.
+     */
     Type getType();
 
+    /**
+     * How the fault resistance and reactance are connected to the ground. Can be SERIES or PARALLEL.
+     */
     ConnectionType getConnectionType();
 
+    /**
+     * The type of fault occurring on the network element: can be THREE-PHASE or SINGLE-PHASE.
+     */
     FaultType getFaultType();
 
     private static ObjectMapper createObjectMapper() {
         return JsonUtil.createObjectMapper().registerModule(new ShortCircuitAnalysisJsonModule());
     }
 
+    /**
+     * Writes a list of faults to a JSON file
+     * @param faults the list of faults
+     * @param jsonFile the path to the JSON file
+     */
     static void write(List<Fault> faults, Path jsonFile) {
         try (OutputStream out = Files.newOutputStream(jsonFile)) {
             createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, faults);
@@ -76,6 +104,11 @@ static void write(List<Fault> faults, Path jsonFile) {
         }
     }
 
+    /**
+     * Reads a JSON file and creates the associated list of faults
+     * @param jsonFile the path to the existing JSON file
+     * @return a list of faults
+     */
     static List<Fault> read(Path jsonFile) {
         try (InputStream is = Files.newInputStream(jsonFile)) {
             return createObjectMapper().readerForListOf(Fault.class).readValue(is);

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java

@@ -27,6 +27,8 @@
 import static com.powsybl.shortcircuit.VoltageRange.checkVoltageRange;
 
 /**
+ * Class to override general short-circuit analysis parameters and make them specific to a particular fault.
+ *
  * @author Thomas Adam {@literal <tadam at silicom.fr>}
  */
 public class FaultParameters {
@@ -241,6 +243,11 @@ private static ObjectMapper createObjectMapper() {
         return JsonUtil.createObjectMapper().registerModule(new ShortCircuitAnalysisJsonModule());
     }
 
+    /**
+     * Writes a list of FaultParameters to a JSON file
+     * @param parameters the list of FaultParameters
+     * @param jsonFile the path to the JSON file
+     */
     public static void write(List<FaultParameters> parameters, Path jsonFile) {
         try (OutputStream out = Files.newOutputStream(jsonFile)) {
             createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, parameters);
@@ -249,6 +256,11 @@ public static void write(List<FaultParameters> parameters, Path jsonFile) {
         }
     }
 
+    /**
+     * Reads a JSON file and creates the associated list of FaultParameters
+     * @param jsonFile the path to the JSON file
+     * @return a list of FaultParameters
+     */
     public static List<FaultParameters> read(Path jsonFile) {
         try (InputStream is = Files.newInputStream(jsonFile)) {
             return createObjectMapper().readerForListOf(FaultParameters.class).readValue(is);
@@ -257,6 +269,9 @@ public static List<FaultParameters> read(Path jsonFile) {
         }
     }
 
+    /**
+     * Method used to validate FaultParameters. The voltage ranges should be defined if the parameter initialVoltageProfileMode is set to CONFIGURED.
+     */
     public void validate() {
         if (initialVoltageProfileMode == InitialVoltageProfileMode.CONFIGURED && (voltageRanges == null || voltageRanges.isEmpty())) {
             throw new PowsyblException("Configured initial voltage profile but nominal voltage ranges with associated coefficients are missing.");

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultResult.java

@@ -14,13 +14,18 @@
 import java.util.List;
 
 /**
+ * Interface to describe the result of the short-circuit analysis for a given fault.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public interface FaultResult extends Extendable<FaultResult> {
 
+    /**
+     * The status of the computation.
+     */
     enum Status {
         /**
-         * The computation went ok and no error were returned
+         * The computation went ok and no error was returned
          */
         SUCCESS,
         /**

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FeederResult.java

@@ -13,6 +13,8 @@
 import javax.annotation.Nullable;
 
 /**
+ * Interface to describe the contribution of a feeder to the short-circuit current after the analysis.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public interface FeederResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFaultResult.java

@@ -14,7 +14,7 @@
 import java.util.List;
 
 /**
- * Results for one fault computation with currents and voltage on the three phases.
+ * Results of the short-circuit calculation with the voltage and currents detailed on the three phases.
  *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFeederResult.java

@@ -10,6 +10,8 @@
 import com.powsybl.iidm.network.ThreeSides;
 
 /**
+ * Result detailed on the three phases for a feeder contributing to the short-circuit current.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FortescueFeederResult extends AbstractFeederResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueShortCircuitBusResults.java

@@ -8,6 +8,8 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * Results detailed on the three phases of the voltages on a bus.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FortescueShortCircuitBusResults extends AbstractShortCircuitBusResults {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueValue.java

@@ -39,26 +39,44 @@ public ThreePhaseValue(double magnitudeA, double magnitudeB, double magnitudeC,
             this.angleC = angleC;
         }
 
+        /**
+         * The magnitude on phase A
+         */
         public double getMagnitudeA() {
             return magnitudeA;
         }
 
+        /**
+         * The magnitude on phase B
+         */
         public double getMagnitudeB() {
             return magnitudeB;
         }
 
+        /**
+         * The magnitude on phase C
+         */
         public double getMagnitudeC() {
             return magnitudeC;
         }
 
+        /**
+         * The angle on phase A
+         */
         public double getAngleA() {
             return angleA;
         }
 
+        /**
+         * The angle on phase B
+         */
         public double getAngleB() {
             return angleB;
         }
 
+        /**
+         * The angle on phase C
+         */
         public double getAngleC() {
             return angleC;
         }
@@ -89,30 +107,52 @@ public FortescueValue(double positiveMagnitude) {
         this(positiveMagnitude, Double.NaN, Double.NaN, Double.NaN, Double.NaN, Double.NaN);
     }
 
+    /**
+     * The magnitude on the positive sequence
+     */
     public double getPositiveMagnitude() {
         return positiveMagnitude;
     }
 
+    /**
+     * The magnitude on the zero sequence
+     */
     public double getZeroMagnitude() {
         return zeroMagnitude;
     }
 
+    /**
+     * The magnitude on the negative sequence
+     */
     public double getNegativeMagnitude() {
         return negativeMagnitude;
     }
 
+    /**
+     * The angle on the positive sequence
+     */
     public double getPositiveAngle() {
         return positiveAngle;
     }
 
+    /**
+     * The angle on the zero sequence
+     */
     public double getZeroAngle() {
         return zeroAngle;
     }
 
+    /**
+     * The angle on the negative sequence
+     */
     public double getNegativeAngle() {
         return negativeAngle;
     }
 
+    /**
+     * Convert the value from the positive, zero and negative sequence to the A, B and C phase components.
+     * @return the three phase components.
+     */
     public ThreePhaseValue toThreePhaseValue() {
 
         // [G1]   [ 1  1  1 ]   [Gh]

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java

@@ -8,11 +8,24 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * The initial voltage profile to consider for the computation.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public enum InitialVoltageProfileMode {
+    /**
+     * The nominal values of the voltage are used.
+     */
     NOMINAL,
-    CONFIGURED, // Voltage profile given by the user
-    PREVIOUS_VALUE // Voltage profile from the loadflow
+
+    /**
+     * The user gives the voltage profile.
+     */
+    CONFIGURED,
+
+    /**
+     * The voltage profile used is the one calculated by the load flow calculation.
+     */
+    PREVIOUS_VALUE
 
 }

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFaultResult.java

@@ -14,7 +14,7 @@
 import java.util.List;
 
 /**
- * Results for one fault computation with current magnitude.
+ * Results for one fault with three-phase current magnitude.
  *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */