tsnet.simulation package¶

Submodules¶

tsnet.simulation.initialize module¶

The tsnet.simulation.initialize contains functions to 1. Initialize the list containing numpy arrays for velocity and head. 2. Calculate initial conditions using Epanet engine. 3. Calculate D-W coefficients based on initial conditions. 4. Calculate demand coefficients based on initial conditions.

tsnet.simulation.initialize.Initializer(tm, t0, engine='DD')[source]¶

Initial Condition Calculation.

Initialize the list containing numpy arrays for velocity and head. Calculate initial conditions using Epanet engine. Calculate D-W coefficients based on initial conditions. Calculate demand coefficients based on initial conditions.

Parameters:	tm (tsnet.network.geometry.TransientModel) – Simulated network t0 (float) – time to calculate initial condition engine (string) – steady state calculation engine: DD: demand driven; PDD: pressure dependent demand, by default DD
Returns:	tm – Network with updated parameters
Return type:	tsnet.network.geometry.TransientModel

tsnet.simulation.initialize.cal_demand_coef(demand, pipe, Hs, He, t0=0.0)[source]¶

Calculate the demand coefficient for the start and end node of the pipe.

Parameters:	demand (list) – Demand at the start (demand[0]) and end demand[1] node pipe (object) – Pipe object Hs (float) – Head at the start node He (float) – Head at the end node t0 (float, optional) – Time to start initial condition calculation, by default 0
Returns:	pipe – Pipe object with calculated demand coefficient
Return type:	object

tsnet.simulation.initialize.cal_roughness_coef(pipe, V, hl)[source]¶

Calculate the D-W roughness coefficient based on initial conditions.

Parameters:	pipe (object) – Pipe object V (float) – Initial flow velocity in the pipe hl (float) – Initial head loss in the pipe
Returns:	pipe – Pipe object with calculated D-W roughness coefficient.
Return type:	object

tsnet.simulation.initialize.pump_operation_points(tm)[source]¶

tsnet.simulation.main module¶

The tsnet.simulation.main module contains function to perform the workflow of read, discretize, initial, and transient simulation for the given .inp file.

tsnet.simulation.main.MOCSimulator(tm, results_obj='results', friction='steady')[source]¶

MOC Main Function

Parameters:	tm (tsnet.network.model.TransientModel) – Network results_obj (string, optional) – the name of the results file, by default ‘results’ friction (string, optional) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
Returns:	tm – Simulated network
Return type:	tsnet.network.model.TransientModel

tsnet.simulation.single module¶

The tsnet.simulation.single contains methods to perform MOC transient simulation on a single pipe, including 1. inner pipe 2. left boundary pipe (without C- charateristic grid) 3. right boundary pipe (without C+ characteristic grid)

tsnet.simulation.single.inner_pipe(linkp, pn, dt, links1, links2, utype, dtype, p, H0, V0, H, V, H10, V10, H20, V20, pump, valve, friction, dVdt, dVdx, dVdt10, dVdx10, dVdt20, dVdx20)[source]¶

MOC solution for an individual inner pipe.

Parameters:

linkp (object) – Current pipe object
pn (int) – Current pipe ID
dt (float) – Time step
H (numpy.ndarray) – Head of current pipe at current time step [m]
V (numpy.ndarray) – Velocity of current pipe at current time step [m/s]
links1 (list) – Upstream adjacent pipes
links2 (list) – Downstream adjacent pipes
utype (list) – Upstream adjacent link type, and if not pipe, their name
dtype (list) – Downstream adjacent link type, and if not pipe, their name
p (list) – pipe list
H0 (numpy.ndarray) – Head of current pipe at previous time step [m]
V0 (numpy.ndarray) – Velocity of current pipe at previous time step [m/s]
H10 (list) – Head of left adjacent nodes at previous time step [m]
V10 (list) – Velocity of left adjacent nodes at previous time step [m/s]
H20 (list) – Head of right adjacent nodes at previous time step [m]
V20 (list) – Velocity of right adjacent nodes at previous time step [m/s]
pump (list) – Characteristics of the pump
valve (list) – Characteristics of the valve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdt (numpy.ndarray) – local instantaneous acceleration approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]
dVdx (numpy.ndarray) – convective instantaneous acceleration approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]
dVdt10 (list) – local instantaneous acceleration of left adjacent nodes at previous time step [m]
dVdx10 (list) – convective instantaneous acceleration of left adjacent nodes at previous time step [m/s]
dVdt20 (list) – local instantaneous acceleration of right adjacent nodes at previous time step [m]
dVdx20 (list) – convective instantaneous acceleration of right adjacent nodes at previous time step [m/s]

