<?xml version="1.0" encoding="utf-8"?>
<CRACDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" DtdVersion="1" DtdRelease="0" xsi:noNamespaceSchemaLocation="crac-document.xsd">
    <DocumentIdentification v="ruleToBeDefined"/>
    <DocumentVersion v="12"/>
    <DocumentType v="Z03"/>
    <ProcessType v="Z03"/>
    <SenderIdentification v="senderEIC" codingScheme="A01"/>
    <SenderRole v="A04"/>
    <ReceiverIdentification v="receiverEIC" codingScheme="A01"/>
    <ReceiverRole v="A36"/>
    <CreationDateTime v="2021-04-30T16:00:00Z"/>
    <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
    <Domain v="10YDOM-1001A061T" codingScheme="A01"/>
    <CRACSeries>
        ...
    </CRACSeries>
</CRACDocument>

A crac document has a time interval for its validity and a lot of its sub-objects have their own time interval of validity as well.
Therefore, this document has to be imported for a specific datetime – hourly-precise – to be able to select only the available elements for this datetime.

Branch

In the PowSyBl vocabulary, a ‘Branch’ is an element which is connected to two terminals (lines, tie-lines, transformers, etc.)
As this object is used almost everywhere in the CRAC, it is introduced first. A branch has few mandatory tags that should be filled in for FARAO to consider them : FromNode, ToNode, Order. They refer to existing network elements by their UCTE code.
However, a branch has also a lot of optional tags that are described right below this example.

<Branch>
    <Name v="Branch_1"/>
    <EIC v="Random EIC"/>
    <AlwaysSelected v="true"/>
    <FromNode v="BBE2AA1 "/>
    <ToNode v="BBE3AA1 "/>
    <Order v="1"/>
    <ImaxAfterOutage v="100" unit="Pct"/>
    <ImaxAfterCRA v="100" unit="Pct"/>
    <IlimitMNE_AfterOutage v="110" unit="Pct"/>
    <IlimitMNE_AfterCRA v="6500" unit="A"/>
    <Vn v="380" unit="kV"/>
    <minMargin v="70" unit="Pct"/>
    <Direction v="DIRECT"/>
    <Selected v="true"/>
    <Sensitivity v="3"/>
    <PTDFListRef>
        <PTDF>
            <Factor unit="Pct" v="4.5"/>
            <Country v="Country_1"/>
        </PTDF>
        <PTDF>
            <Factor unit="Pct" v="-2.3"/>
            <Country v="Country_2"/>
        </PTDF>
    </PTDFListRef>
    <RemedialActions>
        <Name v="Remedial_Action_1"/>
        <Name v="Remedial_Action_2"/>
    </RemedialActions>
</Branch>
  • Name : Alternative way to describe the branch with useful information to identify it more easily when reading logs and results
  • EIC : Identification
  • AlwaysSelected : FARAO does not use this tag, it only reads the selected tag one
  • selected : If selected is false, FARAO will not consider the margin on this branch in its optimization. Default value is true
  • Imax{…} and Ilimit{…} : Please refer respectively to the CriticalBranches and Monitored Elements sections at the end of this page
  • Vn : It is the nominal voltage, but FARAO reads is directly in the network therefore it is useless to fill it
  • minmargin : FARAO does not interact with this tag
  • Direction : Has to be DIRECT, OPPOSITE or BIDIR. If the Branch is defined in a BaseCaseBranch, a CriticalBranch or a MonitoredElement, this tag is mandatory. Please refer to this section JSON CRAC Format for more information on the behavior of FARAO according to the different direction values.
  • Status : Must be OPEN or CLOSE for a branch involved in a topological action. Default value is OPEN. See an example in the topological actions section of this page.
  • Sensitivity : FARAO does not interact with this tag
  • PTDFListRef : FARAO does not interact with this tag
  • Remedial actions : These remedial actions will be available with OnFlowConstraint usage rule for the branches they are associated to

Outages

<CRACSeries>
    <Outages>
        <Outage>
            <Name v="outage_1"/>
            <Branch>
                <FromNode v="BBE1AA1 "/>
                <ToNode v="BBE2AA1 "/>
                <Order v="1"/>
            </Branch>
        </Outage>
        <Outage>
            <Name v="outage_2"/>
            <Branch>
                <FromNode v="BBE1AA1 "/>
                <ToNode v="BBE3AA1 "/>
                <Order v="1"/>
            </Branch>
            <Branch>
                <FromNode v="BBE1AA1 "/>
                <ToNode v="BBE2AA1 "/>
                <Order v="1"/>
            </Branch>
        </Outage>
    </Outages>
    ...
