Power System Model

powerSystem(file::String)

The function builds the composite type PowerSystem and populates bus, branch, generator and base fields. Once the composite type PowerSystem has been created, it is possible to add new buses, branches, or generators, or modify the parameters of existing ones.

Argument

It requires a string path to:

• the HDF5 file with the .h5 extension,
• the Matpower file with the .m extension.

Returns

The PowerSystem composite type with the following fields:

• bus: data related to buses;
• branch: data related to branches;
• generator: data related to generators;
• base: base power and base voltages;
• model: data associated with AC and DC analyses.

Units

JuliaGrid stores all data in per-units and radians format which are fixed, the exceptions are base values in volt-amperes and volts. The prefixes for these base values can be changed using the @base macro.

Example

system = powerSystem("case14.h5")

powerSystem()

Alternatively, the PowerSystem composite type can be initialized by calling the function without any arguments. This allows the model to be built from scratch and modified as needed. This generates an empty PowerSystem type, with only the base power initialized to 1.0e8 volt-amperes (VA).

Example

system = powerSystem()

savePowerSystem(system::PowerSystem; path::String, reference::String, note::String)

The function saves the power system's data in the HDF5 file using the fields bus, branch, generator, and base from the PowerSystem composite type.

Keywords

The location and file name of the HDF5 file is specified by the mandatory keyword path in the format of "path/name.h5". Additional information can be provided by the optional keywords reference and note, which can be saved along with the power system data.

View HDF5 File

To view the saved HDF5 file, you can use the HDFView software.

Example

system = powerSystem("case14.m")
savePowerSystem(system; path = "D:/case14.h5")

acModel!(system::PowerSystem)

The function generates vectors and matrices based on the power system topology and parameters associated with AC analyses.

Updates

The function updates the model.ac field within the PowerSystem composite type, populating the following variables:

• nodalMatrix: the nodal matrix;
• nodalMatrixTranspose: the transpose of the nodal matrix;
• nodalFromFrom: the Y-parameters of the two-port branches;
• nodalFromTo: the Y-parameters of the two-port branches;
• nodalToTo: the Y-parameters of the two-port branches;
• nodalToFrom: the Y-parameters of the two-port branches;
• admittance: the branch admittances.

Example

system = powerSystem("case14.h5")
acModel!(system)

dcModel!(system::PowerSystem)

The function generates vectors and matrices based on the power system topology and parameters associated with DC analyses.

Updates

The function updates the model.dc field within the PowerSystem composite type, populating the following variables:

• nodalMatrix: the nodal matrix;
• admittance: the branch admittances;
• shiftPower: the active powers related to phase-shifting transformers.

Example

system = powerSystem("case14.h5")
dcModel!(system)

addBus!(system::PowerSystem; label, type, active, reactive, conductance, susceptance,
    magnitude, angle, minMagnitude, maxMagnitude, base, area, lossZone)

The function adds a new bus to the PowerSystem composite type.

Keywords

The bus is defined with the following keywords:

• label: a unique label for the bus;
• type: the bus type:
  • type = 1: demand bus (PQ);
  • type = 2: generator bus (PV);
  • type = 3: slack bus (Vθ);
• active (pu or W): the active power demand at the bus;
• reactive (pu or VAr): the reactive power demand at the bus;
• conductance (pu or W): the active power demanded of the shunt element;
• susceptance (pu or VAr): the reactive power injected/demanded of the shunt element;
• magnitude (pu or V): the initial value of the voltage magnitude;
• angle (rad or deg): the initial value of the voltage angle;
• minMagnitude (pu or V): the minimum voltage magnitude value;
• maxMagnitude (pu or V): the maximum voltage magnitude value;
• base (V): the voltage base value;
• area: the area number;
• lossZone: the loss zone.

Updates

The function updates the bus field of the PowerSystem composite type.

Default Settings

The default settings for certain keywords are as follows: type = 1, magnitude = 1.0, minMagnitude = 0.9, maxMagnitude = 1.1, and base = 138e3. The rest of the keywords are initialized with a value of zero. However, the user can modify these default settings by utilizing the @bus macro.

Units

By default, the keyword parameters use per-units (pu) and radians (rad) as units, with the exception of the base keyword argument, which is in volts (V). However, users have the option to use other units instead of per-units and radians, or to specify prefixes for base voltage by using the @power and @voltage macros.

Examples

Adding a bus using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", active = 0.25, angle = 0.175, base = 132e3)

Adding a bus using a custom unit system:

@power(MW, MVAr, MVA)
@voltage(pu, deg, kV)
system = powerSystem()

addBus!(system; label = "Bus 1", active = 25.0, angle = 10.026, base = 132.0)

updateBus!(system::PowerSystem, analysis::Analysis; kwargs...)

