### TSNet: Valve Closure Simulation Setup

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates the initial setup for simulating valve closure in a network using the TSNet package. It covers importing the library, reading an EPANET INP file, and creating a transient model object.

```python
import TSNet

tm = TSNet.TransientModel('network.inp')
```

--------------------------------

### Tnet1_valve_closure.py Example

Source: https://github.com/glorialulu/tsnet/blob/master/docs/usage.rst

A Python script demonstrating a simple transient simulation using tsnet. It covers model generation, setting wave speed and time step, initial condition calculation, defining valve closure, running the simulation, saving results, and plotting.

```python
import tsnet

# Generate a transient model
# Set wave speed
# Set time step and simulation period
# Perform initial condition calculation
# Define valve closure rule
# Run transient simulation and save results to .obj file
# Plot simulation results
```

--------------------------------

### TSNet: Pump Shutdown Simulation Setup

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows the initial steps for setting up a pump shutdown simulation using the TSNet package. It includes importing the library, reading the network file, and creating the transient model object.

```python
import TSNet

tm = TSNet.TransientModel('network.inp')
```

--------------------------------

### TSNet Burst and Leak Simulation - Set Up Burst

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Sets up a burst event at a specific junction (JUNCTION-20), defining the start time, development time, and final emitter coefficient.

```python
ts = 5
tc = 10
final_burst_coeff = 0.5
tm.set_burst('JUNCTION-20', ts, tc, final_burst_coeff)

```

--------------------------------

### Import tsnet Package

Source: https://github.com/glorialulu/tsnet/blob/master/docs/usage.rst

Demonstrates the basic import statement required to use the tsnet package in a Python console.

```python
import tsnet
```

--------------------------------

### Set Up Virtual Environment and Install TSNet

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Steps to set up a virtual environment using virtualenvwrapper and install the local copy of TSNet in development mode.

```shell
$ mkvirtualenv TSNet
$ cd TSNet/
$ python setup.py develop
```

--------------------------------

### Install TSNet from Source

Source: https://github.com/glorialulu/tsnet/blob/master/docs/installation.rst

Installs TSNet after downloading the source code (either via git clone or tarball). This command should be run from the root directory of the TSNet source code.

```python
python setup.py install
```

--------------------------------

### Install TSNet Stable Release

Source: https://github.com/glorialulu/tsnet/blob/master/docs/installation.rst

Installs the most recent stable release of TSNet using pip. This is the recommended method for general users. Ensure you have pip installed.

```console
$ pip install tsnet
```

--------------------------------

### TSNet: Accessing Node Flowrate Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates how to access and print the time history of flow rate at the start node of a specific pipe (P2) after a TSNet transient simulation.

```python
print(tm.links['P2'].start_node_flowrate)
```

--------------------------------

### TSNet: Run Transient Simulation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows how to execute the transient simulation using the TSNet package and specify the output file name for the results.

```python
tm.run_transient_simulation('Tnet1_results.out')
```

--------------------------------

### Install NetworkX and WNTR

Source: https://github.com/glorialulu/tsnet/blob/master/docs/installation.rst

Installs the NetworkX and WNTR Python packages, which are dependencies for TSNet. These commands are run from a Python-enabled command line.

```console
pip install wntr
pip install -U pytest
```

--------------------------------

### TSNet: Valve Closure Operating Rules

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet illustrates how to define the operating rules for a valve closure simulation in TSNet. It specifies parameters like closure time (tc), start time (ts), final opening percentage (se), and closure curve shape (m).

```python
tm.set_valve_operating_rule('V1', tc=2.0, ts=5.0, se=0.1, m=1)
```

--------------------------------

### Run a Subset of Tests

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Example command to run a specific subset of tests using py.test.

```shell
$ py.test .\tests\test_tsnet.py
```

--------------------------------

### TSNet: Compute Steady State

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates the step to compute the steady-state conditions for a transient simulation using the TSNet package. This is crucial for establishing the initial conditions.

```python
tm.compute_steady_state()
```

--------------------------------

### Download TSNet Tarball

