Adaptricity grid model dpgsimgridschema 2.71 · generated 2026-08-11

The node-branch model, attribute by attribute.

The Adaptricity platform simulates a distribution grid from a node-branch model: buses, the branches between them, and the loads, generators and protection hanging off them. This page is the whole XML format — what every element means, what every attribute is for, and which Adaptricity calculation stops working if you leave it out. It is generated straight from the schema, so it cannot drift from it.

Schema
dpgsimgridschema
Version
Element types
16
Attributes
295
Features
10
Generated
2026-08-11
Example grid
Download

Single-line diagram

Hover an element to see what references it. Click to jump to its attributes.

STATIONprimary substationSHAPEfree annotation drawn on the mapto adjacent feederNetwork feederslack busBusbar nodemedium voltageSwitchI>Protection devicetrips the switchFuseTransformerwith tap changerDual-voltage transformerBusbar nodelow voltagePQPQ metermeasures at a branch endLineR, X per kmBusbar nodehouse connectionVoltage regulatorBusbar nodeConnectionnegligible R, XBusbar nodeLoadGGeneratorStorage
Symbols are hand-placed · the references between them are read from the schema Nodes are called buses in the platform

01

<Node>

in <BUSBAR_NODE>17 attributes4 requiredrequired in every grid

A BUSBAR_NODE is to be intended as an electrical node, i.e. any electrical junction between two or more conductors. The denomination 'BUSBAR_NODE' is just a legacy.

Instantiate
<GRID>
  <BUSBAR_NODE>
    <Node ID="n_0013298"
          BaseVoltageInKilovolt="0.4"
          SelfTimeInSeconds="0.50"
          LibraryReliabilityName="REL04"/>
  </BUSBAR_NODE>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates in WGS84).
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——n_0013298ALL

ID (see type StringID). Each Node requires a unique ID among all Nodes.

Hard requirement.

CustomersToBusMatchingIDstring——n_0013298

Customer-specific ID to match data (e.g., smartmeter data) to the bus.

No requirement.

Links out of the grid model — matches external data such as smart-meter series onto this bus

Namestring——Ocean Street 46VIS

A human-readable name.

No requirement.

Descriptionstring——Replaced in 1986VIS

A human-readable description.

No requirement.

ConstructionYearinteger——1998

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/lines

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

IsVerticalboolean——TRUEVIS

Defines if the bus (if it is drawn as a bus bar) is drawn horizontally or vertically. Buses are drawn horizontally by default, i.e., if this attribute is absent.

No requirement.

TypeBusTypeEnum——DistributionCabinetVIS

Denotes the type of the grid node and shall be either TransformerStation, DistributionCabinet, CableJunction, BusBar, ConnectionPoint, SmallConnectionPoint, or Other.

No requirement.

Allowed valuesTransformerStationDistributionCabinetCableJunctionBusBarConnectionPointSmallConnectionPointVirtualPreferredNetworkFeederLocationOther
BaseVoltageInKilovoltFiniteDoublekV—0.4ALL

The nominal voltage of the grid node (as defined by the voltage level).

Required for:

    • All calculations
SelfTimeInSecondsFiniteDoubleSeconds—0.50PRC

Time required to deenergize underlying transformer station in case of fault.

Required for:

    • Protection calculation (only for certain setups; not necessarily required)
StationIDstring——s0389VIS

The ID of the station, if this bus belongs to a station.

No requirement.

Points at <Station> — belongs to this station

xdouble——1.75VIS

x-coordinate of the bus to display in the schematic view.

Required for:

    • Display in schematic view (ony for customer specific schematic visualization; default schematic coordinates are calculated from geo-coordinates)
ydouble——0.25VIS

y-coordinate of the bus to display in the schematic view.

Required for:

    • Display in schematic view (ony for customer specific schematic visualization; default schematic coordinates are calculated from geo-coordinates)
WidthFiniteDoublepoints—15VIS

The width of the bus in the schematic view.

Required for:

    • Display in schematic view
LibraryReliabilityNamestring——REL04REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations

02

<Line>

in <LINE>29 attributes9 requiredrequired in every grid

An electrical link with non-negligible resistance and reactance. For links with negligible R,X, please see 'CONNECTION'.

Instantiate
<GRID>
  <LINE>
    <Line ID="l_029389"
          TemperatureInCelsius="0.68"
          ResistanceInOhmPerKilometer="0.68"
          ReactanceInOhmPerKilometer="0.45"
          MaximumCurrentInAmpere="160.0"
          LengthInKilometer="0.122"
          Bus1ID="b_0224"
          Bus2ID="b_0760"
          LibraryReliabilityName="Model01"/>
  </LINE>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
  • <Schematic>SchematicPointsTypeoptionalDefines support points for rendering branches in a custom way.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——l_029389ALL

ID (see type StringID). Each Line requires a unique ID among all branch types (Line, Connection, Transformer).

Hard requirement.

PhasePhaseEnum——ABSST

Defines the phase of the line. Can be used to define a line as a single phase or a two phase line. If not defined, the line is assumed to be a three phase line.

Allowed valuesABCABBCACABC
Namestring——Mall StreetVIS

A human-readable name.

No requirement.

Descriptionstring——Edited by XYZVIS

A human-readable description.

No requirement.

ConstructionYearinteger——2011

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/lines

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

TemperatureInCelsiusFiniteDoubleohm/km—0.68ALL

Defines the temperature in degree celsius at which the line resistance is provided (parameter 'ResistanceInOhmPerKilometer'). If undefined, a configurable fallback temperature is assumed (default: 20°C).

Optional, if defined used for:

    • Power flow
    • Short circuit
    • All calculations that are based on power flow or short circuit (D-A-CH-CZ, VDE-AR_N, Connection requests, .Sim, .Mon, Future Scenario, N-1, Protection)
ResistanceInOhmPerKilometerFiniteDoubleohm/km—0.68ALL

Can be fetched from the Component Library if resistance and reactance values are not given in the xml.

Required for:

    • All calculations
ReactanceInOhmPerKilometerFiniteDoubleohm/km—0.45ALL

Can be fetched from the Component Library if resistance and reactance values are not given in the xml.

Required for:

    • All calculations
ZeroSequenceResistanceInOhmPerKilometerFiniteDoubleohm/km—0.25SCC

If undefined, zero sequence impedance is linked to positive sequence impedance using a constant factor.

Required for:

    • Short circuit calculations involving ground faults (but it will be derived from positive sequence impedance if missing)
ZeroSequenceReactanceInOhmPerKilometerFiniteDoubleohm/km—0.25SCC

If undefined, zero sequence impedance is linked to positive sequence impedance using a constant factor.

Required for:

    • Short circuit calculations involving ground faults (but it will be derived from positive sequence impedance if missing)
MaximumCurrentInAmpereFiniteDoubleA—160.0ALL

Maximum rated current of the line in Ampere, used to calculate the loading. Can be fetched from the Component Library if the value is not given in the xml.

Required for:

    • All calculations (calculations can be carried out without it but the line loading cannot be determined)
ShortCircuitStabilityThreePhaseInKiloampereFiniteDouble———SCC

Parameter denoting the maximal three phase aperiodic short circuit current the line can withstand.

Required for:

    • Short circuit calculations of maximal three phase aperiodic short circuits (but it will be derived from other parameters if missing)
ShuntCapacitanceInMicrofaradPerKilometerFiniteDoubleuF/km0.07.0ALL

Shunt capacitance of the line in Microfarad per kilometer, used for calculating the shunt admittances. Can be fetched from the Component Library if the value is not given in the xml.

Required for:

    • Power flow based functionalities (makes it more accurate but is not strictly necessary)
LengthInKilometerFiniteDoublekm—0.122ALL

Length of the line in kilometers, used for computing the absolute line parameters.

Required for:

    • All calculations
Manufacturerstring——Cables Inc.LIB