</CRACSeries>

Outages are also commonly called ‘Contingencies’.
Each outage with multiple associated network elements must have them listed as showcased in the “outage_2” example above.

RemedialActions

<CRACSeries>
    ...
    <RemedialActions>
        <RemedialAction>
            <Name v="PST_pra"/>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Operator v="IT"/>
            <Application v="PREVENTIVE"/>
            <SharedWith v="CSE"/>
            ...
        </RemedialAction>
    </RemedialActions>
</CRACSeries>

A remedial action can be of different types, but they will always have :

  • A name
  • A TimeInterval : Has to contain the import datetime.
  • An operator : Represents a country in the UCTE country code format
  • A tag Application : Instant when the remedial action can be applied (SPS should be written for Instant Auto)
  • A tag SharedWith

The SharedWith tag

This tag defines the usage rule of the remedial action. You can refer to this section Remedial actions and usages rules for further explanation on the usage rule behavior.

If SharedWith is “CSE” : FreeToUse
If SharedWith is a UCTE country code : OnFlowConstraintInCountry in the country filled in
If SharedWith is “None” : OnFlowConstraint only for its associated CNECs (c.f. the Branch section above)

Range Actions

  • PST Range Actions
<CRACSeries>
    ...
    <RemedialActions>
        <RemedialAction>
            <Name v="PST_pra"/>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Operator v="IT"/>
            <Application v="PREVENTIVE"/>
            <SharedWith v="CSE"/>
            <PstRange>
                <Branch>
                    <FromNode v="BBE2AA1 "/>
                    <ToNode v="BBE3AA1 "/>
                    <Order v="1"/>
                </Branch>
                <VariationType v="ABSOLUTE"/>
                <Min v="-2"/>
                <Max v="2"/>
            </PstRange>
        </RemedialAction>
    </RemedialActions>
</CRACSeries>

A PST Range Action is defined by its PstRange attribute which contains:

  • a Branch
  • a VariationType : For now the only VariationType handled by FARAO is “ABSOLUTE” : the mix/max admissible taps of the PST.
  • a Min value : Has to be an Integer
  • a Max value : Must be an Integer >= Min value

FARAO minimum tap = max(Network minimum tap, Crac minimum tap)
FARAO maximum tap = min(Network maximum tap, Crac maximum tap)

  • HVDC Range Actions
<CRACSeries>
    ...
    <RemedialActions>
        <RemedialAction>
            <Name v="PRA_HVDC"/>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Operator v="FR"/>
            <Application v="PREVENTIVE"/>
            <SharedWith v="CSE"/>
            <HVDCRange>
                <HVDCNode>
                    <FromNode v="BBE2AA12"/>
                    <ToNode v="FFR3AA12"/>
                    <Order v="1"/>
                </HVDCNode>
                <VariationType v="ABSOLUTE"/>
                <Min v="-100"/>
                <Max v="2000"/>
            </HVDCRange>
        </RemedialAction>
    </RemedialActions>
</CRACSeries>

For now the only VariationType handled by FARAO is “ABSOLUTE” : the min/max admissible set-points of the HVDC.
An HVDC Range Action is modelled by an Injection range Action (the HVDC line is disconnected and replaced by two injections, one on each side of the line, with opposite keys of 1 and -1). FARAO creates the opposite keys by itself, therefore there is no need to specify it.
⚠️There isn’t any check performed to verify that an applied set-point is between the ranges’ min and max.

Network Actions

  • injection set-point
<CRACSeries>
    ...
    <RemedialActions>
        <RemedialAction>
            <Name v="cra_1"/>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Operator v="FR"/>
            <Application v="CURATIVE"/>
            <SharedWith v="None"/>
            <Generation>
                <Node>
                    <Name v="FFR1AA1 "/>
                    <VariationType v="ABSOLUTE"/>
                    <Value v="0"/>
                </Node>
            </Generation>
        </RemedialAction>
    </RemedialActions>
</CRACSeries>