Source: https://github.com/glorialulu/tsnet/blob/master/docs/installation.rst

Downloads the TSNet source code as a tarball from the master branch on GitHub. This is an alternative for obtaining the source code.

```console
$ curl  -OL https://github.com/glorialulu/tsnet/tarball/master
```

--------------------------------

### TSNet Burst and Leak Simulation - Run Simulation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Runs the transient simulation and specifies the name of the results file.

```python
tm.set_transient(0.01)
tm.set_results_write('Tnet3_results.txt')
tm.execute()

```

--------------------------------

### Clone TSNet Repository

Source: https://github.com/glorialulu/tsnet/blob/master/docs/installation.rst

Clones the public Git repository for TSNet. This is useful for developers who want to access the source code directly.

```console
$ git clone git://github.com/glorialulu/tsnet
```

--------------------------------

### TSNet: Run Pump Shutdown Simulation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows how to run the transient simulation for a pump shutdown scenario using TSNet and specify the output results file.

```python
tm.run_transient_simulation('Tnet2_results.out')
```

--------------------------------

### Accessing Link Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/results.rst

Shows how to get head and flow rate information at both the start and end nodes of a specific pipe from the TransientModel object.

```python
pipe = tm.get_link('LINK-40')
start_head = pipe.start_node_head
end_head = pipe.end_node_head
start_velocity = pipe.start_node_velocity
end_velocity = pipe.end_node_velocity
start_flowrate = pipe.start_node_flowrate
end_flowrate = pipe.end_node_flowrate
```

--------------------------------

### TSNet Burst and Leak Simulation - Initialization

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Initializes the TSNet model for a burst and leak simulation. This includes reading the EPANET INP file and setting up the transient model object.

```python
import tsnet

tm = tsnet.TransientModel()
tm.read_inpfile('Tnet3.inp')

```

--------------------------------

### TSNet Pump Shutdown Example

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates a pump shutdown scenario using the TSNet library. It focuses on the simulation logic related to pump behavior and its impact on the network.

```python
import tsnet

tm = tsnet.TransientModel()
tm.read_inpfile('Tnet2.inp')
tm.set_sim_time(100)
tm.set_hydraulics()
tm.set_transient(0.01)
tm.set_pump_shutdown(1, 10)
tm.set_results_write(1)
tm.execute()

```

--------------------------------

### TSNet: Valve Closure Simulation Parameters

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows how to configure simulation parameters for a transient valve closure analysis using TSNet. It includes setting wave speed, time step, and the overall simulation period.

```python
tm.set_wave_speed(1200)
tm.set_time_step(0.1)
tm.set_simulation_period(60)
```

--------------------------------

### TSNet Burst and Leak Simulation - Wave Speed Assignment

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Assigns custom wave speeds to pipes in the TSNet model. This example demonstrates assigning normally distributed wave speeds to each pipe.

```python
import numpy as np

wave_speed = np.random.normal(1200, 100, tm.pipe_count)
tm.set_wave_speed(wave_speed)
tm.set_sim_time(20)
tm.set_hydraulics()

```

--------------------------------

### TSNet: Plotting Pipe Flowrate Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates how to plot the flow rate results in a specific pipe (P2) over time after a TSNet transient simulation.

```python
import matplotlib.pyplot as plt

plt.figure()
plt.plot(tm.time, tm.links['P2'].start_node_flowrate, label='Start Node Flowrate')
plt.plot(tm.time, tm.links['P2'].end_node_flowrate, label='End Node Flowrate')
plt.xlabel('Time (s)')
plt.ylabel('Flow Rate (m^3/s)')
plt.title('Flow Rate in Pipe P2')
plt.legend()
plt.grid(True)
plt.show()
```

--------------------------------

### TSNet: Pump Shutdown Operating Rules

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet illustrates how to define the operating rules for a pump shutdown simulation in TSNet. Parameters include shutdown time (tc), start time (ts), final speed multiplier (se), and shutdown curve shape (m).

```python
tm.set_pump_operating_rule('PUMP2', tc=5.0, ts=10.0, se=0.0, m=1)
```

--------------------------------