Manufacturer name (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
LibraryComponentNamestring——50CU-01LIB

Name of the component, must be unique in the component library (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
LibraryComponentTypestring——Copper 3x50 1kVLIB

Type of the cable (e.g., GKN). It will be removed after grid import, used for component library matching only if the required electrical attributes are missing.

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
IsOverheadboolean——FALSEVIS

true if overhead line, false if underground cable or other (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
Materialstring——CuLIB

Material name (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
CrossSectionstring——3x95/95LIB

Cross section of the cable (e.g. 95mm^2, 3x95/95, ...), notation needs to match the notation in the component library.

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
Bus1IDStringID——b_0224ALL

ID of bus 1 that the line is connected to.

Required for:

    • All calculations

Points at <Node> — first terminal

Bus2IDStringID——b_0760ALL

ID of bus 2 that the line is connected to.

Required for:

    • All calculations

Points at <Node> — second terminal

ConnectedAtBus1boolean—TRUETRUEALL

Denotes whether the line is electrically connected at Bus 1. true if the switch is closed (connected) at bus 1, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectedAtBus2boolean—TRUETRUEALL

Denotes whether the line is electrically connected at Bus 2. true if the switch is closed (connected) at bus 2, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
Ownerstring——Mr.SmithCON

Each branch (lines, transformer, connection) in the grid model can be assigned an owner. The selectable owners can be configured in the general options in the Adaptricity Admin panel. For each owner, you can specify whether the associated branches are to be ignored when evaluating connection requests. These branches are referred to as "ignored" in the following. Ignored branches are handled differently: 1) In Adaptricity.Connect: a bus is ignored when calculating the hosting capacity if it is connected exclusively to ignored branches. As a result, these buses are not available as possible connection points in Adaptricity.Connect. If the 'Hosting capacity on lines' option has been selected, hosting capacities are also not calculated on ignored lines. 2) In the user-defined connection request: During the automatic selection of potential connection nodes, those nodes that are connected exclusively to ignored branches are ignored.

No requirement.

LibraryReliabilityNamestring——Model01REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations

03

<Connection>

in <CONNECTION>16 attributes8 required

An electrical link with negligible resistance and reactance. For links with non-negligible R,X, please see 'LINE'.

Instantiate
<GRID>
  <CONNECTION>
    <Connection ID="con_29875"
                ResistanceInMilliOhm="0.1"
                ReactanceInMilliOhm="0.1"
                Bus1ID="bus_3428"
                Bus2ID="bus_764"
                ConnectedAtBus1="true"
                ConnectedAtBus2="true"
                LibraryReliabilityName="Rel03"/>
  </CONNECTION>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
  • <Schematic>SchematicPointsTypeoptionalDefines support points for rendering branches in a custom way.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——con_29875ALL

ID (see type StringID). Each Line requires a unique ID among all branch types (Line, Connection, Transformer).

Hard requirement.

PhasePhaseEnum——ABSST

Defines the phase of the connection. Can be used to define a connection as a single phase or a two phase connection. If not defined, the connection is assumed to be a three phase connection.

Allowed valuesABCABBCACABC
Namestring——Busbar 23VIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionYearinteger——2016VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/connection

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

ResistanceInMilliOhmFiniteDoublemilliohm—0.1ALL

Resistance in mΩ. If neither ResistanceInMilliOhm nor ReactanceInMilliOhm are provided, the connection has a minimal resistance of 0.01 mΩ (for numerical reasons).

Required for:

    • All calculations (calculations are run with the default value if missing)
ReactanceInMilliOhmFiniteDoublemilliohm—0.1ALL

Reactance in mΩ. If neither ResistanceInMilliOhm nor ReactanceInMilliOhm are provided, the connection has a minimal resistance of 0.01 mΩ (for numerical reasons).

Required for:

      • All calculations ((calculations are run with the default value if missing)
Bus1IDStringID——bus_3428ALL

ID of bus 1 that the connection element it is connected to.

Required for:

      • All calculations

Points at <Node> — first terminal

Bus2IDStringID——bus_764ALL

ID of bus 2 that the connection element it is connected to.

Required for:

      • All calculations

Points at <Node> — second terminal

ConnectedAtBus1boolean—TRUETRUEALL

true if the switch is closed (connected) at bus 1, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectedAtBus2boolean—TRUETRUEALL

true if the switch is closed (connected) at bus 2, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
Ownerstring——Mr FoeCON

Each branch (lines, transformer, connection) in the grid model can be assigned an owner. The selectable owners can be configured in the general options in the Adaptricity Admin panel. For each owner, you can specify whether the associated branches are to be ignored when evaluating connection requests. These branches are referred to as "ignored" in the following. Ignored branches are handled differently: 1) In Adaptricity.Connect: a bus is ignored when calculating the hosting capacity if it is connected exclusively to ignored branches. As a result, these buses are not available as possible connection points in Adaptricity.Connect. If the 'Hosting capacity on lines' option has been selected, hosting capacities are also not calculated on ignored lines. 2) In the user-defined connection request: During the automatic selection of potential connection nodes, those nodes that are connected exclusively to ignored branches are ignored.

No requirement.

LibraryReliabilityNamestring——Rel03REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations

04

<VoltageRegulator>

in <VOLTAGEREGULATOR>13 attributes2 required

Voltage regulators can be created and attached to lines in radial parts of the grid. During a simulation they behave similarly to tap changing transformers and will have an effect on the power flow both in static and time-series based simulations.

Instantiate
<GRID>
  <VOLTAGEREGULATOR>
    <VoltageRegulator ID="vr_2342"
                      HostLineID="line_3892"/>
  </VOLTAGEREGULATOR>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IsIdealTapChangerboolean———

True, if the tap changer reaches its SetpointInPerUnit exactly, regardless of number of taps and the tap size. False, if the tap changer can only realize certain secondary voltages defined by the number of taps and the tap size. The set-point is not be met exactly.

Required for:

    • All calculations
IDrequiredStringID——vr_2342ALL

ID (see type StringID). Each VoltageRegulator requires a unique ID among all VoltageRegulators.

Hard requirement.

Namestring——Voltage Regulator 28VIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionYearinteger——2005VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/transformerVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

HostLineIDStringID——line_3892ALL

ID of the line that the voltage regulator is installed at.

Required for:

    • All calculations

Points at <Line> — installed on this line

NumTapsinteger——5ALL

Number of taps of the transformer (both upward and downward). Required if IsIdealTapChanger is false.

Required for:

    • All calculations
TapSizeFractionInPercentFiniteDouble——2.5ALL

Size of each tap in terms of voltage change. Required if IsIdealTapChanger is false.

Required for:

    • All calculations
DeadBandFractionInPercentFiniteDouble——0.5ALL

Dead-band of the hysteresis controller that switches the taps. Required if IsIdealTapChanger is false.

Required for:

    • All calculations
SetpointInPerUnitFiniteDoublep.u.—1.03ALL

This defines the desired voltage in per unit at the measured bus.

Required for:

    • All calculations

05

<Load>

in <LOAD>19 attributes6 required

Static load.

Instantiate
<GRID>
  <LOAD>
    <Load ID="b_2765"
          ActiveLoadInMegawatt="0.023"
          AnnualActiveEnergyInKilowatthours="123456"
          RatedPowerInKilowatt="123.45"
          Bus1ID="b_0938"
          Connected="true"/>
  </LOAD>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates in WGS84).
  • <ReactivePower>ReactivePoweroptionalDefines the characteristics of the reactive power of the load.
  • <TimeSeriesBehavior>TimeSeriesBehavioroptionalDefines the time series replacement of the load when doing time series simulations.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——b_2765ALL

ID (see type StringID). Each Load requires a unique ID among all Loads.

Hard requirement.

PhasePhaseEnum——ASST

Defines the phase of the load. Can be used to define a load as a single phase or a three phase load. If not defined, the load is assumed to be a three phase load.

Allowed valuesABCABBCACABC
Namestring——Bakery St.GeorgeVIS

A human-readable name.

No requirement.

Descriptionstring——BakeryVIS

A human-readable description

No requirement.

ConstructionYearinteger——1999VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/loadsVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

LoadCategoryLoadCategoryEnum——www.mylistofassets.com/loadsVIS

Denotes the allowed load categories.

No requirement.

Allowed valuesResidentialIndustrialHeat pumpElectric heatingElectric water heaterEV chargerStationary batteryEquivalent aggregated loadOther
ActiveLoadInMegawattFiniteDoubleMW—0.023ALL

Active power in MW that the load consumes from the grid (should normally be positive).

Required for:

    • All calculations, unless ScaleToMatchTransformerMeasurement is set to true
ScaleToMatchTransformerMeasurementboolean—truefalseALL

Defaults to true: the active power of the load is calculated by Adaptricity such that the sum of all loads matches the MaximumMeasuredApparentPowerInMegavoltampere of the transformers of the grid. The power is distributed among the loads relative to their AnnualActiveEnergyInKilowatthours or RatedPowerInKilowatt (configurable in the data integration settings of the project). ActiveLoadInMegawatt may then be left undefined.

Set it to false for a load that keeps the ActiveLoadInMegawatt of this grid file. The power of those loads is subtracted from the transformer measurement before it is distributed among the remaining loads.

Required for:

    • Loads that keep the delivered ActiveLoadInMegawatt (set to false)
AnnualActiveEnergyInKilowatthoursFiniteDoublekWh—123456ALL

Annual Active Energy in kWh that the load consumes from the grid (should normally be positive).

Required for:

    • All calculations
RatedPowerInKilowattFiniteDoublekW—123.45ALL

Rated power in kW that the load consumes from the grid (should normally be positive).

Required for:

    • All calculations
Bus1IDStringID——b_0938ALL

ID of the Bus that the load is connected to.

Required for:

    • All calculations

Points at <Node> — first terminal

MeterIDstring———

ID of the meter representing the load.

Links out of the grid model — a meter supplying measurements for this element

CustomerIDstring———

ID of the customer connected to the load.

Links out of the grid model — a customer record in the platform

NumberOfCustomersinteger——1999VIS

Number of customers connected to the load. Only used for information purposes.

No requirement.

Connectedboolean——b_0938ALL

Denotes whether the load is electrically connected. true if the switch is closed (connected), false if the switch is open (not connected). Defaults to true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectionRequestIDstring——con29783CON

If set to the ID of a connection request, the corresponding request is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a connection request that is used to set the status of the connection request.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

06

<Generator>

in <GENERATOR>21 attributes6 required

Static generator.

Instantiate
<GRID>
  <GENERATOR>
    <Generator ID="gen29783"
               ConnectionType="Direct"
               ActiveGenerationInMegawatt="0.062"
               Bus1ID="b_0760"
               Connected="true"
               LibraryReliabilityName="rel_060"/>
  </GENERATOR>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates in WGS84).
  • <ReactivePower>ReactivePoweroptionalDefines the characteristics of the reactive power generation of the generator.
  • <TimeSeriesBehavior>TimeSeriesBehavioroptionalDefines the time series replacement of the generator when doing time series simulations.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——gen29783ALL

ID (see type StringID). Each Generator requires a unique ID among all Generators.

Hard requirement.

PhasePhaseEnum——ASST

Defines the phase of the generator. Can be used to define a generator as a single phase or a three phase generator. If not defined, the load is assumed to be a three phase generator.

Allowed valuesABCABBCACABC
Namestring——PV plant, Madison SquareVIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionYearinteger——2013VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

NumberOfCustomersinteger——2013VIS