For now the only VariationType handled by FARAO is “ABSOLUTE”, on the node you filled in, the new set-point value will be the one you defined (in MW).

  • topological
<CRACSeries>
    ...
    <RemedialActions>
        <RemedialAction>
            <Name v="cra_1"/>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Operator v="FR"/>
            <Application v="CURATIVE"/>
            <SharedWith v="None"/>
            <Status>
                <Branch>
                    <FromNode v="FFR1AA1 "/>
                    <ToNode v="FFR3AA1 "/>
                    <Order v="1"/>
                    <Status v="OPEN"/>
                </Branch>
            </Status>
        </RemedialAction>
    </RemedialActions>
</CRACSeries>

As mentioned earlier, the status must be OPEN or CLOSE and default value is OPEN.

CriticalBranches

It should contain a BaseCaseBranches tag and at least one CriticalBranch

BaseCaseBranches

<CRACSeries>
    ...
    <CriticalBranches>
        ...
        <BaseCaseBranches>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Branch>
                <Name v="basecase_branch_1"/>
                <FromNode v="NNL1AA1 "/>
                <ToNode v="NNL3AA1 "/>
                <Order v="1"/>
                <Imax unit="A" v="4000"/>
                <Direction v="OPPOSITE"/>
                <Selected v="true"/>
            </Branch>
            <Branch>
                <Name v="basecase_branch_2"/>
                <FromNode v="NNL1AA1 "/>
                <ToNode v="NNL2AA1 "/>
                <Order v="1"/>
                <Imax unit="A" v="4500"/>
                <Direction v="DIRECT"/>
            </Branch>
        </BaseCaseBranches>
    </CriticalBranches>
</CRACSeries>

BaseCaseBranches is made of:

  • A TimeInterval : Must contain the import datetime.
  • A List of branches

For each branch in the list, if Imax is provided, a CNEC will be created on Preventive state.

CriticalBranch

<CRACSeries>
    ...
    <CriticalBranches>
        ...
        <CriticalBranch>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Outage v="outage_1"/>
            <Branch>
                <Name v="French line 1"/>
                <FromNode v="FFR1AA1 "/>
                <ToNode v="FFR2AA1 "/>
                <Order v="1"/>
                <ImaxAfterOutage unit="A" v="4318"/>
                <ImaxAfterCRA unit="A" v="3099"/>
                <Direction v="OPPOSITE"/>
            </Branch>
        </CriticalBranch>
    </CriticalBranches>
</CRACSeries>

Each one needs at least these information :

  • A TimeInterval : Has to contain the import datetime.
  • An outage : Must be an outage name existing in the Outages section
  • A branch

For each critical branch, given an attribute ImaxAfter{Instant}, a CNEC on the given state will be created :

  • ImaxAfterOutage -> Instant Outage
  • ImaxAfterSPS -> Instant Auto
  • ImaxAfterCRA -> Instant Curative

MonitoredElements

<CRACSeries>
    ...
    <MonitoredElements>
        <MonitoredElement>
            <TimeInterval v="2021-04-30T22:00Z/2021-04-30T23:00ZZ"/>
            <Branch>
                <Name v="Branch_1"/>
                <FromNode v="NNL1AA1 "/>
                <ToNode v="NNL3AA1 "/>
                <Order v="1"/>
                <IlimitMNE_AfterOutage v="120" unit="Pct"/>
                <IlimitMNE_AfterSPS v="5750" unit="A"/>
                <IlimitMNE_AfterCRA v="5500" unit="A"/>
                <IlimitMNE v="100" unit="Pct"/>
                <Vn v="380" unit="kV"/>
                <Direction v="DIRECT"/>
            </Branch>
        </MonitoredElement>
    </MonitoredElements>
</CRACSeries>

A MonitoredElement always has a TimeInterval and a branch.
It will not be optimized by FARAO, however it will be monitored. In other words, on this element, FARAO cannot reduce the margin compared to its initial value.

First, if IlimitMNE is filled in, a CNEC on Preventive state will be created. Then, for each outage in the Outages tag and for each attribute IlimitMNE_After{Instant} that is present, a CNEC will be created on the given state:

  • IlimitMNE_AfterOutage -> Instant Outage
  • IlimitMNE_AfterSPS -> Instant Auto
  • IlimitMNE_AfterCRA -> Instant Curative