Phase-wise with multiple lockages

Overview

Note

This example focuses on performing a phase-wise calculation of many lockages based on an input file. It assumes basic exposure to the Python interface and phase-wise calculation. If you are a first-time user of the ZSF, see the Steady-state calculation and Phase-wise calculation examples.

The purpose of this example is to understand the basic steps to perform a phase-wise calculation of many lockages. The goal is to determine the average transports of water and salt over a 60-day period.

Initializing the lock

When initializing the lock with pyzsf.ZSFUnsteady we pass all parameters that stay constant throughout the 60-day period. This includes the parameters for salt intrusion measures like the bubble screens. Note that the head on the lake side is constant, but that the head on the sea side varies. Furthermore, the salinity on both sides of the lock varies over time as well.

lock_parameters = {
    "lock_length": 300.0,
    "lock_width": 25.0,
    "lock_bottom": -7.0,
}

constant_boundary_conditions = {
    "head_lake": 0.0,
    "temperature_lake": 15.0,
    "temperature_sea": 15.0,
}

mitigation_parameters = {
    "density_current_factor_lake": 0.25,
    "density_current_factor_sea": 0.25,
    "distance_door_bubble_screen_lake": 10.0,
    "distance_door_bubble_screen_sea": 10.0,
    "flushing_discharge_high_tide": 0.0,
    "flushing_discharge_low_tide": 0.0,
    "sill_height_lake": 0.5,
}

# Initialize the lock
z = pyzsf.ZSFUnsteady(

Reading the input data

The lockages over the 60-day period are defined in a CSV-file:

Lockages

time	head_sea	routine	salinity_lake	salinity_sea	ship_volume_lake_to_sea	ship_volume_sea_to_lake	t_flushing	t_level	t_open_lake	t_open_sea
2960.0	0.03760156993333333	3	0.8554550242857143	28.529520582857142				300.0
3380.0	0.03760156993333333	4	0.8554550242857143	28.529520582857142		1884.2				420.0
3920.0	0.181197112	1	0.8979030931428571	28.558444978571426				240.0
4280.0	0.181197112	2	0.8979030931428571	28.558444978571426	2482.0				1020.0
5420.0	0.74484631	3	1.023605347	28.62057304				340.0

We read this CSV file using pandas, and convert it to a list of parameter dictionaries:

)

# Read the lockages from a file

Stepping through all lockages

Just like in the Phase-wise calculation example we step through all phases in the locking cycle. We do this by iterating over all locking-phase entries defined in the input CSV file. Depending on the respective phase, we pass either the leveling time, the door-open duration, or the duration of flushing (with the doors closed).

We store the results of every individual locking phase in a list called all_results, to be aggregated later on in the script:

lockages = list(df_lockages.to_dict("records"))

# Go through all lockages
all_results = []

for parameters in lockages:
    routine = int(parameters.pop("routine"))
    t_open_lake = parameters.pop("t_open_lake")
    t_open_sea = parameters.pop("t_open_sea")
    t_level = parameters.pop("t_level")
    t_flushing = parameters.pop("t_flushing")

    parameters["ship_volume_sea_to_lake"] = 0.0
    parameters["ship_volume_lake_to_sea"] = 0.0

    if routine == 1:
        assert t_level > 0
        results = z.step_phase_1(t_level, **parameters)
    elif routine == 2:
        results = z.step_phase_2(t_open_lake, **parameters)
    elif routine == 3:
        assert t_level > 0
        results = z.step_phase_3(t_level, **parameters)
    elif routine == 4:
        results = z.step_phase_4(t_open_sea, **parameters)
    elif routine in {-2, -4}:
        results = z.step_flush_doors_closed(t_flushing, **parameters)
    else:
        raise Exception(f"Unknown routine '{routine}'")

Aggregating output

For many cases we would only be interested in what happens on the lake side, e.g. the average salt flux in kg/s over a certain period of time. For illustrative purposes we however aggregate all outputs. For volumes and mass transports this means summing them. For discharges and salt fluxes, this means averaging them.

    all_results.append(results)

# Aggregate results
duration = 60 * 24 * 3600  # 60 days

overall_results = {}
overall_mass_to_sea = 0.0
overall_mass_to_lake = 0.0

for results in all_results:
    for k, v in results.items():
        if k.startswith(("volume_", "mass_")):
            overall_results[k] = overall_results.get(k, 0.0) + v

    overall_mass_to_sea += results["volume_to_sea"] * results["salinity_to_sea"]
    overall_mass_to_lake += results["volume_to_lake"] * results["salinity_to_lake"]