Returns:

H (numpy.ndarray) – Head results of the current pipe at current time step. [m]
V (numpy.ndarray) – Velocity results of the current pipe at current time step. [m/s]

tsnet.simulation.single.left_boundary(linkp, pn, H, V, H0, V0, links2, p, pump, valve, dt, H20, V20, utype, dtype, friction, dVdt, dVdx, dVdt20, dVdx20)[source]¶

MOC solution for an individual left boundary pipe.

Parameters:

linkp (object) – Current pipe object
pn (int) – Current pipe ID
H (numpy.ndarray) – Head of current pipe at current time step [m]
V (numpy.ndarray) – Velocity of current pipe at current time step [m/s]
links2 (list) – Downstream adjacent pipes
p (list) – pipe list
pump (list) – Characteristics of the pump
valve (list) – Characteristics of the valve
n (int) – Number of discretization of current pipe
dt (float) – Time step
H0 (numpy.ndarray) – Head of current pipe at previous time step [m]
V0 (numpy.ndarray) – Velocity of current pipe at previous time step [m/s]
H20 (list) – Head of right adjacent nodes at previous time step [m]
V20 (list) – Velocity of right adjacent nodes at previous time step [m/s]
utype (list) – Upstream adjacent link type, and if not pipe, their name
dtype (list) – Downstream adjacent link type, and if not pipe, their name
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdt (numpy.ndarray) – local instantaneous velocity approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]
dVdx (numpy.ndarray) – convective instantaneous velocity approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]
dVdt20 (list) – local instantaneous acceleration of right adjacent nodes at previous time step [m]
dVdx20 (list) – convective instantaneous acceleration of right adjacent nodes at previous time step [m/s]

Returns:

H (numpy.ndarray) – Head results of the current pipe at current time step. [m]
V (numpy.ndarray) – Velocity results of the current pipe at current time step. [m/s]

tsnet.simulation.single.right_boundary(linkp, pn, H0, V0, H, V, links1, p, pump, valve, dt, H10, V10, utype, dtype, friction, dVdt, dVdx, dVdt10, dVdx10)[source]¶

MOC solution for an individual right boundary pipe.

linkp : object

Current pipe object

pn : int

Current pipe ID

H : numpy.ndarray

Head of current pipe at current time step [m]

V : numpy.ndarray

Velocity of current pipe at current time step [m/s]

links1 : list

Upstream adjacent pipes

p : list

pipe list

pump : list

Characteristics of the pump

valve : list

Characteristics of the valve

n : int

Number of discretization of current pipe

dt : float

Time step

H0 : numpy.ndarray

Head of current pipe at previous time step [m]

V0 : numpy.ndarray

Velocity of current pipe at previous time step [m/s]

H10 : list

Head of left adjacent nodes at previous time step [m]

V10 : list

Velocity of left adjacent nodes at previous time step [m/s]

utype : list

Upstream adjacent link type, and if not pipe, their name

dtype : list

Downstream adjacent link type, and if not pipe, their name

friction: str

friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’

dVdt: numpy.ndarray

local instantaneous velocity approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]

dVdx: numpy.ndarray

convective instantaneous velocity approximation to be used for unsteady friction calculation, 0 if not in unsteady friction mode [m/s^2]

dVdt10 : list

local instantaneous acceleration of left adjacent nodes at previous time step [m]

dVdx10 : list

convective instantaneous acceleration of left adjacent nodes at previous time step [m/s]

Returns

H : numpy.ndarray: Head results of the current pipe at current time step. [m]
V : numpy.ndarray: Velocity results of the current pipe at current time step. [m/s]

tsnet.simulation.solver module¶

The tsnet.simulation.solver module contains methods to solver MOC for different grid configurations, including: 1. inner_node 2. valve_node 3. pump_node 4. source_pump 5. valve_end 6. dead_end 7. rev_end 8. add_leakage

tsnet.simulation.solver.Reynold(V, D)[source]¶

Calculate Reynold number

Parameters:	V (float) – velocity D (float) – diameter
Returns:	Re – Reynold number
Return type:	float

tsnet.simulation.solver.quasi_steady_friction_factor(Re, KD)[source]¶

Update friction factor based on Reynold number