Number of customers connected to the generator. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/generators

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GenerationCategoryGenerationCategoryEnum——PhotovoltaicSST

Denotes the allowed categories of generation devices.

No requirement.

Allowed valuesPVWindBiomassHydroGas turbineCombined heat and powerEquivalent aggregated generationOther
ConnectionTypeGenerationConnectionEnum——PhotovoltaicSCC

Denotes the type of the connection to the grid.

Required for:

    • Short circuit calculations (makes them more accurate)
Allowed valuesDirectInverterSynchronous MachineAsynchronous MachineConverter
ActiveGenerationInMegawattFiniteDouble——0.062ALL

Active power in MW that the generator injects into the grid (should normally be positive).

Required for:

    • All calculations
AnnualActiveEnergyInKilowatthoursFiniteDouble———

Currently not supported.

No requirement.

RatedPowerInKilowattFiniteDouble———

Currently not supported.

No requirement.

VoltageSetpointInKilovoltFiniteDouble———

Currently not supported.

No requirement.

Bus1IDStringID——b_0760ALL

ID of Bus that the generator is connected to.

Required for:

    • All calculations

Points at <Node> — first terminal

MeterIDstring———

ID of the meter representing the generator.

Links out of the grid model — a meter supplying measurements for this element

CustomerIDstring———

ID of the customer representing the generator.

Links out of the grid model — a customer record in the platform

Connectedboolean—TRUETRUEALL

Denotes whether the generator is electrically connected. true if the switch is closed (connected), false if the switch is open (not connected).

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectionRequestIDstring——b_0760CON

If set to the ID of a connection request, the corresponding request is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a connection request that is used to set the status of the connection request.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

LibraryReliabilityNamestring——rel_060REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations

07

<Storage>

in <STORAGE>20 attributes3 required

Storage.

Required for:

    • Simulations (Storage devices can be used in time series simulations)
Instantiate
<GRID>
  <STORAGE>
    <Storage ID="sto25791"
             Bus1ID="b_0761"
             Connected="true"/>
  </STORAGE>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates in WGS84).
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——sto25791ALL

ID (see type StringID). Each storage requires a unique ID among all storages.

Hard requirement.

Namestring——Battery, Madison SquareVIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionYearinteger——2023VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/storages/

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

StorageCategoryStorageCategoryEnum——BatterySST

Denotes the allowed categories of storage devices.

No requirement.

Allowed valuesBatteryPumped HydroThermalOther Storage
Bus1IDStringID——b_0761ALL

ID of Bus that the Storage is connected to.

Required for:

    • All calculations

Points at <Node> — first terminal

RatedPowerInMegawattFiniteDouble———

Rated power in Megawatt

Required for:

    • Simulations with storage devices
RatedEnergyInMegawattHourFiniteDouble———

Rated Energy in MWh

Optional

ChargingEfficiencyInPercentFiniteDoublepercent—94

Denotes the charging efficiency of storage device

Required for:

    • Simulations with storage devices
DischargingEfficiencyInPercentFiniteDoublepercent—94

Denotes the discharging efficiency of storage device

Required for:

    • Simulations with storage devices
MinStateOfChargeInPercentFiniteDoublepercent—7

Denotes the minimum state of charge of storage device

Optional

MaxStateOfChargeInPercentFiniteDoublepercent—93

Denotes the maximum state of charge of storage device

Optional

InitialStateOfChargeInPercentFiniteDoublepercent—50

Denotes the initial state of charge of storage device

Optional

MeterIDstring———

ID of the meter representing the storage.

Required for:

    • Simulations, if storage device should be represented by a smart meter measurement

Links out of the grid model — a meter supplying measurements for this element

LibraryStorageControllerNamestring——BatterySST

Unique name that identifies the storage controller in the component library.

Required for:

Component library matching

Connectedboolean——b_0938ALL

Denotes whether the storage is electrically connected. true if the switch is closed (connected), false if the switch is open (not connected). Defaults to true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ControlledElementIDStringID——powerline_1

ID of Bus or Branch that is controlled by the storage.

Required for:

    • Simulations

Points at <Node> or <Line> or <Connection> or <Transformer> — bus or branch under control

08

<Transformer>

in <TRANSFORMER>42 attributes17 required

Two-winding transformer.

Instantiate
<GRID>
  <TRANSFORMER>
    <Transformer ID="tr_357"
                 VectorGroup="Dyn5"
                 StarPointGrounding="Direct grounding"
                 TransformerRatingInMegavoltampere="0.4"
                 MaximumApparentPowerInMegavoltampere="0.4"
                 ShortCircuitVoltageInPercent="6.2"
                 CopperLossesInPercent="1.5"
                 RatedVoltageAtBus1="11.0"
                 RatedVoltageAtBus2="0.4"
                 IsTapChanging="false"
                 Bus1ID="bus_176"
                 Bus2ID="bus_736"
                 ConnectedAtBus1="true"
                 ConnectedAtBus2="true"
                 LibraryReliabilityName="Rel_03"
                 MaximumMeasuredApparentPowerInMegavoltampere="0.4"
                 CosPhiAtMaximumApparentPower="0.98"/>
  </TRANSFORMER>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
  • <Schematic>SchematicPointsTypeoptionalDefines support points for rendering branches in a custom way.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——tr_357ALL

ID (see type StringID). Each Transformer requires a unique ID among all branch types (Line, Connection, Transformer).

Hard requirement.

MeasuredVoltageBusIDStringID——bus_234ALL

The bus ID at which the voltage is measured for the tap-changing controller (see type StringID).

Required for:

    • All calculations if the transformer is tap-changing

Points at <Node> — tap-changer voltage measurement point

PhasePhaseEnum——ASST

Defines the phase of the transformer. Can be used to define a transformer as a single phase or three phase transformer. If not defined, the transformer is assumed to be a three phase transformer.

Allowed valuesABCABBCACABC
Namestring——Transformer 45VIS

A human-readable name.

No requirement.

Descriptionstring——Pole mountedVIS

A human-readable description.

No requirement.

ColorIndexnonNegativeInteger——blueVIS

Optional color index that, if set, will force the subgrid containing this transformer to the color with the specified index when grid colorization is turned on. The index references the color in the standard color palette used for grid colorization.

No requirement.

ConstructionYearinteger——1967VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/transformers

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

VectorGroupstring——Dyn5SCC

Vector group (Schaltgruppe) of transformer, e.g. Dyn5.

Required for:

    • Short circuit calculations
StarPointGroundingStarPointGrounding——DirectGroundingSCC

Defines how the star point is grounded. If vectorGroup doesn't have a star point, leave empty.

Required for:

    • Short circuit calculations in case transformer vector group has a star point
Allowed valuesDirect groundingLow-resistance groundingResonant groundingInsulated grid
SecondaryGroundingResistanceInOhmFiniteDoubleohm—15.0SCC

In case the star point grounding type 'Low-resistance grounding' was selected, this number defines the grounding resistance in Ohm.

Required for:

    • Short circuit calculations if transformer grounding type is 'Low-resistance grounding'
SecondaryGroundingInductanceInHenryFiniteDoubleHenry—15.0SCC

In case the star point grounding type 'Resonant grounding' was selected, this number defines the grounding inductance in Henry.

Required for:

    • Short circuit calculations if transformer grounding type is 'Resonant grounding'
TransformerRatingInMegavoltampereFiniteDoubleMVA—0.4ALL

It can be fetched from the Component Library if short circuit voltage and copper losses values are not given in the xml.

Required for:

    • All calculations
MaximumApparentPowerInMegavoltampereFiniteDoubleMVA—0.4ALL

Maximum allowed apparent power. Usually the same as the transformer rating. Can be fetched from the Component Library.

Required for:

    • All calculations
ShortCircuitVoltageInPercentFiniteDoublepercent—6.2ALL

It can be fetched from the Component Library if short circuit voltage and copper losses values are not given in the xml.

Required for:

    • All calculations
CopperLossesInPercentFiniteDoublepercent—1.5ALL

It can be fetched from the Component Library if short circuit voltage and copper losses values are not given in the xml.

Required for:

    • All calculations
RatedVoltageAtBus1FiniteDoublekV—11.0ALL

Rated transformer voltage on the side of Bus 1 in Kilovolt. Used for calculation of the turns ratio.

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
RatedVoltageAtBus2FiniteDoublekV—0.4ALL

Rated transformer voltage on the side of Bus 2 in Kilovolt. Used for calculation of the turns ratio.

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
DualVoltageTrafoIDstring——dual-voltage-trafo-1

Do not set this field. This is an internal ID that groups two transformers that represent a dual voltage transformer that was previously ipmorted in the DUALVOLTAGETRANSFORMER section of the xml

Set by Adaptricity on import — set by Adaptricity on import - do not fill

IsTapChangingboolean—FALSEFALSEALL

True, if transformer is a tap-changing transformer.

Required for:

    • All calculations if transformer is tap changing
IsIdealTapChangerboolean———

True, if the tap changer reaches its SetpointInPerUnit exactly, regardless of number of taps and the tap size. False, if the tap changer can only realize certain secondary voltages defined by the number of taps and the tap size. The set-point is not be met exactly.

Required for:

    • All calculations if transformer is tap changing
NumTapsint——FALSEALL

For tap-changing transformers, it defines the number of taps. Required if IsIdealTapChanger is false.

Required for:

    • All calculations if transformer is tap changing
TapSizeInPercentFiniteDoublepercent—2.5ALL

For tap-changing transformers, it defines the tap size in percent (%). Required if IsIdealTapChanger is false.

Required for:

    • All calculations if transformer is tap changing
DeadBandInPercentFiniteDoublepercent—0.5ALL

