diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b6c0d8f1..716416335 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## staged +- Fixed typo in `create_transformer`, `create_xfmrcode` and ENGINEERING model documentation, `configurations` -> `configuration` and `buses` -> `bus` on transformer objects (#463) - Fixed creation of switch objects from dss, where ENGINEERING switches are expected to be zero-length objects (#462) - Fixed typo in single phase line parameters, should have been `line.c0 = line.c1` (#468) - Fixed missing `npts` property in loadshape in case3_balanced.dss (#466) diff --git a/docs/src/manual/eng-data-model.md b/docs/src/manual/eng-data-model.md index 595e8c786..ee5c367ef 100644 --- a/docs/src/manual/eng-data-model.md +++ b/docs/src/manual/eng-data-model.md @@ -165,30 +165,30 @@ This is a pi-model branch. When a `linecode` is given, and any of `rs`, `xs`, `b These are n-winding (`nwinding`), n-phase (`nphase`), lossy transformers. Note that most properties are now Vectors (or Vectors of Vectors), indexed over the windings. -| Name | Default | Type | Units | Used | Description | -| ---------------- | ------------------------------------ | ---------------------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `bus` | | `Vector{String}` | | always | List of bus for each winding, `size=nwindings` | -| `connections` | | `Vector{Vector{Int}}` | | always | List of connection for each winding, `size=((nconductors),nwindings)` | -| `configurations` | `fill(WYE, nwindings)` | `Vector{ConnConfig}` | | always | `WYE` or `DELTA`. List of configuration for each winding, `size=nwindings` | -| `xfmrcode` | | `String` | | always | id of | -| `xsc` | `zeros(nwindings*(nwindings-1)/2)` | `Vector{Real}` | `sm_nom[1]` | always | List of short-circuit reactances between each pair of windings, relative to the VA rating of the first winding; enter as a list of the upper-triangle elements | -| `rw` | `zeros(nwindings)` | `Vector{Real}` | `sm_nom[1]` | always | Active power lost due to resistance of each winding, relative to the VA rating of each winding winding | -| `cmag` | `0.0` | `Real` | `sm_nom[1]` | always | Total no-load reactive power drawn by the transformer, relative to VA rating of the first winding (magnetizing current) | -| `noloadloss` | `0.0` | `Real` | `sm_nom[1]` | always | Total no-load active power drawn by the transformer, relative to VA rating of the first winding | -| `tm_nom` | `ones(nwindings)` | `Vector{Real}` | | always | Nominal tap ratio for the transformer, `size=nwindings` (multiplier) | -| `tm_ub` | | `Vector{Vector{Real}}` | | opf | Maximum tap ratio for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | -| `tm_lb` | | `Vector{Vector{Real}}` | | opf | Minimum tap ratio for for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | -| `tm_set` | `fill(fill(1.0,nphases),nwindings)` | `Vector{Vector{Real}}` | | always | Set tap ratio for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | -| `tm_fix` | `fill(fill(true,nphases),nwindings)` | `Vector{Vector{Bool}}` | | oltc | Indicates for each winding and phase whether the tap ratio is fixed, `size=((nphases),nwindings)` | -| `polarity` | `fill(1,nwindings)` | `Vector{Int}` | | always | | -| `vm_nom` | | `Vector{Real}` | volt | always | | -| `sm_nom` | | `Vector{Real}` | watt | always | | -| `sm_ub` | | `Real` | watt | opf | Rating for the total apparent power magnitude at each winding | -| `status` | `ENABLED` | `Status` | | always | `ENABLED` or `DISABLED`. Indicates if component is enabled or disabled, respectively | +| Name | Default | Type | Units | Used | Description | +| --------------- | ------------------------------------ | ---------------------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bus` | | `Vector{String}` | | always | List of bus for each winding, `size=nwindings` | +| `connections` | | `Vector{Vector{Int}}` | | always | List of connection for each winding, `size=((nconductors),nwindings)` | +| `configuration` | `fill(WYE, nwindings)` | `Vector{ConnConfig}` | | always | `WYE` or `DELTA`. List of configuration for each winding, `size=nwindings` | +| `xfmrcode` | | `String` | | always | id of | +| `xsc` | `zeros(nwindings*(nwindings-1)/2)` | `Vector{Real}` | `sm_nom[1]` | always | List of short-circuit reactances between each pair of windings, relative to the VA rating of the first winding; enter as a list of the upper-triangle elements | +| `rw` | `zeros(nwindings)` | `Vector{Real}` | `sm_nom[1]` | always | Active power lost due to resistance of each winding, relative to the VA rating of each winding winding | +| `cmag` | `0.0` | `Real` | `sm_nom[1]` | always | Total no-load reactive power drawn by the transformer, relative to VA rating of the first winding (magnetizing current) | +| `noloadloss` | `0.0` | `Real` | `sm_nom[1]` | always | Total no-load active power drawn by the transformer, relative to VA rating of the first winding | +| `tm_nom` | `ones(nwindings)` | `Vector{Real}` | | always | Nominal tap ratio for the transformer, `size=nwindings` (multiplier) | +| `tm_ub` | | `Vector{Vector{Real}}` | | opf | Maximum tap ratio for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | +| `tm_lb` | | `Vector{Vector{Real}}` | | opf | Minimum tap ratio for for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | +| `tm_set` | `fill(fill(1.0,nphases),nwindings)` | `Vector{Vector{Real}}` | | always | Set tap ratio for each winding and phase, `size=((nphases),nwindings)` (base=`tm_nom`) | +| `tm_fix` | `fill(fill(true,nphases),nwindings)` | `Vector{Vector{Bool}}` | | oltc | Indicates for each winding and phase whether the tap ratio is fixed, `size=((nphases),nwindings)` | +| `polarity` | `fill(1,nwindings)` | `Vector{Int}` | | always | | +| `vm_nom` | | `Vector{Real}` | volt | always | | +| `sm_nom` | | `Vector{Real}` | watt | always | | +| `sm_ub` | | `Real` | watt | opf | Rating for the total apparent power magnitude at each winding | +| `status` | `ENABLED` | `Status` | | always | `ENABLED` or `DISABLED`. Indicates if component is enabled or disabled, respectively | #### Asymmetric, Lossless, Two-Winding (AL2W) Transformers (`transformer`) -Special case of the Generic transformer, which is still a `transformer` object, but has a simplified method for its definition. These are transformers are asymmetric (A), lossless (L) and two-winding (2W). Asymmetric refers to the fact that the secondary is always has a `WYE` configuration, whilst the primary can be `DELTA`. The table below indicates alternate, more simple ways to specify the special case of an AL2W Transformer. `xsc` and `rw` cannot be specified for an AL2W transformer, because it is lossless. To use this definition format, all of `f_bus`, `t_bus`, `f_connections`, `t_connections`, and `configuration` must be used, and none of `buses`, `connections`, `configurations` may be used. `xfmrcode` is ignored for this component. +Special case of the Generic transformer, which is still a `transformer` object, but has a simplified method for its definition. These are transformers are asymmetric (A), lossless (L) and two-winding (2W). Asymmetric refers to the fact that the secondary is always has a `WYE` configuration, whilst the primary can be `DELTA`. The table below indicates alternate, more simple ways to specify the special case of an AL2W Transformer. `xsc` and `rw` cannot be specified for an AL2W transformer, because it is lossless. To use this definition format, all of `f_bus`, `t_bus`, `f_connections`, `t_connections`, and `configuration` must be used, and none of `buses`, `connections`, `configuration` may be used. `xfmrcode` is ignored for this component. | Name | Default | Type | Units | Used | Description | | --------------- | -------------------- | -------------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------- | @@ -259,7 +259,7 @@ Special case of the shunt capacitors, which is part of the `shunt` object, and e | Name | Default | Type | Units | Used | Description | | -------------- | ------- | ---------------- | ----- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `type` | | `Vector{String}` | | capc | Control type, default is `current` for controlled phase, `` for uncontrolled phase,`size=1`for`kvar`type, otherwise`size=(nphases)` | +| `type` | | `Vector{String}` | | capc | Control type, default is `current` for controlled phase, `` for uncontrolled phase,`size=1`for`kvar`type, otherwise`size=(nphases)` | | `element` | | `String` | | capc | `source_id` of element (typically line or transformer) to which CapControl is connected | | `terminal` | | `Vector{Int}` | | capc | Number of the terminal of circuit element to which CapControl is connected, default is `1` for controlled phase, `0` for uncontrolled phase, `size=1` for `kvar` type, otherwise `size=(nphases)` | | `onsetting` | | `Vector{Real}` | | capc | Value at which the CapControl switches the capacitor on, default is `300.0` for controlled phase, `0.0` for uncontrolled phase, `size=1` for `kvar` type, otherwise `size=(nphases)` | @@ -322,9 +322,9 @@ ZIP load models are split into `IMPEDANCE`, `CURRENT`, `POWER` models. - `(pd[i]/pd_nom) = pd_cz[i]*(v[i]/vm_nom)^2 + pd_ci[i]*(v[i]/vm_nom) + pd_cp[i]` - `(qd[i]/qd_nom) = qd_cz[i]*(v[i]/vm_nom)^2 + qd_ci[i]*(v[i]/vm_nom) + qd_cp[i]` -| Name | Default | Type | Units | Used | Description | -| -------- | ------- | ------ | ----- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `zipv` | | `Vector{Real}` | | `model==ZIP` | First 3 are ZIP weighting factors for active power (`pd_cz,pd_ci,pd_cp`), next 3 are ZIP weighting factors for reactive power (`qd_cz,qd_ci,qd_cp`), last 1 is cut-off voltage in p.u. of base kV; load is 0 below this cut-off | +| Name | Default | Type | Units | Used | Description | +| ------ | ------- | -------------- | ----- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `zipv` | | `Vector{Real}` | | `model==ZIP` | First 3 are ZIP weighting factors for active power (`pd_cz,pd_ci,pd_cp`), next 3 are ZIP weighting factors for reactive power (`qd_cz,qd_ci,qd_cp`), last 1 is cut-off voltage in p.u. of base kV; load is 0 below this cut-off | ### Generators (`generator`) @@ -400,7 +400,7 @@ A storage object is a flexible component that can represent a variety of energy | `sm_ub` | | `Real` | watt | opf | Power rating, | | `cm_ub` | | `Real` | amp | opf | Current rating, | | `charge_efficiency` | | `Real` | percent | always | charging efficiency (losses) | -| `discharge_efficiency` | | `Real` | percent | always | discharging efficiency (losses) | +| `discharge_efficiency` | | `Real` | percent | always | discharging efficiency (losses) | | `qs_ub` | | `Real` | | opf | Maximum reactive power injection, | | `qs_lb` | | `Real` | | opf | Minimum reactive power injection, | | `rs` | | `Real` | ohm | always | converter resistance | @@ -451,16 +451,16 @@ Linecodes are easy ways to specify properties common to multiple lines. Transformer codes are easy ways to specify properties common to multiple transformers -| Name | Default | Type | Units | Used | Description | -| ---------------- | -------------------------------------- | ---------------------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `configurations` | `fill(WYE, nwindings)` | `Vector{ConnConfig}` | | always | `WYE` or `DELTA`. List of configuration for each winding, `size=nwindings` | -| `xsc` | `[0.0]` | `Vector{Real}` | ohm | always | List of short-circuit reactances between each pair of windings; enter as a list of the upper-triangle elements, `size=(nwindings == 2 ? 1 : 3)` | -| `rw` | `zeros(nwindings)` | `Vector{Real}` | ohm | always | List of the winding resistance for each winding, `size=nwindings` | -| `tm_nom` | `ones(nwindings)` | `Vector{Real}` | | always | Nominal tap ratio for the transformer, `size=nwindings` (multiplier) | -| `tm_ub` | | `Vector{Vector{Real}}` | | opf | Maximum tap ratio for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | -| `tm_lb` | | `Vector{Vector{Real}}` | | opf | Minimum tap ratio for for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | -| `tm_set` | `fill(fill(1.0, nphases), nwindings)` | `Vector{Vector{Real}}` | | always | Set tap ratio for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | -| `tm_fix` | `fill(fill(true, nphases), nwindings)` | `Vector{Vector{Bool}}` | | always | Indicates for each winding and phase whether the tap ratio is fixed, `size=((nphases), nwindings)` | +| Name | Default | Type | Units | Used | Description | +| --------------- | -------------------------------------- | ---------------------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `configuration` | `fill(WYE, nwindings)` | `Vector{ConnConfig}` | | always | `WYE` or `DELTA`. List of configuration for each winding, `size=nwindings` | +| `xsc` | `[0.0]` | `Vector{Real}` | ohm | always | List of short-circuit reactances between each pair of windings; enter as a list of the upper-triangle elements, `size=(nwindings == 2 ? 1 : 3)` | +| `rw` | `zeros(nwindings)` | `Vector{Real}` | ohm | always | List of the winding resistance for each winding, `size=nwindings` | +| `tm_nom` | `ones(nwindings)` | `Vector{Real}` | | always | Nominal tap ratio for the transformer, `size=nwindings` (multiplier) | +| `tm_ub` | | `Vector{Vector{Real}}` | | opf | Maximum tap ratio for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | +| `tm_lb` | | `Vector{Vector{Real}}` | | opf | Minimum tap ratio for for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | +| `tm_set` | `fill(fill(1.0, nphases), nwindings)` | `Vector{Vector{Real}}` | | always | Set tap ratio for each winding and phase, `size=((nphases), nwindings)` (base=`tm_nom`) | +| `tm_fix` | `fill(fill(true, nphases), nwindings)` | `Vector{Vector{Bool}}` | | always | Indicates for each winding and phase whether the tap ratio is fixed, `size=((nphases), nwindings)` | ### Time Series (`time_series`) diff --git a/src/data_model/components.jl b/src/data_model/components.jl index 97fca9d86..971061a5b 100644 --- a/src/data_model/components.jl +++ b/src/data_model/components.jl @@ -455,7 +455,7 @@ end """ create_xfmrcode(; - configurations::Union{Vector{ConnConfig},Missing}=missing, + configuration::Union{Vector{ConnConfig},Missing}=missing, xsc::Union{Vector{<:Real},Missing}=missing, rw::Union{Vector{<:Real},Missing}=missing, tm_nom::Union{Vector{<:Real},Missing}=missing, @@ -469,7 +469,7 @@ end creates transformer code with some defaults """ function create_xfmrcode(; - configurations::Union{Vector{ConnConfig},Missing}=missing, + configuration::Union{Vector{ConnConfig},Missing}=missing, xsc::Union{Vector{<:Real},Missing}=missing, rw::Union{Vector{<:Real},Missing}=missing, tm_nom::Union{Vector{<:Real},Missing}=missing, @@ -481,7 +481,7 @@ function create_xfmrcode(; )::Dict{String,Any} n_windings = 0 - for v in [configurations, rw, tm_nom, tm_lb, tm_ub, tm_set, tm_fix] + for v in [configuration, rw, tm_nom, tm_lb, tm_ub, tm_set, tm_fix] if !ismissing(v) n_windings = length(v) break @@ -489,7 +489,7 @@ function create_xfmrcode(; end @assert n_windings >= 2 "Cannot determine valid number of windings" - @assert all(length(v) == n_windings for v in [configurations, rw, tm_nom, tm_lb, tm_ub, tm_set, tm_fix]) "Number of windings inconsistent between parameters" + @assert all(length(v) == n_windings for v in [configuration, rw, tm_nom, tm_lb, tm_ub, tm_set, tm_fix]) "Number of windings inconsistent between parameters" n_phases = 0 for v in [tm_lb, tm_ub, tm_set, tm_fix] @@ -502,7 +502,7 @@ function create_xfmrcode(; @assert n_phases >= 1 "Cannot determine valid number of phases" eng_obj = Dict{String,Any}( - "configurations" => !ismissing(configurations) ? configurations : fill(WYE, n_windings), + "configuration" => !ismissing(configuration) ? configuration : fill(WYE, n_windings), "xsc" => !ismissing(xsc) ? xsc : zeros(Int(n_windings * (n_windings-1)//2)), "rw" => !ismissing(rw) ? rw : zeros(n_windings), "tm_nom" => !ismissing(tm_nom) ? tm_nom : ones(n_windings), @@ -515,9 +515,9 @@ end """ create_transformer( - buses::Vector{String}, + bus::Vector{String}, connections::Vector{Vector{Int}}; - configurations::Union{Vector{ConnConfig},Missing}=missing, + configuration::Union{Vector{ConnConfig},Missing}=missing, xfmrcode::Union{String,Missing}=missing, xsc::Union{Vector{<:Real},Missing}=missing, rw::Union{Vector{<:Real},Missing}=missing, @@ -537,8 +537,8 @@ end creates a n-winding transformer object with some defaults """ -function create_transformer(buses::Vector{String}, connections::Vector{Vector{Int}}; - configurations::Union{Vector{ConnConfig},Missing}=missing, +function create_transformer(bus::Vector{String}, connections::Vector{Vector{Int}}; + configuration::Union{Vector{ConnConfig},Missing}=missing, xfmrcode::Union{String,Missing}=missing, xsc::Union{Vector{<:Real},Missing}=missing, rw::Union{Vector{<:Real},Missing}=missing, @@ -556,13 +556,13 @@ function create_transformer(buses::Vector{String}, connections::Vector{Vector{In kwargs... )::Dict{String,Any} - n_windings = length(buses) + n_windings = length(bus) n_conductors = length(connections[1]) transformer = Dict{String,Any}( - "buses" => buses, + "bus" => bus, "connections" => connections, - "configurations" => !ismissing(configurations) ? configurations : fill(WYE, n_windings), + "configuration" => !ismissing(configuration) ? configuration : fill(WYE, n_windings), "xsc" => !ismissing(xsc) ? xsc : zeros(Int(n_windings * (n_windings-1)//2)), "rw" => !ismissing(rw) ? rw : zeros(n_windings), "cmag" => imag,