Power System Model

powerSystem(file::String)

The function builds the composite type PowerSystem and populates bus, branch, generator and base fields. Once the 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 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.

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 type, populating the 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 type, populating the 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 type.

Keywords

The bus is defined with the following keywords:

• label: Unique label for the bus.
• type: Bus type:
  • type = 1: demand bus (PQ),
  • type = 2: generator bus (PV),
  • type = 3: slack bus (Vθ).
• active (pu or W): Active power demand at the bus.
• reactive (pu or VAr): Reactive power demand at the bus.
• conductance (pu or W): Active power demanded of the shunt element.
• susceptance (pu or VAr): Reactive power injected/demanded of the shunt element.
• magnitude (pu or V): Initial value of the bus voltage magnitude.
• angle (rad or deg): Initial value of the bus voltage angle.
• minMagnitude (pu or V): Minimum bus voltage magnitude value.
• maxMagnitude (pu or V): Maximum bus voltage magnitude value.
• base (V): Line-to-line voltage base value.
• area: Area number.
• lossZone: Loss zone.

Note that all voltage values, except for base voltages, are referenced to line-to-neutral voltages, while powers, when given in SI units, correspond to three-phase power.

Updates

The function updates the bus field of the PowerSystem 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 and radians as units, with the exception of the base keyword argument, which is in volts. 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)
@voltage(pu, deg, kV)

system = powerSystem()

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

updateBus!(system::PowerSystem; kwargs...)

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

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. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the bus field within the PowerSystem type, and in cases where parameters impact variables in the ac field, it automatically adjusts the field.

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)

updateBus!(analysis::Analysis; kwargs...)

The function extends the updateBus! function. By passing the Analysis type, the function first updates the specific bus within the PowerSystem type using the provided kwargs, and then updates the Analysis type with all parameters associated with that bus.

A key feature of this function is that any prior modifications made to the specified bus are preserved and applied to the Analysis type when the function is executed, ensuring consistency throughout the update process.

Example

system = powerSystem("case14.h5")
analysis = newtonRaphson(system)

updateBus!(analysis; label = 2, active = 0.15, susceptance = 0.15)

@bus(kwargs...)

The macro generates a template for a bus.

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 and radians as units, with the exception of the base keyword argument, which is in volts. 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:

@bus(type = 2, active = 0.25, angle = 0.1745)

system = powerSystem()

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

Adding a bus template using a custom unit system:

@power(MW, MVAr)
@voltage(pu, deg, kV)
@bus(type = 2, active = 25.0, angle = 10.0, base = 132.0)

system = powerSystem()

addBus!(system; label = "Bus 1", reactive = -4.0)

addBranch!(system::PowerSystem;
    label, from, to, status,
    resistance, reactance, conductance, susceptance, turnsRatio, shiftAngle,
    minDiffAngle, maxDiffAngle, minFromBus, maxFromBus, minToBus, maxToBus, type)

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

Keywords

The branch is defined with the following keywords:

• label: 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.
• minFromBus (pu, VA, W, or A): Minimum branch flow limit at the from-bus end.
• maxFromBus (pu, VA, W, or A): Maximum branch flow limit at the from-bus end.
• minToBus (pu, VA, W, or A): Minimum branch flow limit at the to-bus end.
• maxToBus (pu, VA, W, or A): Maximum branch flow limit at the to-bus end.
• type: Types of minFromBus, maxFromBus, minToBus, and maxToBus branch flow limits:
  • type = 1: active power flow (pu or W),
  • type = 2: apparent power flow (pu or VA),
  • type = 3: apparent power flow (pu or VA) with a squared inequality constraint,
  • type = 4: current magnitude flow (pu or A),
  • type = 5: current magnitude flow (pu or A) with a squared inequality constraint.

Note that when powers are given in SI units, they correspond to three-phase power.

Updates

The function updates the branch field within the PowerSystem type, and in cases where parameters impact variables in the ac and dc fields, it automatically adjusts the fields.

Default Settings

By default, certain keywords are assigned default values: status = 1, turnsRatio = 1.0, type = 3, 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 and radians. However, the user can choose to use other units besides per-units and radians by utilizing macros such as @power, @voltage, @current, 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)

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)

addBranch!(analysis::Analysis; kwargs...)

The function extends the addBranch! function. When the Analysis type is passed, the function first adds the specified branch to the PowerSystem type using the provided kwargs, and then adds the same branch to the Analysis type.

Example

system = powerSystem("case14.h5")
analysis = newtonRaphson(system)

addBranch!(analysis; label = 21, reactance = 0.21, susceptance = 0.06)

updateBranch!(system::PowerSystem; kwargs...)

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

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. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the branch field within the PowerSystem type, and in cases where parameters impact variables in the ac and dc fields, it automatically adjusts the fields.

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.22, susceptance = 0.06)

updateBranch!(analysis::Analysis; kwargs...)