The function allows for the alteration of parameters for an existing bus.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined process avoids the need to completely rebuild vectors and matrices when adjusting these parameters.

Keywords

To update a specific bus, provide the necessary kwargs input arguments in accordance with the keywords specified in the addBus! function, along with their respective values. Ensure that the label keyword matches the label of the existing bus you want to modify. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the bus field within the PowerSystem composite type, and in cases where parameters impact variables in the ac field, it automatically adjusts the field. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Units

Units for input parameters can be changed using the same method as described for the addBus! function.

Example

system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
updateBus!(system; label = "Bus 1", active = 0.15, susceptance = 0.15)

@bus(kwargs...)

The macro generates a template for a bus, which can be utilized to define a bus using the addBus! function.

Keywords

To define the bus template, the kwargs input arguments must be provided in accordance with the keywords specified within the addBus! function, along with their corresponding values.

Units

By default, the keyword parameters use per-units (pu) and radians (rad) as units, with the exception of the base keyword argument, which is in volts (V). However, users have the option to use other units instead of per-units and radians, or to specify prefixes for base voltage by using the @power and @voltage macros.

Examples

Adding a bus template using the default unit system:

system = powerSystem()

@bus(type = 2, active = 0.25, angle = 0.1745)
addBus!(system; label = "Bus 1", reactive = -0.04, base = 132e3)

Adding a bus template using a custom unit system:

@power(MW, MVAr, MVA)
@voltage(pu, deg, kV)
system = powerSystem()

@bus(type = 2, active = 25.0, angle = 10.0, base = 132.0)
addBus!(system; label = "Bus 1", reactive = -4.0)

addBranch!(system::PowerSystem, analysis::Analysis; label, from, to, status,
    resistance, reactance, conductance, susceptance, turnsRatio, shiftAngle,
    minDiffAngle, maxDiffAngle, longTerm, shortTerm, emergency, type)

The function adds a new branch to the PowerSystem composite type. A branch can be added between already defined buses.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined approach circumvents the necessity for completely reconstructing vectors and matrices when adding a new branch.

Keywords

The branch is defined with the following keywords:

• label: a unique label for the branch;
• from: from-bus label, corresponds to the bus label;
• to: to-bus label, corresponds to the bus label;
• status: operating status of the branch:
  • status = 1: in-service;
  • status = 0: out-of-service;
• resistance (pu or Ω): series resistance;
• reactance (pu or Ω): series reactance;
• conductance (pu or S): total shunt conductance;
• susceptance (pu or S): total shunt susceptance;
• turnsRatio: transformer off-nominal turns ratio, equal to one for a line;
• shiftAngle (rad or deg): transformer phase shift angle, where positive value defines delay;
• minDiffAngle (rad or deg): minimum voltage angle difference value between from-bus and to-bus ends;
• maxDiffAngle (rad or deg): maximum voltage angle difference value between from-bus and to-bus ends;
• longTerm (pu or VA, W): long-term flow rating (equal to zero for unlimited);
• shortTerm (pu or VA, W): short-term flow rating (equal to zero for unlimited);
• emergency (pu or VA, W): emergency flow rating (equal to zero for unlimited);
• type: types of longTerm, shortTerm, and emergency flow ratings:
  • type = 1: apparent power flow (pu or VA);
  • type = 2: active power flow (pu or W);
  • type = 3: current magnitude flow (pu or VA at 1 pu voltage).

Updates

The function updates the branch field within the PowerSystem composite type, and in cases where parameters impact variables in the ac and dc fields, it automatically adjusts the fields. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Default Settings

By default, certain keywords are assigned default values: status = 1, turnsRatio = 1.0, type = 1, minDiffAngle = -2pi, and maxDiffAngle = 2pi. The rest of the keywords are initialized with a value of zero. However, the user can modify these default settings by utilizing the @branch macro.

Units

The default units for the keyword parameters are per-units (pu) and radians (rad). However, the user can choose to use other units besides per-units and radians by utilizing macros such as @power, @voltage, and @parameter.

Examples

Adding a branch using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
addBus!(system; label = "Bus 2", type = 1, active = 0.15, reactive = 0.08)

addBranch!(system; from = "Bus 1", to = "Bus 2", reactance = 0.12, shiftAngle = 0.1745)

Adding a branch using a custom unit system:

@voltage(pu, deg, kV)
system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
addBus!(system; label = "Bus 2", type = 1, active = 0.15, reactive = 0.08)

addBranch!(system; from = "Bus 1", to = "Bus 2", reactance = 0.12, shiftAngle = 10)

updateBranch!(system::PowerSystem, analysis::Analysis; kwargs...)

