Skip to content

Releases: dss-extensions/AltDSS-Python

AltDSS-Python v0.2.4

29 Mar 06:29
@PMeira PMeira
0.2.4
2b6fa7e
Compare
Choose a tag to compare
AltDSS-Python v0.2.4 Latest
Latest

Version 0.2.4 is being released to synchronize the engine across our Python packages. This version also includes a minor improvement:

  • altdss.Bus: the Bus collection now implements the in operator: "some_name" in altdss.Bus or 29 in altdss.Bus both work.

This package was born from the previous DSS.Obj API developed inside DSS-Python, but more recently extended with a lot of exclusive features.

❓What is AltDSS-Python?

AltDSS is a Python package that provides access to the DSS-Extensions engine, using DSS C-API and CFFI, providing a new, unique interface with many exclusive features. Some of these features target complementing the original/classic API (as seen in DSS-Python, OpenDSSDirect.py and the official OpenDSS COM implementation), more modern experience in Python, and other features target performance aspects.

The engine itself is a customized port of the Windows/Delphi code to Free Pascal, including several quality-of-life improvements for Python users. If you are new to DSS-Extensions, see our FAQ here, as well as general documentation in the main website.

AltDSS-Python can used together with DSS-Python and OpenDSSDirect.py, since they all share the same engine. And, since multiple DSS engines are supported, there are utility functions to map across the packages. AltDSS-Python, or just AltDSS in this context, uses a whole different paradigm from the older Python packages, moving away from the "Active..." paradigm. The new AltDSS includes integration to all OpenDSS object types (access, creation, manipulation, all directly in Python), exposed as Python objects, and also allows using batches of DSS objects to accelerate some operations that would be otherwise slow in Python, pushing many operations to the engine, ranging from collected results for multiple objects, to efficient use of DSS properties. For example, bulk updating (incrementing/decrementing/multiplying/etc.) an int or float property for thousands of elements doesn't require copying the data and is done directly in the engine, after the input data for the operation is prepared in Python.

Installation

The package is available on PyPI:

For a minimal install, use :

pip install altdss==0.2.3

To install all recommended packages:

pip install altdss[all]==0.2.3

Recent changes

Since this is the first public announcement on GitHub Releases, the full changelog is reproduced below.

Remember that changes in our alternative OpenDSS engine, currently known as AltDSS/DSS C-API, are always
relevant. See DSS C-API's repository for more information.

0.2.3

The engine was updated to AltDSS/DSS C-API 0.14.4 in order to implement some of changes below.

  • new and batch_new:
    • Added docstrings.
    • Adjust the engine implementation to check for existing elements to avoid accidentally creating elements with the same name (on user error).
    • The default for the begin_edit keyword argument tweaked so most users don't need to worry about it. See the docs for details.
  • New functions edit for objects and batches. These are shorthands for the whole (begin_edit, set properties, end_edit) dance.

0.2.2

