altdss

Name	altdss JSON
Version	0.2.4 JSON
	download
home_page	None
Summary	Modern, detailed Python interface/bindings and tools based on the AltDSS/DSS C-API project, the alternative OpenDSS implementation from DSS-Extensions.org. Tries to expose all OpenDSS objects, bulk operations and many details which previously required using the Text interface, or just weren't available.
upload_time	2024-03-29 05:48:09
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	BSD 3-Clause License Copyright (c) 2017-2024, Paulo Meira Copyright (c) 2017-2024, AltDSS-Python contributors All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
keywords	altdss electric power systems opendss opendssdirect powerflow short-circuit
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

# AltDSS-Python

*Modern Python bindings for an alternative implementation of EPRI's OpenDSS*

[![PyPI](https://img.shields.io/pypi/v/altdss)](https://pypi.org/project/altdss/) <img alt="Supports Linux" src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black"> <img alt="Supports macOS" src="https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white"> <img alt="Supports Microsoft Windows" src="https://img.shields.io/badge/Windows-0078D6?logo=windows&logoColor=white">

AltDSS-Python, or just `altdss` when used from Python, builds on the DSS-Python backend infrastructure and experience shared in both DSS-Python and OpenDSSDirect.py to cover many aspects that the classic OpenDSS APIs (DSS-Python, OpenDSSDirect.py, official OpenDSS COM implementation, and anything based on the DCSL/OpenDSSDirect.DLL) cannot achieve comfortably or with good performance. Many features are only possible due to our alternative engine (AltDSS), used through the [AltDSS/DSS C-API](https://github.com/dss-extensions/dss_capi) library.

This package is available for Windows, Linux and macOS, including Intel and ARM processes, both 32 and 64-bit. As such, it enables OpenDSS to run in many environments the official implementation cannot, from a Raspberry Pi to a HPC cluster, and cloud environments like Google Colab (some of our notebooks examples are ready-to-run on Colab).

AltDSS-Python is part of DSS-Extensions, a larger effort to port the original OpenDSS to support more platforms (OSs, processor architectures), programming languages, and extend both the OpenDSS engine and API, represented in the AltDSS engine:

For alternatives for other programming languages, including in MATLAB, C++, C#/.NET, Rust and Go, please check [https://dss-extensions.org/](https://dss-extensions.org/) and our hub repository at [dss-extensions/dss-extensions](https://github.com/dss-extensions/dss-extensions) for more documentation, discussions and the [FAQ](https://github.com/dss-extensions/dss-extensions#faq).

```mermaid
flowchart TD
C["AltDSS engine/DSS C-API\n(libdss_capi)"] --> P["DSS-Python: Backend"]
P --- DSSPY["DSS-Python\n(dss package)"]
P --- ODDPY["OpenDSSDirect.py\n(opendssdirect package)"]
P --- ALTDSSPY["AltDSS-Python\n(altdss package)"]
```

</center>

AltDSS-Python is one of three Python projects under DSS-Extensions. See [DSS-Extensions — OpenDSS: Overview of Python APIs](https://dss-extensions.org/python_apis.html) for a brief comparison between these and the official COM API. Both OpenDSSDirect.py and DSS-Python expose the classic OpenDSS API (closer to the COM implementation). AltDSS-Python, on the other hand, exposes all OpenDSS objects, batch operations, and a more intuitive API. If required, users can mix all three packages in the same project to access some of their unique features, or just to avoid changing legacy/stable code.

Since the base code is shared, other features from [DSS-Python such as plotting](https://dss-extensions.org/DSS-Python/examples/Plotting.html) can be used here. Other examples from DSS-Python or OpenDSSDirect.py can be adapted quite easily too.

## What is AltDSS?

To avoid confusion between the official OpenDSS provided by EPRI and the alternative, unofficial implementation provided by the DSS-Extensions group of projects, our implementation of the OpenDSS engine, exposed as a software library (e.g. DLL or shared object), will be slowly renamed to AltDSS engine. The classic parts of our DSS C-API is still in place and will remain for usage in DSS-Python and OpenDSSDirect.py.

The "Alt" prefix tries to encompass a few aspects:
- An alternative implementation
- A new approach for the API
- A more searchable name (just "DSS" is too generic nowadays), and easier to cite.

What didn't change:
- It's the same engine that's been developed since 2018 on DSS-Extensions.
- Our cross-validation with the official OpenDSS implementation continues.
- If you have used DSS C-API, DSS-Python, DSS MATLAB, DSS Sharp, OpenDSSDirect.jl or OpenDSSDirect.py since 2018 or 2019 (depending on the package), you were already using "AltDSS".

If you somehow need compatibility with the official OpenDSS COM implementation at API level, prefer to stay with the classic API implementations such DSS-Python and OpenDSSDirect.py, and avoid anything marked as "API Extension".

## What is AltDSS-Python?

AltDSS-Python is a new Python package that goes along with DSS-Python and OpenDSSDirect.py to provide a further Pythonic experience.

This new package uses many unique aspects of our alternative implementation of the engine and of the API to expose all types of DSS objects currently implemented in AltDSS.

When referring to Python, we will call AltDSS-Python just AltDSS, for short. The same will happen for other future language bindings based on the same concepts.

Notable features are:
- **All DSS objects** implemented in our implementation of the OpenDSS engine are exposed.
- Avoids the active element idiom. Users can interact with multiple objects without requiring to activate them.
- The original separate APIs for general circuit elements, PC elements, PD elements and others are encapsulated together with the access to the DSS properties in a single context. We hope to achieve a better autocomplete experience in IDEs and easier discoverability of the available functions. For example, a [`Line` object](https://dss-extensions.org/AltDSS-Python/apidocs/altdss/altdss.Line.html#altdss.Line.Line) contains all the DSS properties the the Line object (as Python properties), plus inherited methods/properties from common DSS objects, Circuit element objects, and PD element objects.
- Due to duplication, the access to the DSS properties replace many of the old COM-style properties. The names of the properties in Python that reflect the DSS properties are kept as close as possible. A few exceptions are names like `%Rs` (which is an invalid identifier in Python) that is exposed as `pctRs`. We hope that reusing the same names will reduce the cognitive load for the users and provide an easier transition between API and GUI (e.g. the main official OpenDSS GUI) usage. That is, a .DSS script is now closer to an AltDSS Python script and users shouldn't be required to learn two completely different conventions.
- More native types, including more extensive usage of Python enumerations and complex numbers.
- Batches! Manipulate batches of uniform objects (including DSS properties and general functions) or non-uniform collections of objects (general functions only, at the moment), with lower overhead.
- New dedicated EnergyMeter classes, including direct `MeterSection` inspection.

Note that the general interaction through .DSS scripts is unchanged and users can use AltDSS-Python together with DSS-Python or OpenDSSDirect.py since the engine is shared. That is, although it would be recommended to fully use AltDSS-Python when a v1.0 is done, there is no rush to migrate. Users can enjoy some of the new features piecewise, like batches or the APIs for all DSS object types not exposed in the classic APIs.

## Why a new package?

Besides the naming issue, although both DSS-Python and OpenDSSDirect.py acquired features since 2018, when DSS-Extensions was born, adding a lot of the features from AltDSS would break compatibility in a major way. Initially, more Pythonic and extra features were expected to land on OpenDSSDirect.py. Looking into the list of publications and public repositories using both packages suggests that breaking the API to introduce features is not advisable.

Moreover, many users still see OpenDSSDirect.py and think that it uses OpenDSSDirect.DLL. That is not the case, and even when it was (before August 2018), the Linux and macOS builds of OpenDSS were not supported by EPRI, the original OpenDSS developer. Effectively, OpenDSSDirect.py (OpenDSSDirect.jl is in a similar situation) never used an official binary on non-Windows platforms.

That said, we hope both new and experienced OpenDSS users find it easy to adopt it.

## Documentation

Visit https://dss-extensions.org/AltDSS-Python/

Especially useful for a quick overview: https://dss-extensions.org/AltDSS-Python/examples/GettingStarted.html

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "altdss",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "Paulo Meira <pmeira@ieee.org>",
    "keywords": "altdss, electric power systems, opendss, opendssdirect, powerflow, short-circuit",
    "author": null,
    "author_email": "Paulo Meira <pmeira@ieee.org>, Dheepak Krishnamurthy <me@kdheepak.com>",
    "download_url": "https://files.pythonhosted.org/packages/73/8e/4e9e75dbafdb9001e7bcce98190ad816bc838af7e982e00d1ce091a3c8d1/altdss-0.2.4.tar.gz",
    "platform": null,
    "description": "# AltDSS-Python\n\n*Modern Python bindings for an alternative implementation of EPRI's OpenDSS*\n\n[![PyPI](https://img.shields.io/pypi/v/altdss)](https://pypi.org/project/altdss/) <img alt=\"Supports Linux\" src=\"https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black\"> <img alt=\"Supports macOS\" src=\"https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white\"> <img alt=\"Supports Microsoft Windows\" src=\"https://img.shields.io/badge/Windows-0078D6?logo=windows&logoColor=white\">\n\nAltDSS-Python, or just `altdss` when used from Python, builds on the DSS-Python backend infrastructure and experience shared in both DSS-Python and OpenDSSDirect.py to cover many aspects that the classic OpenDSS APIs (DSS-Python, OpenDSSDirect.py, official OpenDSS COM implementation, and anything based on the DCSL/OpenDSSDirect.DLL) cannot achieve comfortably or with good performance. Many features are only possible due to our alternative engine (AltDSS), used through the [AltDSS/DSS C-API](https://github.com/dss-extensions/dss_capi) library. \n\nThis package is available for Windows, Linux and macOS, including Intel and ARM processes, both 32 and 64-bit. As such, it enables OpenDSS to run in many environments the official implementation cannot, from a Raspberry Pi to a HPC cluster, and cloud environments like Google Colab (some of our notebooks examples are ready-to-run on Colab).\n\nAltDSS-Python is part of DSS-Extensions, a larger effort to port the original OpenDSS to support more platforms (OSs, processor architectures), programming languages, and extend both the OpenDSS engine and API, represented in the AltDSS engine:\n\n<p align=\"center\">\n    <img alt=\"Overview of related projects\" src=\"https://github.com/dss-extensions/dss-extensions/blob/main/images/repomap.png?raw=true\">\n</p>\n\nFor alternatives for other programming languages, including in MATLAB, C++, C#/.NET, Rust and Go, please check [https://dss-extensions.org/](https://dss-extensions.org/) and our hub repository at [dss-extensions/dss-extensions](https://github.com/dss-extensions/dss-extensions) for more documentation, discussions and the [FAQ](https://github.com/dss-extensions/dss-extensions#faq).\n\n<center>\n\n```mermaid\nflowchart TD\n    C[\"AltDSS engine/DSS C-API\\n(libdss_capi)\"] --> P[\"DSS-Python: Backend\"]\n    P --- DSSPY[\"DSS-Python\\n(dss package)\"]\n    P --- ODDPY[\"OpenDSSDirect.py\\n(opendssdirect package)\"]\n    P --- ALTDSSPY[\"AltDSS-Python\\n(altdss package)\"]\n```\n\n</center>\n\nAltDSS-Python is one of three Python projects under DSS-Extensions. See [DSS-Extensions \u2014 OpenDSS: Overview of Python APIs](https://dss-extensions.org/python_apis.html) for a brief comparison between these and the official COM API. Both OpenDSSDirect.py and DSS-Python expose the classic OpenDSS API (closer to the COM implementation). AltDSS-Python, on the other hand, exposes all OpenDSS objects, batch operations, and a more intuitive API. If required, users can mix all three packages in the same project to access some of their unique features, or just to avoid changing legacy/stable code.\n\nSince the base code is shared, other features from [DSS-Python such as plotting](https://dss-extensions.org/DSS-Python/examples/Plotting.html) can be used here. Other examples from DSS-Python or OpenDSSDirect.py can be adapted quite easily too.\n\n## What is AltDSS?\n\nTo avoid confusion between the official OpenDSS provided by EPRI and the alternative, unofficial implementation provided by the DSS-Extensions group of projects, our implementation of the OpenDSS engine, exposed as a software library (e.g. DLL or shared object), will be slowly renamed to AltDSS engine. The classic parts of our DSS C-API is still in place and will remain for usage in DSS-Python and OpenDSSDirect.py.\n\nThe \"Alt\" prefix tries to encompass a few aspects:\n- An alternative implementation\n- A new approach for the API\n- A more searchable name (just \"DSS\" is too generic nowadays), and easier to cite.\n\nWhat didn't change:\n- It's the same engine that's been developed since 2018 on DSS-Extensions.\n- Our cross-validation with the official OpenDSS implementation continues.\n- If you have used DSS C-API, DSS-Python, DSS MATLAB, DSS Sharp, OpenDSSDirect.jl or OpenDSSDirect.py since 2018 or 2019 (depending on the package), you were already using \"AltDSS\".\n\nIf you somehow need compatibility with the official OpenDSS COM implementation at API level, prefer to stay with the classic API implementations such DSS-Python and OpenDSSDirect.py, and avoid anything marked as \"API Extension\".\n\n## What is AltDSS-Python?\n\nAltDSS-Python is a new Python package that goes along with DSS-Python and OpenDSSDirect.py to provide a further Pythonic experience.\n\nThis new package uses many unique aspects of our alternative implementation of the engine and of the API to expose all types of DSS objects currently implemented in AltDSS.\n\nWhen referring to Python, we will call AltDSS-Python just AltDSS, for short. The same will happen for other future language bindings based on the same concepts.\n\nNotable features are:\n- **All DSS objects** implemented in our implementation of the OpenDSS engine are exposed.\n- Avoids the active element idiom. Users can interact with multiple objects without requiring to activate them.\n- The original separate APIs for general circuit elements, PC elements, PD elements and others are encapsulated together with the access to the DSS properties in a single context. We hope to achieve a better autocomplete experience in IDEs and easier discoverability of the available functions. For example, a [`Line` object](https://dss-extensions.org/AltDSS-Python/apidocs/altdss/altdss.Line.html#altdss.Line.Line) contains all the DSS properties the the Line object (as Python properties), plus inherited methods/properties from common DSS objects, Circuit element objects, and PD element objects.\n- Due to duplication, the access to the DSS properties replace many of the old COM-style properties. The names of the properties in Python that reflect the DSS properties are kept as close as possible. A few exceptions are names like `%Rs` (which is an invalid identifier in Python) that is exposed as `pctRs`. We hope that reusing the same names will reduce the cognitive load for the users and provide an easier transition between API and GUI (e.g. the main official OpenDSS GUI) usage. That is, a .DSS script is now closer to an AltDSS Python script and users shouldn't be required to learn two completely different conventions.\n- More native types, including more extensive usage of Python enumerations and complex numbers.\n- Batches! Manipulate batches of uniform objects (including DSS properties and general functions) or non-uniform collections of objects (general functions only, at the moment), with lower overhead.\n- New dedicated EnergyMeter classes, including direct `MeterSection` inspection.\n\nNote that the general interaction through .DSS scripts is unchanged and users can use AltDSS-Python together with DSS-Python or OpenDSSDirect.py since the engine is shared. That is, although it would be recommended to fully use AltDSS-Python when a v1.0 is done, there is no rush to migrate. Users can enjoy some of the new features piecewise, like batches or the APIs for all DSS object types not exposed in the classic APIs.\n\n## Why a new package?\n\nBesides the naming issue, although both DSS-Python and OpenDSSDirect.py acquired features since 2018, when DSS-Extensions was born, adding a lot of the features from AltDSS would break compatibility in a major way. Initially, more Pythonic and extra features were expected to land on OpenDSSDirect.py. Looking into the list of publications and public repositories using both packages suggests that breaking the API to introduce features is not advisable.\n\nMoreover, many users still see OpenDSSDirect.py and think that it uses OpenDSSDirect.DLL. That is not the case, and even when it was (before August 2018), the Linux and macOS builds of OpenDSS were not supported by EPRI, the original OpenDSS developer. Effectively, OpenDSSDirect.py (OpenDSSDirect.jl is in a similar situation) never used an official binary on non-Windows platforms.\n\nThat said, we hope both new and experienced OpenDSS users find it easy to adopt it.\n\n\n## Documentation\n\nVisit https://dss-extensions.org/AltDSS-Python/\n\nEspecially useful for a quick overview: https://dss-extensions.org/AltDSS-Python/examples/GettingStarted.html\n",
    "bugtrack_url": null,
    "license": "BSD 3-Clause License  Copyright (c) 2017-2024, Paulo Meira Copyright (c) 2017-2024, AltDSS-Python contributors All rights reserved.  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:  * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.  * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.  * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
    "summary": "Modern, detailed Python interface/bindings and tools based on the AltDSS/DSS C-API project, the alternative OpenDSS implementation from DSS-Extensions.org. Tries to expose all OpenDSS objects, bulk operations and many details which previously required using the Text interface, or just weren't available.",
    "version": "0.2.4",
    "project_urls": {
        "Bug Tracker": "https://github.com/dss-extensions/AltDSS-Python/issues",
        "Changelog": "https://github.com/dss-extensions/AltDSS-Python/blob/main/docs/changelog.md",
        "Documentation": "https://dss-extensions.org/AltDSS-Python",
        "Homepage": "https://github.com/dss-extensions/AltDSS-Python",
        "Repository": "https://github.com/dss-extensions/AltDSS-Python.git"
    },
    "split_keywords": [
        "altdss",
        " electric power systems",
        " opendss",
        " opendssdirect",
        " powerflow",
        " short-circuit"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4d2227c2cb4c642e58f600515ddde6e2b650ecbde36faf907a5188e11932189e",
                "md5": "ea75d2a3bbb662af9ac685dd907a065a",
                "sha256": "91d876f4c072eeedcd4c582700e5207b7f1b1729e2df0098ca5c461cc5f53f0f"
            },
            "downloads": -1,
            "filename": "altdss-0.2.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ea75d2a3bbb662af9ac685dd907a065a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 391969,
            "upload_time": "2024-03-29T05:48:06",
            "upload_time_iso_8601": "2024-03-29T05:48:06.996414Z",
            "url": "https://files.pythonhosted.org/packages/4d/22/27c2cb4c642e58f600515ddde6e2b650ecbde36faf907a5188e11932189e/altdss-0.2.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "738e4e9e75dbafdb9001e7bcce98190ad816bc838af7e982e00d1ce091a3c8d1",
                "md5": "0451467f62bab61fac0cc816679dc552",
                "sha256": "c2caccd1147c3a17c05605a700818ede77cd9406072684c6545727bd96d92937"
            },
            "downloads": -1,
            "filename": "altdss-0.2.4.tar.gz",
            "has_sig": false,
            "md5_digest": "0451467f62bab61fac0cc816679dc552",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 464734,
            "upload_time": "2024-03-29T05:48:09",
            "upload_time_iso_8601": "2024-03-29T05:48:09.164765Z",
            "url": "https://files.pythonhosted.org/packages/73/8e/4e9e75dbafdb9001e7bcce98190ad816bc838af7e982e00d1ce091a3c8d1/altdss-0.2.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-29 05:48:09",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "dss-extensions",
    "github_project": "AltDSS-Python",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "altdss"
}

None