diff --git a/CHANGELOG.md b/CHANGELOG.md index 49c9c80..29efe12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] - +### Added +- Documentation pages +### Changed +- Set github actions for publishing packages automatically ## [0.0.5] - 2020-12-03 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a6a8928 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Contributing + +We'd love to accept your patches and contributions to this project. There are just a few small +guidelines you need to follow. + +## Guidelines +1. Write your patch +1. Add a test case to your patch +1. Make sure that all tests run properly +1. Send your patch as a PR + +## Installation + +You can install the WandaToolbox package as follows: +``` +pip install wandatoolbox +``` + +## Development installation and testing + +For development you can use the 'editable' installation: +``` +pip install -e . +pytest +``` + +## Building the package + +Building the backage is done as follows: +``` +pip install setuptools wheel +python setup.py sdist bdist_wheel +``` + +## Creating a release + +We use bump2version to update the version numbers. Bump2version will also create a tag and commit the +changes. This can then be pushed using +``` +git push origin --tags +``` +The Github Actions have been configured to run the tests and flake8 linting and publish to test.Pypi +on every push. If a commit is also tagged it will also publish to Pypi. diff --git a/README.md b/README.md index 3ec7a15..dac1bce 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,12 @@ [![Documentation Status](https://readthedocs.org/projects/wandatoolbox/badge/?version=latest)](https://wandatoolbox.readthedocs.io/en/latest/?badge=latest) # Wanda Toolbox -Toolbox (python scripts) for Wanda modellers +Toolbox (python scripts) for Wanda modellers. This toolbox includes several tools and utilities that can help with Wanda modelling, +running simulations and analyzing and visualizing simulation results. This module is closely related to PyWanda, the Python bindings for the Wanda API. -This toolbox includes several tools and utilities that can help with Wanda modelling and -running simulations. +Wanda is an advanced water hammer software, designed for engineers by engineers. The Python API bindings can be used to create Wanda models, +run simulations, and extract the simulation results. The Wanda Toolbox module includes additional scripts to go beyond the basic data retrieval of pywanda. + ## Installation Run the following to install this package: @@ -18,62 +20,8 @@ pip install WandaToolbox Also see: https://pypi.org/project/wandatoolbox/ ## Usage -Generic usage of the WandaPlot classes: -```python -from wandatoolbox.wanda_plot import PlotSyschar, PlotText, PlotTable, PlotImage, plot -import matplotlib.pyplot as plt -from matplotlib.backends.backend_pdf import PdfPages -import pandas as pd -import pywanda as pw +Tutorial and reference documentation is provided at [wandatoolbox.readthedocs.io](https://wandatoolbox.readthedocs.io). A PDF version of the manual is available [here](https://wandatoolbox.readthedocs.io/_/downloads/en/latest/pdf/). And the source code is always available at [https://github.com/MichielTukker/WandaToolbox](github.com/MichielTukker/WandaToolbox). -model = pw.WandaModel(r'c:\Wandamodel.wdi', 'c:\Wanda 4.6\Bin\\') - -with PdfPages(f'Document.pdf') as pdf: - img = plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png') - df = pd.read_excel(r'example_data\syschar_test.xlsx', header=0, index_col=0) - scenario_names = ["Current min", "Current max", "Future min", "Future max"] - - subplots_table = [ - PlotTable(df, ['description', "Current min", "Current max", "Future min", "Future max"]), - PlotImage(img), PlotText("Yada yada yada"), - PlotSyschar("BOUNDQ B1", 105.0, "Supplier #1", df, 'Wanda_name', - scenario_names, 3, "Industry description", 'Discharge (m3/day)', 'Head (m)') - ] - plot(model, subplots_table, - 'Main title', - f'Subtitle 1', - 'Subtitle 2', - 'Subtitle 3', - 'Subtitle 4', - f'Figure number: 1', - company_image=plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png'), - fontsize=10) - pdf.savefig() - plt.close() -``` - -Generic usage of the monte-carlo class: -```python -from wandatoolbox.analysis.monte_carlo import MonteCarloInputProperty, MonteCarloOutputProperty, WandaMonteCarlo -import pywanda as pw -import os - -def main(): - wandacase_fullpath = os.path.join(os.getcwd(), "Sewage_transient.wdi") - wanda_bin_directory = r'c:\Program Files (x86)\Deltares\Wanda 4.6\Bin\\' - model = pw.WandaModel(wandacase_fullpath, wanda_bin_directory) - parameters = [MonteCarloInputProperty(" PIPES", "Wall roughness", 2.5 / 1000, 0.5 / 1000, "normal", True)] - outputs = [MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MIN"), - MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MAX")] - analysis = WandaMonteCarlo(model, parameters, outputs, nruns=25, n_workers=2) - analysis.run() - analysis.plot_results(filename_prefix="test", width=1000, height=800) - analysis.cleanup() - - -if __name__ == "__main__": - main() # This main() method is essential due to the way Python's multiprocessing module works -``` -# Support +## Support No official support! For questions/improvements/comments, contact Deltares or Wanda support desk? diff --git a/docs/advanced/analysis.rst b/docs/advanced/analysis.rst new file mode 100644 index 0000000..794baf1 --- /dev/null +++ b/docs/advanced/analysis.rst @@ -0,0 +1,31 @@ +analysis tools +=============== + +Monte-carlo analysis +-------------------- +Generic usage of the monte-carlo class: + +.. code-block:: python + :linenos: + + from wandatoolbox.analysis.monte_carlo import MonteCarloInputProperty, MonteCarloOutputProperty, WandaMonteCarlo + import pywanda as pw + import os + + def main(): + wandacase_fullpath = os.path.join(os.getcwd(), "Sewage_transient.wdi") + wanda_bin_directory = r'c:\Program Files (x86)\Deltares\Wanda 4.6\Bin\\' + model = pw.WandaModel(wandacase_fullpath, wanda_bin_directory) + parameters = [MonteCarloInputProperty(" PIPES", "Wall roughness", 2.5 / 1000, 0.5 / 1000, "normal", True)] + outputs = [MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MIN"), + MonteCarloOutputProperty(" PIPES", "Pressure", keyword=True, extreme="MAX")] + analysis = WandaMonteCarlo(model, parameters, outputs, nruns=25, n_workers=2) + analysis.run() + analysis.plot_results(filename_prefix="test", width=1000, height=800) + analysis.cleanup() + + + if __name__ == "__main__": + main() # This main() method is essential due to the way Python's multiprocessing module works + +The monte carlo toolset will run multiple simulation in parallel, greatly reducing the simulation time. \ No newline at end of file diff --git a/docs/advanced/callibration.rst b/docs/advanced/callibration.rst new file mode 100644 index 0000000..8117add --- /dev/null +++ b/docs/advanced/callibration.rst @@ -0,0 +1,2 @@ +Callibration +============= \ No newline at end of file diff --git a/docs/advanced/optimization.rst b/docs/advanced/optimization.rst new file mode 100644 index 0000000..b1bba61 --- /dev/null +++ b/docs/advanced/optimization.rst @@ -0,0 +1,2 @@ +Optimization +============= \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..270c5ee --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. mdinclude:: ../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/figures.rst b/docs/figures.rst new file mode 100644 index 0000000..7a034d2 --- /dev/null +++ b/docs/figures.rst @@ -0,0 +1,44 @@ +Plotting figures +======================================== + +Usage +-------- +WandaToolbox supports plotting various objects to a formatted PDF, which can be included as an appendix in your +report. WandaToolbox.wanda_plot supports time and location series where data is exported directly from Wanda models. +It also supports adding tables, images or text blocks on pages, and supports generating system characteristics for +a range of flow rates and discharge points. + +Code example: + +.. code-block:: python + :linenos: + + from wandatoolbox.wanda_plot import PlotSyschar, PlotText, PlotTable, PlotImage, plot + import matplotlib.pyplot as plt + from matplotlib.backends.backend_pdf import PdfPages + import pandas as pd + import pywanda as pw + + model = pw.WandaModel(r'c:\Wandamodel.wdi', 'c:\Wanda 4.6\Bin\\') + img = plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png') + df = pd.read_excel(r'example_data\syschar_test.xlsx', header=0, index_col=0) + scenario_names = ["Current min", "Current max", "Future min", "Future max"] + + with PdfPages(f'Document.pdf') as pdf: + subplots_table = [ + PlotTable(df, ['description', "Current min", "Current max", "Future min", "Future max"]), + PlotImage(img), PlotText("Yada yada yada"), + PlotSyschar("BOUNDQ B1", 105.0, "Supplier #1", df, 'Wanda_name', + scenario_names, 3, "Industry description", 'Discharge (m3/day)', 'Head (m)') + ] + plot(model, subplots_table, + 'Main title', + f'Subtitle 1', + 'Subtitle 2', + 'Subtitle 3', + 'Subtitle 4', + f'Figure number: 1', + company_image=plt.imread('WandaToolbox\data\DELTARES_ENABLING_CMYK.png'), + fontsize=10) + pdf.savefig() + plt.close() diff --git a/docs/index.rst b/docs/index.rst index 2702ed2..797ed07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,16 +3,39 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to WandaToolbox's documentation! +WandaToolbox documentation! ======================================== +.. include:: readme.rst + + +Contents +============ .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 1 - members - readme changelog + contributing + + +.. toctree:: + :caption: The Basics + :maxdepth: 1 + + figures + paramterscript + miscellaneous + + +.. toctree:: + :caption: Advanced Topics + :maxdepth: 1 + + advanced/analysis + advanced/callibration + advanced/optimization + + Indices and tables diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst new file mode 100644 index 0000000..6d341f8 --- /dev/null +++ b/docs/miscellaneous.rst @@ -0,0 +1,2 @@ +Misc. functions and tools +======================================== \ No newline at end of file diff --git a/docs/paramterscript.rst b/docs/paramterscript.rst new file mode 100644 index 0000000..ef3021d --- /dev/null +++ b/docs/paramterscript.rst @@ -0,0 +1,2 @@ +Parameterscript +======================================== \ No newline at end of file diff --git a/docs/readme.rst b/docs/readme.rst index 29f2c14..1192b96 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1,6 +1,2 @@ -================= -README -================= - .. mdinclude:: ../README.md