For tap-changing transformers, it defines the dead band of the hysteresis controller in percent (%). Required if IsIdealTapChanger is false.

Required for:

    • All calculations if transformer is tap changing
SetpointInPerUnitFiniteDoublep.u.1.01.03ALL

For tap-changing transformers, it defines the desired voltage in per unit at the measured bus.

Required for:

    • All calculations if transformer is tap changing
Modelstring——11/0.4 400LIB

Text field (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing)

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
Manufacturerstring——Transformers Inc.LIB

Manufacturer name (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing)

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
LibraryComponentNamestring——Transformer CamelLIB

Name of the component, must be unique in the component library (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
LibraryComponentTypestring——Transformer CLIB

Type of the transformer as described in the library (it will be removed after grid import, used for component library matching only if the required electrical attributes are missing).

Required for:

    • Component library matching (not all parameters for component library matching are necessary to be present simultaneously)
Bus1IDStringID——bus_176ALL

ID of bus 1 that the transformer is connected to.

Required for:

    • All calculations

Points at <Node> — first terminal

Bus2IDStringID——bus_736ALL

ID of bus 2 that the transformer is connected to.

Required for:

    • All calculations

Points at <Node> — second terminal

ConnectedAtBus1boolean—TRUETRUEALL

Denotes whether the transformer is electrically connected. true if the switch is closed (connected) at bus 1, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectedAtBus2boolean—TRUETRUEALL

Denotes whether the transformer is electrically connected. true if the switch is closed (connected) at bus 2, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
Ownerstring——Mr. BeanCON

Each branch (lines, transformer, connection) in the grid model can be assigned an owner. The selectable owners can be configured in the general options in the Adaptricity Admin panel. For each owner, you can specify whether the associated branches are to be ignored when evaluating connection requests. These branches are referred to as "ignored" in the following. Ignored branches are handled differently: 1) In Adaptricity.Connect: a bus is ignored when calculating the hosting capacity if it is connected exclusively to ignored branches. As a result, these buses are not available as possible connection points in Adaptricity.Connect. If the 'Hosting capacity on lines' option has been selected, hosting capacities are also not calculated on ignored lines. 2) In the user-defined connection request: During the automatic selection of potential connection nodes, those nodes that are connected exclusively to ignored branches are ignored.

No requirement.

LibraryReliabilityNamestring——Rel_03REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations
MaximumMeasuredApparentPowerInMegavoltampereFiniteDoubleMVA—0.4ALL

Maximum measured apparent power. Usually the same as the transformer rating.

Required for:

    • All calculations
CosPhiAtMaximumApparentPowerFiniteDoubleMVA—0.98ALL

CosPhi at maximum apparent power.

Required for:

    • All calculations
CosPhiTypeAtMaximumApparentPowercosPhiType——INDUCTIVESST

Defines the cosPhi Type at maximum apparent power.

Allowed valuesINDUCTIVECAPACITIVE
MeterIDstring———

ID of the meter measuring power and/or voltage. This field is only relevant if you are using v3 of the data integration API or later. The voltage is used in time series simulations (incl. Monitoring) to set the operational voltage at the slack bus. The active and reactive power are shown in Monitoring next to the simulated power of the transformer. A mismatch of the latter indicates an infeasible simulation result, that could be caused by e.g. missing meters, measurement errors/outliers, power theft, incorrect grid model parameters.

Links out of the grid model — a meter supplying measurements for this element

MeterAtSecondarySideboolean———

Denotes whether the meter is electrically connected to secondary side of transformer true if the meter is connected at secondary side false if the meter is connected at primary side. Default value is true.

Required for:

    • All calculations

09

<DualVoltageTransformer>

in <DUALVOLTAGETRANSFORMER>26 attributes19 required

Transformer with two secondary voltages.

Instantiate
<GRID>
  <DUALVOLTAGETRANSFORMER>
    <DualVoltageTransformer ID="tr_357"
                            LibraryReliabilityName="Model01"
                            Bus1ID="bus_3428"
                            Bus2ID="bus_764"
                            Bus3ID="bus_764"
                            ConnectedAtBus1="true"
                            ConnectedAtBus2="true"
                            ConnectedAtBus3="true"
                            SecondaryShortCircuitVoltageInPercent="6.2"
                            TertiaryShortCircuitVoltageInPercent="6.2"
                            SecondaryCopperLossesInPercent="1.5"
                            TertiaryCopperLossesInPercent="1.5"
                            TransformerRatingInMegavoltampere="0.4"
                            SecondaryPowerFraction="0.4"
                            RatedVoltageAtBus1="11.0"
                            RatedVoltageAtBus2="0.42"
                            RatedVoltageAtBus3="0.4"
                            ResistanceWindingV2InOhm="0.4"
                            ResistanceWindingV3InOhm="0.4"/>
  </DUALVOLTAGETRANSFORMER>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
  • <Schematic>SchematicPointsTypeoptionalDefines support points for rendering branches in a custom way.
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——tr_357ALL

ID (see type StringID). Each Transformer requires a unique ID among all branch types (Line, Connection, Transformer).

Hard requirement.

Namestring——Transformer 45VIS

A human-readable name.

No requirement.

Descriptionstring——Pole mountedVIS

A human-readable description.

No requirement.

ConstructionYearinteger——1958VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/fusesVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

Ownerstring——Mr.SmithCON

Each branch (lines, transformer, connection) in the grid model can be assigned an owner. The selectable owners can be configured in the general options in the Adaptricity Admin panel. For each owner, you can specify whether the associated branches are to be ignored when evaluating connection requests. These branches are referred to as "ignored" in the following. Ignored branches are handled differently: 1) In Adaptricity.Connect: a bus is ignored when calculating the hosting capacity if it is connected exclusively to ignored branches. As a result, these buses are not available as possible connection points in Adaptricity.Connect. If the 'Hosting capacity on lines' option has been selected, hosting capacities are also not calculated on ignored lines. 2) In the user-defined connection request: During the automatic selection of potential connection nodes, those nodes that are connected exclusively to ignored branches are ignored.

No requirement.

LibraryReliabilityNamestring——Model01REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations
Bus1IDStringID——bus_3428ALL

ID of bus 1 that the connection element it is connected to.

Required for:

      • All calculations

Points at <Node> — first terminal

Bus2IDStringID——bus_764ALL

ID of bus 2 that the connection element it is connected to.

Required for:

      • All calculations

Points at <Node> — second terminal

Bus3IDStringID——bus_764ALL

ID of bus 3 that the connection element it is connected to.

Required for:

      • All calculations

Points at <Node> — third terminal

ConnectedAtBus1boolean—TRUETRUEALL

true if the switch is closed (connected) at bus 1, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectedAtBus2boolean—TRUETRUEALL

true if the switch is closed (connected) at bus 2, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
ConnectedAtBus3boolean—TRUETRUEALL

true if the switch is closed (connected) at bus 3, false if the switch is open (not connected). Default value is true.

Required for:

    • All calculations (calculations are run with the default value if missing)
SecondaryShortCircuitVoltageInPercentFiniteDoublepercent—6.2ALL

Short circuit voltage between primary bus and center tap

Required for:

    • All calculations
TertiaryShortCircuitVoltageInPercentFiniteDoublepercent—6.2ALL

Short circuit voltage between center tap and tertiary bus

Required for:

    • All calculations
SecondaryCopperLossesInPercentFiniteDoublepercent—1.5ALL

Copper losses at the whole secondary winding (as percentage of transformer rating)

Required for:

    • All calculations
TertiaryCopperLossesInPercentFiniteDoublepercent—1.5ALL

Copper losses at a part of the secondary winding (as percentage of transformer rating)

Required for:

    • All calculations
TransformerRatingInMegavoltampereFiniteDoubleMVA—0.4ALL

Maximum apparent power the transformer can handle

Required for:

    • All calculations
SecondaryPowerFractionFiniteDoubleMVA—0.4ALL

Fraction of transformer rating that can be drawn from center tap

Required for:

    • All calculations
RatedVoltageAtBus1FiniteDoublekV—11.0ALL

Voltage at the primary bus in Kilovolt (highest of the three voltages). Used for calculation of the turns ratio.

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
RatedVoltageAtBus2FiniteDoublekV—0.42ALL

Voltage at center tap bus in Kilovolt (intermediate voltage) Used for calculation of the turns ratio.

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
RatedVoltageAtBus3FiniteDoublekV—0.4ALL

Voltage at tertiary bus in Kilovolt (lowest of the three voltages) Used for calculation of the turns ratio.

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
ResistanceWindingV2InOhmFiniteDoublekV—0.4ALL

Resistance of V-W winding at the intermediate voltage

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)
ResistanceWindingV3InOhmFiniteDoublekV—0.4ALL

Resistance of V-W winding at the lowest voltage

Required for:

    • All calculations (defaults to the value of the bus voltage if missing)

10

<Feeder>

in <FEEDER>24 attributes14 requiredrequired in every grid

Network feeder.

Instantiate
<GRID>
  <FEEDER>
    <Feeder ID="Feed01"
            HostBusID="b_0392"
            OperationalVoltageInPerUnit="1.0"
            OperationalAngleInRadians="0.0"
            MaxSourceShortCircuitPowerInMegavoltampere="3500.0"
            MinSourceShortCircuitPowerInMegavoltampere="2500.0"
            MaxSinglePhaseToGroundFaultCurrentInKiloampere="2500.0"
            MinSinglePhaseToGroundFaultCurrentInKiloampere="3500.0"
            MaxThreePhaseReactanceToResistanceRatio="5"
            MinThreePhaseReactanceToResistanceRatio="5"
            MaxSinglePhaseReactanceToResistanceRatio="5"
            MinSinglePhaseReactanceToResistanceRatio="5"
            ReactanceToResistanceRatio="5"
            Connected="true"/>
  </FEEDER>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——Feed01ALL

