LimitViolation.java

/**
 * Copyright (c) 2016, All partners of the iTesla project (http://www.itesla-project.eu/consortium)
 * Copyright (c) 2017, RTE (http://www.rte-france.com)
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 * SPDX-License-Identifier: MPL-2.0
 */
package com.powsybl.security;

import com.powsybl.commons.extensions.AbstractExtendable;
import com.powsybl.iidm.network.*;
import org.jspecify.annotations.Nullable;

import java.util.Objects;
import java.util.Optional;

/**
 * A generic representation of a violation of a network equipment security limit.
 * For example, it may represent a current overload on a line.
 *
 * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
 */
public class LimitViolation extends AbstractExtendable<LimitViolation> {

    private final String subjectId;

    private final String subjectName;

    private final LimitViolationType limitType;

    private final double limit;

    private final String limitName;

    private final int acceptableDuration;

    private final double limitReduction;

    private final double value;

    private final ThreeSides side;

    private final ViolationLocation voltageLocation;

    /**
     * Create a new LimitViolation.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param subjectName        An optional name of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
     */
    public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value, @Nullable ThreeSides side, @Nullable ViolationLocation voltageLocation) {
        this.subjectId = Objects.requireNonNull(subjectId);
        this.subjectName = subjectName;
        this.limitType = Objects.requireNonNull(limitType);
        this.limitName = limitName;
        this.acceptableDuration = acceptableDuration;
        this.limit = limit;
        this.limitReduction = limitReduction;
        this.value = value;
        this.side = checkSide(limitType, side);
        this.voltageLocation = voltageLocation;
    }

    /**
     * Create a new LimitViolation.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param subjectName        An optional name of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
     */
    public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value, @Nullable ThreeSides side) {
        this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, side, null);
    }

    /**
     * Create a new LimitViolation without side.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param subjectName        An optional name of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     */
    public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value) {
        this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, (ThreeSides) null);

    }

    /**
     * Create a new LimitViolation.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param subjectName        An optional name of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
     */
    public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value, TwoSides side) {
        this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, Objects.requireNonNull(side).toThreeSides());
    }

    /**
     * Create a new LimitViolation.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
     */
    public LimitViolation(String subjectId, LimitViolationType limitType, String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value, TwoSides side) {
        this(subjectId, null, limitType, limitName, acceptableDuration, limit, limitReduction, value, Objects.requireNonNull(side).toThreeSides());
    }

    /**
     * Create a new LimitViolation without side.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId          The identifier of the network equipment on which the violation occurred.
     * @param limitType          The type of limit which has been violated.
     * @param limitName          An optional name for the limit which has been violated.
     * @param acceptableDuration The acceptable duration, in seconds, associated to the current violation value. Only relevant for current limits.
     * @param limit              The value of the limit which has been violated.
     * @param limitReduction     The limit reduction factor used for violation detection.
     * @param value              The actual value of the physical value which triggered the detection of a violation.
     */
    public LimitViolation(String subjectId, LimitViolationType limitType, String limitName, int acceptableDuration,
                          double limit, double limitReduction, double value) {
        this(subjectId, null, limitType, limitName, acceptableDuration, limit, limitReduction, value, (ThreeSides) null);
    }

    /**
     * Create a new LimitViolation, for types other than current limits.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId      The identifier of the network equipment on which the violation occurred.
     * @param limitType      The type of limit which has been violated.
     * @param limit          The value of the limit which has been violated.
     * @param limitReduction The limit reduction factor used for violation detection.
     * @param value          The actual value of the physical value which triggered the detection of a violation.
     * @param voltageLocation    Detailed information about the location of the violation.
     */
    public LimitViolation(String subjectId, LimitViolationType limitType, double limit, double limitReduction, double value, ViolationLocation voltageLocation) {
        this(subjectId, null, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, voltageLocation);
    }

    /**
     * Create a new LimitViolation, for types other than current limits.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId      The identifier of the network equipment on which the violation occurred.
     * @param subjectName    An optional name of the network equipment on which the violation occurred.
     * @param limitType      The type of limit which has been violated.
     * @param limit          The value of the limit which has been violated.
     * @param limitReduction The limit reduction factor used for violation detection.
     * @param value          The actual value of the physical value which triggered the detection of a violation.
     */
    public LimitViolation(String subjectId, String subjectName, LimitViolationType limitType, double limit, double limitReduction, double value) {
        this(subjectId, subjectName, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, null);
    }

    /**
     * Create a new LimitViolation, for types other than current limits.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId      The identifier of the network equipment on which the violation occurred.
     * @param subjectName    An optional name of the network equipment on which the violation occurred.
     * @param limitType      The type of limit which has been violated.
     * @param limit          The value of the limit which has been violated.
     * @param limitReduction The limit reduction factor used for violation detection.
     * @param value          The actual value of the physical value which triggered the detection of a violation.
     * @param voltageLocation    Detailed information about the location of the violation.
     */
    public LimitViolation(String subjectId, String subjectName, LimitViolationType limitType, double limit, double limitReduction, double value, ViolationLocation voltageLocation) {
        this(subjectId, subjectName, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, voltageLocation);
    }

    /**
     * Create a new LimitViolation, for voltage angle limit.
     *
     * <p>According to the violation type, all parameters may not be mandatory. See constructor overloads for particular types.
     *
     * @param subjectId      The identifier of the network equipment on which the violation occurred.
     * @param limitType      The type of limit which has been violated.
     * @param limit          The value of the limit which has been violated.
     * @param limitReduction The limit reduction factor used for violation detection.
     * @param value          The actual value of the physical value which triggered the detection of a violation.
     */
    public LimitViolation(String subjectId, LimitViolationType limitType, double limit, double limitReduction, double value) {
        this(subjectId, null, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, null);
    }

    /**
     * The identifier of the network equipment on which the violation occurred.
     *
     * @return the identifier of the network equipment on which the violation occurred.
     */
    public String getSubjectId() {
        return subjectId;
    }

    /**
     * The identifier of the network equipment on which the violation occurred.
     *
     * @return the identifier of the network equipment on which the violation occurred.
     */
    public Optional<ViolationLocation> getViolationLocation() {
        return Optional.ofNullable(voltageLocation);
    }

    /**
     * The name of the network equipment on which the violation occurred.
     * May be {@code null}.
     *
     * @return the name of the network equipment on which the violation occurred.
     */
    @Nullable
    public String getSubjectName() {
        return subjectName;
    }

    /**
     * The type of limit which has been violated.
     *
     * @return the type of limit which has been violated.
     */
    public LimitViolationType getLimitType() {
        return limitType;
    }

    /**
     * The value of the limit which has been violated.
     *
     * @return the value of the limit which has been violated.
     */
    public double getLimit() {
        return limit;
    }

    /**
     * The name of the limit which has been violated. May be {@code null}.
     *
     * @return the value of the limit which has been violated. May be {@code null}.
     */
    @Nullable
    public String getLimitName() {
        return limitName;
    }

    /**
     * The acceptable duration, in seconds, associated to the current violation value.
     * Only relevant for current limits.
     *
     * @return the acceptable duration, in seconds, associated to the current violation value.
     */
    public int getAcceptableDuration() {
        return acceptableDuration;
    }

    /**
     * The limit reduction factor used for violation detection.
     * For example when monitoring values above 95% of a given limit, this will return {@code 0.95}
     *
     * @return the limit reduction factor used for violation detection.
     */
    public double getLimitReduction() {
        return limitReduction;
    }

    /**
     * The actual value of the physical value which triggered the detection of a violation.
     *
     * @return the actual value of the physical value which triggered the detection of a violation.
     */
    public double getValue() {
        return value;
    }

    /**
     * The side of the equipment with two sides (like branch) where the violation occurred.
     *
     * @return the side of the equipment with two sides (like branch) where the violation occurred.
     */
    public TwoSides getSideAsTwoSides() {
        return Objects.requireNonNull(side).toTwoSides();
    }

    /**
     * The side of the equipment where the violation occurred. Will be {@code null} for equipments
     * other than branches and three windings transformers.
     *
     * @return the side of the equipment where the violation occurred. Will be {@code null} for equipments
     * other than branches and three windings transformers.
     */
    @Nullable
    public ThreeSides getSide() {
        return side;
    }

    private static ThreeSides checkSide(LimitViolationType limitType, ThreeSides side) {
        if (limitType == LimitViolationType.ACTIVE_POWER
            || limitType == LimitViolationType.APPARENT_POWER
            || limitType == LimitViolationType.CURRENT) {
            return Objects.requireNonNull(side);
        } else {
            return null;
        }
    }

    public String toString() {
        return "Subject id: " + this.subjectId + ", Subject name: " + this.subjectName + ", limitType: " +
                this.limitType + ", limit: " + this.limit + ", limitName: " + this.limitName +
                ", acceptableDuration: " + this.acceptableDuration + ", limitReduction: " + this.limitReduction +
                ", value: " + this.value + ", side: " + this.side + ", voltageLocation: " + this.voltageLocation;
    }
}