overall_results["salinity_to_sea"] = overall_mass_to_sea / overall_results["volume_to_sea"]
overall_results["salinity_to_lake"] = overall_mass_to_lake / overall_results["volume_to_lake"]

overall_discharges = {}
for k, v in overall_results.items():
    if k.startswith("volume_"):
        overall_discharges[f"discharge_{k[7:]}"] = v / duration
overall_results.update(overall_discharges)

Finally, the average fluxes are logged to the console

assert overall_results.keys() == all_results[0].keys()

# Log to console

The output should show something like:

Overall results (60 day aggregates and averages):
{'discharge_from_lake': 2.626938120554457,
 'discharge_from_sea': 2.9855208663562096,
 'discharge_to_lake': 2.7409909136666557,
 'discharge_to_sea': 2.872713264556223,
 'mass_transport_lake': -215507325.24071646,
 'mass_transport_sea': -215288300.05404428,
 'salinity_to_lake': 16.334431315958305,
 'salinity_to_sea': 13.297877648040927,
 'volume_from_lake': 13618047.216954306,
 'volume_from_sea': 15476940.17119059,
 'volume_to_lake': 14209296.896447944,
 'volume_to_sea': 14892145.563459458}

The whole script

All together, the whole example script is as follows:

import pprint

import pandas as pd

import pyzsf


lock_parameters = {
    "lock_length": 300.0,
    "lock_width": 25.0,
    "lock_bottom": -7.0,
}

constant_boundary_conditions = {
    "head_lake": 0.0,
    "temperature_lake": 15.0,
    "temperature_sea": 15.0,
}

mitigation_parameters = {
    "density_current_factor_lake": 0.25,
    "density_current_factor_sea": 0.25,
    "distance_door_bubble_screen_lake": 10.0,
    "distance_door_bubble_screen_sea": 10.0,
    "flushing_discharge_high_tide": 0.0,
    "flushing_discharge_low_tide": 0.0,
    "sill_height_lake": 0.5,
}

# Initialize the lock
z = pyzsf.ZSFUnsteady(
    15.0, 0.0, **lock_parameters, **constant_boundary_conditions, **mitigation_parameters
)

# Read the lockages from a file
df_lockages = pd.read_csv("lockages.csv", index_col=0)
lockages = list(df_lockages.to_dict("records"))

# Go through all lockages
all_results = []

for parameters in lockages:
    routine = int(parameters.pop("routine"))
    t_open_lake = parameters.pop("t_open_lake")
    t_open_sea = parameters.pop("t_open_sea")
    t_level = parameters.pop("t_level")
    t_flushing = parameters.pop("t_flushing")

    parameters["ship_volume_sea_to_lake"] = 0.0
    parameters["ship_volume_lake_to_sea"] = 0.0

    if routine == 1:
        assert t_level > 0
        results = z.step_phase_1(t_level, **parameters)
    elif routine == 2:
        results = z.step_phase_2(t_open_lake, **parameters)
    elif routine == 3:
        assert t_level > 0
        results = z.step_phase_3(t_level, **parameters)
    elif routine == 4:
        results = z.step_phase_4(t_open_sea, **parameters)
    elif routine in {-2, -4}:
        results = z.step_flush_doors_closed(t_flushing, **parameters)
    else:
        raise Exception(f"Unknown routine '{routine}'")

    all_results.append(results)

# Aggregate results
duration = 60 * 24 * 3600  # 60 days

overall_results = {}
overall_mass_to_sea = 0.0
overall_mass_to_lake = 0.0

for results in all_results:
    for k, v in results.items():
        if k.startswith(("volume_", "mass_")):
            overall_results[k] = overall_results.get(k, 0.0) + v

    overall_mass_to_sea += results["volume_to_sea"] * results["salinity_to_sea"]
    overall_mass_to_lake += results["volume_to_lake"] * results["salinity_to_lake"]

overall_results["salinity_to_sea"] = overall_mass_to_sea / overall_results["volume_to_sea"]
overall_results["salinity_to_lake"] = overall_mass_to_lake / overall_results["volume_to_lake"]

overall_discharges = {}
for k, v in overall_results.items():
    if k.startswith("volume_"):
        overall_discharges[f"discharge_{k[7:]}"] = v / duration
overall_results.update(overall_discharges)

assert overall_results.keys() == all_results[0].keys()

# Log to console
print("Overall results (60 day aggregates and averages):")
pprint.pprint(overall_results)