The function allows for the alteration of parameters for an existing branch.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined process avoids the need to completely rebuild vectors and matrices when adjusting these parameter

Keywords

To update a specific branch, provide the necessary kwargs input arguments in accordance with the keywords specified in the addBranch! function, along with their respective values. Ensure that the label keyword matches the label of the existing branch you want to modify. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the branch field within the PowerSystem composite type, and in cases where parameters impact variables in the ac and dc fields, it automatically adjusts the fields. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Units

Units for input parameters can be changed using the same method as described for the addBranch! function.

Example

system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
addBus!(system; label = "Bus 2", type = 1, active = 0.15, reactive = 0.08)

addBranch!(system; label = "Branch 1", from = "Bus 1", to = "Bus 2", reactance = 0.12)
updateBranch!(system; label = "Branch 1", reactance = 0.02, susceptance = 0.062)

@branch(kwargs...)

The macro generates a template for a branch, which can be utilized to define a branch using the addBranch! function.

Keywords

To define the branch template, the kwargs input arguments must be provided in accordance with the keywords specified within the addBranch! function, along with their corresponding values.

Units

The default units for the keyword parameters are per-units and radians. However, the user can choose to use other units besides per-units and radians by utilizing macros such as @power, @voltage, and @parameter.

Examples

Adding a branch template using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
addBus!(system; label = "Bus 2", type = 1, active = 0.15, reactive = 0.08)

@branch(reactance = 0.12, shiftAngle = 0.1745)
addBranch!(system; label = "Branch 1", from = "Bus 1", to = "Bus 2")

Adding a branch template using a custom unit system:

@voltage(pu, deg, kV)
system = powerSystem()

addBus!(system; label = "Bus 1", type = 3, active = 0.25, reactive = -0.04)
addBus!(system; label = "Bus 2", type = 1,  active = 0.15, reactive = 0.08)

@branch(shiftAngle = 10)
addBranch!(system; label = "Branch 1", from = "Bus 1", to = "Bus 2", reactance = 0.12)

addGenerator!(system::PowerSystem, analysis::Analysis; label, bus, status,
    active, reactive, magnitude, minActive, maxActive, minReactive, maxReactive,
    lowActive, minLowReactive, maxLowReactive, upActive, minUpReactive, maxUpReactive,
    loadFollowing, reactiveTimescale, reserve10min, reserve30min, area)

The function adds a new generator to the PowerSystem composite type. The generator can be added to an already defined bus.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined approach circumvents the necessity for completely reconstructing vectors and matrices when adding a new generator.

Keywords

The generator is defined with the following keywords:

• label: a unique label for the generator;
• bus: the label of the bus to which the generator is connected;
• status: the operating status of the generator:
  • status = 1: in-service;
  • status = 0: out-of-service;
• active (pu or W): output active power;
• reactive (pu or VAr): output reactive power;
• magnitude (pu or V): voltage magnitude setpoint;
• minActive (pu or W): minimum allowed output active power value;
• maxActive (pu or W): maximum allowed output active power value;
• minReactive (pu or VAr): minimum allowed output reactive power value;
• maxReactive (pu or VAr): maximum allowed output reactive power value;
• lowActive (pu or W): lower allowed active power output value of PQ capability curve;
• minLowReactive (pu or VAr): minimum allowed reactive power output value at lowActive value;
• maxLowReactive (pu or VAr): maximum allowed reactive power output value at lowActive value;
• upActive (pu or W): upper allowed active power output value of PQ capability curve;
• minUpReactive (pu or VAr): minimum allowed reactive power output value at upActive value;
• maxUpReactive (pu or VAr): maximum allowed reactive power output value at upActive value;
• loadFollowing (pu/min or W/min): ramp rate for load following/AG;
• reserve10min (pu or W): ramp rate for 10-minute reserves;
• reserve30min (pu or W): ramp rate for 30-minute reserves;
• reactiveTimescale (pu/min or VAr/min): ramp rate for reactive power, two seconds timescale;
• area: area participation factor.

Updates

The function updates the generator field within the PowerSystem composite type, and in cases where parameters impact variables in the bus field, it automatically adjusts the field. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Default Settings

By default, certain keywords are assigned default values: status = 1 and magnitude = 1.0 per-unit. The rest of the keywords are initialized with a value of zero. However, the user can modify these default settings by utilizing the @generator macro.

Units

By default, the input units are associated with per-units (pu) as shown. However, users have the option to use other units instead of per-units using the @power and @voltage macros.

Examples

Adding a generator using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", type = 2, active = 0.2, base = 132e3)

addGenerator!(system; bus = "Bus 1", active = 0.5, magnitude = 1.1)

Adding a generator using a custom unit system:

@power(MW, MVAr, MVA)
@voltage(kV, deg, kV)
system = powerSystem()