This release includes a lot more tests, reaching 100% coverage of the Python code of several important modules, considering both the public and private tests. The engine was updated to AltDSS/DSS C-API 0.14.3 to include a couple of new features and fixes found during the tests.

  • SystemY: in AltDSS.SystemY, return the matrix as a SciPy sparse matrix directly.
  • BusBatch: Add missing Name function (the bus names were already exposed in the individual objects and at circuit level in AltDSS.BusNames).
  • Batch, creation function .batch(...):
    • Fix by list of indices (...batch(idx=[0,1,10])
    • Add some basic type checks
    • Add support for selecting items by float property (...batch(kW=0) or ...batch(kV=[0.0, 1.0]))
    • Add support for filtering multiple properties (...batch(Phases=2, kV=[0.0, 1.0])), and filtering existing batches.
  • CircuitElement/CircuitElementBatch: Complement doc strings; fix some type hints.
  • CircuitElementBatch:
    • Fix MaxCurrent. This will require the backend to be updated to v0.14.3.
    • Implement OCPDevice
  • NonUniformBatch: allow batch[idx] to get a single element by index.
  • Setters:
    • Allow using None to clear object references (e.g. altdss.Load[0].Daily = None)
    • Allow using list of live objects to fill a property that represents a DSS object.
  • ArrayProxy:
    • Fix BatchFloat64ArrayProxy.to_list(). It was returning an array instead a list.
    • Accepts lists for in-place sub, e.g. arrayProxy -= [1.1, 1.4] now works as expected.
    • Use new low-level operations for in-place operations with array values

0.2.1

  • Meter/Generator/etc.: Remove the previous workaround for issue with the AltDSS/DSS C-API headers related to RegisterValues -- now working without it. Add test.

0.2.0

Version incremented to 0.2.0 due to the number of changes in the function/property names. The engine is also updated to AltDSS/DSS C-API 0.14.2.

  • PDElement:

    • Fix ParentPDElement
    • Fix and update names:
      • pctNorm to pctNormal
      • pctEmerg to pctEmergency
    • Batch: add pctNormal and pctEmergency
    • Add/complement docstrings

  • Bus class:

    • Fix errors in ZSC0, ZSC1, Voltages
    • Batch: fix len(bus_batch)
    • Fix element batches (PCElements, PDElements)
    • Tweak tracking when buses are redefined but there are still live objects
    • Complement docstrings
    • Update names of several items:
      • Voc to VOC
      • Isc to ISC
      • YscMatrix to YSC
      • ZscMatrix to ZSC
      • Zsc012Matrix to ZSC012
      • Zsc0 to ZSC0
      • Zsc1 to ZSC1
      • ZscRefresh to ZSCRefresh

  • AltDSS (main class): adjust capitalization of a few items:

    • NodeVmagByPhase to NodeVMagByPhase
    • NodeVmagPUByPhase to NodeVMagPUByPhase
    • BusVmag to BusVMag
    • BusVmagPu to BusVMagPU

0.1.3

  • Meter/Generator/etc.: Add workaround for issue with the AltDSS/DSS C-API headers related to RegisterValues.
  • Monitor: fix issue with Channel returning the whole data instead of the channel data.

0.1.2

  • Fix SetterFlags: import from backend instead of defining a new enum here.

  • Batch:

    • Implement __slots__ to constrain the attributes and avoid accidental names.
    • EnergyMeter.Loads: make it a function to avoid issues with uninitialized meters (such as new meters).
    • Minor quality of life changes, such as returning zero instead of error for some empty batches.

  • Known issue: reading pctEmerg or pctNorm for uninitialized PDElements (missing solution for the circuit) will crash. This is already fixed in the engine and will be included in the next backend update.

0.1.1

  • Batch: fix setter for single object
  • Line: adjust Conductors to allow any conductor data object (WireData, CNData, TSData).
  • LineGeometry: rename "Wire" to "Conductors", follow the changes in Line.
  • Depend on DSS-Python 0.15.2 for the updated backend.
  • Add tests to ensure the following issues don't happen again:
    • Bus: Fix typo in puVMagAngle (rename it from puVmagAngle), and Voc.
    • Meters: Fix typo in call to DoReliabilityCalc
    • Circuit: Fix typo in NumCircuitElements
    • PCE: Found a function not implemented in the engine. Fixed there.

0.1.0

First version. Still depends on DSS-Python for the backend, but otherwise can be used for a lot of common operations by itself.

Highlights compared to the previous Obj API on DSS-Python:

  • The method find() (and __getitem__) now assume 0-based numeric indices. This is more appropriate to Python, e.g. altdss.Load[0] now returns the first load.
  • Besides the previous DSS property functions, new API methods to allow extracting data and manipulating objects through generalized versions of the classic (COM-like) API.
  • Introduce extra batch types for special classes
  • Introduce non-uniform batches
  • Introduce dynamic batches, avoiding redundant copies
  • Special handling of EnergyMeter and MeterSections
  • Object lifetime: implement synchronization of circuit state and pointers, invalidating dead pointer instead of crashing

0.0.1

Published to PyPI to reserve the name (now yanked to avoid issues).

Assets 2
Loading

AltDSS-Python v0.2.3

19 Mar 05:26
@PMeira PMeira
0.2.3
9e26270
Compare
Choose a tag to compare
AltDSS-Python v0.2.3

This is the first public announcement here on the GitHub Releases for the AltDSS-Python package.

We recommend users to check: https://dss-extensions.org/AltDSS-Python/

Although v0.1.0 was released on 2024-02-12, we held this announcement until now to allow this package to be tested more before recommending it. We've seen several releases since the first published package, and many features have been tested and improved. Special thanks to the team at Unicamp, Brazil, for providing feedback and bug reports on the earlier releases.

This package was born from the previous DSS.Obj API developed inside DSS-Python, but more recently extended with a lot of exclusive features.

❓What is AltDSS-Python?

AltDSS is a Python package that provides access to the DSS-Extensions engine, using DSS C-API and CFFI, providing a new, unique interface with many exclusive features. Some of these features target complementing the original/classic API (as seen in DSS-Python, OpenDSSDirect.py and the official OpenDSS COM implementation), more modern experience in Python, and other features target performance aspects.

The engine itself is a customized port of the Windows/Delphi code to Free Pascal, including several quality-of-life improvements for Python users. If you are new to DSS-Extensions, see our FAQ here, as well as general documentation in the main website.

AltDSS-Python can used together with DSS-Python and OpenDSSDirect.py, since they all share the same engine. And, since multiple DSS engines are supported, there are utility functions to map across the packages. AltDSS-Python, or just AltDSS in this context, uses a whole different paradigm from the older Python packages, moving away from the "Active..." paradigm. The new AltDSS includes integration to all OpenDSS object types (access, creation, manipulation, all directly in Python), exposed as Python objects, and also allows using batches of DSS objects to accelerate some operations that would be otherwise slow in Python, pushing many operations to the engine, ranging from collected results for multiple objects, to efficient use of DSS properties. For example, bulk updating (incrementing/decrementing/multiplying/etc.) an int or float property for thousands of elements doesn't require copying the data and is done directly in the engine, after the input data for the operation is prepared in Python.

Installation

The package is available on PyPI:

For a minimal install, use :

pip install altdss==0.2.3

To install all recommended packages:

pip install altdss[all]==0.2.3

Recent changes

Since this is the first public announcement on GitHub Releases, the full changelog is reproduced below.

Remember that changes in our alternative OpenDSS engine, currently known as AltDSS/DSS C-API, are always
relevant. See DSS C-API's repository for more information.

0.2.3

The engine was updated to AltDSS/DSS C-API 0.14.4 in order to implement some of changes below.

  • new and batch_new:
    • Added docstrings.
    • Adjust the engine implementation to check for existing elements to avoid accidentally creating elements with the same name (on user error).
    • The default for the begin_edit keyword argument tweaked so most users don't need to worry about it. See the docs for details.
  • New functions edit for objects and batches. These are shorthands for the whole (begin_edit, set properties, end_edit) dance.

0.2.2

This release includes a lot more tests, reaching 100% coverage of the Python code of several important modules, considering both the public and private tests. The engine was updated to AltDSS/DSS C-API 0.14.3 to include a couple of new features and fixes found during the tests.

  • SystemY: in AltDSS.SystemY, return the matrix as a SciPy sparse matrix directly.
  • BusBatch: Add missing Name function (the bus names were already exposed in the individual objects and at circuit level in AltDSS.BusNames).
  • Batch, creation function .batch(...):
    • Fix by list of indices (...batch(idx=[0,1,10])
    • Add some basic type checks
    • Add support for selecting items by float property (...batch(kW=0) or ...batch(kV=[0.0, 1.0]))
    • Add support for filtering multiple properties (...batch(Phases=2, kV=[0.0, 1.0])), and filtering existing batches.
  • CircuitElement/CircuitElementBatch: Complement doc strings; fix some type hints.
  • CircuitElementBatch:
    • Fix MaxCurrent. This will require the backend to be updated to v0.14.3.
    • Implement OCPDevice
  • NonUniformBatch: allow batch[idx] to get a single element by index.
  • Setters:
    • Allow using None to clear object references (e.g. altdss.Load[0].Daily = None)
    • Allow using list of live objects to fill a property that represents a DSS object.
  • ArrayProxy:
    • Fix BatchFloat64ArrayProxy.to_list(). It was returning an array instead a list.
    • Accepts lists for in-place sub, e.g. arrayProxy -= [1.1, 1.4] now works as expected.
    • Use new low-level operations for in-place operations with array values

0.2.1

  • Meter/Generator/etc.: Remove the previous workaround for issue with the AltDSS/DSS C-API headers related to RegisterValues -- now working without it. Add test.

0.2.0

Version incremented to 0.2.0 due to the number of changes in the function/property names. The engine is also updated to AltDSS/DSS C-API 0.14.2.

  • PDElement:

    • Fix ParentPDElement
    • Fix and update names:
      • pctNorm to pctNormal
      • pctEmerg to pctEmergency
    • Batch: add pctNormal and pctEmergency
    • Add/complement docstrings

  • Bus class:

    • Fix errors in ZSC0, ZSC1, Voltages
    • Batch: fix len(bus_batch)
    • Fix element batches (PCElements, PDElements)
    • Tweak tracking when buses are redefined but there are still live objects
    • Complement docstrings
    • Update names of several items:
      • Voc to VOC
      • Isc to ISC
      • YscMatrix to YSC
      • ZscMatrix to ZSC
      • Zsc012Matrix to ZSC012
      • Zsc0 to ZSC0
      • Zsc1 to ZSC1
      • ZscRefresh to ZSCRefresh

  • AltDSS (main class): adjust capitalization of a few items:

    • NodeVmagByPhase to NodeVMagByPhase
    • NodeVmagPUByPhase to NodeVMagPUByPhase
    • BusVmag to BusVMag
    • BusVmagPu to BusVMagPU

0.1.3

  • Meter/Generator/etc.: Add workaround for issue with the AltDSS/DSS C-API headers related to RegisterValues.
  • Monitor: fix issue with Channel returning the whole data instead of the channel data.

0.1.2

  • Fix SetterFlags: import from backend instead of defining a new enum here.

  • Batch:

    • Implement __slots__ to constrain the attributes and avoid accidental names.
    • EnergyMeter.Loads: make it a function to avoid issues with uninitialized meters (such as new meters).
    • Minor quality of life changes, such as returning zero instead of error for some empty batches.

  • Known issue: reading pctEmerg or pctNorm for uninitialized PDElements (missing solution for the circuit) will crash. This is already fixed in the engine and will be included in the next backend update.

0.1.1

  • Batch: fix setter for single object
  • Line: adjust Conductors to allow any conductor data object (WireData, CNData, TSData).
  • LineGeometry: rename "Wire" to "Conductors", follow the changes in Line.
  • Depend on DSS-Python 0.15.2 for the updated backend.
  • Add tests to ensure the following issues don't happen again:
    • Bus: Fix typo in puVMagAngle (rename it from puVmagAngle), and Voc.
    • Meters: Fix typo in call to DoReliabilityCalc
    • Circuit: Fix typo in NumCircuitElements
    • PCE: Found a function not implemented in the engine. Fixed there.

0.1.0

First version. Still depends on DSS-Python for the backend, but otherwise can be used for a lot of common operations by itself.

Highlights compared to the previous Obj API on DSS-Python:

  • The method find() (and __getitem__) now assume 0-based numeric indices. This is more appropriate to Python, e.g. altdss.Load[0] now returns the first load.
  • Besides the previous DSS property functions, new API methods to allow extracting data and manipulating objects through generalized versions of the classic (COM-like) API.
  • Introduce extra batch types for special classes
  • Introduce non-uniform batches
  • Introduce dynamic batches, avoiding redundant copies
  • Special handling of EnergyMeter and MeterSections
  • Object lifetime: implement synchronization of circuit state and pointers, invalidating dead pointer instead of crashing

0.0.1

Published to PyPI to reserve the name (now yanked to avoid issues).

Assets 2
Loading