### TSNet: Pump Shutdown Simulation Parameters

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates setting simulation parameters for a pump shutdown scenario in TSNet. It includes wave speed and simulation period.

```python
tm.set_wave_speed(1200)
tm.set_simulation_period(50)
```

--------------------------------

### TSNet Burst and Leak Simulation - Compute Steady State

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Computes the steady-state results of the network to establish the initial conditions for the transient simulation.

```python
tm.set_steady_state()

```

--------------------------------

### TSNet Burst and Leak Simulation - Plot Velocity

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Plots the velocity results in LINK-40 to analyze flow dynamics during the transient event.

```python
import matplotlib.pyplot as plt

velocity = tm.get_link_velocity('LINK-40')
time = tm.get_time()

plt.plot(time, velocity)
plt.xlabel('Time (s)')
plt.ylabel('Velocity (m/s)')
plt.title('Tnet3 - Velocity in LINK-40')
plt.grid(True)
plt.show()

```

--------------------------------

### MOC Time Step Calculation Example

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Demonstrates the calculation of the maximum time step and the number of computation units required for a simulation based on pipe network configuration. It highlights how these factors reduce the total number of computation nodes needed for a given simulation duration.

```math
Maximum Time Step = 0.5s
Number of computation units for pipes 1 and 2 = 2 and 4, respectively.
Total computation units = 2 + 4 = 6.
Simulation duration = 10s.
Total computation nodes = (Simulation duration / Maximum Time Step) * Total computation units
Total computation nodes = (10s / 0.5s) * 6 = 20 * 6 = 120 (Note: The text states 26, implying a different calculation or interpretation of 'computation nodes').
```

--------------------------------

### Pump Operations (Shut-off and Start-up)

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Enables simulation of controlled pump operations, including shut-off and start-up. Parameters are similar to valve operations, defining the period, start time, end state, and operation constant.

```python
tc = 1 # pump closure period
ts = 0 # pump closure start time
se = 0 # end open percentage
m = 1 # closure constant
pump_op = [tc,ts,se,m]
tm.pump_shut_off('PUMP2', pump_op)
```

```python
tc = 1 # pump opening period [s]
ts = 0 # pump opening start time [s]
se = 1 # end open percentage [s]
m = 1 # opening constant [dimensionless]
pump_op = [tc,ts,se,m]
tm.pump_start_up('PUMP2',pump_op)
```

--------------------------------

### TSNet: Plotting Node Head Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows the Python code used to plot the head results at a specific node (N3) after a TSNet transient simulation.

```python
import matplotlib.pyplot as plt

plt.figure()
plt.plot(tm.time, tm.nodes['N3'].head)
plt.xlabel('Time (s)')
plt.ylabel('Head (m)')
plt.title('Head at Node N3')
plt.grid(True)
plt.show()
```

--------------------------------

### TSNet Burst and Leak Simulation - Plot Head at Multiple Nodes

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Plots the head results at multiple junctions (JUNCTION-8, JUNCTION-16, JUNCTION-45, JUNCTION-90) to observe pressure transients across the network.

```python
import matplotlib.pyplot as plt

head_8 = tm.get_node_head('JUNCTION-8')
head_16 = tm.get_node_head('JUNCTION-16')
head_45 = tm.get_node_head('JUNCTION-45')
head_90 = tm.get_node_head('JUNCTION-90')
time = tm.get_time()

plt.plot(time, head_8, label='JUNCTION-8')
plt.plot(time, head_16, label='JUNCTION-16')
plt.plot(time, head_45, label='JUNCTION-45')
plt.plot(time, head_90, label='JUNCTION-90')
plt.xlabel('Time (s)')
plt.ylabel('Head (m)')
plt.title('Tnet3 - Head at Multiple Junctions')
plt.legend()
plt.grid(True)
plt.show()

```

--------------------------------

### TSNet: Accessing Node Demand Discharge Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet demonstrates how to retrieve and print the demand discharge at a specific node (JUNCTION-105) over the simulation period after a TSNet transient simulation.

```python
print(tm.nodes['JUNCTION-105'].demand_discharge)
```

--------------------------------