ID (see type StringID).

Hard requirement.

Namestring——Main FeederVIS

A human-readable name.

No requirement.

HostBusIDrequiredStringID——b_0392ALL

Bus ID of the bus that the network feeder is attached to. Becomes the slack bus of the power flow model.

Required for:

    • All calculations

Points at <Node> — becomes the slack bus

Descriptionstring——My descriptionVIS

A human-readable documentation

No requirement.

ConstructionYearinteger——1958VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets/feedersVIS

URL that is displayed in our system. Can be used for switching to another system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

OperationalVoltageInPerUnitDoubleOrPhasewiseDoublep.u.1.01.0ALL

Sets the voltage of the slack bus and consequently influences the power flow behavior of the entire grid.

Required for:

    • All calculations
OperationalAngleInRadiansDoubleOrPhasewiseDoublep.u.1.00.0ALL

Can be set to arbitrary value (e.g. zero) since only the angle differences within the grid matter for the power flow.

Required for:

    • All calculations
MaxHostingCapacityLoadInKilowattDoubleOrPhasewiseDoublekW—10000.0

Denotes the maximum hosting capacity power for load of the overlying grid.

No requirement.

MaxHostingCapacityGenerationInKilowattDoubleOrPhasewiseDoublekW—10000.0

Denotes the maximum hosting capacity power for generation of the overlying grid.

No requirement.

VoltageFactorMaxFiniteDouble—1.00.0

Denotes the voltage multiplier for computation of maximum short-circuit currents according to IEC 60909. Not supported yet (currently, a default value of 1 is used).

No requirement.

VoltageFactorMinFiniteDouble—1.00.0

Denotes the voltage multiplier for computation of minimum short-circuit currents according to IEC 60909. Not supported yet (currently, a default value of 1 is used).

No requirement.

MaxSourceShortCircuitPowerInMegavoltampereFiniteDoubleMVA—3500.0SCC

Denotes the maximum short-circuit power of the overlying grid according to IEC 60909.

Required for:

    • Short circuit calculations
MinSourceShortCircuitPowerInMegavoltampereFiniteDoubleMVA—2500.0SCC

Denotes the minimum short-circuit power of the overlying grid according to IEC 60909.

Required for:

    • Short circuit calculations
MaxSinglePhaseToGroundFaultCurrentInKiloampereFiniteDoublekA—2500.0SCC

Denotes the maximum short-circuit single-phase-to-ground fault current at the bus of the overlying grid.

Required for:

    • Short circuit calculations
MinSinglePhaseToGroundFaultCurrentInKiloampereFiniteDoublekA—3500.0SCC

Denotes the minimum short-circuit single-phase-to-ground fault current at the bus of the overlying grid.

Required for:

  • Short circuit calculations
MaxThreePhaseReactanceToResistanceRatioFiniteDouble——5SCC

Denotes the X/R ratio at the bus of the overlying grid at maximum three-phase fault current.

Required for:

    • Short circuit calculations
MinThreePhaseReactanceToResistanceRatioFiniteDouble——5SCC

Denotes the X/R ratio at the bus of the overlying grid at minimum three-phase fault current.

Required for:

  • Short circuit calculations
MaxSinglePhaseReactanceToResistanceRatioFiniteDouble——5SCC

Denotes the X/R ratio at the bus of the overlying grid at maximum single-phase-to-ground fault current.

Required for:

  • Short circuit calculations
MinSinglePhaseReactanceToResistanceRatioFiniteDouble——5SCC

Denotes the X/R ratio at the bus of the overlying grid at minimum single-phase-to-ground fault current.

Required for:

  • Short circuit calculations
ReactanceToResistanceRatioFiniteDouble——5SCC

Denotes the X/R ratio of the overlying grid.

Required for:

    • Short circuit calculations
Connectedboolean—TRUETRUEALL

Denotes whether the network feeder is electrically connected. true if the switch is closed (connected) at the host bus, false if the switch is open (not connected).

Required for:

    • All calculations (calculations are run with the default value of 'true' if missing)

11

<Fuse>

in <FUSE>11 attributes5 required

Fuse.

Instantiate
<GRID>
  <FUSE>
    <Fuse ID="fs_37928"
          HostBranchID="line_287685"
          BranchEnd="Bus1"
          FuseType="Grid"
          LibraryFuseName="Fuse11kv_300A"/>
  </FUSE>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——fs_37928PRC

ID (see type StringID). Each Fuse requires a unique ID among all Fuses.

Hard requirement.

Namestring——Fuse NameVIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionYearinteger——1976VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets.com/fusesVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

HostBranchIDStringID——line_287685PRC

ID of the branch that the fuse is connected to (required).

Required for:

    • All calculations

Points at <Line> or <Connection> or <Transformer> — attached to a branch end

BranchEndBranchEndEnum—Bus1line_287685PRC

The branch end that the fuse is connected to (Bus1 or Bus2). Default value is 'Bus1'.

Required for:

    • All calculations
Allowed valuesBus1Bus2
FuseTypeFuseTypeEnum—Bus1GridPRC

Denoting the type of fuse. Possible entries: Grid (installed in the distribution grid), Connection (installed at a connection point, e.g. house)

Required for:

    • Protection calculations
Allowed valuesGridConnection
LibraryFuseNamestring—Bus1Fuse11kv_300APRCLIB

Unique name that identifies the fuse in the component library.

Required for:

    • Component library matching

12

<ProtectionDevice>

in <PROTECTIONDEVICE>9 attributes1 required

Protection Device. See type 'ProtectionDevice'

Instantiate
<GRID>
  <PROTECTIONDEVICE>
    <ProtectionDevice ID="id_0001"/>
  </PROTECTIONDEVICE>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID———

ID (see type StringID). Each ProtectionDevice requires a unique ID among all ProtectionDevices.

Hard requirement.

Namestring———

A human-readable name.

No requirement.

Descriptionstring———

A human-readable description.

No requirement.

ConstructionYearinteger———

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI———

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

DirectionProtectionDeviceDirection———

The direction of the current for which the protection device should trip in the case of a short-circuit. Defaults to 'Undirected'.

No requirement.

Allowed valuesUndirectedBus 1 to Bus 2Bus 2 to Bus 1
HostSwitchIDStringID———

ID of the switch where the protection device is connected to. Previously called 'HostCircuitBreakerID'.

Required.

Points at <Switch> — protects via this switch

13

<Switch>

in <SWITCH>12 attributes6 required

A switch, either Disconnect Switch, Load Switch, or Circuit Breaker.

Instantiate
<GRID>
  <SWITCH>
    <Switch ID="sw_293874"
            Type="Circuit Breaker"
            BranchEnd="Bus1"
            HostBranchID="ln_2938"
            MaxAperiodicShortCircuitCurrentInKiloampere="3.5"
            LibraryReliabilityName="switchType04"/>
  </SWITCH>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——sw_293874ALL

ID (see type StringID). Each Switch requires a unique ID among all Switches.

Hard requirement.

Namestring——My nameVIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

TypeSwitchTypeEnum——LoadSwitchALL

Type of the switch.

Required for:

    • All calculations
Allowed valuesCircuit BreakerDisconnect SwitchLoad Switch
BranchEndBranchEndEnum—Bus1Bus1ALL

Specificities if the switch is placed at bus1 or bus2 of its host edge: “Bus1”, “Bus2”.

Required for:

    • All calculations
Allowed valuesBus1Bus2
HostBranchIDstring——ln_2938ALL

ID of the branch, which the switch is allocated to.

Required for:

    • All calculations

Points at <Line> or <Connection> or <Transformer> — attached to a branch end

MaxAperiodicShortCircuitCurrentInKiloampereFiniteDoublekA—3.5PRC

No requirement.

Optional for:

    • Protection calculation
ConstructionYearinteger——2004VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets/switchVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

LibraryReliabilityNamestring——switchType04REL

Defines the used reliability model of Adaptricity's component library. The reliability model defines how long and how frequently the component is expected to fail.

Required for:

    • Reliability calculations

14

<PqMeter>

in <PQMETER>6 attributes1 required

A PQ meter whose measurements are used solely for comparison (measured vs. simulated) or to display measured values or to evaluate alerts. It is defined on branches and measures values on the branch or on a bus connected to the branch.

Instantiate
<GRID>
  <PQMETER>
    <PqMeter ID="id_0001"/>
  </PQMETER>
</GRID>
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID———

ID (see type StringID). Each PqMeter requires a unique ID among all PqMeters.

Hard requirement.

Namestring———

A human-readable name.

Descriptionstring———

A human-readable description.

MeterIDstring———

ID of the meter.

Links out of the grid model — a meter supplying measurements for this element

HostBranchIDStringID———

ID of the branch that the PQ meter is attached to.

Points at <Line> or <Connection> or <Transformer> — attached to a branch end

BranchEndBranchEndEnum———

The branch end that the PQ meter measures at (Bus1 or Bus2).

Allowed valuesBus1Bus2

15

<Station>

in <STATION>11 attributes4 required

Any container for grid elements. It can model anything from a distribution cabinet to a substation.

Instantiate
<GRID>
  <STATION>
    <Station ID="st_293847"
             x="1.5"
             y="0.6"
             Width="20"/>
  </STATION>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——st_293847ALL

ID (see type StringID). Each station requires a unique ID among all stations.

Hard requirement.

Namestring——My nameVIS

A human-readable name.

No requirement.

Descriptionstring——My descriptionVIS

A human-readable description.

No requirement.

ConstructionYearinteger——1978VIS

The year that the component was built in the field. Only used for information purposes.

