Merge pull request #11 from DAI-Lab/readme_update

Readme update

Author: 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,58 @@ 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
+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
+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)

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
     }
 }