From ef3ed46ac495b08228cd04c34a19d937c36cb366 Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Wed, 16 Apr 2025 15:51:04 -0400 Subject: [PATCH 1/7] readme updates: edit overview/pygridsim, update python numbers tested on --- README.md | 30 ++++++------------------------ 1 file changed, 6 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index e53e97f..8963247 100644 --- a/README.md +++ b/README.md @@ -13,33 +13,30 @@ # PyGridSim -Package to simulate OpenDSS circuits on Python. - -NOTE: README comes from dai cookie cutter, will be updated -NOTE: will be moved to Dai lab repository +PyGridSim is a package with the goal of simulating OpenDSS circuits on Python. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. - Documentation: https://amzhao.github.io/PyGridSim - Homepage: https://github.com/amzhao/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 user to create circuits with the amount of customization they desire. Thus, 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 ## 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 +72,8 @@ git checkout stable make install ``` -## Install for Development - -If you want to contribute to the project, a few more steps are required to make the project ready -for development. - -Please head to the [Contributing Guide](https://amzhao.github.io/PyGridSim/contributing.html#get-started) -for more details about this process. - -# Quickstart - -In this short tutorial we will guide you through a series of steps that will help you -getting started with **PyGridSim**. - -TODO: Create a step by step guide here. Also figure out how to ensure prerequisites properly. - # What's next? For more details about **PyGridSim** and all its possibilities and features, please check the [documentation site]( -https://amzhao.github.io/PyGridSim/). +TODO: gitbool link). From cd7cae5699ff22aad972e55d0e96685822329f9d Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Fri, 25 Apr 2025 16:27:35 -0400 Subject: [PATCH 2/7] readme --- sim_results.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 sim_results.json diff --git a/sim_results.json b/sim_results.json new file mode 100644 index 0000000..d416db5 --- /dev/null +++ b/sim_results.json @@ -0,0 +1,12 @@ +{ + "Voltages": { + "source": 499.8731711082983, + "load0": 492.7281111524284, + "load1": 492.7258134420103, + "load2": 489.1438851877899, + "load3": 489.1367759844901, + "generator0": 493.16438027796073, + "generator1": 493.1599368184952 + }, + "RealLoss": 85800.44056922143 +} \ No newline at end of file From 61e42d0bbffc3716cc40b196b6f6e031b3b30c52 Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Fri, 25 Apr 2025 16:27:52 -0400 Subject: [PATCH 3/7] readme --- sim_results.json | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 sim_results.json diff --git a/sim_results.json b/sim_results.json deleted file mode 100644 index d416db5..0000000 --- a/sim_results.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "Voltages": { - "source": 499.8731711082983, - "load0": 492.7281111524284, - "load1": 492.7258134420103, - "load2": 489.1438851877899, - "load3": 489.1367759844901, - "generator0": 493.16438027796073, - "generator1": 493.1599368184952 - }, - "RealLoss": 85800.44056922143 -} \ No newline at end of file From 31b21d32b208dc9a15073cdb1e63cf581f93523a Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Sat, 26 Apr 2025 16:20:59 -0400 Subject: [PATCH 4/7] update readme with quickstart --- README.md | 46 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8963247..ad31c3b 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ # PyGridSim -PyGridSim is a package with the goal of simulating OpenDSS circuits on Python. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. +PyGridSim is a package that allows user to simulating OpenDSS circuits with Python. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. - Documentation: https://amzhao.github.io/PyGridSim - Homepage: https://github.com/amzhao/PyGridSim @@ -22,7 +22,7 @@ PyGridSim is a package with the goal of simulating OpenDSS circuits on Python. P PyGridSim allows user to create circuits with the amount of customization they desire. Thus, 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 @@ -72,8 +72,44 @@ git checkout stable make install ``` -# What's next? +# 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 +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() +``` + +## Defaults-Based Circuit Creation +```python +circuit = PyGridSim() + +# Add Custom Source and Load +circuit.add_load_nodes(load_type="house") +circuit.update_source(source_type="turbine") + +# Add Line +circuit.add_lines([("source", "load0")], line_type="lv") + +# Solve and Print Results +circuit.solve() +print(circuit.results(["Voltages", "Losses"])) +circuit.clear() +``` + +# Resources For more details about **PyGridSim** and all its possibilities -and features, please check the [documentation site]( -TODO: gitbool link). +and features, please check the [Gitbook page for PyGridSim](https://dtail.gitbook.io/pygridsim) From bfcba0b46aab9066aa48de86b65107abec9f49f8 Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Sun, 27 Apr 2025 13:02:11 -0400 Subject: [PATCH 5/7] respond to comments --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ad31c3b..2171dcd 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,10 @@

- - +[![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) [![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) @@ -13,14 +15,14 @@ # PyGridSim -PyGridSim is a package that allows user to simulating OpenDSS circuits with Python. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. +PyGridSim is a package for simulating OpenDSS circuits. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. -- Documentation: https://amzhao.github.io/PyGridSim -- Homepage: https://github.com/amzhao/PyGridSim +- Documentation: https://dtail.gitbook.io/pygridsim +- Homepage: https://dai.lids.mit.edu/ # Overview -PyGridSim allows user to create circuits with the amount of customization they desire. Thus, 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. +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. # Installation From c2f7992b223ec93c909b671540bd3fcfd6062dc0 Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Sun, 27 Apr 2025 13:08:38 -0400 Subject: [PATCH 6/7] add descriptions and outputs --- README.md | 14 ++++++++++++++ sim.json | 8 ++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2171dcd..8a1ff3e 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,13 @@ 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. + ## Defaults-Based Circuit Creation ```python circuit = PyGridSim() @@ -111,6 +118,13 @@ 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}} +``` + +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. + # Resources For more details about **PyGridSim** and all its possibilities diff --git a/sim.json b/sim.json index ed80665..4fd2254 100644 --- a/sim.json +++ b/sim.json @@ -1,10 +1,10 @@ { "Voltages": { - "source": 1912.250959225854, - "load0": 164.87512862167387 + "source": 9999.598243195385, + "load0": 8294.334838925915 }, "Losses": { - "Active Power Loss": 181552.68984510849, - "Reactive Power Loss": 377394.0863595363 + "Active Power Loss": 9059444.425434513, + "Reactive Power Loss": 31084427.834760502 } } \ No newline at end of file From 11edc79be871fe5a49d154cd23f07309154f57f4 Mon Sep 17 00:00:00 2001 From: Angela Zhao Date: Sun, 27 Apr 2025 19:01:30 -0400 Subject: [PATCH 7/7] homepage link and badge changes --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.md b/README.md index 8a1ff3e..10ab78f 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,13 @@ [![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) -[![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) - - # PyGridSim PyGridSim is a package for simulating OpenDSS circuits. PyGridSim uses a functional interface to allow users to efficiently generate circuits of various scopes. - Documentation: https://dtail.gitbook.io/pygridsim -- Homepage: https://dai.lids.mit.edu/ +- Homepage: https://github.com/DAI-Lab/PyGridSim/ # Overview