### Plotting Simulation Results

Source: https://github.com/glorialulu/tsnet/blob/master/docs/results.rst

Provides an example of plotting simulation results (e.g., head) against time stamps using matplotlib.

```python
import matplotlib.pyplot as plt
plt.plot(tt ,head)
```

--------------------------------

### TSNet Burst and Leak Simulation - Plot Burst Discharge

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Plots the burst discharge results at JUNCTION-20 to analyze water loss due to the burst event.

```python
import matplotlib.pyplot as plt

burst_discharge = tm.get_burst_discharge('JUNCTION-20')
time = tm.get_time()

plt.plot(time, burst_discharge)
plt.xlabel('Time (s)')
plt.ylabel('Burst Discharge (m^3/s)')
plt.title('Tnet3 - Burst Discharge at JUNCTION-20')
plt.grid(True)
plt.show()

```

--------------------------------

### TSNet: Plotting Node Head Results for Pump Shutdown

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

This snippet shows the Python code to plot the head results at a specific node (JUNCTION-105) during a pump shutdown simulation using TSNet.

```python
import matplotlib.pyplot as plt

plt.figure()
plt.plot(tm.time, tm.nodes['JUNCTION-105'].head)
plt.xlabel('Time (s)')
plt.ylabel('Head (m)')
plt.title('Head at JUNCTION-105 during Pump Shutdown')
plt.grid(True)
plt.show()
```

--------------------------------

### TSNet Burst and Leak Simulation - Plot Leak Discharge

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Plots the leak discharge results at JUNCTION-22 to analyze water loss due to the background leak.

```python
import matplotlib.pyplot as plt

leak_discharge = tm.get_leak_discharge('JUNCTION-22')
time = tm.get_time()

plt.plot(time, leak_discharge)
plt.xlabel('Time (s)')
plt.ylabel('Leak Discharge (m^3/s)')
plt.title('Tnet3 - Leak Discharge at JUNCTION-22')
plt.grid(True)
plt.show()

```

--------------------------------

### TSNet Burst and Leak Simulation - Define Leak

Source: https://github.com/glorialulu/tsnet/blob/master/docs/examples.rst

Defines a background leak at a specific junction (JUNCTION-22) and sets its emitter coefficient. This leak is included in the initial condition calculation.

```python
tm.set_leak('JUNCTION-22', 0.01)

```

--------------------------------

### tsnet.simulation.initialize Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.simulation.rst

Details the functions and classes within the tsnet.simulation.initialize module, including any undocumented members and inheritance hierarchies. This module is likely responsible for setting up simulation parameters and initial states.

```python
import tsnet.simulation.initialize

# Access members and documentation for tsnet.simulation.initialize
# Example: help(tsnet.simulation.initialize)
```

--------------------------------

### Clone TSNet Repository

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Instructions for cloning the TSNet repository locally after forking it on GitHub.

```shell
$ git clone git@github.com:your_name_here/TSNet.git
```

--------------------------------

### tsnet.simulation.main Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.simulation.rst

Provides documentation for the tsnet.simulation.main module, which contains the primary logic for running simulations. It lists all members, undocumented members, and inheritance information.

```python
import tsnet.simulation.main

# Access members and documentation for tsnet.simulation.main
# Example: help(tsnet.simulation.main)
```

--------------------------------

### Initialize Transient Simulation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Sets up the initial conditions for a transient simulation by running a steady-state hydraulics simulation. Supports Demand-Driven (DD) or Pressure-Dependent Demand (PDD) engines.

```python
t0 = 0. # initialize the simulation at 0 [s]
engine = 'DD' # demand driven simulator
tm = tsnet.simulation.Initializer(tm, t0, engine)
```

--------------------------------

### TSNet Overview and Features

Source: https://github.com/glorialulu/tsnet/blob/master/README.rst

Provides a high-level overview of the TSNet package, its purpose in transient simulation of water networks, and its key features. It highlights the open-source nature and flexibility compared to commercial software.

