Skip to content

Commit c0346fd

Browse files
BramHillebrandBramHillebrand
committed
updated minimal example to work with warm water
1 parent fa71753 commit c0346fd

File tree

2 files changed

+145
-145
lines changed

2 files changed

+145
-145
lines changed

‎README.md

+119-119
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,119 @@
1-
# PYSIMDEUM
2-
3-
`pysimdeum` is a Python package for modelling and simulating residential stochastic water demand at the end-use level.
4-
5-
Main functionalities:
6-
7-
- Build and populate houses with users and water end-use devices according to country specific statistics
8-
- Simulate water usage stochastically based on the statistics
9-
- 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, ...)
10-
- Serialization: `pysimdeum` supports different output formats (e.g., csv, excel, netcdf, ...)
11-
- Plotting results using matplotlib
12-
13-
A detailed documentation will be soon available under https://pysimdeum.readthedocs.io.
14-
15-
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:
16-
17-
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, doi:https://doi.org/10.1016/j.watres.2022.119500.https://www.sciencedirect.com/science/article/pii/S0043135422014452 https://livelink.kwrwater.nl/livelink/livelink.exe/Open/69638292
18-
19-
---
20-
**Warning!**
21-
22-
Be warned, that `pysimdeum` is still changing a lot. Until it's marked as 1.0.0, you should assume that it is unstable and act accordingly. We are trying to avoid breaking changes but they can and will occur!
23-
24-
---
25-
26-
## Installation
27-
28-
`pysimdeum` uses features only available in a newer Python version, which is why Python >= 3.8 is needed along with several Python package dependencies.
29-
30-
`pysimdeum` is available on PyPI and can be easily installed together with its dependencies using `pip`:
31-
32-
```bash
33-
pip install pysimdeum
34-
```
35-
36-
Alternatively, you can install `pysimdeum` from its repository:
37-
38-
39-
```bash
40-
pip install git+https://github.com/KWR-Water/pysimdeum.git
41-
```
42-
43-
### Dependencies
44-
45-
`pysimdeum` requires the following Python packages:
46-
47-
- matplotlib
48-
- numpy
49-
- pandas
50-
- toml
51-
- xarray
52-
- scipy
53-
54-
## Basic Usage
55-
56-
To use `pysimdeum` , you first have to import it in your script:
57-
58-
```python
59-
import pysimdeum
60-
```
61-
62-
In `pysimdeum` , everything is about the `House`. If you want to start with a new, empty House, type the following:
63-
64-
```python
65-
house = pySIMDEUM.built_house(house_type='one_person')
66-
```
67-
68-
If you want to build a specific House, e.g., a one-person household, you can use the `house_type` keyword:
69-
70-
```python
71-
# Built a house (one-person household)
72-
house = pySIMDEUM.built_house(house_type='one_person')
73-
```
74-
The house is automatically populated by people, which follow certain statistics, and "furnished" with water end-use devices or appliances (e.g., toilet, bathtub, ...). You can check, which appliances are available by using the `appliances` or `users` property of the House:
75-
76-
```python
77-
# Show users and water end-use devices present in the house
78-
print(house.users)
79-
print(house.appliances)
80-
```
81-
82-
To simulate the water consumption of a house, you can use the House\`s `simulate` method:
83-
84-
```python
85-
# Simulate water consumption for house (xarray.DataArray)
86-
consumption = house.simulate(num_patterns=100)
87-
```
88-
89-
The simulation result is an `xarray.DataArray` --- basically a labelled `numpy.ndarray` with four dimensions / axes (i.e., time, user, enduse, patterns).
90-
91-
You can easily create statistics over the consumption object, for example, to compute the average total consumption (sum of consumption of all users and enduses as an average over the patterns), you can build the sum over the `user` and `enduse` axes (the total consumption), and then build the mean over the `patterns` axes
92-
93-
```python
94-
# Build statistics from consumption
95-
tot_cons = consumption.sum(['enduse', 'user']).mean([ 'patterns'])
96-
```
97-
98-
If you want to plot the results pand additionally depict some rolling averages (e.g., hourly means = 3600 seconds), you can this in the following way
99-
100-
```python
101-
# Plot total consumption
102-
tot_cons.plot()
103-
tot_cons.rolling(time=3600, center=True).mean().plot()
104-
plt.show()
105-
```
106-
107-
## License
108-
109-
`pysimdeum` is available under a [EUPL-1.2 license](https://github.com/KWR-Water/pysimdeum/blob/master/LICENSE).
110-
111-
## Contributing
112-
113-
If you want to contribute, please check out our [Code of Conduct](https://github.com/KWR-Water/pysimdeum/blob/master/CODE_OF_CONDUCT.md) and our [Contribution Guide](https://github.com/KWR-Water/pysimdeum/blob/master/CONTRIBUTING.md). Looking forward to your pull request or issue!
114-
115-
## Citing
116-
117-
If you publish work based on `pysimdeum` , we appreciate a citation of the following reference:
118-
119-
- 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.
1+
# PYSIMDEUM
2+
3+
`pysimdeum` is a Python package for modelling and simulating residential stochastic water demand at the end-use level.
4+
5+
Main functionalities:
6+
7+
- Build and populate houses with users and water end-use devices according to country specific statistics
8+
- Simulate water usage stochastically based on the statistics
9+
- 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, ...)
10+
- Serialization: `pysimdeum` supports different output formats (e.g., csv, excel, netcdf, ...)
11+
- Plotting results using matplotlib
12+
13+
A detailed documentation will be soon available under https://pysimdeum.readthedocs.io.
14+
15+
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:
16+
17+
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, doi:https://doi.org/10.1016/j.watres.2022.119500.https://www.sciencedirect.com/science/article/pii/S0043135422014452 https://livelink.kwrwater.nl/livelink/livelink.exe/Open/69638292
18+
19+
---
20+
**Warning!**
21+
22+
Be warned, that `pysimdeum` is still changing a lot. Until it's marked as 1.0.0, you should assume that it is unstable and act accordingly. We are trying to avoid breaking changes but they can and will occur!
23+
24+
---
25+
26+
## Installation
27+
28+
`pysimdeum` uses features only available in a newer Python version, which is why Python >= 3.8 is needed along with several Python package dependencies.
29+
30+
`pysimdeum` is available on PyPI and can be easily installed together with its dependencies using `pip`:
31+
32+
```bash
33+
pip install pysimdeum
34+
```
35+
36+
Alternatively, you can install `pysimdeum` from its repository:
37+
38+
39+
```bash
40+
pip install git+https://github.com/KWR-Water/pysimdeum.git
41+
```
42+
43+
### Dependencies
44+
45+
`pysimdeum` requires the following Python packages:
46+
47+
- matplotlib
48+
- numpy
49+
- pandas
50+
- toml
51+
- xarray
52+
- scipy
53+
54+
## Basic Usage
55+
56+
To use `pysimdeum` , you first have to import it in your script:
57+
58+
```python
59+
import pysimdeum
60+
```
61+
62+
In `pysimdeum` , everything is about the `House`. If you want to start with a new, empty House, type the following:
63+
64+
```python
65+
house = pySIMDEUM.built_house(house_type='one_person')
66+
```
67+
68+
If you want to build a specific House, e.g., a one-person household, you can use the `house_type` keyword:
69+
70+
```python
71+
# Built a house (one-person household)
72+
house = pySIMDEUM.built_house(house_type='one_person')
73+
```
74+
The house is automatically populated by people, which follow certain statistics, and "furnished" with water end-use devices or appliances (e.g., toilet, bathtub, ...). You can check, which appliances are available by using the `appliances` or `users` property of the House:
75+
76+
```python
77+
# Show users and water end-use devices present in the house
78+
print(house.users)
79+
print(house.appliances)
80+
```
81+
82+
To simulate the water consumption of a house, you can use the House\`s `simulate` method:
83+
84+
```python
85+
# Simulate water consumption for house (xarray.DataArray)
86+
consumption = house.simulate(num_patterns=100)
87+
```
88+
89+
The simulation result is an `xarray.DataArray` --- basically a labelled `numpy.ndarray` with four dimensions / axes (i.e., time, user, enduse, patterns).
90+
91+
You can easily create statistics over the consumption object, for example, to compute the average total consumption (sum of consumption of all users and enduses as an average over the patterns), you can build the sum over the `user` and `enduse` axes (the total consumption), and then build the mean over the `patterns` axes. There are two `flowtypes` defined. `totalflow` and `hotflow`. `totalflow` reflects the total water use while `hotflow` reflects the water that has been heated up.
92+
93+
```python
94+
# Build statistics from consumption
95+
tot_cons = consumption.sum(['enduse', 'user']).sel(flowtypes='totalflow').mean([ 'patterns'])
96+
```
97+
98+
If you want to plot the results pand additionally depict some rolling averages (e.g., hourly means = 3600 seconds), you can this in the following way
99+
100+
```python
101+
# Plot total consumption
102+
tot_cons.plot()
103+
tot_cons.rolling(time=3600, center=True).mean().plot()
104+
plt.show()
105+
```
106+
107+
## License
108+
109+
`pysimdeum` is available under a [EUPL-1.2 license](https://github.com/KWR-Water/pysimdeum/blob/master/LICENSE).
110+
111+
## Contributing
112+
113+
If you want to contribute, please check out our [Code of Conduct](https://github.com/KWR-Water/pysimdeum/blob/master/CODE_OF_CONDUCT.md) and our [Contribution Guide](https://github.com/KWR-Water/pysimdeum/blob/master/CONTRIBUTING.md). Looking forward to your pull request or issue!
114+
115+
## Citing
116+
117+
If you publish work based on `pysimdeum` , we appreciate a citation of the following reference:
118+
119+
- 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.

‎examples/minimal_example.py

+26-26
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
1-
import pysimdeum
2-
import matplotlib.pyplot as plt
3-
4-
# Built a house (one-person household)
5-
house = pysimdeum.built_house(house_type='one_person')
6-
print(house)
7-
8-
# Show the inhabitants of a house
9-
print("List of Users:")
10-
print(house.users)
11-
12-
# Show water end-use devices present in the house
13-
print("List of Devices:")
14-
print(house.appliances)
15-
16-
# Simulate water consumption for house (xarray.DataArray)
17-
consumption = house.simulate(num_patterns=100)
18-
19-
# Build statistics from consumption
20-
tot_cons = consumption.sum(['enduse', 'user']).mean([ 'patterns'])
21-
print(tot_cons)
22-
23-
# Plot total consumption
24-
tot_cons.plot()
25-
tot_cons.rolling(time=3600, center=True).mean().plot()
26-
plt.show()
1+
import pysimdeum
2+
import matplotlib.pyplot as plt
3+
4+
# Built a house (one-person household)
5+
house = pysimdeum.built_house(house_type='one_person')
6+
print(house)
7+
8+
# Show the inhabitants of a house
9+
print("List of Users:")
10+
print(house.users)
11+
12+
# Show water end-use devices present in the house
13+
print("List of Devices:")
14+
print(house.appliances)
15+
16+
# Simulate water consumption for house (xarray.DataArray)
17+
consumption = house.simulate(num_patterns=100)
18+
19+
# Build statistics from consumption
20+
tot_cons = consumption.sum(['enduse', 'user']).sel(flowtypes='totalflow').mean([ 'patterns'])
21+
print(tot_cons)
22+
23+
# Plot total consumption
24+
tot_cons.plot()
25+
tot_cons.rolling(time=3600, center=True).mean().plot()
26+
plt.show()

0 commit comments

Comments
 (0)