diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..4197c02 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,27 @@ +# DSSData's code of conduct + +We expected that each people that interact with this project follows these basics guidelines inspired by the [Julia Community - Standards](https://julialang.org/community/standards/): + +## Be respectful and inclusive + +Do not use overtly sexual language or imagery. Do not attack anyone based on any aspect of personal identity, including gender, sexuality, politics, religion, ethnicity, race, age, or ability. Keep in mind that what you write or say in public is read or heard by many people who don't know you personally, so please refrain from making prejudiced or sexual jokes and comments – even ones that you might consider acceptable in private. Ask yourself if a comment or statement might make someone feel unwelcomed or like an outsider. + +## Give credit + +All contributors are expected to respect copyright laws and ethical attribution standards. This applies to both code and written materials, such as documentation or blog posts. Materials that violate the law, are plagiaristic, or ethically dubious in some way will be removed from officially-maintained lists of resources. + +If you believe one of these standards has been violated, you can file an issue on this repository or confidentially contact the manteiner Felipe Monteiro at fmarkson@outlook.com. Keep in mind that most mistakes are due to ignorance rather than malice. + +## Be concise + +Constructive criticism and suggestions are welcome, but longer issues report or the missing of a [Minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example) only difficuts the problem addressment. Consider writing a blog post if you feel that you have enough to say on a particular subject. + +## Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule) + +- Treat others as you would like others to treat you. +- Do not treat others in ways that you would not like to be treated. +- What you wish upon others, you wish upon yourself. + +## Any concern? + +If you have a conflict or concern that requires resolution, please contact with the manteiner Felipe Monteiro at fmarkson@outlook.com. \ No newline at end of file diff --git a/DEV.md b/DEV.md new file mode 100644 index 0000000..2113363 --- /dev/null +++ b/DEV.md @@ -0,0 +1,61 @@ +# Development of the DSSData + +## How the project is organized + +The [SystemClass](https://felipemarkson.github.io/dssdata/tutorial/#loading-your-dss-file) has only the responsibility to process the ```.dss``` file. + +The [Power flow modes](https://felipemarkson.github.io/dssdata/tutorial/#run-power-flow) has only the responsibility to configure and run a power flow mode with Actions and Tools. + +The [Actions](https://felipemarkson.github.io/dssdata/tutorial/#creating-your-first-action) has only the responsibility to change the distribution system state temporarily. + +The [Tools](https://felipemarkson.github.io/dssdata/tutorial/#creating-your-first-tool) has only the responsibility to get data information from the current state of the distribution system. + +The [Reduction](https://felipemarkson.github.io/dssdata/tutorial/#creating-your-first-reduction) has only the responsibility to transform various tool's returns in a DataFrame. + +See the package [documentation](https://felipemarkson.github.io/dssdata/) for more details + +## The dependence manager and development environment + +We use [Poetry](https://python-poetry.org/) to manage the dependencies. + +You can quickly get all the development environment run the following commands: +``` bash +$ git clone https://github.com/felipemarkson/dssdata.git +$ cd dssdata +$ poetry install +$ poetry shell +``` +**_Make sure that you have installed the [Python version required](https://felipemarkson.github.io/dssdata/#requirements)._** + +## Linting +[Flake8](https://flake8.pycqa.org/en/latest/) in default configuration. + +## Documentation + +We use [Google's Style Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for docstrings documentation. + +All public functions must be documented at last with docstrings. + +You can see more details to how to simulate the documentation on #72. + +### How to run the documentation + +```console +$ mkdocs serve +``` + +### How to deploy the documentation +```console +$ mkdocs gh-deploy +``` + +## Tests and CI + +We use the [unittest](https://docs.python.org/3/library/unittest.html) for our functional tests. We know that it is not the best choice, but it works fine. + +```console +$ python -m unittest +``` + +If you have other suggestions on how to build our tests, please tell us in an Issue. + diff --git a/README.md b/README.md index 44c831e..b16001b 100644 --- a/README.md +++ b/README.md @@ -26,26 +26,60 @@ We built the DSSData for you just write what you want in a simple function, plug You don't need anymore write a routine to run each power flow per time. -## Documentation - -See [DSSData Documentation](https://felipemarkson.github.io/dssdata). - -## Installation +## Quick Start +### Installation We strongly recommend the use of virtual environments manager. -### Using pip - ```console pip install dssdata ``` -### Using poetry +### Static Power Flow (Snapshot) -```console -poetry add dssdata +First, comment any `solve`, output command (e.g: `show`), or solve configurations (e.g: `set mode=Snap`) from your `.dss` file. + +_**NOTE**: Any `Monitor` is needed to get the data._ + +Supposing that you file is in the path `master.dss`: + +```python +from dssdata import SystemClass +from dssdata.pfmodes import run_static_pf +from dssdata.tools import voltages + +distSys = SystemClass(path="master.dss", kV=[13.8, 0.230], loadmult=1.0) + +[voltageDataFrame] = run_static_pf(distSys, tools=[voltages.get_all]) +print(voltageDataFrame) ``` +### Time series Power Flow + +First, comment any `solve`, output command (e.g: `show`), or solve configurations (e.g: `set mode=daily stepsize=5m time=...`) from your `.dss` file. + +_**NOTE**: Any `Monitor` is needed to get the data._ + +_**NOTE**: The `Loadshape` must be defined in the `.dss` file_ + +Supposing that you file is in the path `master.dss`: + +```python +from dssdata import SystemClass +from dssdata.pfmodes import cfg_tspf, run_tspf +from dssdata.tools import lines, voltages + +distSys = SystemClass(path="master.dss", kV=[13.8], loadmult=1.2) +cfg_tspf(distSys, step_size="5m", initial_time=(0, 0)) + +[voltageDataFrame] = run_tspf(distSys, tools=[voltages.get_all], num_steps=288) +print(voltageDataFrame) +``` + +## Documentation + +We provide an full API documentation and examples in the [DSSData Documentation](https://felipemarkson.github.io/dssdata). + ## Citing If you find DSSData useful in your work, we kindly request that you cite it as below: @@ -64,9 +98,8 @@ If you find DSSData useful in your work, we kindly request that you cite it as b ## Help us to improve DSSData -See our [Issue](https://github.com/felipemarkson/dssdata/issues) section! - +See our [Issue](https://github.com/felipemarkson/dssdata/issues) section, our [Development Guidelines](DEV.md), and our [Code of conduct](CODE_OF_CONDUCT.md). -## Contributors: +### Contributors: - [JonasVil](https://github.com/felipemarkson/power-flow-analysis/commits?author=JonasVil) diff --git a/dssdata/__init__.py b/dssdata/__init__.py index 297fe96..60cd818 100644 --- a/dssdata/__init__.py +++ b/dssdata/__init__.py @@ -2,7 +2,7 @@ from os import path as pathfunc from typing import Iterable, List -__version__ = "0.1.8" +__version__ = "0.2" def _redirect_handler(path) -> List[str]: diff --git a/pyproject.toml b/pyproject.toml index 6dd8453..993cec9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "dssdata" -version = "0.1.9" +version = "0.2.0" description = "Organizing OpenDSS data" authors = ["Felipe M. S. Monteiro "] license = "MIT" @@ -16,7 +16,7 @@ classifiers = [ [tool.poetry.dependencies] python = "^3.9" -"OpenDSSDirect.py" = "0.7.*" +"OpenDSSDirect.py" = "0.8.*" pandas = "1.*"