```text
TSNet performs transient simulation in water networks using Method of Characteristics (MOC).

Features:
* Create water network models based on .inp files
* Generate transient events by operating valves and pumps
* Add disruptive events including pipe bursts and leakages
* Add surge protection devices
* Choose between steady,quasi-steady, and unsteady friction models
* Perform transient simulation using MOC method
* Visualize results
```

--------------------------------

### Add Burst to Network

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Simulates a burst event by defining its start time, development time, and final emitter coefficient. Bursts occur only during transient calculations.

```python
ts = 1 # burst start time
tc = 1 # time for burst to fully develop
final_burst_coeff = 0.01 # final burst coeff [ m^3/s/(m H20)^(1/2)]
tm.add_burst('JUNCTION-20', ts, tc, final_burst_coeff)
```

--------------------------------

### Deploying Changes

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Commands for maintainers to deploy changes, including version bumping, pushing commits and tags, which triggers Travis CI for PyPI deployment.

```shell
$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags
```

--------------------------------

### tsnet.simulation Module Contents

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.simulation.rst

Provides a comprehensive overview of the tsnet.simulation package itself, listing all its members, undocumented members, and inheritance structures across its submodules.

```python
import tsnet.simulation

# Access members and documentation for the tsnet.simulation package
# Example: help(tsnet.simulation)
```

--------------------------------

### TSNet API Documentation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Provides an overview of key classes and their functionalities within the TSNet library for transient water network simulation.

```APIDOC
tsnet.network.TransientModel:
  __init__(inp_file: str)
    Initializes a transient model from an EPANET INP file.
    Parameters:
      inp_file: Path to the EPANET INP file.

  Adds features for transient simulation beyond the base WNTR model, including spatial discretization, temporal discretization, valve/pump/burst operation rules, surge tanks, and time history results storage.

tsnet.simulation.Initializer:
  __init__(tm: tsnet.network.TransientModel, t0: float, engine: str = 'DD')
    Initializes the transient simulation by calculating steady-state conditions.
    Parameters:
      tm: The TransientModel object.
      t0: The time [s] at which to calculate the initial condition.
      engine: The hydraulic simulation engine ('DD' for Demand-Driven, 'PDD' for Pressure-Dependent Demand).

  Uses WNTR for steady-state simulations.

tsnet.simulation.MOCSimulator:
  __init__(tm: tsnet.network.TransientModel, results_obj: str)
    Runs the transient simulation using the Method of Characteristics (MOC).
    Parameters:
      tm: The initialized TransientModel object.
      results_obj: The name for saving simulation results.

  Solves transient flow equations using MOC. Stores results in a '.obj' file.

Governing Equations:
  Mass Conservation:
    d(H)/dt + (a^2/g) * d(V)/dx - g*V*sin(alpha) = 0
  Momentum Conservation:
    (1/g) * d(V)/dt + d(H)/dx + h_f = 0
    where H is head, V is flow velocity, t is time, a is wave speed, g is gravity, alpha is pipe slope, and h_f is head loss per unit length.

Method of Characteristics (MOC):
  Transforms partial differential equations into ordinary differential equations along characteristic lines (C+ and C-).
  C+:
    dV/dt + (g/a) * dH/dt + g*h_f - (g/a)*V*sin(alpha) = 0  along dx/dt = a
  C-:
    dV/dt - (g/a) * dH/dt + g*h_f - (g/a)*V*sin(alpha) = 0  along dx/dt = -a

Headloss in Pipes:
  Uses Darcy-Weisbach equation for head loss calculation, regardless of EPANET friction method.
  Darcy-Weisbach coefficients (f) are computed based on initial condition head loss per unit length (h_f0) and flow velocity (V0).
```

--------------------------------

### Build Transient Model from INP File

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Creates a transient model object by loading data from an EPANET INP file. This is the initial step in setting up a transient simulation.

```python
inp_file = 'examples/networks/Tnet1.inp'
tm = tsnet.network.TransientModel(inp_file)
```

--------------------------------

### TSNet Friction Model Selection

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Demonstrates how to select the friction model ('steady', 'quasi-steady', or 'unsteady') when initializing the MOCSimulator in TSNet.

