Merge branch 'main' into node_naming

Author: amzhao16

HISTORY.md

@@ -1 +1,13 @@
-# History
+History
+=======
+## 0.1.0 - 2025-05-01
+
+First PyGridSim release to PyPI: https://pypi.org/project/pygridsim/
+
+* Add Proper Packaging - [PR #1](https://github.com/DAI-Lab/PyGridSim/pull/1) by @sarahmish
+* Add Type Checking, Exports, Enum Config File, Generators/PV - [PR #3](https://github.com/DAI-Lab/PyGridSim/pull/3) by @amzhao16
+* Pass Github Actions - [PR #5](https://github.com/DAI-Lab/PyGridSim/pull/5) by @amzhao16
+* Add Naming Consistency, Customization Tests - [PR #6](https://github.com/DAI-Lab/PyGridSim/pull/6) by @amzhao16
+* Support User Query Functions - [PR #7](https://github.com/DAI-Lab/PyGridSim/pull/7) by @amzhao16
+* Enhance Results.py - [PR #8](https://github.com/DAI-Lab/PyGridSim/pull/8) by @amzhao16
+* Update README - [PR #11](https://github.com/DAI-Lab/PyGridSim/pull/11) by @amzhao16

README.md

@@ -4,42 +4,37 @@
 </p>
 
 <!-- Uncomment these lines after releasing the package to PyPI for version and downloads badges -->
-<!--[![PyPI Shield](https://img.shields.io/pypi/v/pygridsim.svg)](https://pypi.python.org/pypi/pygridsim)-->
-<!--[![Downloads](https://pepy.tech/badge/pygridsim)](https://pepy.tech/project/pygridsim)-->
-[![Github Actions Shield](https://img.shields.io/github/workflow/status/amzhao/PyGridSim/Run%20Tests)](https://github.com/amzhao/PyGridSim/actions)
-[![Coverage Status](https://codecov.io/gh/amzhao/PyGridSim/branch/master/graph/badge.svg)](https://codecov.io/gh/amzhao/PyGridSim)
-
-
+[![Development Status](https://img.shields.io/badge/Development%20Status-2%20--%20Pre--Alpha-yellow)](https://pypi.org/search/?c=Development+Status+%3A%3A+2+-+Pre-Alpha)
+[![PyPI Shield](https://img.shields.io/pypi/v/pygridsim.svg)](https://pypi.python.org/pypi/pygridsim)
+[![Downloads](https://pepy.tech/badge/pygridsim)](https://pepy.tech/project/pygridsim)
+[![Run Tests](https://github.com/DAI-Lab/PyGridSim/actions/workflows/tests.yml/badge.svg)](https://github.com/DAI-Lab/PyGridSim/actions/workflows/tests.yml)
 
 # PyGridSim
 
-Package to simulate OpenDSS circuits on Python.
+PyGridSim is a package for simulating OpenDSS circuits. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes.
 
-NOTE: README comes from dai cookie cutter, will be updated
-NOTE: will be moved to Dai lab repository
-
-- Documentation: https://amzhao.github.io/PyGridSim
-- Homepage: https://github.com/amzhao/PyGridSim
+- Documentation: https://dtail.gitbook.io/pygridsim
+- Homepage: https://github.com/DAI-Lab/PyGridSim/ 
 
 # Overview
 
-PyGridSim aims to provide accessible access to tools like OpenDSS, AltDSS using Python. The goal is to create large-scale electrical circuits representing residential neighborhoods (and other scenarios) using an intuitive interface, without any background in OpenDSS software.
+PyGridSim allows users to create and customize circuits. Users can either fully specify each component they add to the circuit, or lean on library-provided parameter sets. PyGridSim supports the batch creation of every circuit component, emphasizing scalability and efficiently in building large circuits.
 
-# Install
+# Installation
 
 ## Requirements
 
-**PyGridSim** has been developed and tested on [Python 3.5, 3.6, 3.7 and 3.8](https://www.python.org/downloads/)
+**PyGridSim** has been developed and tested on [Python 3.10, 3.11 and 3.12](https://www.python.org/downloads/)
 
 Also, although it is not strictly required, the usage of a [virtualenv](https://virtualenv.pypa.io/en/latest/)
 is highly recommended in order to avoid interfering with other software installed in the system
 in which **PyGridSim** is run.
 
-These are the minimum commands needed to create a virtualenv using python3.6 for **PyGridSim**:
+These are the minimum commands needed to create a virtualenv using python3.10 for **PyGridSim**:
 
 ```bash
 pip install virtualenv
-virtualenv -p $(which python3.6) PyGridSim-venv
+virtualenv -p $(which python3.10) PyGridSim-venv
 ```
 
 Afterwards, you have to execute this command to activate the virtualenv:
@@ -75,23 +70,60 @@ git checkout stable
 make install
 ```
 
-## Install for Development
+# Quick Start
+Users of PyGridSim have the option between creating a fully customized circuit and using PyGridSim-provided parameters to build their circuit. Consider the simplest circuit: one source, one load, and a line connecting them. The following code snippet demonstrates how to model and print results on this circuit on PyGridSim with both methods.
+
+## Customized Circuit Creation
+```python
+from pygridsim import PyGridSim
+circuit = PyGridSim()
+
+# Add Custom Source and Load
+circuit.add_load_nodes(params={"kV": 0.12, "kW": 1, "kvar": 1})
+circuit.update_source(params={"kV": 0.5})
+
+# Add Line
+circuit.add_lines([("source", "load0")], params={"length": 1})
+
+# Solve and Print Results
+circuit.solve()
+print(circuit.results(["Voltages", "Losses"]))
+circuit.clear()
+```
+
+Running this code yields the following printed output:
+```
+{'Voltages': {'source': 499.7123955784113, 'load0': 120.73408045756985}, 'Losses': {'Active Power Loss': 465617.30157676246, 'Reactive Power Loss': 969502.2898991327}}
+```
+
+Note that the losses here are expressed in Watts, and the Voltages in Volts. The circuit observes some loss due to a much higher source voltage than load voltage, with most of the loss being reactive power loss. The circuit is created with a step-down transformer in the line by default, which enables the source and load to maintain isolated voltage levels at rest.
 
-If you want to contribute to the project, a few more steps are required to make the project ready
-for development.
+## Defaults-Based Circuit Creation
+```python
+from pygridsim import PyGridSim
+circuit = PyGridSim()
 
-Please head to the [Contributing Guide](https://amzhao.github.io/PyGridSim/contributing.html#get-started)
-for more details about this process.
+# Add Custom Source and Load
+circuit.add_load_nodes(load_type="house")
+circuit.update_source(source_type="turbine")
 
-# Quickstart
+# Add Line
+circuit.add_lines([("source", "load0")], line_type="lv")
 
-In this short tutorial we will guide you through a series of steps that will help you
-getting started with **PyGridSim**.
+# Solve and Print Results
+circuit.solve()
+print(circuit.results(["Voltages", "Losses"]))
+circuit.clear()
+```
+
+The following output is printed:
+```
+{'Voltages': {'source': 2418.845494533779, 'load0': 169.53107121049976}, 'Losses': {'Active Power Loss': 351310.95859906287, 'Reactive Power Loss': 730351.7183868886}}
+```
 
-TODO: Create a step by step guide here. Also figure out how to ensure prerequisites properly.
+The defaults-based ranges for source and load nodes are higher than the ones specified in the above customization example, explaining the higher voltages set for both nodes. We once again observe some loss in the system, with most of that being in reactive power loss.
 
-# What's next?
+# Resources
 
 For more details about **PyGridSim** and all its possibilities
-and features, please check the [documentation site](
-https://amzhao.github.io/PyGridSim/).
+and features, please check the [Gitbook page for PyGridSim](https://dtail.gitbook.io/pygridsim)

pygridsim/__init__.py

@@ -4,7 +4,7 @@
 
 __author__ = 'Angela Zhao'
 __email__ = '[email protected]'
-__version__ = '0.1.0.dev1'
+__version__ = '0.1.1.dev0'
 
 from pygridsim.core import PyGridSim
 

pygridsim/configs.py

@@ -66,3 +66,10 @@
         "kW": defaults.INDUSTRIAL_GEN_KW,
     }
 }
+
+NAME_TO_CONFIG = {
+    "load": LOAD_CONFIGURATIONS,
+    "source": SOURCE_CONFIGURATIONS,
+    "generator": GENERATOR_CONFIGURATIONS,
+    "line": LINE_CONFIGURATIONS
+}

pygridsim/core.py

@@ -2,6 +2,7 @@
 from altdss import altdss
 
 from pygridsim.defaults import RESERVED_PREFIXES
+from pygridsim.configs import NAME_TO_CONFIG
 from pygridsim.lines import _make_line
 from pygridsim.parameters import _make_generator, _make_load_node, _make_pv, _make_source_node
 from pygridsim.results import _export_results, _query_solution
@@ -24,12 +25,12 @@ def __init__(self):
             num_generators (int): Number generators in circuit so far.
             nickname_to_name (dict[str, str]): Map from nicknames to their internal names.
         """
-        self.num_loads = 0
+        self.num_generators = 0
         self.num_lines = 0
-        self.num_transformers = 0
+        self.num_loads = 0
         self.num_pv = 0
-        self.num_generators = 0
         self.nickname_to_name = {}
+
         altdss.ClearAll()
         altdss('new circuit.MyCircuit')
 
@@ -65,6 +66,7 @@ def add_load_nodes(self,
             list[OpenDSS object]:
                 A list of OpenDSS objects representing the load nodes created.
         """
+
         params = params or dict()
         names = names or list()
         if len(names) > num:
@@ -229,7 +231,9 @@ def results(self, queries: list[str], export_path=""):
 
         Args:
             queries (list[str]):
-                A list of queries to the circuit ("Voltages", "Losses", "TotalPower")
+                A list of queries to the circuit: one of ("Voltages", "Losses", "TotalPower")
+                or partial queries ("RealLoss", "ReactiveLoss", "RealPower", "ReactivePower")
+                that query one component of Losses/TotalPower
             export_path (str, optional):
                 The file path to export results. If empty, results are not exported.
                 Defaults to "".
@@ -254,6 +258,37 @@ def clear(self):
             None
         """
         altdss.ClearAll()
-        self.num_loads = 0
-        self.num_lines = 0
-        self.num_transformers = 0
+
+    def get_types(self, component: str, show_ranges: bool = False):
+        """Provides list of all supported Load Types
+
+        Args:
+            component (str):
+                Which component to get, one of (one of "load", "source", "pv", "line")
+            show_ranges (bool, optional):
+                Whether to show all configuration ranges in output.
+
+        Returns:
+            list:
+                A list containing all load types, if show_ranges False.
+                A list of tuples showing all load types and configurations, if show_ranges True.
+        """
+        component_simplified = component.lower().replace(" ", "")
+        if (component_simplified[-1] == "s"):
+            component_simplified = component_simplified[:-1]
+        configuration = {}
+        if component_simplified in NAME_TO_CONFIG:
+            configuration = NAME_TO_CONFIG[component_simplified]
+        else:
+            raise KeyError(
+                f"Invalid component input: expect one of {[name for name in NAME_TO_CONFIG]}")
+
+        if not show_ranges:
+            return [component_type.value for component_type in configuration]
+
+        component_types = []
+        for component_type in configuration:
+            config_dict = configuration[component_type]
+            component_types.append((component_type.value, config_dict))
+
+        return component_types

pygridsim/results.py

@@ -6,10 +6,12 @@
 
 from altdss import altdss
 
-
 def _query_solution(query, name_to_nickname):
-    match query:
-        case "Voltages":
+    query_fix = query.lower().replace(" ", "")
+    vector_losses = altdss.Losses()
+    vector_power = altdss.TotalPower()
+    match query_fix:
+        case "voltages":
             bus_vmags = {}
             for bus_name, bus_vmag in zip(altdss.BusNames(), altdss.BusVMag()):
                 return_name = bus_name
@@ -18,14 +20,24 @@ def _query_solution(query, name_to_nickname):
                     return_name += "/" + nickname
                 bus_vmags[return_name] = float(bus_vmag)
             return bus_vmags
-        case "Losses":
-            vector_losses = altdss.Losses()
+        case "losses" | "loss":
             losses = {}
             losses["Active Power Loss"] = vector_losses.real
             losses["Reactive Power Loss"] = vector_losses.imag
             return losses
-        case "TotalPower":
-            return altdss.TotalPower()
+        case "totalpower" | "power":
+            power = {}
+            power["Active Power"] = vector_power.real
+            power["Reactive Power"] = vector_power.imag
+            return power
+        case "activeloss" | "activepowerloss" | "realloss" | "realpowerloss":
+            return vector_losses.real
+        case "reactiveloss" | "reactivepowerloss":
+            return vector_losses.imag
+        case "activepower" | "realpower":
+            return vector_power.real
+        case "reactivepower":
+            return vector_power.imag
         case _:
             return "Invalid"
 

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.0.dev1
+current_version = 0.1.1.dev0
 commit = True
 tag = True
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.(?P<release>[a-z]+)(?P<candidate>\d+))?

setup.py

@@ -90,6 +90,6 @@
     test_suite='tests',
     tests_require=tests_require,
     url='https://github.com/amzhao/PyGridSim',
-    version='0.1.0.dev1',
+    version='0.1.1.dev0',
     zip_safe=False,
 )

sim.json

@@ -0,0 +1,10 @@
+{
+    "Voltages": {
+        "source": 9999.598243195385,
+        "load0": 8294.334838925915
+    },
+    "Losses": {
+        "Active Power Loss": 9059444.425434513,
+        "Reactive Power Loss": 31084427.834760502
+    }
+}

tests/test_circuit.py

@@ -193,6 +193,19 @@ def test_012_node_naming(self):
         circuit.solve()
         print(circuit.results(["Voltages", "Losses"]))
 
+    def test_013_all_results(self):
+        circuit = PyGridSim()
+        circuit.update_source()
+        circuit.add_load_nodes()
+        circuit.add_generators(num=2, gen_type="small")
+        circuit.add_lines([("source", "load0"), ("generator0", "load0")])
+        circuit.solve()
+        # Should be flexible with capitalization, spaces
+        queries = ["Voltages", "losses", "Total Power"]
+        # Add "partial" queries to just parts of losses/total power
+        queries += ["realpowerloss", "reactive Loss", "Active Power", "reactivepower"]
+        print(circuit.results(queries))
+
 
 class TestCustomizedCircuit(unittest.TestCase):
     """
@@ -292,3 +305,25 @@ def test_106_transformer_parameters(self):
         circuit.solve()
         print(circuit.results(["Voltages", "Losses"]))
         circuit.clear()
+
+
+class TestTypeQueryFunctions(unittest.TestCase):
+
+    def setUp(self):
+        """Set up test fixtures, if any."""
+        print("\nTest", self._testMethodName)
+
+    def tearDown(self):
+        """Tear down test fixtures, if any."""
+
+    def test_200_type_queries(self):
+        circuit = PyGridSim()
+        # should still work if plural, capitalized, spaces
+        for component in ["load ", "sources", "Line", "GENERATOR"]:
+            print(circuit.get_types(component))
+            print(circuit.get_types(component, show_ranges=True))
+
+    def test_200_invalid_type_quer(self):
+        circuit = PyGridSim()
+        with self.assertRaises(KeyError):
+            circuit.get_types("bad_component_name")