Parameters:	Re (float) – velocity KD (float) – relative roughness height (K/D)
Returns:	f – quasi-steady friction factor
Return type:	float

tsnet.simulation.solver.unsteady_friction(Re, dVdt, dVdx, V, a, g)[source]¶

Calculate unsteady friction

Parameters:	Re (float) – velocity dVdt (float) – local instantaneous acceleration dVdx (float) – instantaneous convective acceleration V (float) – velocity a (float) – wave speed g (float) – gravitational acceleration
Returns:	Ju – unsteady friction factor
Return type:	float

tsnet.simulation.solver.cal_friction(friction, f, D, V, KD, dt, dVdt, dVdx, a, g)[source]¶

Calculate friction term

Parameters:	friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’ f (float) – steady friction factor D (float) – pipe diameter V (float) – pipe flow velocity KD (float) – relative roughness height dt (float) – time step dVdt (float) – local instantaneous acceleration dVdx (float) – convective instantaneous acceleration a (float) – wave speed g (float) – gravitational accelerations
Returns:	total friction, including steady and unsteady
Return type:	float

tsnet.simulation.solver.cal_Cs(link1, link2, H1, V1, H2, V2, s1, s2, g, dt, friction, dVdx1, dVdx2, dVdt1, dVdt2)[source]¶

Calculate coefficients for MOC characteristic lines

Parameters:

link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

Returns:

A1 (list) – list of left adjacent pipe cross-section area
A2 (list) – list of right adjacent pipe cross-section area
C1 (list) – list of left adjacent pipe MOC coefficients
C2 (list) – list of right adjacent pipe MOC coefficients

tsnet.simulation.solver.inner_node_unsteady(link, H0, V0, dt, g, dVdx, dVdt)[source]¶

Inner boundary MOC using C+ and C- characteristic curve with unsteady friction

Parameters:

link (object) – current pipe
H0 (list) – head at previous time step
V0 (list) – velocity at previous time step
dt (float) – Time step
g (float) – Gravity acceleration
dVdx (list) – List of convective instantaneous acceleration
dVdt (list) – List of local instantaneous acceleration

Returns:

HP (float) – Head at current pipe inner nodes at current time
VP (float) – Velocity at current pipe inner nodes at current time

tsnet.simulation.solver.inner_node_quasisteady(link, H0, V0, dt, g)[source]¶

Inner boundary MOC using C+ and C- characteristic curve with unsteady friction

Parameters:

link (object) – current pipe
H0 (list) – head at previous time step
V0 (list) – velocity at previous time step
dt (float) – Time step
g (float) – Gravity acceleration
dVdx (list) – List of convective instantaneous acceleration
dVdt (list) – List of local instantaneous acceleration

Returns:

HP (float) – Head at current pipe inner nodes at current time
VP (float) – Velocity at current pipe inner nodes at current time

tsnet.simulation.solver.inner_node_steady(link, H0, V0, dt, g)[source]¶

Inner boundary MOC using C+ and C- characteristic curve with unsteady friction

Parameters:

link (object) – current pipe
H0 (list) – head at previous time step
V0 (list) – velocity at previous time step
dt (float) – Time step
g (float) – Gravity acceleration

Returns:

HP (float) – Head at current pipe inner nodes at current time
VP (float) – Velocity at current pipe inner nodes at current time

tsnet.simulation.solver.valve_node(KL_inv, link1, link2, H1, V1, H2, V2, dt, g, nn, s1, s2, friction, dVdx1, dVdx2, dVdt1, dVdt2)[source]¶

Inline valve node MOC calculation

Parameters:

KL_inv (int) – Inverse of the valve loss coefficient at current time
link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
nn (int) – The index of the calculation node
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.pump_node(pumpc, link1, link2, H1, V1, H2, V2, dt, g, nn, s1, s2, friction, dVdx1, dVdx2, dVdt1, dVdt2)[source]¶

Inline pump node MOC calculation

Parameters:

pumpc (list) – Parameters (a, b,c) to define pump characteristic cure, so that .. math:: h_p = a*Q**2 + b*Q + c
link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
nn (int) – The index of the calculation node
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.source_pump(pump, link2, H2, V2, dt, g, s2, friction, dVdx2, dVdt2)[source]¶

Source Pump boundary MOC calculation

Parameters:

pump (list) – pump[0]: elevation of the reservoir/tank pump[1]: Parameters (a, b,c) to define pump characteristic cure, so that .. math:: h_p = a*Q**2 + b*Q + c
link2 (object) – Pipe object of C- charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.valve_end(H1, V1, V, nn, a, g, f, D, dt, KD, friction, dVdx2, dVdt2)[source]¶