```python
import tsnet.simulation

results_obj = 'Tnet3' # name of the object for saving simulation results
friction = 'unsteady' # or "steady" or "quasi-steady", by default "steady"
tm = tsnet.simulation.MOCSimulator(tm, results_obj, friction)
```

--------------------------------

### Pipe-to-Pipe Junction Boundary Condition with Leak

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Example boundary conditions for a pipe-to-pipe junction with a leak, relating heads and flow velocities at the junction node. Includes leakage coefficient and cross-sectional areas.

```math
H_2^t = H_3^t;   V_2^t * A_1  = V_3^t * A_2 + k_l * sqrt(H_2^t)
```

--------------------------------

### Add Demand Pulse to Network

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Models transients generated by an instantaneous demand pulse. The demand pulse is defined by its total duration, start time, transmission time, and peak amplitude, following a trapezoidal shape.

```python
tc = 1 # total demand period [s]
ts = 1 # demand pulse start time [s]
tp = 0.2 # demand pulse transmission time [s]
dp = 1 # demand peak amplitude [unitless]
demand_pulse = [tc,ts,tp,dpa]
tm.add_demand_pulse('N2',demand_pulse)
```

--------------------------------

### tsnet.simulation.single Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.simulation.rst

Documents the tsnet.simulation.single module, focusing on functionalities related to executing individual simulation runs. Includes information on members, undocumented members, and inheritance.

```python
import tsnet.simulation.single

# Access members and documentation for tsnet.simulation.single
# Example: help(tsnet.simulation.single)
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Steps to stage all changes, commit them with a descriptive message, and push the branch to GitHub.

```shell
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

--------------------------------

### TSNet Convergence Analysis - Pump Shut-down

Source: https://github.com/glorialulu/tsnet/blob/master/docs/validation.rst

Analyzes the consistency of TSNet solutions with varying time steps (0.002s, 0.0055s, 0.0115s) for the pump shut-down event in Tnet3. TSNet shows good consistency across time steps, while Hammer exhibits significant deviations and uncharacteristic results for time steps larger than 0.002s.

```APIDOC
Network:
  - Tnet3 (Complex network)

Transient Event:
  - Pump shut-down

Time Steps Tested:
  - TSNet: {0.002s, 0.0055s, 0.0115s}
  - Hammer: {0.002s, 0.0055s, 0.0115s}

Analysis:
  - Consistency of pressure transients at JUNCTION-30 (green lines) and JUNCTION-90 (purple lines) for different time steps.

TSNet Results:
  - Pressure transients are closely resembling each other across different time steps.
  - Anticipated level of detail about wave phenomena (reflection, transmission, propagation, attenuation) observed.

Hammer Results:
  - Significantly different and uncharacteristic results for time steps > 0.002s (0.0055s, 0.0115s).
  - Characteristics of deviation: small transient amplitude, delayed pressure peaks, high attenuation.
  - Consistency observed only when time step < 0.002s.

Visualizations:
  - convergence (a): TSNet results for different time steps.
  - convergence (b): Hammer results for different time steps.
```

--------------------------------

### tsnet Module Contents

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.rst

This section details the members, undocumented members, and inheritance of the tsnet module. It serves as the main entry point for understanding the package's core components.

```python
import tsnet

# Accessing members of the tsnet module
# Example: tsnet.some_function()

# The following are typically documented by the automodule directive:
# - tsnet.network
# - tsnet.postprocessing
# - tsnet.simulation
# - tsnet.utils
```

--------------------------------

### TSNet Citation and Licensing

Source: https://github.com/glorialulu/tsnet/blob/master/README.rst

Details on how to cite the TSNet package in academic work and information about its licensing, which is the MIT license.

```text
To cite TSNet, use one of the following references:

Xing, Lu, and Lina Sela. "Transient simulations in water distribution networks: TSNet python package." Advances in Engineering Software 149 (2020): 102884.

TSNet is released under the MIT license. See the LICENSE.txt file.
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/glorialulu/tsnet/blob/master/CONTRIBUTING.rst

Commands to check if local changes pass flake8 linting and all tests, including testing across different Python versions using tox.

```shell
$ flake8 TSNet tests
$ python setup.py test or py.test
$ tox
```

--------------------------------

### tsnet.simulation.solver Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.simulation.rst

Details the tsnet.simulation.solver module, which likely handles the computational aspects and algorithms used in the simulations. It lists members, undocumented members, and inheritance.

```python
import tsnet.simulation.solver

