parsing error of transformer xhl vs x12 parameters in circuit.ToJSON()

[John-Boik]

I'm not sure if this is the right repository to report this problem, but it looks like the circuit.ToJSON function of OpenDSSDirect will ignore transformer parameters xhl, xht, and xlt, thus setting these parameters to their default values. But it will recognize the alternative versions of the parameters, x12, x13, and x23.

An example DSS file comes from the test sets of PowerModelsDistribtion, given below. Saving this as a file and using the script below to generate a JSON object, the object has default values for xhl, xht, and xlt of transformer [1], rather than zeros. Changing the DSS file to use x12=0, x13=0, and x23=0 instead results in a JSON object with the correct (zero) values.

Julia Script, where the DSS file is saved as filename.dss:

import OpenDSSDirect as DSS
DSS.Basic.AllowEditor(false)
DSS.dss("""
    clear
    redirect "filename.dss"
    """)
ckt = DSS.Circuit.ToJSON(Int32(1)|Int32(4)|Int32(32)|Int32(64)|Int32(128)|Int32(512))
println("xlt= ", ckt["transformer"][1]["xlt"])  # should be 0.0

DSS script:

clear

! Base Frequency
Set DefaultBaseFrequency=50

! New Circuit
New circuit.ut_trans
~ BasekV=11 BaseMVA=0.1 pu=1.0  ISC3=9999999999 ISC1=9999999999

! Transformers
New Transformer.TX1 windings=3 phases=3 Buses=[1 2 3]
~ Conns=[Delta Wye Wye]
~ kVs=[11 4 0.4]
~ kVAs=[500 500 500]
~ %Rs=[0 0 0]
~ xhl=0 xht=0 xlt=0
~ %noloadloss=0
~ %imag=0
~ leadlag=lead

! Transmission Lines
New Line.LINE1 Bus1=SourceBus Bus2=1 phases=3 X1=3 R1=6

! Loads
New Load.LOAD1 Phases=1 Bus1=2.1 kV=2.30 kW=43 kvar=76 vminpu=0.8 vmaxpu=1.2
New Load.LOAD2 Phases=1 Bus1=2.2 kV=2.30 kW=52 kvar=85 vminpu=0.8 vmaxpu=1.2
New Load.LOAD3 Phases=1 Bus1=2.3 kV=2.30 kW=61 kvar=94 vminpu=0.8 vmaxpu=1.2
New Load.LOAD4 Phases=1 Bus1=3.1 kV=0.23 kW=74 kvar=41 vminpu=0.8 vmaxpu=1.2
New Load.LOAD5 Phases=1 Bus1=3.2 kV=0.23 kW=85 kvar=52 vminpu=0.8 vmaxpu=1.2
New Load.LOAD6 Phases=1 Bus1=3.3 kV=0.23 kW=96 kvar=63 vminpu=0.8 vmaxpu=1.2
New Load.LOAD7 Phases=1 Bus1=1.3 kV=6.351 kW=205 kvar=185 vminpu=0.8 vmaxpu=1.2

! Set Voltage Bases
Set voltagebases=[11  4 0.4]
Calcvoltagebases

! Solve network
solve

[John-Boik]

It looks like the problem is a bit worse. It appears that circuit.ToJSON() ignores both xhl and x12 in DSS files for transformers, and instead uses the default value of 700.

Also, the same problem appears in OpenDSSDirect.py and dss_python versions. And the problem is not in the ToJSON function itself, as inspection of the OpenDSSDirect transformer (e.g., DSS.Transformers.Xhl()) shows the problem too.

[PMeira]

Looks like you found a corner-case bug, but it's the other way around -- X23 and X13 should have replaced the zero with the default/replacement values. That isn't happening due to a missing flag, should be fixed in the next release (in a few days).

An example DSS file comes from the test sets of PowerModelsDistribtion

Zero should not be allowed for X12, X23 and X13 (XHL, XLT and XHT are synonyms). If zero is provided, it's should be replaced by a default value. Non-zero values seem to be working as expected. If PMD is generating 0 for those, it's invalid data.

On the OpenDSS GUI, it will give a warning popup about the zero value, but still replace the value. When running through the official COM DLL with AllowForms=false (the typical scenario for automation with the official OpenDSS), users don't see the warning and the behavior matches what happens here on DSS-Extensions.

Nowadays, on DSS-Extensions, it might be a better idea to adjust that to generate a proper error when 0 is used as input, adding a compatibility flag to restore the current/legacy behavior. Same idea for read-only properties (OpenDSS silently ignores writing to those). I'll make changes according to this.

Redundant properties/fields (search for "redundant" in https://dss-extensions.org/dss-format/Transformer.html ) such as synonyms are omitted from the JSON output, so XHL shouldn't appear, only X12. We chose to use X12 and mark XHL as redundant given that XHL is context-specific and the concept of H(igh) and L(ow) voltage windings don't always match with the actual voltages and can be confusing to new users.

Also note that (X12, X13, X23) is somewhat redundant with XSCArray (but actually this one is more general). Looking into the original issue, I noticed that XSCArray doesn't handle the replacement values in case of zeros, so I'll just add an extra constraint to this to ensure non-zero values and error out otherwise. It might be a good idea to keep only XSCArray down the line in the JSON output (and maybe rename it to just XSC), but I won't change that now since there might be a better way to handle this.

Also, the same problem appears in OpenDSSDirect.py and dss_python versions.

Yeah, all projects here share the same engine, it wouldn't make sense to group these in the same GitHub org and have them behave differently. The general behavior should be very close across all programming languages we support. There will be an option to use the official engine in the next release of DSS C-API, but it will be quite limited -- none of our extended functionality at engine level, and initially only supporting Windows since it's supported by EPRI at the moment.