:warning: Warning: this code does not represent best practice for customisation. Instead we recommend use of decorators to overwrite behaviour. Users can see examples of decorators in the customise_interactions and customise_riverreservoir guides. This guide may still be useful for WSIMOD code examples, and it will still work in many cases.
There is currently a GitHub (issue)[https://github.com/barneydobson/wsi/issues/11] to revise this guide.
Customise an arc (.py)¶
Note - this script can also be opened in interactive Python if you wanted to play around. On the GitHub it is in docs/demo/scripts
Introduction¶
In this tutorial we will demonstrate how to customise an arc on-the-fly. If you are creating a new type of arc that is a generic physical object (e.g., a weir), then you should probably create a new subclass of existing classes. However, if you are aiming to alter the behaviour of an arc that already has a class to fit some super specific behaviour, then it may be more suitable to customise on-the-fly. In addition, customising on-the-fly is very similar to creating a subclass, so the skills demonstrated here are likely to be transferrable.
We will use the Oxford demo as our base model, and build off it by assigning a varying capacity to the river abstraction depending on reservoir storage
Create baseline¶
We will first create and simulate the Oxford model to formulate baseline results. We use a version of the model with the minimum required flow from the node customisation demo.
Start by importing packages.
In [1]:
Copied!
import os
import pandas as pd
from matplotlib import pyplot as plt
from wsimod.demo.create_oxford import create_oxford_model_mrf
import os
import pandas as pd
from matplotlib import pyplot as plt
from wsimod.demo.create_oxford import create_oxford_model_mrf
The model can be automatically created using the data_folder
In [2]:
Copied!
# Select the root path for the data folder. Use the appropriate value for your case.
data_folder = os.path.join(os.path.abspath(""), "docs", "demo", "data")
baseline_model = create_oxford_model_mrf(data_folder)
# Select the root path for the data folder. Use the appropriate value for your case.
data_folder = os.path.join(os.path.abspath(""), "docs", "demo", "data")
baseline_model = create_oxford_model_mrf(data_folder)
Simulate baseline flows
In [3]:
Copied!
baseline_flows, baseline_tanks, _, _ = baseline_model.run()
baseline_flows = pd.DataFrame(baseline_flows)
baseline_tanks = pd.DataFrame(baseline_tanks)
baseline_flows, baseline_tanks, _, _ = baseline_model.run()
baseline_flows = pd.DataFrame(baseline_flows)
baseline_tanks = pd.DataFrame(baseline_tanks)
0%| | 0/1456 [00:00<?, ?it/s]
3%|█████▌ | 40/1456 [00:00<00:03, 399.91it/s]
6%|███████████▋ | 83/1456 [00:00<00:03, 415.98it/s]
9%|█████████████████▌ | 126/1456 [00:00<00:03, 420.04it/s]
12%|███████████████████████▌ | 169/1456 [00:00<00:03, 422.86it/s]
15%|█████████████████████████████▋ | 213/1456 [00:00<00:02, 427.99it/s]
18%|███████████████████████████████████▊ | 257/1456 [00:00<00:02, 429.19it/s]
21%|█████████████████████████████████████████▊ | 300/1456 [00:00<00:02, 425.71it/s]
24%|███████████████████████████████████████████████▊ | 343/1456 [00:00<00:02, 426.18it/s]
27%|█████████████████████████████████████████████████████▊ | 386/1456 [00:00<00:02, 425.17it/s]
29%|███████████████████████████████████████████████████████████▊ | 429/1456 [00:01<00:02, 388.60it/s]
32%|█████████████████████████████████████████████████████████████████▊ | 472/1456 [00:01<00:02, 399.60it/s]
36%|████████████████████████████████████████████████████████████████████████ | 517/1456 [00:01<00:02, 411.10it/s]
39%|██████████████████████████████████████████████████████████████████████████████▏ | 561/1456 [00:01<00:02, 417.39it/s]
42%|████████████████████████████████████████████████████████████████████████████████████▎ | 605/1456 [00:01<00:02, 421.94it/s]
45%|██████████████████████████████████████████████████████████████████████████████████████████▎ | 648/1456 [00:01<00:01, 424.15it/s]
47%|████████████████████████████████████████████████████████████████████████████████████████████████▎ | 691/1456 [00:01<00:01, 423.80it/s]
50%|██████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 734/1456 [00:01<00:01, 423.52it/s]
53%|████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 777/1456 [00:01<00:01, 414.86it/s]
56%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 821/1456 [00:01<00:01, 420.17it/s]
59%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌ | 865/1456 [00:02<00:01, 425.12it/s]
63%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 911/1456 [00:02<00:01, 432.10it/s]
66%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 956/1456 [00:02<00:01, 436.47it/s]
69%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▉ | 1001/1456 [00:02<00:01, 440.03it/s]
72%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 1046/1456 [00:02<00:00, 437.00it/s]
75%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏ | 1090/1456 [00:02<00:00, 434.52it/s]
78%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1134/1456 [00:02<00:00, 432.21it/s]
81%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1178/1456 [00:02<00:00, 427.49it/s]
84%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1221/1456 [00:02<00:00, 426.05it/s]
87%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1264/1456 [00:02<00:00, 425.83it/s]
90%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1307/1456 [00:03<00:00, 424.98it/s]
93%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1350/1456 [00:03<00:00, 424.48it/s]
96%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1393/1456 [00:03<00:00, 425.27it/s]
99%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏ | 1436/1456 [00:03<00:00, 424.49it/s]
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1456/1456 [00:03<00:00, 423.35it/s]
When we plot the results, we see some alarmingly low reservoir levels - I am sure that Thames Water would not be happy about this
In [4]:
Copied!
f, axs = plt.subplots(3, 1, figsize=(6, 6))
baseline_flows.groupby("arc").get_group("farmoor_to_mixer").set_index("time")[
["flow"]
].plot(ax=axs[0], title="River flow downstream of abstractions")
axs[0].set_yscale("symlog")
axs[0].set_ylim([10e3, 10e7])
baseline_flows.groupby("arc").get_group("abstraction_to_farmoor").set_index("time")[
["flow"]
].plot(ax=axs[1], title="Abstraction")
axs[1].legend()
baseline_tanks.groupby("node").get_group("farmoor").set_index("time")[["storage"]].plot(
ax=axs[2], title="Reservoir storage"
)
axs[2].legend()
f.tight_layout()
f, axs = plt.subplots(3, 1, figsize=(6, 6))
baseline_flows.groupby("arc").get_group("farmoor_to_mixer").set_index("time")[
["flow"]
].plot(ax=axs[0], title="River flow downstream of abstractions")
axs[0].set_yscale("symlog")
axs[0].set_ylim([10e3, 10e7])
baseline_flows.groupby("arc").get_group("abstraction_to_farmoor").set_index("time")[
["flow"]
].plot(ax=axs[1], title="Abstraction")
axs[1].legend()
baseline_tanks.groupby("node").get_group("farmoor").set_index("time")[["storage"]].plot(
ax=axs[2], title="Reservoir storage"
)
axs[2].legend()
f.tight_layout()
Customise arc¶
The easiest way to customise an arc is by changing its get_excess
function. This is the function that determines how much capacity there is in
the arc when called.
In reality it is common for operational constraints to be seasonal, so we will define monthly amounts that, when reservoir levels are below them, the abstraction capacity can be increased. These amounts have the month as the key and the percentage that the reservoir is full as values.
In [5]:
Copied!
levels = {
1: 0.7,
2: 0.8,
3: 0.9,
4: 0.95,
5: 0.95,
6: 0.95,
7: 0.95,
8: 0.9,
9: 0.8,
10: 0.7,
11: 0.7,
12: 0.7,
}
levels = {
1: 0.7,
2: 0.8,
3: 0.9,
4: 0.95,
5: 0.95,
6: 0.95,
7: 0.95,
8: 0.9,
9: 0.8,
10: 0.7,
11: 0.7,
12: 0.7,
}
We also need to determine what the new abstraction capacity will be, we will choose a simple multiplier on the existing capacity
In [6]:
Copied!
capacity_multiplier = 1.25
capacity_multiplier = 1.25
We can now redefine the get_excess function. We can start with a trimmed down
version of the original get_excess function:
def get_excess(self, direction, vqip = None, tag = 'default'):
pipe_excess = self.capacity - self.flow_in
node_excess = self.in_port.pull_check(vqip, tag)
excess = min(pipe_excess, node_excess['volume'])
return self.v_change_vqip(node_excess, excess)
This shows only the bits of the function that are relevant for pulls. In order to implement the new variable capacity, we will need to:
-identify the month
-identify the reservoir volume expressed as a percent
-adjust the capacity to reflect possibility of increased abstractions
In [7]:
Copied!
def get_excess_new(arc, direction, vqip=None, tag="default"):
"""
Args:
arc:
direction:
vqip:
tag:
Returns:
"""
# All nodes have access to the 't' parameter, which is a datetime object
# that can return the month
month = arc.out_port.t.month
# Get percent full
pct = arc.out_port.get_percent()
# Adjust capacity
if arc.levels[month] > pct:
capacity = arc.capacity * arc.capacity_multiplier
else:
capacity = arc.capacity
# Proceed with get_excess function as normal
pipe_excess = capacity - arc.flow_in
node_excess = arc.in_port.pull_check(vqip, tag)
excess = min(pipe_excess, node_excess["volume"])
return arc.v_change_vqip(node_excess, excess)
def get_excess_new(arc, direction, vqip=None, tag="default"):
"""
Args:
arc:
direction:
vqip:
tag:
Returns:
"""
# All nodes have access to the 't' parameter, which is a datetime object
# that can return the month
month = arc.out_port.t.month
# Get percent full
pct = arc.out_port.get_percent()
# Adjust capacity
if arc.levels[month] > pct:
capacity = arc.capacity * arc.capacity_multiplier
else:
capacity = arc.capacity
# Proceed with get_excess function as normal
pipe_excess = capacity - arc.flow_in
node_excess = arc.in_port.pull_check(vqip, tag)
excess = min(pipe_excess, node_excess["volume"])
return arc.v_change_vqip(node_excess, excess)
Finally we need a wrapper to assign the new function and the associated parameters
In [8]:
Copied!
def apply_variable_capacity(arc, levels, multiplier):
"""
Args:
arc:
levels:
multiplier:
"""
# Assign parameters
arc.levels = levels
arc.capacity_multiplier = multiplier
# Change get_excess function to new one above
arc.get_excess = lambda **x: get_excess_new(arc, **x)
def apply_variable_capacity(arc, levels, multiplier):
"""
Args:
arc:
levels:
multiplier:
"""
# Assign parameters
arc.levels = levels
arc.capacity_multiplier = multiplier
# Change get_excess function to new one above
arc.get_excess = lambda **x: get_excess_new(arc, **x)
Now we can create a new model
In [9]:
Copied!
customised_model = create_oxford_model_mrf(data_folder)
customised_model = create_oxford_model_mrf(data_folder)
.. and assign the new variable capacity
In [10]:
Copied!
apply_variable_capacity(
customised_model.arcs["abstraction_to_farmoor"], levels, capacity_multiplier
)
apply_variable_capacity(
customised_model.arcs["abstraction_to_farmoor"], levels, capacity_multiplier
)
Inspect results¶
Let us rerun and view the results to see if it has worked.
In [11]:
Copied!
flows_var_cap, tanks_var_cap, _, _ = customised_model.run()
flows_var_cap = pd.DataFrame(flows_var_cap)
tanks_var_cap = pd.DataFrame(tanks_var_cap)
flows_var_cap, tanks_var_cap, _, _ = customised_model.run()
flows_var_cap = pd.DataFrame(flows_var_cap)
tanks_var_cap = pd.DataFrame(tanks_var_cap)
0%| | 0/1456 [00:00<?, ?it/s]
3%|█████▏ | 37/1456 [00:00<00:03, 363.69it/s]
5%|██████████▎ | 74/1456 [00:00<00:03, 363.94it/s]
8%|███████████████▍ | 111/1456 [00:00<00:03, 362.77it/s]
10%|█████████████████████ | 151/1456 [00:00<00:03, 373.52it/s]
13%|██████████████████████████▎ | 189/1456 [00:00<00:03, 370.42it/s]
16%|████████████████████████████████ | 230/1456 [00:00<00:03, 381.56it/s]
18%|█████████████████████████████████████▌ | 269/1456 [00:00<00:03, 377.51it/s]
21%|██████████████████████████████████████████▊ | 307/1456 [00:00<00:03, 371.76it/s]
24%|████████████████████████████████████████████████ | 345/1456 [00:00<00:03, 361.16it/s]
26%|█████████████████████████████████████████████████████▎ | 382/1456 [00:01<00:03, 309.44it/s]
29%|█████████████████████████████████████████████████████████▊ | 415/1456 [00:01<00:03, 313.48it/s]
31%|██████████████████████████████████████████████████████████████▍ | 448/1456 [00:01<00:03, 297.23it/s]
33%|██████████████████████████████████████████████████████████████████▊ | 479/1456 [00:01<00:03, 282.11it/s]
35%|███████████████████████████████████████████████████████████████████████▌ | 513/1456 [00:01<00:03, 296.08it/s]
37%|███████████████████████████████████████████████████████████████████████████▉ | 545/1456 [00:01<00:03, 300.16it/s]
40%|████████████████████████████████████████████████████████████████████████████████▎ | 576/1456 [00:01<00:03, 264.88it/s]
41%|████████████████████████████████████████████████████████████████████████████████████▏ | 604/1456 [00:01<00:03, 256.76it/s]
43%|███████████████████████████████████████████████████████████████████████████████████████▉ | 631/1456 [00:02<00:03, 244.54it/s]
45%|███████████████████████████████████████████████████████████████████████████████████████████▍ | 656/1456 [00:02<00:03, 232.63it/s]
47%|███████████████████████████████████████████████████████████████████████████████████████████████ | 682/1456 [00:02<00:03, 238.70it/s]
49%|██████████████████████████████████████████████████████████████████████████████████████████████████▋ | 708/1456 [00:02<00:03, 242.16it/s]
50%|██████████████████████████████████████████████████████████████████████████████████████████████████████▏ | 733/1456 [00:02<00:02, 243.18it/s]
52%|█████████████████████████████████████████████████████████████████████████████████████████████████████████▉ | 760/1456 [00:02<00:02, 248.21it/s]
54%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████▋ | 787/1456 [00:02<00:02, 252.29it/s]
56%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 813/1456 [00:02<00:02, 253.62it/s]
58%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 842/1456 [00:02<00:02, 262.92it/s]
60%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▋ | 873/1456 [00:02<00:02, 275.35it/s]
62%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 904/1456 [00:03<00:01, 284.14it/s]
64%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 935/1456 [00:03<00:01, 290.94it/s]
66%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▊ | 967/1456 [00:03<00:01, 297.19it/s]
68%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 997/1456 [00:03<00:01, 292.70it/s]
71%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1027/1456 [00:03<00:01, 269.89it/s]
72%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1055/1456 [00:03<00:01, 245.17it/s]
74%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▉ | 1081/1456 [00:03<00:01, 230.57it/s]
76%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1105/1456 [00:03<00:01, 219.49it/s]
77%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1128/1456 [00:04<00:01, 213.59it/s]
79%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌ | 1150/1456 [00:04<00:01, 209.39it/s]
80%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌ | 1172/1456 [00:04<00:01, 204.59it/s]
82%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌ | 1193/1456 [00:04<00:01, 201.90it/s]
83%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1214/1456 [00:04<00:01, 194.74it/s]
85%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏ | 1234/1456 [00:04<00:01, 189.68it/s]
86%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▊ | 1253/1456 [00:04<00:01, 187.90it/s]
87%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1272/1456 [00:04<00:00, 186.84it/s]
89%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 1291/1456 [00:04<00:00, 186.33it/s]
90%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▋ | 1310/1456 [00:05<00:00, 185.81it/s]
91%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▍ | 1329/1456 [00:05<00:00, 185.60it/s]
93%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████ | 1348/1456 [00:05<00:00, 183.33it/s]
94%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▋ | 1367/1456 [00:05<00:00, 183.85it/s]
95%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▎ | 1386/1456 [00:05<00:00, 182.12it/s]
96%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▉ | 1405/1456 [00:05<00:00, 181.95it/s]
98%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▌ | 1424/1456 [00:05<00:00, 183.40it/s]
99%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▏ | 1443/1456 [00:05<00:00, 181.54it/s]
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1456/1456 [00:05<00:00, 250.17it/s]
We can see that the reservoir storage is able to recharge much more quickly from the lowest point because of the increased abstractions. We also see negligible change in river flow because the increased abstractions are mainly occurring when the flow is quite high. This is still unlikely to be a preferred option in practice because the lowest reservoir storage is unchanged. This happens because the increased capacity available is not helpful when the flows are so low that the minimum required flow is active. Better luck next time Thames Water!
In [12]:
Copied!
f, axs = plt.subplots(3, 1, figsize=(6, 6))
plot_flows1 = pd.concat(
[
baseline_flows.groupby("arc")
.get_group("farmoor_to_mixer")
.set_index("time")
.flow.rename("Baseline"),
flows_var_cap.groupby("arc")
.get_group("farmoor_to_mixer")
.set_index("time")
.flow.rename("Customised"),
],
axis=1,
)
plot_flows1.plot(ax=axs[0], title="River flow downstream of abstractions")
axs[0].set_yscale("symlog")
axs[0].set_ylim([10e3, 10e7])
plot_flows2 = pd.concat(
[
baseline_flows.groupby("arc")
.get_group("abstraction_to_farmoor")
.set_index("time")
.flow.rename("Baseline"),
flows_var_cap.groupby("arc")
.get_group("abstraction_to_farmoor")
.set_index("time")
.flow.rename("Customised"),
],
axis=1,
)
plot_flows2.plot(ax=axs[1], title="Abstraction")
axs[1].legend()
plot_tanks = pd.concat(
[
baseline_tanks.groupby("node")
.get_group("farmoor")
.set_index("time")
.storage.rename("Baseline"),
tanks_var_cap.groupby("node")
.get_group("farmoor")
.set_index("time")
.storage.rename("Customised"),
],
axis=1,
)
plot_tanks.plot(ax=axs[2], title="Reservoir storage")
axs[2].legend()
f.tight_layout()
f, axs = plt.subplots(3, 1, figsize=(6, 6))
plot_flows1 = pd.concat(
[
baseline_flows.groupby("arc")
.get_group("farmoor_to_mixer")
.set_index("time")
.flow.rename("Baseline"),
flows_var_cap.groupby("arc")
.get_group("farmoor_to_mixer")
.set_index("time")
.flow.rename("Customised"),
],
axis=1,
)
plot_flows1.plot(ax=axs[0], title="River flow downstream of abstractions")
axs[0].set_yscale("symlog")
axs[0].set_ylim([10e3, 10e7])
plot_flows2 = pd.concat(
[
baseline_flows.groupby("arc")
.get_group("abstraction_to_farmoor")
.set_index("time")
.flow.rename("Baseline"),
flows_var_cap.groupby("arc")
.get_group("abstraction_to_farmoor")
.set_index("time")
.flow.rename("Customised"),
],
axis=1,
)
plot_flows2.plot(ax=axs[1], title="Abstraction")
axs[1].legend()
plot_tanks = pd.concat(
[
baseline_tanks.groupby("node")
.get_group("farmoor")
.set_index("time")
.storage.rename("Baseline"),
tanks_var_cap.groupby("node")
.get_group("farmoor")
.set_index("time")
.storage.rename("Customised"),
],
axis=1,
)
plot_tanks.plot(ax=axs[2], title="Reservoir storage")
axs[2].legend()
f.tight_layout()