# Access members and documentation for tsnet.simulation.solver
# Example: help(tsnet.simulation.solver)
```

--------------------------------

### Project Dependencies

Source: https://github.com/glorialulu/tsnet/blob/master/requirements_dev.txt

This section lists the Python packages and their specified versions used in the Glorialulu/tsnet project. These dependencies are crucial for setting up the development environment and ensuring consistent builds.

```python
pip==21.1
bumpversion==0.5.3
wheel==0.32.1
watchdog==0.9.0
flake8==3.5.0
tox
coverage==4.5.1
Sphinx==1.8.1
twine==1.12.1
pytest
pytest-runner
```

--------------------------------

### tsnet.postprocessing Module Contents

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.postprocessing.rst

This section provides an overview of the tsnet.postprocessing module's contents, including its members, undocumented members, and inheritance.

```python
import tsnet.postprocessing

# Example usage (if available in the source, otherwise this is a placeholder)
# Assuming postprocessing has a main processing function:
# processed_data = tsnet.postprocessing.process(raw_data)
```

--------------------------------

### Retrieving Results Object from File

Source: https://github.com/glorialulu/tsnet/blob/master/docs/results.rst

Demonstrates how to load a saved TransientModel object from a pickle file to access simulation results.

```python
import pickle
file = open('results.obj', 'rb')
tm = pickle.load(file)
```

--------------------------------

### Tnet 0 Network Comparison

Source: https://github.com/glorialulu/tsnet/blob/master/docs/validation.rst

Compares TSNet and Hammer results for a simple network with one reservoir, two pipes, and one valve. The transient event involves closing an end-valve over 2 seconds. Figures show flow rate and pressure transients, indicating a perfect match between TSNet and Hammer.

```APIDOC
Network Topology:
  - 1 Reservoir
  - 2 Pipes
  - 1 Valve

Wave Speed:
  - Pipes: 1200 m/s

Transient Event:
  - Closure of end-valve from t=0s to t=2s.
  - Flow rate decreases linearly from 0.05 m^3/s to 0 m^3/s.

Simulation Period:
  - 60s

Comparison Metrics:
  - Flow rate through the valve
  - Pressure transients at node N-1

Results:
  - TSNet (solid line) vs. Hammer (dashed-dotted line).
  - Perfect match observed for this simple network.

Visualizations:
  - tnet0_network.png: Topology of the network.
  - tnet0_hammer.png: Comparison of flow rate (a) and pressure head (b).
```

--------------------------------

### Run Transient Simulation using MOC

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Executes the transient simulation using the Method of Characteristics (MOC). Results are stored in a specified object file for retrieval.

```python
results_obj = 'Tnet1' # name of the object for saving simulation results
tm = tsnet.simulation.MOCSimulator(tm, results_obj)
```

--------------------------------

### Tnet 3 Network Comparison - Closure of VALVE-1

Source: https://github.com/glorialulu/tsnet/blob/master/docs/validation.rst

Compares TSNet and Hammer results for Tnet3 during the closure of VALVE-1. Similar to other events, discrepancies are expected due to differing numerical implementations between the two software packages.

```APIDOC
Network:
  - Tnet3 (Complex network)

Transient Event:
  - Closure of VALVE-1

Comparison Metrics:
  - Pressure and flow transients.

Expected Outcome:
  - Similar results but not exact due to differences in numerical schemes.

Visualizations:
  - valve_hammer.png: Comparison of TSNet and Hammer results for the valve closure event.
