OpenDSSDirect.py v0.5.0
OpenDSSDirect.py version 0.5.0 upgrades to DSS_Python 0.10.6. The version was bumped to v0.5.0 to reflect changes with the default behavior.
With this set of releases from the DSS Extensions project, most API calls are checked, avoiding surprising/confusing messages when the errors are not handled immediately. In OpenDSSDirect.py, the error messages provided in the OpenDSS Error interface are automatically mapped to Python exceptions and should now provide a better context for the errors.
Two new important compatibility settings are introduced:
opendssdirect.Error.ExtendedErrors
(defaults to enabled state): this new mechanism provides more error messages from the validation checks at the API level. You can disable the new messages, falling back to the previous behavior, usingopendssdirect.Error.ExtendedErrors(False)
.opendssdirect.Basic.LegacyModels
(defaults to disabled state): in OpenDSS v9.0, the old PVSystem, Storage, ... models were deprecated and removed from the official release. In ODD.py, you can toggle the old models usingopendssdirect.Basic.LegacyModels(True)
. The current/new models, previously known as PVSystem2, Storage2, ... have been validated with the official tests and enabled by default.
OpenDSSDirect.py can be installed using pip. For more: http://dss-extensions.org/OpenDSSDirect.py/notebooks/Installation.html
As OpenDSSDirect.py accumulates changes from DSS_Python (all ported to OpenDSSDirect.py), DSS C-API and the official OpenDSS, read below for other important changes including bug-fixes.
Changes from DSS_Python 0.10.6
DSS_Python is the project that focuses on providing an interface, at Python level, that can be used as a drop-in replacement for the official OpenDSS COM interface. Users can combine both OpenDSSDirect.py and DSS_Python in the same application, sharing the same OpenDSS engine.
- Updated to DSS C-API 0.10.6, which includes most changes up to OpenDSS v9.0.0.3.
- Debug builds of DSS C-API are now included. See the Debugging document.
- New
DSS.LegacyModels
: allow using the legacy/deprecated models forPVsystem
,Storage
,InvControl
, andStorageController
. - New
DSS.Error.ExtendedErrors
: controls if the new extended error messages are used. - Many new properties and functions in
DSS.ActiveCircuit.PDElements
. - Now most of the low-level API calls are checked, mapping the errors from the
DSS.Error
interface to Python exceptions more frequently.
Changes from DSS C-API 0.10.6
DSS C-API is the low-level, extended OpenDSS library used in the DSS Extensions project. It provides a plain C interface, easily used by many programming languages.
- This version should be fully API compatible with 0.10.3+. The behavior of some functions changed with the new extensions. Especially, empty strings are explicitly return as nulls instead of "\0". This conforms to the behavior already seen in arrays of strings.
- The binary releases now use Free Pascal 3.2.0. We observed the solution process is around 6% faster, and results are even closer to the official OpenDSS.
- The releases now include both the optimized/default binary and a non-optimized/debug version. See the Debugging document for more.
- Extended API validation and Extended Errors mechanism:
- The whole API was reviewed to add basic checks for active circuit and element access.
- By default, invalid accesses now result in errors reported through the Error interface. This can be disabled to achieve the previous behavior, more compatible with the official COM implementation -- that is, ignore the error, just return a default/invalid value and assume the user has handled it.
- The mechanism can be toggled by API functions
DSS_Set_ExtendedErrors
andDSS_Get_ExtendedErrors
, or environment variableDSS_CAPI_EXTENDED_ERRORS=0
to disable (defaults to enabled state).
- New Legacy Models mechanism:
- OpenDSS 9.0+ dropped the old
PVsystem
,Storage
,InvControl
, andStorageController
models, replacing with the new versions previously known asPVsystem2
,Storage2
,InvControl2
andStorageController2
. - The behavior and parameters from the new models are different -- they are better, more complete and versatile models. Check the official OpenDSS docs and examples for further information.
- The implementation of the new models in DSS C-API was validated successfully with all test cases available. As such, we mirror the decision to make them the default models.
- As an extension, we implemented the Legacy Models option. By toggling it, a
clear
command will be issued and the alternative models will be loaded. This should allow users to migrate to the new version but, if something that used to work with the old models stopped working somehow, the user can toggle the old models. The idea is to keep reproducibility of results while we keep updating the engine and the API. - Since EPRI dropped/deprecated the old models, we might drop them too, in a future release. Please open an issue on GitHub or send a message if those old models are important to you.
- The mechanism can be controlled by API functions
DSS_Set_LegacyModels
andDSS_Get_LegacyModels
, or environment variableDSS_CAPI_LEGACY_MODELS=1
to enable (defaults to disabled state).
- OpenDSS 9.0+ dropped the old
- WireData API: expose the
CapRadius
property as a new pair of functions. - PDElements API: extended with many batch functions exposing equivalents to some CSV reports:
AllNames
,AllMaxCurrents
,AllPctNorm
,AllPctEmerg
,AllCurrents
,AllCurrentsMagAng
,AllCplxSeqCurrents
,AllSeqCurrents
,AllPowers
,AllSeqPowers
,AllNumPhases
,AllNumConductors
,AllNumTerminals
. CktElement_Get_SeqPowers
: fix issue for positive sequence circuits (wrong results could corrupt memory).- Many API functions were optimized to avoid unnecessary allocations and copies.
- Some bugs found in DSS C-API and also reported upstream (already fixed in SVN):
CapRadius
DSS property: if the radius was initialized usingGMRac
,CapRadius
was left uninitialized, resulting in invalid/NaN values.Sensors
API: some functions edited capacitors instead of sensors.
- Updated to the official OpenDSS revision 2903, corresponding to versions 9.0.0+. Changes include:
- ExportCIMXML: updated.
- Relay: Fix in
GetPropertyValue
. - Line: In
DumpProperties
andMakePosSequence
, the length is handled differently for lines withLineGeometry
orLineSpacing
. - Bus API: new
LineList
,LoadList
functions. - Lines API: SeasonRating now returns NormAmps if there's no SeasonSignal.
- New command DSS
Zsc012
: "Returns symmetrical component short circuit impedances Z0, Z1, and Z2 for the ACTIVE 3-PHASE BUS. Determined from Zsc matrix." PVsystem2
,Storage2
,InvControl2
,StorageController2
updated and renamed.