No requirement.

ConstructionMonthMonth——02VIS

The Month that the component was built in the field. Only used for information purposes.

No requirement.

ExternalURLanyURI——www.mylistofassets/stationVIS

URL that is displayed in our system. Can be used for switching to an external system.

No requirement.

GridUpgradeIDstring——GU-2026-000001

If set to the ID of a grid upgrade, the corresponding grid upgrade is automatically closed when the grid is imported via grid data integration.

No requirement.

Links out of the grid model — ID of a grid upgrade that is used to set the status of the grid upgrade.

TypeStationTypeEnum——TransformerStationVIS

Denotes the type of station and shall be either TransformerStation, DistributionCabinet, Substation, or Other.

No requirement.

Allowed valuesTransformerStationDistributionCabinetSubstationOther
xFiniteDouble—0.01.5STT

x-coordinate of the station to display in the schematic view.

Required for:

    • Display in schematic view
yFiniteDouble—0.00.6STT

y-coordinate of the station to display in the schematic view.

Required for:

    • Display in schematic view
WidthFiniteDoublepoints—20STT

The width of the bus in the schematic view.

Required for:

    • Display in schematic view

16

<Shape>

in <SHAPE>19 attributes3 required

A geometrical shape, for display only.

Instantiate
<GRID>
  <SHAPE>
    <Shape ID="shape01"
           DisplayType="Map"
           Type="Rectangle"/>
  </SHAPE>
</GRID>

Child elements

  • <GIS>GISTypeoptionalDefines the GIS information (geometry and coordinates).
AttributeTypeUnitDefaultExampleFeatures
IDrequiredStringID——shape01VIS

A string ID, unique within the grid model.

Hard requirement.

DisplayTyperequiredDisplayTypeEnum——MapVIS

Definition whether the shape is displayed on the schematic or on the map view: “Schematic”, “Map”.

Hard requirement.

Allowed valuesSchematicMap
TyperequiredFormTypeEnum——RectangleVIS

Type of the geometry.

Possible types are:

“Line”, “Arrow”, “Ellipse”, “Rectangle”, “Polygon”

Hard requirement.

Allowed valuesLineArrowEllipseRectanglePolygon
x1FiniteDoublepoints—234.23VIS

The x-coordinate of the upper left corner of the shape.

Required for:

    • Schematic display
y1FiniteDoublepoints—24.87VIS

The y-coordinate of the upper left corner of the shape.

Required for:

    • Schematic display
x2FiniteDoublepoints—24.87VIS

The x-coordinate of the lower right corner of the shape.

Required for:

    • Schematic display
y2FiniteDoublepoints—24.87VIS

The y-coordinate of the lower right corner of the shape.

Required for:

    • Schematic display
Namestring——My nameVIS

A human-readable name.

No requirement.

Descriptionstring——My DescriptionVIS

A human-readable description.

No requirement.

Textstring——My TextVIS

Text to be shown within the shape.

No requirement.

TextStyleinteger——2VIS

A bit mask of text styles.

The following constants are OR-ed bitwise:

  • 1: italic
  • 2: bold
  • 4: underlined
  • 8: strikethrough

No requirement.

TextPositionTextPositionEnumType——TopVIS

Position, where text is displayed within the shape.

No requirement.

Allowed valuesTopLeftTopCenterTopRightMiddleLeftMiddleCenterMiddleRightBottomLeftBottomCenterBottomRight
TextOrientationTextOrientationEnumType——VerticalVIS

Orientation of the text.

No requirement.

Allowed valuesHorizontalVertical
FontSizeinteger——15VIS

Font size of the text.

No requirement.

TextColorColorType——#blackVIS

Color of the text.

No requirement.

OutlineColorColorType——#blackVIS

Color of the shape outline.

No requirement.

BackgroundColorColorType——#whiteVIS

Background color of the shape.

No requirement.

OutlineWidthinteger——2.0VIS

Width of the shape outline.

No requirement.

StationIDstring——st_293847VIS

The ID of the station, if this shape belongs to a station.

No requirement.

Points at <Station> — belongs to this station

Plain fields on <GRID>

  • <description>stringDescriptive field to add comments.

Reserved, not yet supported

These containers are declared in the schema so that files carrying them still validate, but Adaptricity does not read them yet.

  • <ASYMMETRIC_LINE>Not supported yet.
  • <ASYMMETRIC_TRANSFORMER>Not supported yet.
  • <THREE-W-TRANSFORMER>Not supported yet.
  • <SHUNT>Not supported yet.

Worked example

A complete four-bus feeder

Every snippet above shows one element in isolation. This is what they look like wired together: the IDs are what turn a pile of elements into a network. This file is validated against the schema on every build.

example_grid.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
  A complete, valid Adaptricity grid model, kept as small as it can be while still showing
  every kind of link the format has.

  What it describes: one 11 kV source bus in a substation, a distribution transformer down to
  400 V, two cable sections along a street, a residential load and a rooftop PV plant.

      Feeder f_01                     (slack, sets the reference voltage)
        |
      n_mv01  11 kV busbar            in station st_01
        |
      Transformer t_01  Dyn5          Bus1ID -> n_mv01, Bus2ID -> n_lv01
        |
      n_lv01  400 V busbar            in station st_01
        |     Switch sw_01            HostBranchID -> l_01, BranchEnd Bus1
      Line l_01  0.122 km
        |
      n_lv02  house connection ────── Load ld_01
        |     Fuse fu_01              HostBranchID -> l_02, BranchEnd Bus2
      Line l_02  0.085 km
        |
      n_lv03  house connection ────── Generator g_01  (PV, 12 kW)

  The IDs are the whole point: they are what turns a list of components into a network.
  Bus1ID/Bus2ID attach a branch to two buses, HostBusID makes a bus the slack, HostBranchID
  attaches switchgear to one end of a branch, and StationID groups buses into a substation.

  Written against the newest schema. The build fits it to whichever version it is rendering for -
  rewriting the DPGXMLVersion stamp, dropping what that version does not have - and validates the
  result, so it cannot drift out of date. Do not hand-edit it for an older version.
