ShuntCompensator.java

/**
 * Copyright (c) 2016, All partners of the iTesla project (http://www.itesla-project.eu/consortium)
 * 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.iidm.network;

import java.util.OptionalInt;

/**
 * A shunt compensator.
 *
 * <p>
 *  Characteristics
 * </p>
 *
 * <table style="border: 1px solid black; border-collapse: collapse">
 *     <thead>
 *         <tr>
 *             <th style="border: 1px solid black">Attribute</th>
 *             <th style="border: 1px solid black">Type</th>
 *             <th style="border: 1px solid black">Unit</th>
 *             <th style="border: 1px solid black">Required</th>
 *             <th style="border: 1px solid black">Default value</th>
 *             <th style="border: 1px solid black">Description</th>
 *         </tr>
 *     </thead>
 *     <tbody>
 *         <tr>
 *             <td style="border: 1px solid black">Id</td>
 *             <td style="border: 1px solid black">String</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">yes</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">Unique identifier of the shunt compensator</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">Name</td>
 *             <td style="border: 1px solid black">String</td>
 *             <td style="border: 1px solid black">-</td>
 *             <td style="border: 1px solid black">yes</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">Human-readable name of the shunt compensator</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">bPerSection</td>
 *             <td style="border: 1px solid black">double</td>
 *             <td style="border: 1px solid black">S</td>
 *             <td style="border: 1px solid black">yes</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">The Positive sequence shunt (charging) susceptance per section </td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">MaximumSectionCount</td>
 *             <td style="border: 1px solid black">integer</td>
 *             <td style="border: 1px solid black">-</td>
 *             <td style="border: 1px solid black">yes</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">The maximum number of sections that may be switched on</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">CurrentSectionCount</td>
 *             <td style="border: 1px solid black">integer</td>
 *             <td style="border: 1px solid black">-</td>
 *             <td style="border: 1px solid black">yes</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">The current number of section that may be switched on</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">RegulatingTerminal</td>
 *             <td style="border: 1px solid black">Terminal</td>
 *             <td style="border: 1px solid black">-</td>
 *             <td style="border: 1px solid black">no</td>
 *             <td style="border: 1px solid black"> The shunt compensator's terminal </td>
 *             <td style="border: 1px solid black">The terminal used for regulation</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">TargetV</td>
 *             <td style="border: 1px solid black">double</td>
 *             <td style="border: 1px solid black">kV</td>
 *             <td style="border: 1px solid black">only if VoltageRegulatorOn is set to true</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">The voltage target</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">TargetDeadband</td></td>
 *             <td style="border: 1px solid black">double</td>
 *             <td style="border: 1px solid black">kV</td>
 *             <td style="border: 1px solid black">only if VoltageRegulatorOn is set to true</td>
 *             <td style="border: 1px solid black"> - </td>
 *             <td style="border: 1px solid black">The deadband used to avoid excessive update of controls</td>
 *         </tr>
 *         <tr>
 *             <td style="border: 1px solid black">VoltageRegulatorOn</td>
 *             <td style="border: 1px solid black">boolean</td>
 *             <td style="border: 1px solid black">-</td>
 *             <td style="border: 1px solid black">no</td>
 *             <td style="border: 1px solid black"> false </td>
 *             <td style="border: 1px solid black">The voltage regulating status</td>
 *         </tr>
 *     </tbody>
 * </table>
 *
 * To create a shunt compensator, see {@link ShuntCompensatorAdder}
 *
 * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
 * @see ShuntCompensatorAdder
 */
public interface ShuntCompensator extends Injection<ShuntCompensator> {

    /**
     * Get the count of sections in service.
     * Please note sections can only be sequentially in service i.e. the first sectionCount sections are in service.
     * <p>
     * It is expected to be greater than one and lesser than or equal to the
     * maximum section count.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    int getSectionCount();

    /**
     * Get the count of sections in service if it is defined.
     * Otherwise, get an empty optional.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default OptionalInt findSectionCount() {
        return OptionalInt.of(getSectionCount());
    }

    /**
     * Get the maximum number of sections that can be in service
     */
    int getMaximumSectionCount();