```

--------------------------------

### MOC Numerical Scheme Explanation

Source: https://github.com/glorialulu/tsnet/blob/master/docs/transient.rst

Explains the explicit Method of Characteristics (MOC) technique for solving compatibility equations in pipe networks. It details the use of boundary and inner nodes, computational units, and how heads and flow velocities are computed at each time step based on previous information and boundary conditions.

```APIDOC
Numerical Scheme:
  Method: Explicit MOC
  Purpose: Solve compatibility equations for pipe networks.
  Nodes:
    - Boundary Nodes: Represent physical elements (tanks, junctions, valves, pumps, leaks, bursts) or discontinuities.
    - Inner Nodes: Numerically specified to divide pipes into segments (computational units) for wave propagation modeling.
  Computation:
    - Heads (H) and Flow Velocities (V) are computed for each node at each time step.
    - Computation depends on node type (inner/boundary) and specific boundary conditions.
  Inner Node Condition:
    - If no change in pipe or flow conditions: H_2^t = H_3^t and V_2^t = V_3^t.
    - Otherwise, additional head/flow boundary conditions are introduced between points 2 and 3, alongside compatibility equations.
  Boundary Conditions: Detailed descriptions are provided in subsequent sections.
```

--------------------------------

### Tnet 3 Network Comparison - Pump Shut-down

Source: https://github.com/glorialulu/tsnet/blob/master/docs/validation.rst

Compares TSNet and Hammer results for a more complex network (Tnet3) during a pump shut-down event. The simulation uses a time step of 0.002s. Results show very similar pressure changes in terms of attenuation and phase shift, with slight discrepancies due to different wave speed adjustment and boundary condition schemes.

```APIDOC
Network:
  - Tnet3 (Complex network)

Transient Event:
  - Shut down of PUMP-1

Time Step:
  - TSNet: 0.002s
  - Hammer: 0.002s

Comparison Metrics:
  - Pressure change with respect to nominal pressure at multiple junctions.

Results:
  - TSNet (solid lines) vs. Hammer (dashed lines).
  - Very similar attenuation and phase shift observed over 20s.
  - Slight discrepancies attributed to different wave speed adjustment and boundary condition configurations.

Visualizations:
  - tnet3_pump_hammer_002.png: Comparison of pressure transients at multiple junctions.
```

--------------------------------

### Retrieving Time Step and Timestamps

Source: https://github.com/glorialulu/tsnet/blob/master/docs/results.rst

Explains how to access the simulation time step and the array of timestamps from the TransientModel object.

```python
dt = tm.time_step
tt = tm.simulation_timestamps
```

--------------------------------

### Tnet 3 Network Comparison - Burst at JUNCTION-73

Source: https://github.com/glorialulu/tsnet/blob/master/docs/validation.rst

Compares TSNet and Hammer results for Tnet3 during a burst event at JUNCTION-73. The specific numerical schemes and expected outcomes are discussed, noting that exact matches are not anticipated due to implementation differences.

```APIDOC
Network:
  - Tnet3 (Complex network)

Transient Event:
  - Burst at JUNCTION-73

Comparison Metrics:
  - Pressure and flow transients.

Expected Outcome:
  - Similar results but not exact due to differences in numerical schemes (e.g., wave speed adjustment, pressure-dependent demand, boundary conditions).

Visualizations:
  - burst_hammer.png: Comparison of TSNet and Hammer results for the burst event.
```

--------------------------------

### tsnet.network.topology Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.network.rst

Details the topology functionalities within the tsnet.network package. Lists all members, undocumented members, and inheritance.

```python
import tsnet.network.topology

# Access members and functionalities from tsnet.network.topology
```

--------------------------------

### tsnet.postprocessing.time_history Module

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.postprocessing.rst

This section details the tsnet.postprocessing.time_history module, covering its members, undocumented members, and inheritance.

```python
import tsnet.postprocessing.time_history

# Example usage (if available in the source, otherwise this is a placeholder)
# Assuming time_history has functions like analyze_history:
# result = tsnet.postprocessing.time_history.analyze_history(data)
```

--------------------------------

### tsnet.network Module Contents

Source: https://github.com/glorialulu/tsnet/blob/master/docs/apidocs/tsnet.network.rst

Details the overall contents of the tsnet.network package. Lists all members, undocumented members, and inheritance.

```python
import tsnet.network

# Access members and functionalities from the tsnet.network package
```