-->
<GRID DPGXMLVersion="2.71">

  <description>Willow Street — worked example for the Adaptricity grid model format.</description>

  <!-- ============ Stations: group buses into a substation for the schematic view ========= -->
  <STATION>
    <Station ID="st_01"
             Name="Willow Street substation"
             Description="11/0.4 kV distribution substation"
             Type="TransformerStation"
             ConstructionYear="1994"
             x="1.0" y="1.0" Width="20">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.376890" Lon="8.541700"/></Points>
      </GIS>
    </Station>
  </STATION>

  <!-- ============ Buses. Every branch and every injection points at one of these ========= -->
  <BUSBAR_NODE>
    <Node ID="n_mv01"
          Name="Willow Street 11 kV"
          Type="TransformerStation"
          BaseVoltageInKilovolt="11.0"
          StationID="st_01"
          LibraryReliabilityName="REL04"
          ConstructionYear="1994">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.376890" Lon="8.541700"/></Points>
      </GIS>
    </Node>

    <Node ID="n_lv01"
          Name="Willow Street 400 V"
          Type="BusBar"
          BaseVoltageInKilovolt="0.4"
          StationID="st_01"
          LibraryReliabilityName="REL04">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.376902" Lon="8.541735"/></Points>
      </GIS>
    </Node>

    <Node ID="n_lv02"
          Name="Willow Street 14"
          Description="House connection point"
          Type="ConnectionPoint"
          BaseVoltageInKilovolt="0.4"
          CustomersToBusMatchingID="MP-4471902"
          LibraryReliabilityName="REL04">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.377640" Lon="8.542510"/></Points>
      </GIS>
    </Node>

    <Node ID="n_lv03"
          Name="Willow Street 22"
          Description="House connection point"
          Type="ConnectionPoint"
          BaseVoltageInKilovolt="0.4"
          CustomersToBusMatchingID="MP-4471938"
          LibraryReliabilityName="REL04">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.378180" Lon="8.543090"/></Points>
      </GIS>
    </Node>
  </BUSBAR_NODE>

  <!-- ============ Network feeder: makes n_mv01 the slack bus of the load flow ============ -->
  <FEEDER>
    <Feeder ID="f_01"
            Name="Willow Street infeed"
            HostBusID="n_mv01"
            OperationalVoltageInPerUnit="1.02"
            OperationalAngleInRadians="0.0"
            MaxSourceShortCircuitPowerInMegavoltampere="250.0"
            MinSourceShortCircuitPowerInMegavoltampere="180.0"
            ReactanceToResistanceRatio="7.0"
            Connected="true"/>
  </FEEDER>

  <!-- ============ Transformer: the branch between the two voltage levels ================= -->
  <TRANSFORMER>
    <Transformer ID="t_01"
                 Name="Willow Street T1"
                 Bus1ID="n_mv01"
                 Bus2ID="n_lv01"
                 ConnectedAtBus1="true"
                 ConnectedAtBus2="true"
                 VectorGroup="Dyn5"
                 StarPointGrounding="Direct grounding"
                 TransformerRatingInMegavoltampere="0.63"
                 MaximumApparentPowerInMegavoltampere="0.63"
                 ShortCircuitVoltageInPercent="4.1"
                 CopperLossesInPercent="1.1"
                 RatedVoltageAtBus1="11.0"
                 RatedVoltageAtBus2="0.4"
                 IsTapChanging="true"
                 NumTaps="5"
                 TapSizeInPercent="2.5"
                 SetpointInPerUnit="1.02"
                 DeadBandInPercent="0.5"
                 MeasuredVoltageBusID="n_lv01"
                 MaximumMeasuredApparentPowerInMegavoltampere="0.48"
                 CosPhiAtMaximumApparentPower="0.97"
                 CosPhiTypeAtMaximumApparentPower="INDUCTIVE"
                 Manufacturer="Transformers Inc."
                 LibraryComponentName="11/0.4 630"
                 LibraryReliabilityName="REL_TR03"
                 ConstructionYear="1994">
      <GIS ShapeType="Point">
        <Points><Point Lat="47.376896" Lon="8.541718"/></Points>
      </GIS>
    </Transformer>
  </TRANSFORMER>

  <!-- ============ Lines: the cable sections along the street ============================= -->
  <LINE>
    <Line ID="l_01"
          Name="Willow Street section 1"
          Bus1ID="n_lv01"
          Bus2ID="n_lv02"
          ConnectedAtBus1="true"
          ConnectedAtBus2="true"
          LengthInKilometer="0.122"
          ResistanceInOhmPerKilometer="0.206"
          ReactanceInOhmPerKilometer="0.080"
          ZeroSequenceResistanceInOhmPerKilometer="0.824"
          ZeroSequenceReactanceInOhmPerKilometer="0.320"
          MaximumCurrentInAmpere="275.0"
          TemperatureInCelsius="20.0"
          IsOverhead="false"
          Material="Al"
          CrossSection="4x150"
          LibraryComponentType="Aluminium 4x150 1kV"
          LibraryReliabilityName="REL_CBL01"
          ConstructionYear="1994">
      <GIS ShapeType="Line">
        <Points>
          <Point Lat="47.376902" Lon="8.541735"/>
          <Point Lat="47.377301" Lon="8.542140"/>
          <Point Lat="47.377640" Lon="8.542510"/>
        </Points>
      </GIS>
    </Line>

    <Line ID="l_02"
          Name="Willow Street section 2"
          Bus1ID="n_lv02"
          Bus2ID="n_lv03"
          ConnectedAtBus1="true"
          ConnectedAtBus2="true"
          LengthInKilometer="0.085"
          ResistanceInOhmPerKilometer="0.320"
          ReactanceInOhmPerKilometer="0.082"
          MaximumCurrentInAmpere="195.0"
          TemperatureInCelsius="20.0"
          IsOverhead="false"
          Material="Al"
          CrossSection="4x95"
          LibraryComponentType="Aluminium 4x95 1kV"
          LibraryReliabilityName="REL_CBL01"
          ConstructionYear="2008">
      <GIS ShapeType="Line">
        <Points>
          <Point Lat="47.377640" Lon="8.542510"/>
          <Point Lat="47.378180" Lon="8.543090"/>
        </Points>
      </GIS>
    </Line>
  </LINE>

  <!-- ============ Switchgear: attaches to one END of a branch, not to a bus ============== -->
  <SWITCH>
    <Switch ID="sw_01"
            Name="Willow Street feeder switch"
            Type="Load Switch"
            HostBranchID="l_01"
            BranchEnd="Bus1"
            MaxAperiodicShortCircuitCurrentInKiloampere="25.0"
            LibraryReliabilityName="REL_SW02"
            ConstructionYear="1994"/>
  </SWITCH>

  <FUSE>
    <Fuse ID="fu_01"
          Name="House connection fuse, Willow Street 22"
          HostBranchID="l_02"
          BranchEnd="Bus2"
          FuseType="Connection"
          LibraryFuseName="NH00 gG 100A"/>
  </FUSE>

  <!-- ============ Injections: what the grid actually serves ============================== -->
  <LOAD>
    <Load ID="ld_01"
          Name="Willow Street 14"
          LoadCategory="Residential"
          Bus1ID="n_lv02"
          ActiveLoadInMegawatt="0.0084"
          AnnualActiveEnergyInKilowatthours="14200"
          RatedPowerInKilowatt="24.0"
          NumberOfCustomers="4"
          Connected="true">
      <ReactivePower Type="FIXED_COS_PHI" FixedCosPhi="0.97" CosPhiType="INDUCTIVE"/>
      <TimeSeriesBehavior Type="PreInstalledProfile" Name="H0 residential"/>
    </Load>
  </LOAD>

  <GENERATOR>
    <Generator ID="g_01"
               Name="Willow Street 22, rooftop PV"
               GenerationCategory="PV"
               ConnectionType="Inverter"
               Bus1ID="n_lv03"
               ActiveGenerationInMegawatt="0.012"
               AnnualActiveEnergyInKilowatthours="11400"
               RatedPowerInKilowatt="12.0"
               Connected="true"
               LibraryReliabilityName="REL_GEN01"
               ConstructionYear="2021">
      <ReactivePower Type="FIXED_COS_PHI" FixedCosPhi="1.0" CosPhiType="INDUCTIVE"/>
      <TimeSeriesBehavior Type="PreInstalledProfile" Name="PV south 30 degrees"/>
    </Generator>
  </GENERATOR>

</GRID>

Notes on the schema itself

Values the published XSD gives as examples that do not fit their own type — most look like copy-paste slips upstream. The snippets above substitute a valid value, so what you copy from this page is always legal XML.

  • schema-exampleNode.IsVertical has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleLine.IsOverhead has extra:example='FALSE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleLine.ConnectedAtBus1 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleLine.ConnectedAtBus2 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleConnection.ConnectedAtBus1 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleConnection.ConnectedAtBus2 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleLoad.LoadCategory has extra:example='www.mylistofassets.com/loads', which is not a valid LoadCategoryEnum (allowed: Residential, Industrial, Heat pump, Electric heating) - the snippet uses a valid value instead
  • schema-exampleLoad.Connected has extra:example='b_0938', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleGenerator.GenerationCategory has extra:example='Photovoltaic', which is not a valid GenerationCategoryEnum (allowed: PV, Wind, Biomass, Hydro) - the snippet uses a valid value instead
  • schema-exampleGenerator.ConnectionType has extra:example='Photovoltaic', which is not a valid GenerationConnectionEnum (allowed: Direct, Inverter, Synchronous Machine, Asynchronous Machine) - the snippet uses a valid value instead
  • schema-exampleGenerator.Connected has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleStorage.Connected has extra:example='b_0938', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleTransformer.ColorIndex has extra:example='blue', which is not a valid nonNegativeInteger - the snippet uses a valid value instead
  • schema-exampleTransformer.StarPointGrounding has extra:example='DirectGrounding', which is not a valid StarPointGrounding (allowed: Direct grounding, Low-resistance grounding, Resonant grounding, Insulated grid) - the snippet uses a valid value instead
  • schema-exampleTransformer.IsTapChanging has extra:example='FALSE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleTransformer.NumTaps has extra:example='FALSE', which is not a valid int - the snippet uses a valid value instead
  • schema-exampleTransformer.ConnectedAtBus1 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleTransformer.ConnectedAtBus2 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleDualVoltageTransformer.ConnectedAtBus1 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleDualVoltageTransformer.ConnectedAtBus2 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleDualVoltageTransformer.ConnectedAtBus3 has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleFeeder.Connected has extra:example='TRUE', which is not a valid boolean - the snippet uses a valid value instead
  • schema-exampleFuse.BranchEnd has extra:example='line_287685', which is not a valid BranchEndEnum (allowed: Bus1, Bus2) - the snippet uses a valid value instead
  • schema-exampleSwitch.Type has extra:example='LoadSwitch', which is not a valid SwitchTypeEnum (allowed: Circuit Breaker, Disconnect Switch, Load Switch) - the snippet uses a valid value instead
  • schema-exampleShape.TextPosition has extra:example='Top', which is not a valid TextPositionEnumType (allowed: TopLeft, TopCenter, TopRight, MiddleLeft) - the snippet uses a valid value instead
  • schema-exampleShape.TextColor has extra:example='#black', which is not a valid ColorType - the snippet uses a valid value instead
  • schema-exampleShape.OutlineColor has extra:example='#black', which is not a valid ColorType - the snippet uses a valid value instead
  • schema-exampleShape.BackgroundColor has extra:example='#white', which is not a valid ColorType - the snippet uses a valid value instead
  • schema-exampleShape.OutlineWidth has extra:example='2.0', which is not a valid integer - the snippet uses a valid value instead

What the feature codes mean

Every attribute in the schema is tagged with the Adaptricity features that need it. A solid chip means the attribute is mandatory for that feature; an outlined chip means it improves the result but the feature still runs without it.

ALLAll calculations

Required by every Adaptricity computation. Without these attributes the node-branch model is incomplete and no power flow can run.

PANTONE 242U · Secure Purple

GISGeographical display

Places the element on the map in its real geographical layout, using WGS84 coordinates.

PANTONE 5415U

CONAdaptricity.Connect

Used by the connection-request workflow — assessing whether a new load or generator can be connected at a given point in the grid.

PANTONE 2461 C · APAC

SCCShort-circuit calculations

Feeds fault-current computation. Several of these can be derived from the positive-sequence impedance if omitted, at the cost of accuracy.

PANTONE 186U

PRCProtection calculation

Drives protection-device coordination and grading. The XSD also spells this code PTC on one attribute; both mean the same feature.

PANTONE 7413 C · EMEA

RELReliability calculations

Selects the component's reliability model — how often and how long it is expected to fail — from Adaptricity's component library.

PANTONE 556U

LIBComponent library matching

Descriptive properties used to match the component against Adaptricity's line and transformer library, so missing electrical parameters can be filled in automatically. Removed after import.

PANTONE 476U

SSTUnbalanced / phase-wise simulation

Declares which phases an element occupies. Without it the element is treated as symmetric three-phase.

PANTONE 110U

STTStation schematic layout

Positions and sizes elements inside a station's detail scheme in the schematic view.

PANTONE 5415U, shaded

VISVisualisation & readability