The function extends the updateBranch! function. By passing the Analysis type, the function first updates the specific branch within the PowerSystem type using the provided kwargs, and then updates the Analysis type with all parameters associated with that branch.

A key feature of this function is that any prior modifications made to the specified branch are preserved and applied to the Analysis type when the function is executed, ensuring consistency throughout the update process.

Example

system = powerSystem("case14.h5")
analysis = newtonRaphson(system)

updateBranch!(analysis; label = 2, reactance = 0.32, susceptance = 0.07)

@branch(kwargs...)

The macro generates a template for a branch.

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:

@branch(reactance = 0.12, shiftAngle = 0.1745)

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")

Adding a branch template using a custom unit system:

@voltage(pu, deg)
@branch(shiftAngle = 10)

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)

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

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

Keywords

The generator is defined with the following keywords:

• label: Unique label for the generator.
• bus: Label of the bus to which the generator is connected.
• status: 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 active power output value.
• maxActive (pu or W): Maximum allowed active power output value.
• minReactive (pu or VAr): Minimum allowed reactive power output value.
• maxReactive (pu or VAr): Maximum allowed reactive power output 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.
• reactiveRamp (pu/min or VAr/min): Ramp rate for reactive power, two seconds timescale.
• area: Area participation factor.

Note that voltage magnitude values are referenced to line-to-neutral voltages, while powers, when given in SI units, correspond to three-phase power.

Updates

The function updates the generator field within the PowerSystem type, and in cases where parameters impact variables in the bus field, it automatically adjusts the field.

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 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)
@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)

addGenerator!(analysis::Analysis; kwargs...)

The function extends the addGenerator! function. When the Analysis type is passed, the function first adds the specified generator to the PowerSystem type using the provided kwargs, and then adds the same generator to the Analysis type.

Example

system = powerSystem("case14.h5")
analysis = newtonRaphson(system)

addGenerator!(analysis; bus = 1, active = 0.5, reactive = 0.2)

updateGenerator!(system::PowerSystem; kwargs...)

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

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. If any keywords are omitted, their corresponding values will remain unchanged.

Updates

The function updates the generator field within the PowerSystem type, and in cases where parameters impact variables in the bus field, it automatically adjusts the field.

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)

updateGenerator!(analysis::Analysis; kwargs...)

The function extends the updateGenerator! function. By passing the Analysis type, the function first updates the specific generator within the PowerSystem type using the provided kwargs, and then updates the Analysis type with parameters associated with that generator.

A key feature of this function is that any prior modifications made to the specified generator are preserved and applied to the Analysis type when the function is executed, ensuring consistency throughout the update process.

Example

system = powerSystem("case14.h5")
analysis = newtonRaphson(system)

updateGenerator!(analysis; label = 2, active = 0.35)

cost!(system::PowerSystem; generator, 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 type. It has the capability to append a cost to an already defined generator.

Keywords

The function accepts five keywords:

• generator: Corresponds to the already defined generator label.
• active: Active power cost model:
  • active = 1: adding or updating cost, and piecewise linear is being used,
  • active = 2: adding or updating cost, and polynomial is being used.
• reactive: Reactive power cost model:
  • reactive = 1: adding or updating cost, and piecewise linear is being used,
  • reactive = 2: adding or updating cost, and polynomial is being used.
• piecewise: Cost model defined by input-output points given as Matrix{Float64}:
  • 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: The n-th degree polynomial coefficients given as Vector{Float64}:
  • first element ($/puⁿ-hr, $/Wⁿhr or $/VArⁿ-hr): coefficient of the n-th degree term, ....,
  • penultimate element ($/pu-hr, $/W-hr or $/VAr-hr): coefficient of the first degree term,
  • last element ($/hr): constant coefficient.

Updates

The function updates the generator.cost field within the PowerSystem type.

Units

By default, the input units related with active powers are per-units, 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; generator = "Generator 1", active = 2, polynomial = [1100.0; 500.0; 150.0])

Adding a cost using a custom unit system:

@power(MW, MVAr)

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; generator = "Generator 1", active = 2, polynomial = [0.11; 5.0; 150.0])

cost!(analysis::Analysis; kwargs...)

The function extends the cost! function. When the Analysis type is passed, the function first adds or modifies an existing cost in the PowerSystem type using the provided kwargs and then applies the same changes to the Analysis type.

A key feature of this function is that any prior modifications to the specified cost are preserved and applied to the Analysis type when the function is executed, ensuring consistency throughout the update process.

Example

using Ipopt

system = powerSystem("case14.h5")
analysis = acOptimalPowerFlow(system, Ipopt.Optimizer)

cost!(analysis; generator = 2, active = 2, polynomial = [1100.0; 500.0; 150.0])

@generator(kwargs...)

The macro generates a template for a generator.

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. 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:

@generator(magnitude = 1.1)

system = powerSystem()

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

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)
@voltage(kV, deg, kV)
@generator(magnitude = 145.2)

system = powerSystem()

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

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