addBus!(system; label = "Bus 1", type = 2, active = 20, base = 132)

addGenerator!(system; bus = "Bus 1", active = 50, magnitude = 145.2)

updateGenerator!(system::PowerSystem, analysis::Analysis; kwargs...)

The function allows for the alteration of parameters for an existing generator.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined process avoids the need to completely rebuild vectors and matrices when adjusting these parameter

Keywords

To update a specific generator, provide the necessary kwargs input arguments in accordance with the keywords specified in the addGenerator! function, along with their respective values. Ensure that the label keyword matches the label of the existing generator you want to modify. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the generator field within the PowerSystem composite type, and in cases where parameters impact variables in the bus field, it automatically adjusts the field. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Units

Units for input parameters can be changed using the same method as described for the addBranch! function.

Example

system = powerSystem()

addBus!(system; label = "Bus 1", type = 2, active = 0.2, base = 132e3)

addGenerator!(system; label = "Generator 1", bus = "Bus 1", active = 0.5)
updateGenerator!(system; label = "Generator 1", active = 0.6, reactive = 0.2)

cost!(system::PowerSystem, analysis::Analysis; label, active, reactive,
    piecewise, polynomial)

The function either adds a new cost or modifies an existing one for the active or reactive power generated by the corresponding generator within the PowerSystem composite type. It has the capability to append a cost to an already defined generator.

Arguments

If the Analysis type is omitted, the function applies changes to the PowerSystem composite type only. However, when including the Analysis type, it updates both the PowerSystem and Analysis types. This streamlined approach circumvents the necessity for completely reconstructing vectors and matrices when adding a new branch.

Keywords

The function accepts five keywords:

• label: corresponds to the already defined generator label;
• active: cost model:
  • active = 1: adding or updating cost for the active power, and piecewise linear is being used;
  • active = 2: adding or updating cost for the active power, and polynomial is being used;
• reactive: cost model:
  • reactive = 1: adding or updating cost for the reactive power, and piecewise linear is being used;
  • reactive = 2: adding or updating cost for the reactive power, and polynomial is being used;
• piecewise: cost model defined by input-output points given as Array{Float64,2}:
  • first column (pu, W or VAr): active or reactive power output of the generator;
  • second column (💵/hr): cost for the specified active or reactive power output;
• polynomial: n-th degree polynomial coefficients given as Array{Float64,1}:
  • first element (💵/puⁿhr, 💵/Wⁿhr or 💵/VArⁿhr): coefficient of the n-th degree term, ...;
  • penultimate element (💵/puhr, 💵/Whr or 💵/VArhr): coefficient of the first degree term;
  • last element (💵/hr): constant coefficient.

Updates

The function updates the generator.cost field within the PowerSystem composite type. Furthermore, it guarantees that any modifications to the parameters are transmitted to the Analysis type.

Units

By default, the input units related with active powers are per-units (pu), but they can be modified using the macro @power.

Examples

Adding a cost using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", active = 0.25, reactive = -0.04, base = 132e3)

addGenerator!(system; label = "Generator 1", bus = "Bus 1", active = 0.5)
cost!(system; label = "Generator 1", active = 2, polynomial = [1100.0; 500.0; 150.0])

Adding a cost using a custom unit system:

@power(MW, MVAr, MVA)
system = powerSystem()

addBus!(system; label = "Bus 1", active = 25, reactive = -4, base = 132e3)

addGenerator!(system; label = "Generator 1", bus = "Bus 1", active = 50, reactive = 10)
cost!(system; label = "Generator 1", active = 2, polynomial = [0.11; 5.0; 150.0])

@generator(kwargs...)

The macro generates a template for a generator, which can be utilized to define a generator using the addGenerator! function.

Keywords

To define the generator template, the kwargs input arguments must be provided in accordance with the keywords specified within the addGenerator! function, along with their corresponding values.

Units

By default, the input units are associated with per-units (pu) as shown. However, users have the option to use other units instead of per-units using the @power and @voltage macros.

Examples

Adding a generator using the default unit system:

system = powerSystem()

addBus!(system; label = "Bus 1", type = 2, active = 0.25, reactive = -0.04, base = 132e3)

@generator(magnitude = 1.1)
addGenerator!(system; label = "Generator 1", bus = "Bus 1", active = 0.5, reactive = 0.1)

Adding a generator using a custom unit system:

@power(MW, MVAr, MVA)
@voltage(kV, deg, kV)
system = powerSystem()

addBus!(system; label = "Bus 1", type = 2, active = 25, reactive = -4, base = 132)

@generator(magnitude = 145.2)
addGenerator!(system; label = "Generator 1", bus = "Bus 1", active = 50, reactive = 10)