From cf598b153e8983beb681555cbaceadbe324c2bc8 Mon Sep 17 00:00:00 2001 From: Coline Piloquet <55250145+colinepiloquet@users.noreply.github.com> Date: Mon, 22 Jul 2024 11:09:10 +0200 Subject: [PATCH] [Short-circuit API] Add some javadoc (#3096) Signed-off-by: Coline PILOQUET --- .../com/powsybl/shortcircuit/BranchFault.java | 12 +++-- .../com/powsybl/shortcircuit/BusFault.java | 3 +- .../shortcircuit/FailedFaultResult.java | 2 + .../java/com/powsybl/shortcircuit/Fault.java | 47 ++++++++++++++++--- .../powsybl/shortcircuit/FaultParameters.java | 15 ++++++ .../com/powsybl/shortcircuit/FaultResult.java | 7 ++- .../powsybl/shortcircuit/FeederResult.java | 2 + .../shortcircuit/FortescueFaultResult.java | 2 +- .../shortcircuit/FortescueFeederResult.java | 2 + .../FortescueShortCircuitBusResults.java | 2 + .../powsybl/shortcircuit/FortescueValue.java | 40 ++++++++++++++++ .../InitialVoltageProfileMode.java | 17 ++++++- .../shortcircuit/MagnitudeFaultResult.java | 2 +- .../shortcircuit/MagnitudeFeederResult.java | 2 + .../MagnitudeShortCircuitBusResults.java | 2 + .../shortcircuit/ShortCircuitBusResults.java | 2 + .../shortcircuit/ShortCircuitConstants.java | 2 + .../shortcircuit/ShortCircuitParameters.java | 11 ++++- .../com/powsybl/shortcircuit/StudyType.java | 15 ++++++ 19 files changed, 166 insertions(+), 21 deletions(-) diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BranchFault.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BranchFault.java index b6fb7456102..7d15a9c1fbd 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BranchFault.java +++ b/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 } */ 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; } diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BusFault.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BusFault.java index fefecf88c36..13880b30988 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BusFault.java +++ b/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 } */ diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FailedFaultResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FailedFaultResult.java index f7eed04af6e..6ca4bf13eb5 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FailedFaultResult.java +++ b/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 } */ public class FailedFaultResult extends AbstractFaultResult { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java index 3cd1407aad2..7c09ba6fbe3 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java @@ -21,25 +21,30 @@ /** * Interface to describe the characteristics of the fault to be simulated. - * Used for elementary short-circuit analysis only. * * @author Anne Tilloy {@literal } */ 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, @@ -47,27 +52,50 @@ enum FaultType { //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 faults, Path jsonFile) { try (OutputStream out = Files.newOutputStream(jsonFile)) { createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, faults); @@ -76,6 +104,11 @@ static void write(List 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 read(Path jsonFile) { try (InputStream is = Files.newInputStream(jsonFile)) { return createObjectMapper().readerForListOf(Fault.class).readValue(is); diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java index 79d3735ddf4..bb39bd6be56 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java +++ b/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 } */ 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 parameters, Path jsonFile) { try (OutputStream out = Files.newOutputStream(jsonFile)) { createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, parameters); @@ -249,6 +256,11 @@ public static void write(List 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 read(Path jsonFile) { try (InputStream is = Files.newInputStream(jsonFile)) { return createObjectMapper().readerForListOf(FaultParameters.class).readValue(is); @@ -257,6 +269,9 @@ public static List 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."); diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultResult.java index f9c57c56432..a13dafed7ef 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultResult.java +++ b/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 } */ public interface FaultResult extends Extendable { + /** + * 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, /** diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FeederResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FeederResult.java index a3ef82cd7b7..84f8588190b 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FeederResult.java +++ b/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 } */ public interface FeederResult { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFaultResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFaultResult.java index b2b3039319d..67bbe1bc1c5 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFaultResult.java +++ b/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 } */ diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFeederResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFeederResult.java index 2d0da7f18e6..f060d66f9e9 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFeederResult.java +++ b/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 } */ public class FortescueFeederResult extends AbstractFeederResult { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueShortCircuitBusResults.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueShortCircuitBusResults.java index 4b8ed0e6a7b..1dd32987f89 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueShortCircuitBusResults.java +++ b/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 } */ public class FortescueShortCircuitBusResults extends AbstractShortCircuitBusResults { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueValue.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueValue.java index 686384dd8a1..ed8697503f8 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueValue.java +++ b/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] diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java index cca84f64fd2..5e2511a592f 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java +++ b/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 } */ 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 } diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFaultResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFaultResult.java index ce4af0ebc71..981df0864ec 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFaultResult.java +++ b/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 } */ diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFeederResult.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFeederResult.java index 9b3d1012fb6..3bc3000c8a7 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFeederResult.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFeederResult.java @@ -10,6 +10,8 @@ import com.powsybl.iidm.network.ThreeSides; /** + * Three-phase current of a feeder contributing to the short-circuit current. + * * @author Coline Piloquet {@literal } */ public class MagnitudeFeederResult extends AbstractFeederResult { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeShortCircuitBusResults.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeShortCircuitBusResults.java index be9f4ea801e..27f161a9392 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeShortCircuitBusResults.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeShortCircuitBusResults.java @@ -8,6 +8,8 @@ package com.powsybl.shortcircuit; /** + * Three-phase voltage results on a bus after the short-circuit computation. + * * @author Coline Piloquet {@literal } */ public class MagnitudeShortCircuitBusResults extends AbstractShortCircuitBusResults { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitBusResults.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitBusResults.java index 9c6efacb33c..2ebf22da5d6 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitBusResults.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitBusResults.java @@ -8,6 +8,8 @@ package com.powsybl.shortcircuit; /** + * An interface describing the voltage results on a bus. + * * @author Coline Piloquet {@literal } */ public interface ShortCircuitBusResults { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitConstants.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitConstants.java index 79b5de910fc..c487ef37cc7 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitConstants.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitConstants.java @@ -8,6 +8,8 @@ package com.powsybl.shortcircuit; /** + * Some constants related to the short-circuit API. Includes the default values of parameters. + * * @author Coline Piloquet {@literal } */ public final class ShortCircuitConstants { diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitParameters.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitParameters.java index 015d13ea5a2..4523bbf7f35 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitParameters.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitParameters.java @@ -113,6 +113,10 @@ private void readExtensions(PlatformConfig platformConfig) { } } + /** + * Whether limit violations should be returned after the calculation. + * They indicate whether the maximum or minimum allowable current has been reached. + */ public boolean isWithLimitViolations() { return withLimitViolations; } @@ -196,7 +200,7 @@ public ShortCircuitParameters setMinVoltageDropProportionalThreshold(double minV return this; } - /** In case of a sub-transient study, a multiplicative coefficient to obtain the sub-transient reactance of the generators + /** In the case of a sub-transient study, a multiplicative coefficient to obtain the sub-transient reactance of the generators * from the transient reactance. By default, X''d = 0.7 * X'd. */ public double getSubTransientCoefficient() { @@ -267,7 +271,7 @@ public ShortCircuitParameters setWithNeutralPosition(boolean withNeutralPosition * The initial voltage profile mode, it can be either: * - nominal: nominal voltages will be used * - configured: the voltage profile is given by the user, voltage ranges and associated coefficients should be given using {@link VoltageRange} - * - previous value: the voltage profile computed from the loadflow will be used + * - previous value: the voltage profile computed from the load flow will be used */ public InitialVoltageProfileMode getInitialVoltageProfileMode() { return initialVoltageProfileMode; @@ -304,6 +308,9 @@ public ShortCircuitParameters setDetailedReport(boolean detailedReport) { return this; } + /** + * Validates the ShortCircuitParameters. If the initial voltage profile mode is set to CONFIGURED, then the voltage ranges should not be empty. + */ 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."); diff --git a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/StudyType.java b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/StudyType.java index c4cbffb7fb1..710b8337864 100644 --- a/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/StudyType.java +++ b/shortcircuit-api/src/main/java/com/powsybl/shortcircuit/StudyType.java @@ -7,8 +7,23 @@ */ package com.powsybl.shortcircuit; +/** + * The type of short-circuit calculation, transient, sub-transient or steady-state. + */ public enum StudyType { + + /** + * The first stage of the short circuit, right when the fault occurs. + */ SUB_TRANSIENT, + + /** + * The second stage of the short circuit, before the system stabilizes. + */ TRANSIENT, + + /** + * The final stage of the short circuit, when all transient effects have disappeared. + */ STEADY_STATE }