PYSIMDEUM

pysimdeum is a Python package for modelling and simulating residential stochastic water demand and discharge at the end-use level.

Main functionalities:

• Build and populate houses with users and water end-use devices according to region (e.g. country, city, state) specific statistics
• Simulate water usage and demand stochastically based on the statistics
• The results are stored as xarray.DataArray, so all the simulation information can be accessed and aggregated afterwards (e.g., specific end-uses, sums over water usage of users, rolling means over time, ...)
• Serialisation: pysimdeum supports different output formats (e.g., csv, excel, netcdf, ...)
• Plotting results using matplotlib

For more detailed instructions, see our documentation.

Output is based on statistics about household sizes and water use of the Netherlands. These can be changed either within the code or by creating the correct toml files. An overview of worldwide differences is available in:

Mazzoni, F., Alvisi, S., Blokker, E. J. M., Buchberger, S. G., Castelletti, A., Cominola, A., Gross, M. P., Jacobs, H. E., Mayer, P., Steffelbauer, D. B., Stewart, R. A., Stillwell, A. S., Tzatchkov, V., Yamanaka, V. H. A. and Franchini, M. (2022). "Investigating the characteristics of residential end uses of water: a worldwide review." Water Research, art. no. 119500, https://www.sciencedirect.com/science/article/abs/pii/S0043135422014452

Installation

pysimdeum uses features only available in a newer Python version, which is why Python >= 3.8 is needed along with several Python package dependencies.

As a user

pysimdeum is available on PyPI and can be easily installed together with its dependencies using pip:

pip install pysimdeum

Alternatively, you can install pysimdeum from its repository:

pip install git+https://github.com/KWR-Water/pysimdeum.git

As a developer

git clone git@github.com:KWR-Water/pysimdeum.git
cd pysimdeum
mamba create -n pysimdeum python=3.11 pip -c conda-forge
mamba activate pysimdeum
pip install -r requirements.txt .

Basic Usage

To use pysimdeum, you first have to import it in your script:

import pysimdeum

In pysimdeum, everything is about the House. If you want to build a specific House, e.g., a one-erson household, you can use the house_type keyword. Type the following:

# Build a one-person household
house = pysimdeum.built_house(house_type='one_person')

The house is automatically populated by a person, which follows certain statistics, and "furnished" with water end-use devices or appliances (e.g., toilet, bathtub, ...). You can check which appliances are available, and who are the possible users, by using the appliances or users property of the House:

print(house.users)
print(house.appliances)

To simulate the water consumption of a house, you can use the House's simulate method:

# Simulate water consumption for house
consumption = house.simulate(num_patterns=1)

pysimdeum also allows you to simulate discharge flows that are linked to your consumption flows.

# Simulate water consumption and discharge for house
consumption, discharge = house.simulate(num_patterns=1, simulate_discharge=True)

The consumption (and discharge) simulation result is an xarray.DataArray - basically a labelled numpy.ndarray with four dimensions / axes (i.e. time, user, enduse, patterns)

You can easily create statistics over the consumption and discharge objects, for example, to compute the total consumption (sum of consumption of all users and enduses), you can build the sum over the user and enduse axes (the total consumption). Within consumption, there are two flowtypes defined. totalflow and hotflow. totalflow reflects the total water use while hotflow reflects the water that has been heated up.

# Build statistics from consumption
tot_cons = consumption.sum(['enduse', 'user']).sel(flowtypes='totalflow').mean(['patterns'])

If you want to plot the results and additionally depict some rolling averages (e.g. hourly means = 3600 seconds), you can do this in the following way:

# Plot total consumption
tot_cons.plot()
tot_cons.rolling(time=3600, center=True).mean().plot()
plt.show()

Or produce plots for a specific enduse such as KitchenTap

# Plot total consumption of KitchenTap enduse
consumption.sum(["user"]).sel(enduse="KitchenTap").sel(flowtypes="totalflow").plot()

License

pysimdeum is available under a EUPL-1.2 license.

Contributing

If you want to contribute, please check out our Code of Conduct and our Contribution Guide. Looking forward to your pull request or issue!

Citing

If you publish work based on pysimdeum , we appreciate a citation of the following reference:

• Steffelbauer, D.B., Hillebrand B., Blokker, E.J.M., 2022. pySIMDEUM: An open-source stochastic water demand end-use model in Python. Proceedings of the 2nd joint Water Distribution System Analysis and Computing and Control in the Water Industry (WDSA/CCWI2022) conference, Valencia (Spain), 18-22 July 2022.