    /**
     * Change the count of sections in service.
     * Please note sections can only be sequentially in service i.e. the first sectionCount sections are in service.
     * <p>
     * Depends on the working variant.
     *
     * @see VariantManager
     * @param sectionCount the number of sections wanted to be put in service
     * @return the shunt compensator to chain method calls.
     */
    ShuntCompensator setSectionCount(int sectionCount);

    /**
     * Unset the count of sections in service.
     * Note: this can be done <b>only</b> in SCADA validation level.
     */
    default ShuntCompensator unsetSectionCount() {
        throw ValidationUtil.createUnsetMethodException();
    }

    /**
     * Get the susceptance (in S) of the shunt in its current state i.e. the sum of the sections' susceptances for all sections in service.
     * Return 0 if no section is in service (disconnected state).
     * @see #getSectionCount()
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    double getB();

    /**
     * Get the conductance (in S) of the shunt in its current state i.e. the sum of the sections' conductances for all sections in service.
     * If the conductance of a section in service is undefined, it is considered equal to 0.
     * Return 0 if no section is in service (disconnected state).
     * @see #getSectionCount()
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    double getG();

    /**
     * Get the susceptance (in S) for a given activated sections count i.e. the sum of the sections' susceptances from 1 to sectionCount.
     * Return O if sectionCount is equal to 0 (disconnected state).
     *
     * @param sectionCount count of wanted activated sections. Must be in [0; maximumSectionCount]. Else, throws a {@link ValidationException}.
     */
    double getB(int sectionCount);

    /**
     * Get the conductance (in S) for a given activated sections count i.e. the sum of the sections' conductances from 1 to sectionCount.
     * If the conductance of a section is undefined, it is considered equal to 0.
     * Return 0 if sectionCount is equal to 0 (disconnected state).
     *
     * @param sectionCount count of wanted activated sections. Must be in [0; maximumSectionCount]. Else, throws a {@link ValidationException}.
     */
    double getG(int sectionCount);

    /**
     * Get the model type of the shunt compensator (linear or non-linear)
     */
    ShuntCompensatorModelType getModelType();

    /**
     * Get the shunt model.
     */
    ShuntCompensatorModel getModel();

    <M extends ShuntCompensatorModel> M getModel(Class<M> modelType);

    /**
     * Get the terminal used for regulation.
     */
    default Terminal getRegulatingTerminal() {
        throw new UnsupportedOperationException();
    }

    /**
     * Set the terminal used for regulation.
     * If null is passed as regulating terminal, the regulation is considered local.
     */
    default ShuntCompensator setRegulatingTerminal(Terminal regulatingTerminal) {
        throw new UnsupportedOperationException();
    }

    /**
     * Get the shunt compensator's regulating status.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    boolean isVoltageRegulatorOn();

    /**
     * Set the shunt compensator's regulating status.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default ShuntCompensator setVoltageRegulatorOn(boolean voltageRegulatorOn) {
        throw new UnsupportedOperationException();
    }

    /**
     * Get the shunt compensator's voltage target in kV if it exists. Else return NaN.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default double getTargetV() {
        throw new UnsupportedOperationException();
    }

    /**
     * Set the shunt compensator's voltage target in kV.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default ShuntCompensator setTargetV(double targetV) {
        throw new UnsupportedOperationException();
    }

    /**
     * Get the shunt compensator's deadband (in kV) used to avoid excessive update of discrete control while regulating.
     * This attribute is necessary only if the shunt compensator is regulating.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default double getTargetDeadband() {
        throw new UnsupportedOperationException();
    }

    /**
     * Set the shunt compensator's deadband (in kV) used to avoid excessive update of discrete control while regulating.
     * This attribute is necessary only if the shunt compensator is regulating. It must be positive.
     * <p>
     * Depends on the working variant.
     * @see VariantManager
     */
    default ShuntCompensator setTargetDeadband(double targetDeadband) {
        throw new UnsupportedOperationException();
    }

    @Override
    default IdentifiableType getType() {
        return IdentifiableType.SHUNT_COMPENSATOR;
    }
}