Never required for a computation, but makes the grid legible to a human in the Adaptricity frontend — names, descriptions, colours, schematic coordinates.

PANTONE Cool Gray 7 U

Types and enumerations

The named types attributes refer to, with their allowed values.

BranchEndEnumstring

The BranchEndEnum at which end of a branch (line, transformer, connection) something is measured/installed .

Bus1Bus2

BusTypeEnumstring

Each bus can optionally have a bus type. Depending on the type the bus is visualized differently in the schematic grid viewer. Unless otherwise indicated, this property doesn't affect calculations.

TransformerStationDistributionCabinetCableJunctionBusBarConnectionPointSmallConnectionPointVirtualPreferredNetworkFeederLocationOther

ColorTypestring

A hex color CSS string in the format #RRGGBBAA

pattern #[0-9a-fA-F]{8}

cosPhiTypestring

Defines in which situations reactive power is injected into or consumed from the grid. This depends on the cosPhiType and sometimes on the 'reference frame'. Loads are evaluated in the 'consumer reference frame' and generators in the 'producer reference frame'.

INDUCTIVECAPACITIVE

DisplayTypeEnumstring

SchematicMap

DoubleOrPhasewiseDoubleunion of inline types

Either a single double or a phase-wise double with three doubles separated by spaces.

FiniteDoubledouble

minExclusive -INF · maxExclusive INF

FormTypeEnumstring

LineArrowEllipseRectanglePolygon

FuseTypeEnumstring

GridConnection

GenerationCategoryEnumstring

Generators can have a category. This is used for filtering.

PVWindBiomassHydroGas turbineCombined heat and powerEquivalent aggregated generationOther

GenerationConnectionEnumstring

DirectInverterSynchronous MachineAsynchronous MachineConverter

LoadCategoryEnumstring

ResidentialIndustrialHeat pumpElectric heatingElectric water heaterEV chargerStationary batteryEquivalent aggregated loadOther

Monthinteger

minInclusive 1 · maxInclusive 12

PhaseEnumstring

ABCABBCACABC

ProtectionDeviceDirectionstring

UndirectedBus 1 to Bus 2Bus 2 to Bus 1

ReactivePowerTypestring

FIXED_QFIXED_COS_PHILIBRARY_CHARACTERISTIC

ShapeTypeEnumstring

PointLinePolygon

StarPointGroundingstring

This type characterizes how the star point of a transformer is grounded. This is relevant in case of a short circuit. Not all transformers have a star point. Only if the vector group contains a 'y' character on the secondary side, e.g. 'Dy', the transformer has a star point. In the Adaptricity platform the StarPointGrounding property is interpreted as grounding information for a star point the secondary side of the transformer. This property is not mandatory. However, if not provided for transformers that do have a star point on the secondary side, short circuit calculation is not possible.

Direct groundingLow-resistance groundingResonant groundingInsulated grid

StationTypeEnumstring

The type of the station. This property doesn't affect calculations.

TransformerStationDistributionCabinetSubstationOther

StorageCategoryEnumstring

BatteryPumped HydroThermalOther Storage

StringIDstring

A valid ID is any non-empty string. Each element requires a unique ID. Usually IDs must be unique among their own type. For branch types (Line, Connection, Transformer) all IDs must be unique among all branch types. E.g., a line must not have the same ID as a transformer.

minLength 1

SwitchTypeEnumstring

Circuit BreakerDisconnect SwitchLoad Switch

TextOrientationEnumTypestring

HorizontalVertical

TextPositionEnumTypestring

TopLeftTopCenterTopRightMiddleLeftMiddleCenterMiddleRightBottomLeftBottomCenterBottomRight

TimeSeriesBehaviorTypeEnumstring

IgnoreCustomProfilePreInstalledProfileModelMeteredMeteredActivePowerMasked

DefiniteTimeOvercurrentProtectioncomplex

DistanceProtectioncomplex

GISTypecomplex

  • ShapeTypeShapeTypeEnumType of shape, either Point, Line, or Polygon
  • <Points>inline

    • ReactivePowercomplex

    • TypeReactivePowerType
    • FixedReactivePowerInKilovoltamperedouble
    • FixedCosPhidouble
    • CosPhiTypecosPhiType
    • LibraryCharacteristicNamestring

    SchematicPointsTypecomplex

    • <Points>inline

      • TimeSeriesBehaviorcomplex

      • Namestring
      • TypeTimeSeriesBehaviorTypeEnum

      About the model

      The schema's own introduction

      Grid Simulations with Adaptricity - Required Grid Data

      1. Purpose of this XML Schema

      This XML Schema Definition (XSD) specifies the node-branch data model that is required for electricity grid simulations within the Adaptricity platform. It serves as a basis for mapping the available data points at a grid operator to the attributes required by Adaptricity such that a data converter can be constructed. Besides that, a grid XML file can be validated against this XSD.

      2. Elements of the Node-Branch Model

      Grid models in the Adaptricity platform consist of a node-branch model of the topology with defined parameters for the various grid elements.

      Possible types of nodes are house connection points, busbars, cable sleeves etc. The branches can be lines (overhead or underground), transformers (possibly with tap-changer), and connections. At a node (generally referred to as "bus" in the Adaptricity platform), further elements can be connected: Network feeder, load, or generator. Switches, line voltage regulators, and fuses are attached to a defined end of an existing branch element.

      The network feeder has a special meaning in the grid model: It represents the connection of the simulated grid to the overlying grid level by pointing to the so-called slack bus in the load flow model. A slack bus is a grid node that supplies or consumes the exact amount of active and reactive power such that the power balance of the simulated grid is fulfilled. In doing so, the slack bus maintains a defined voltage magnitude and angle. While the angle can be set to an arbitrary value, the voltage magnitude (defined in per-unit) has a strong impact on the behavior of the grid since it sets the voltage reference level. It should be set to a realistic level in static simulations or parameterized with a measured voltage time-series in a time-series simulation. Both can be done within the Adaptricity platform.

      The grid topology can be displayed in a schematic view with freely configurable layout as well as on a map in its real geographical layout. Note that a grid that looks correct in the GIS view can still have missing logical links since, e.g., a line can be correctly drawn between two buses without being topologically connected to these two buses. Consequently, it is usually useful to verify the correctness of a grid import in the schematic view.

      In the schematic view, grid elements are positioned based on x-y coordinates on a canvas. After a GIS-based import, the GIS coordinates provide the basis for initial placement of the elements on the canvas. Consequently, it is not necessary to fill them separately in the GIS export.

      For running a power flow computation, the node-branch model needs to be complete in the sense that all grid elements are properly connected (e.g., every branch has a start and end node and no disconnected parts of the grid exist) and all required electrical parameters are defined.

      For attaching static load and generation objects or time series to grid buses for the purpose of load flows and time-series simulations in the Adaptricity platform, buses need to be referenced, e.g., in the list of final customers present on that grid. For this purpose, the ID, name, description or a special property called customersToBusMatchingID can be used. This mechanism establishes the link between the grid topology and anything that happens on that topology.

      3. Possible Splitting of the Grid Model

      A real grid area of a grid operator (e.g., the perimeter of a primary substation including low-voltage connections, or even a larger region) can be contained in one comprehensive grid model. Alternatively, it can be split into different grid models in order to speed up certain computation tasks (e.g., connection requests). The splitting can either be conducted automatically on a cyclic import via the Grid Data Integration (GDI) interface, or manually on any given grid model in the grid editor.

      4. Detail Schemes and Switching States

      The topology of a grid area is comprised of two different aspects:

      a. The layout of cables and overhead lines in the field b. The inner topology of primary and secondary substations and distribution cabinets

      While a. is usually quite straight-forward to extract from a GIS, b. is usually contained in special schematic diagrams, often referred to as detail schemes. Especially on lower voltage levels, the inner topology usually determines how a grid is operated (radially, in closed rings, weakly meshed, fully meshed) by means of switches that are open or closed. Both the switching state of switches and fuses as well as the activation state of lines can be set in the Adaptricity grid model format.

      In order to obtain a consistent topology for grid simulations, both a. and b. need to be merged to the same node-branch model by traversing the grid and associating the correct switching states to the correct line ends and transformer terminals. This is a requirement for the export mechanism which is run on the source data.

      5. Descriptive and Electrical Parameters of Lines and Transformers

      While a GIS often contains descriptive information about the component type used in the field (e.g. cable cross section and material, transformer brand and model), it often does not contain the numerical parameters needed for a load flow computation (e.g., resistance and reactance). To perform a load flow on a GIS-based grid model, these usually must be supplied separately.

      In the Adaptricity platform, a component library for lines and transformers is available which can be matched to the components used in a grid model. The library comes with several pre-configured parameter sets for typical lines and transformers and can be extended by the user.

      The procedure for using the component database to enrich a GIS-based grid model import is as follows:

      • First, it must be ensured that all the cables and transformers in the grid model coming from the GIS have a unique property, or combination of properties, that allows to identify the component unambiguously. E.g.
        • A component name for the transformer or line which is unique (straight-forward matching between component names of grid model and component libraries)
        • A transformer type which is clearly identifiable by its power rating (e.g., since the grid operator only uses one transformer type per rating)
        • A transformer type which is clearly identifiable by its brand and model name
        • A cable type which is clearly identifiable by its material and cross section (e.g., aluminum 150mm², since the grid operator only uses one type of aluminum 150mm² cables)
      • Then, two alternatives exist:
        • Adapting the component library such that for each imported component a suitable match in the library exists
        • Adapting the data situation in the GIS such that the imported descriptive parameters match a record in the database
      • During import of a grid model, the matching is performed automatically, and the model is enriched with the proper electrical parameters. For grid elements that have no unambiguous match in the database, the user is queried for a matching decision.
      TOP