End Valve boundary MOC calculation

Parameters:

H1 (float) – Head of the C+ charateristics curve
V1 (float) – Velocity of the C+ charateristics curve
V (float) – Velocity at the valve end at current time
nn (int) – The index of the calculation node
a (float) – Wave speed at the valve end
g (float) – Gravity acceleration
f (float) – friction factor of the current pipe
D (float) – diameter of the current pipe
dt (float) – Time step
KD (float) – relative roughness height
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.dead_end(linkp, H1, V1, elev, nn, a, g, f, D, dt, KD, friction, dVdx1, dVdt1)[source]¶

Dead end boundary MOC calculation with pressure dependant demand

Parameters:

linkp (object) – Current pipe
H1 (float) – Head of the C+ charateristics curve
V1 (float) – Velocity of the C+ charateristics curve
elev (float) – Elevation at the dead end node
nn (int) – The index of the calculation node
a (float) – Wave speed at the valve end
g (float) – Gravity acceleration
f (float) – friction factor of the current pipe
D (float) – diameter of the current pipe
dt (float) – Time step
KD (float) – relative roughness height
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve

tsnet.simulation.solver.rev_end(H2, V2, H, nn, a, g, f, D, dt, KD, friction, dVdx2, dVdt2)[source]¶

Reservoir/ Tank boundary MOC calculation

Parameters:

H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
H (float) – Head of the reservoir/tank
nn (int) – The index of the calculation node
a (float) – Wave speed at the valve end
g (float) – Gravity acceleration
f (float) – friction factor of the current pipe
D (float) – diameter of the current pipe
dt (float) – Time step
KD (float) – relative roughness height
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.add_leakage(emitter_coef, block_per, link1, link2, elev, H1, V1, H2, V2, dt, g, nn, s1, s2, friction, dVdx1=0, dVdx2=0, dVdt1=0, dVdt2=0)[source]¶

Leakage Node MOC calculation

Parameters:

emitter_coef (float) – float, optional Required if leak_loc is defined The leakage coefficient of the leakage .. math:: Q_leak = leak_A [ m^3/s/(m H20)^(1/2)] * sqrt(H)
link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
nn (int) – The index of the calculation node
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.surge_tank(tank, link1, link2, H1, V1, H2, V2, dt, g, nn, s1, s2, friction, dVdx1, dVdx2, dVdt1, dVdt2)[source]¶

Surge tank node MOC calculation

Parameters:

tank (int) –
tank shape parameters [As, z, Qs]

As : cross-sectional area of the surge tank z : water level in the surge tank at previous time step Qs : water flow into the tank at last time step
link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
nn (int) – The index of the calculation node
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

tsnet.simulation.solver.air_chamber(tank, link1, link2, H1, V1, H2, V2, dt, g, nn, s1, s2, friction, dVdx1, dVdx2, dVdt1, dVdt2)[source]¶

Surge tank node MOC calculation

Parameters:

tank (int) –
tank shape parameters [As, ht, C, z, Qs]

As : cross-sectional area of the surge tank ht : tank height C : air constant z : water level in the surge tank at previous time step Qs : water flow into the tank at last time step
link1 (object) – Pipe object of C+ charateristics curve
link2 (object) – Pipe object of C- charateristics curve
H1 (list) – List of the head of C+ charateristics curve
V1 (list) – List of the velocity of C+ charateristics curve
H2 (list) – List of the head of C- charateristics curve
V2 (list) – List of the velocity of C- charateristics curve
dt (float) – Time step
g (float) – Gravity acceleration
nn (int) – The index of the calculation node
s1 (list) – List of signs that represent the direction of the flow in C+ charateristics curve
s2 (list) – List of signs that represent the direction of the flow in C- charateristics curve
friction (str) – friction model, e.g., ‘steady’, ‘quasi-steady’, ‘unsteady’, by default ‘steady’
dVdx1 (list) – List of convective instantaneous acceleration on the C+ characteristic curve
dVdx2 (list) – List of convective instantaneous acceleration on the C- characteristic curve
dVdt1 (list) – List of local instantaneous acceleration on the C+ characteristic curve
dVdt2 (list) – List of local instantaneous acceleration on the C- characteristic curve

Module contents¶

The tsnet.simulation package contains methods to run transient simulation using MOC method