From 8c388783db2d3d3d5d773a4cdffe6fab04f506c4 Mon Sep 17 00:00:00 2001 From: fengshang1972 <51705206+fengshang1972@users.noreply.github.com> Date: Wed, 22 Jul 2020 11:38:53 -0400 Subject: [PATCH] PDA equations, Tables in Chapter 8, etc. --- ...orithms.rst => 12_analysis_algorithms.rst} | 172 ++++--- .../{12_questions.rst => 13_questions.rst} | 0 User_Manual/docs/3_network_model.rst | 37 +- User_Manual/docs/8_analyzing_network.rst | 426 +++++++++--------- User_Manual/docs/conf.py | 3 +- User_Manual/docs/front_matter.rst | 22 +- User_Manual/docs/index.rst | 4 +- User_Manual/docs/index_latex.rst | 4 +- User_Manual/docs/references.rst | 18 +- 9 files changed, 345 insertions(+), 341 deletions(-) rename User_Manual/docs/{analysis_algorithms.rst => 12_analysis_algorithms.rst} (96%) rename User_Manual/docs/{12_questions.rst => 13_questions.rst} (100%) diff --git a/User_Manual/docs/analysis_algorithms.rst b/User_Manual/docs/12_analysis_algorithms.rst similarity index 96% rename from User_Manual/docs/analysis_algorithms.rst rename to User_Manual/docs/12_analysis_algorithms.rst index 64c935f..785bd91 100644 --- a/User_Manual/docs/analysis_algorithms.rst +++ b/User_Manual/docs/12_analysis_algorithms.rst @@ -26,10 +26,7 @@ Hydraulics opposite direction. The relation between the frictional head loss and the flow in the pipe can be expressed as - .. math:: - \begin{align} - h_{Lij} = r \: q_{ij} \: |q_{ij}|^{n-1} + m \: q_{ij} \: |q_{ij}| - \end{align} + .. math:: h_{Lij} = r \: q_{ij} \: |q_{ij}|^{n-1} + m \: q_{ij} \: |q_{ij}| :label: eq_headloss where :math:`h_{Lij}` is head loss, :math:`r` is a resistance coefficient, :math:`n` @@ -40,9 +37,9 @@ Hydraulics can be represented by a power law of the form .. math:: - \begin{align} + \begin{aligned} h_{Lij} = {-\omega}^{2} \: ( {h}_{0} - r \: { ( {q_{ij}} \: / \: {\omega} )}^{n} \: ) - \end{align} + \end{aligned} :label: eq_headloss_pumps where :math:`h_{0}` is the shutoff head for the pump, :math:`\omega` is a @@ -53,9 +50,9 @@ Hydraulics requires that .. math:: - \begin{align} + \begin{aligned} h_{i} - h_{j} = h_{Lij} (q_{ij}) - \end{align} + \end{aligned} :label: eq_link_energy where :math:`h_i` and :math:`h_j` are the hydraulic heads at each node, respectively. @@ -63,9 +60,9 @@ Hydraulics Conservation of mass at a node :math:`i` requires that total inflow equal total outflow: .. math:: - \begin{align} + \begin{aligned} {\sum_{j}}\: {q_{ij}} - {D}_{i} = 0 - \end{align} + \end{aligned} :label: eq_node_continuity where the summation is made over all nodes :math:`j` connected to node :math:`i`, and @@ -88,9 +85,9 @@ Hydraulics a set of linear equations for :math:`\boldsymbol{h}`: .. math:: - \begin{align} + \begin{aligned} \boldsymbol{Ah} = \boldsymbol{F} - \end{align} + \end{aligned} :label: eq_matrix_form where :math:`\boldsymbol{A}` is an :math:`(N \times N)` square symmetric coefficient matrix, @@ -100,9 +97,9 @@ Hydraulics The diagonal elements of the coefficient matrix are: .. math:: - \begin{align} + \begin{aligned} {A}_{ii}= \sum_{j} \: \frac{1}{g_{ij}} - \end{align} + \end{aligned} :label: eq_diag_coeffs while the non-zero, off-diagonal terms are: @@ -116,26 +113,26 @@ Hydraulics between nodes :math:`i` and :math:`j` with respect to flow. For pipes: .. math:: - \begin{align} + \begin{aligned} {g}_{ij} = n \: r \: {{| q_{ij} | }^{n - 1}} + \frac{\partial r}{\partial q_{ij}} \: |q_{ij}|^n + 2m \: | q_{ij} | - \end{align} + \end{aligned} :label: eq_grad_headloss while for pumps: .. math:: - \begin{align} + \begin{aligned} {g}_{ij} = n \: \omega^{2} \: r \: ({q}_{ij} \:/ \: {\omega} )^{n-1} - \end{align} + \end{aligned} :label: eq_grad_headloss_pumps Each right hand side term :math:`F_{i}` consists of the net flow imbalance at node :math:`i` plus a flow correction factor: .. math:: - \begin{align} + \begin{aligned} {F}_{i} = \sum_{{j}} \: \left( q_{ij} + {h}_{Lij} \: / \: {g_{ij}} \right) - {D}_{i} + \sum_{f} \: {H_{f}} \:/ \: {g_{if}} - \end{align} + \end{aligned} :label: eq_matrix_rhs where the last term applies to any links connecting node :math:`i` to a fixed @@ -145,17 +142,17 @@ Hydraulics new flows in each link between nodes :math:`i` and :math:`j` are found from: .. math:: - \begin{align} + \begin{aligned} {q}_{ij} = {q}_{ij} - {\Delta} \: {q}_{ij} - \end{align} + \end{aligned} :label: eq_flow_update where .. math:: - \begin{align} + \begin{aligned} {\Delta} \: {q}_{ij} = \left( {h}_{Lij} - {h}_{i} + {h}_{j}\right) \: {/} \: {g_{ij}} - \end{align} + \end{aligned} :label: eq_delta_q One interesting feature of the GGA is that the flow updating formula always @@ -176,21 +173,21 @@ Hydraulics proposed. Here we use Wagner’s equation (Wagner et al., 1988): .. math:: - \begin{align} + \begin{aligned} q_{Di} = \left\{ \begin{array}{l l} D_{i} & p_{i} \ge P_{f} \\ - D_{i} \left( \frac{p_{i} - P_{0}}{P_{f} - P_{0}} \right) ^{e} \; & P_{0} < p_i < P_{f} \\ + D_{i} \left( \frac{p_{i} - P_{0}}{P_{f} - P_{0}} \right) ^{\frac{1}{e}} \; & P_{0} < p_i < P_{f} \\ 0 & p_{i} \le P_{0} \end{array} \right. - \end{align} + \end{aligned} :label: eq_wagners :math:`D_{i}` is the full normal demand at node :math:`i` when the pressure :math:`p_{i}` equals or exceeds :math:`P_{f}`, :math:`P_{0}` is the pressure - below which the demand is :math:`0`, and :math:`e` is an exponent usually set equal + below which the demand is :math:`0`, and :math:`\frac{1}{e}` is a pressure function exponent usually set equal to :math:`0.5` (to mimic flow through an orifice). The power function portion of Wagner's equation can be inverted to express head @@ -198,9 +195,9 @@ Hydraulics to a virtual reservoir with fixed head :math:`P_{0} + E_{i}`: .. math:: - \begin{align} + \begin{aligned} h_{i} - P_{0} - E_{i} = R_{Di} \: {q_{Di}}^{e} - \end{align} + \end{aligned} :label: eq_inv_wagner where :math:`R_{Di} = (P_{f} - P_{0})/D_{i}^{e}` is the virtual link’s resistance @@ -218,29 +215,29 @@ Hydraulics :math:`D`: .. math:: - \begin{align} + \begin{aligned} g_{D} &= R_{\text{HIGH}} \\ h_{LD} &= P_f - P_0 + R_{\text{HIGH}} \: (q_{D} - D) - \end{align} + \end{aligned} where :math:`R_{\text{HIGH}}` is a large resistance factor (e.g. :math:`10^8`). 2. If the current demand flow :math:`q_D` is less than zero: .. math:: - \begin{align} + \begin{aligned} g_{D} &= R_{\text{HIGH}} \\ h_{LD} &= R_{\text{HIGH}} \: q_D - \end{align} + \end{aligned} 3. Otherwise the power function portion of the inverted Wagner equation is used to evaluate the head loss and gradient: .. math:: - \begin{align} - g_{D} &= e \: R_{D} \: {q_{D}} ^{e - 1} \\ - h_{LD} &= g_{D} \: q_D \: / \: e - \end{align} + \begin{aligned} + g_{D} &= e \: R_{D} \: {q_{D}} ^{e - 1} \\ + h_{LD} &= g_{D} \: q_D / \: e + \end{aligned} These head loss and gradient values are then incorporated into the normal set of GGA matrix equations as follows: @@ -273,7 +270,7 @@ Hydraulics **Linear Equation Solver** - The linear system of equations :math:`\boldsymbol{Ah} = \boldsymbol{F}` is solved using + The system of linear equations :math:`\boldsymbol{Ah} = \boldsymbol{F}` is solved using Cholesky decomposition applied to a sparse representation of the symmetric coefficient matrix :math:`\boldsymbol{A}` (George and Liu, 1981). Cholesky decomposition constructs a lower triangular matrix :math:`\boldsymbol{L}` such that: @@ -285,10 +282,10 @@ Hydraulics Nodal heads can then be found by solving: .. math :: - \begin{align} + \begin{aligned} \boldsymbol{L} \: \boldsymbol{y} = \boldsymbol{F} \\ \boldsymbol{L}^{T} \: \boldsymbol{h} = \boldsymbol{y} - \end{align} + \end{aligned} where :math:`\boldsymbol{y}` is an intermediate :math:`(N \times 1)` vector. Because of the lower triangular structure of :math:`\boldsymbol{L}` this set of equations can @@ -366,7 +363,7 @@ Hydraulics .. math:: - \begin{align} + \begin{aligned} f &= X1 + R \: (X2 + R \: (X3 + R \: X4)) \\ R &= \frac{Re}{2000} \\ X1 &= 7\: FA - FB \\ @@ -379,7 +376,7 @@ Hydraulics Y3 &= -2 \: log(Y2) \\ AA &= -1.5634601348517065795 \\ AB &= 0.00328895476345399058690 - \end{align} + \end{aligned} The only time the head loss resistance coefficient is a function of flow rate is for the Darcy-Weisbach's transitional and fully turbulent flow regimes. The contribution that these cases @@ -437,10 +434,10 @@ Hydraulics head loss become: .. math:: - \begin{align} + \begin{aligned} g_{E} &= C* \: \eta \: {|q_{E}|}^{\eta - 1} \\ h_{LE} &= \gamma \: g_{E} \: q_{E} - \end{align} + \end{aligned} where :math:`\eta = 1/\gamma` and :math:`C* = (1/C)^{\eta}`. These expressions can then be used in the GGA solution method in the same manner as @@ -456,10 +453,10 @@ Hydraulics Instead closed links are assigned a linear head loss function with a very high resistance coefficient: .. math:: - \begin{align} + \begin{aligned} h_L &= R_{\text{HIGH}} \: q \\ g &= R_{\text{HIGH}} - \end{align} + \end{aligned} where :math:`R_{\text{HIGH}}` is set at 10\ :sup:`8`. @@ -472,10 +469,10 @@ Hydraulics following low resistance head loss equation is used: .. math:: - \begin{align} + \begin{aligned} h_L &= R_{\text{LOW}} \: q \\ g &= R_{\text{LOW}} - \end{align} + \end{aligned} where :math:`R_{\text{LOW}}` is set at 10\ :sup:`-6`. @@ -491,11 +488,11 @@ Hydraulics following equations: .. math:: - \begin{align} + \begin{aligned} m &= { 0.02517 \: K} \: / \: {d}^{4} \\ g &= 2 \: m \: |q| \\ h_L &= g \: q \: / \: 2 - \end{align} + \end{aligned} *Pressure Breaker Valve (PBV)* @@ -503,10 +500,10 @@ Hydraulics This can be enforced by assigning the following values to the link's :math:`g` and :math:`h_{L}` values: .. math:: - \begin{align} + \begin{aligned} g &= 1 \: / \: R_{\text{HIGH}} \\ h_L &= H_{L}* - \end{align} + \end{aligned} If the valve's minor loss coefficient happens to produce a head loss greater than the setting at the valve's current flow rate then the valve is treated as a TCV. @@ -518,10 +515,10 @@ Hydraulics :math:`h_{0}` of that line segment to compute a head loss and its gradient as follows: .. math:: - \begin{align} + \begin{aligned} g &= r \\ h_L &= h_{0} + r \: q - \end{align} + \end{aligned} *Flow Control Valve (FCV)* @@ -531,10 +528,10 @@ Hydraulics downstream node. The resulting expressions for the valve's gradient and head loss are: .. math:: - \begin{align} + \begin{aligned} g &= R_{\text{HIGH}} \\ h_L &= g \: (q - Q*) - \end{align} + \end{aligned} The right hand side element :math:`F_i` corresponding to the valve's upstream node :math:`i` has :math:`Q*` subtracted from it while the element :math:`F_j` @@ -553,11 +550,11 @@ Hydraulics and right hand side vector :math:`\boldsymbol{F}` are made directly: .. math:: - \begin{align} + \begin{aligned} {A}_{jj} &= {A}_{jj} + R_{\text{HIGH}} \\ {F}_{j} &= {F}_{j} + (P* + {E}_{j}) \: R_{\text{HIGH}} \\ {F}_{i} &= {F}_{i} - \Sigma \: {q}_{jk} - \end{align} + \end{aligned} where :math:`\Sigma \: {q}_{jk}` is the net flow out of node :math:`j` to all other nodes except node :math:`i` (and will be negative because it is a net outflow). The absolute value @@ -577,11 +574,11 @@ Hydraulics matrix :math:`\boldsymbol{A}` and right hand side vector :math:`\boldsymbol{F}` are made directly: .. math:: - \begin{align} + \begin{aligned} {A}_{ii} &= {A}_{ii} + R_{\text{HIGH}} \\ {F}_{i} &= {F}_{i} + (P* + {E}_{i}) \: R_{\text{HIGH}} \\ {F}_{j} &= {F}_{j} + \Sigma \: {q}_{ki} - \end{align} + \end{aligned} where :math:`\Sigma \: {q}_{ki}` is the net flow into node :math:`i` from all other nodes except node :math:`j` (and will be positive because it is a net inflow). This quantity also becomes @@ -602,10 +599,10 @@ Hydraulics equations are used to compute the link's head loss and gradient: .. math:: - \begin{align} + \begin{aligned} h_L &= G_{\text{LOW}} \: q \\ g &= G_{\text{LOW}} - \end{align} + \end{aligned} This prevents a gradient value from ever being lower than :math:`G_{\text{LOW}}`. @@ -643,7 +640,7 @@ Hydraulics *Check Valves* - The psuedo-code used to check the status of a pipe with a check valve looks as follows: + The pseudo-code used to check the status of a pipe with a check valve looks as follows: :: @@ -740,9 +737,9 @@ Hydraulics (both real and virtual) must be less than a stipulated **ACCURACY** value: .. math:: - \begin{align} + \begin{aligned} \frac {\sum_{} \: |{\Delta}q|} { \sum_{} \: |q| } < \text{ACCURACY} - \end{align} + \end{aligned} 2. The error in satisfying the energy balance equation Eq. :eq:`eq_link_energy` for each link (excluding closed links and active PRVs/PSVs) must be less than a specified head @@ -811,10 +808,10 @@ Hydraulics replace :math:`dV_{s}/dt` with its forward difference approximation: .. math:: - \begin{align} + \begin{aligned} {V_s}(t + {\Delta}t) &= {V_s}(t) + {Q_{s,net}(t)} \: {\Delta}t \\ {H_s}(t + {\Delta}t) &= E_s + Y({V_s}(t + {\Delta}t)) - \end{align} + \end{aligned} The tank levels :math:`H(t)` and nodal demands existing at time :math:`t` are used in the GGA to solve the static network conservation equations resulting in set of new net flows into each @@ -902,9 +899,9 @@ Water Quality .. _eq-advec_trans: .. math:: - \begin{align} + \begin{aligned} \frac{ \partial {C}_{i}} {\partial t} = - u_{i} \frac{\partial{C}_{i}}{\partial x} + r({C}_{i}) - \end{align} + \end{aligned} :label: eq:advec_trans .. @@ -923,9 +920,9 @@ Water Quality For a specific node :math:`k` one can write: .. math:: - \begin{align} + \begin{aligned} C_{i|x=0} = \frac{\sum_{ j \in I_k} Q_{j} C_{j|x= L_j}+Q_{k,ext} C_{k,ext}} {\sum_{j \in I_k} Q_j + Q_{k,ext}} - \end{align} + \end{aligned} :label: eq:nodal_mixing where :math:`i` = link with flow leaving node :math:`k`, :math:`I_k` = set @@ -946,9 +943,9 @@ Water Quality :math:`W_{s,IN}` is the rate of mass inflow into tank :math:`s`: .. math:: - \begin{align} + \begin{aligned} W_{s,IN} = \sum_{i \in I_{s}} {Q}_{i}{C}_{i | x={L}_{i}} - \end{align} + \end{aligned} :label: eq_mass_inflow where :math:`I_s` is the set of links flowing into the facility. @@ -956,9 +953,9 @@ Water Quality :math:`Q_{s,OUT}` is the rate of flow out of tank :math:`s`: .. math:: - \begin{align} + \begin{aligned} Q_{s,OUT} = \sum_{j \in O_{s}} {Q}_{j} - \end{align} + \end{aligned} :label: eq_tank_outflow where :math:`O_s` is the set of links receiving outflow from the tank. @@ -977,9 +974,9 @@ Water Quality equation expresses these phenomena: .. math:: - \begin{align} + \begin{aligned} \frac{\partial ({V}_{s} {C}_{s}) }{\partial t} = W_{s,IN} - Q_{s,OUT} \: {C}_{s} - {V}_{s} \: r({C}_{s}) - \end{align} + \end{aligned} :label: eq_mixing1 where :math:`V_s` = volume in storage at time :math:`t`, :math:`C_s` = concentration @@ -995,20 +992,17 @@ Water Quality The mass balance on the first compartment is: .. math:: - \begin{equation} - \begin{split} + :label: eq_tank_mixing21 + \frac{\partial ({V}_{s1}{C}_{s1})}{\partial t} & = W_{s,IN} - Q_{s,OUT}\:{C}_{s1} - Q_{s,{1{\to}2}}\: C_{s1} \\ & + Q_{s,{2{\to}1}} \: C_{s2} - {V}_{s1} \: r({C}_{s1}) - \end{split} - \end{equation} - :label: eq_tank_mixing21 while for the second compartment: .. math:: - \begin{align} + \begin{aligned} \frac{\partial ({V}_{s2}{C}_{s2})}{\partial t} = Q_{s,{1{\to}2}} \: C_{s1} - Q_{s,{2{\to}1}} \: C_{s2} - {V}_{s2} \: r({C}_{s2}) - \end{align} + \end{aligned} :label: eq_tank_mixing22 In these equations :math:`s1` refers to the first compartment, :math:`s2` to the second @@ -1027,9 +1021,9 @@ Water Quality a pipe. The boundary condition at the tank's entrance (where :math:`x = 0`) is .. math:: - \begin{equation} + \begin{aligned} C_{s|x=0} = W_{s,IN} \: / \: Q_{s,IN} - \end{equation} + \end{aligned} :label: eq_tank_mixing3 where :math:`Q_{s,IN}` is the total inflow into the tank. The outflow concentration from the @@ -1058,12 +1052,12 @@ Water Quality substance then the rate expression becomes .. math:: - \begin{align} + \begin{aligned} \begin{array}{l l} R = {K}_{b} ({C}_{L}-C) \: {C}^{n-1} & for \; n > 0, K_b < 0 \\ R = {K}_{b} (C - {C}_{L}) \: {C}^{n - 1} & for \; n > 0, K_b < 0 \end{array} - \end{align} + \end{aligned} where :math:`C_L` = the limiting concentration. diff --git a/User_Manual/docs/12_questions.rst b/User_Manual/docs/13_questions.rst similarity index 100% rename from User_Manual/docs/12_questions.rst rename to User_Manual/docs/13_questions.rst diff --git a/User_Manual/docs/3_network_model.rst b/User_Manual/docs/3_network_model.rst index adf80ad..ad20b00 100644 --- a/User_Manual/docs/3_network_model.rst +++ b/User_Manual/docs/3_network_model.rst @@ -152,7 +152,7 @@ Physical Components .. note:: The pressure-flow relation at a junction defined by an emitter should not be confused with the pressure-demand relation when - performing a pressure driven analysis (PDA). See :ref:`Pressure Driven Demand` + performing a pressure driven analysis (PDA). See :ref:`Hydraulic Simulation Model` for more information. **Pipes** @@ -850,23 +850,25 @@ Hydraulic Simulation Model than normal will occur automatically whenever one of the following events occurs: - - The next output reporting time period occurs - - The next time pattern period occurs - - A tank becomes empty or full - - A simple control or rule-based control is activated - - EPANET's hydraulic analysis allows for two different ways of modeling water demands (i.e., consumption) - at network junction nodes. Demand Driven Analysis (DDA) requires that demands at each point in time are - fixed values that must be delivered no matter what nodal pressures and link flows are produced by a - hydraulic solution. This has been the classical approach used to model demands, but it can result in - situations where required demands are satisfied at nodes with negative pressures - a physical impossibility. - An alternative approach, known as Pressure Driven Analysis (PDA), allows the actual demand delivered at a - node to depend on the node's pressure. Below some minimum pressure demand is zero, above some service pressure - the full required demand is supplied and in between demand varies as a power law function of pressure. Using - PDA is one way to avoid having positive demands at nodes with negative pressures. - - EPANET's Hydraulic Analysis Options are used to select a choice of demand model and to supply the parameters used by PDA. + - The next output reporting time period occurs + + - The next time pattern period occurs + + - A tank becomes empty or full + - A simple control or rule-based control is activated + + EPANET's hydraulic analysis allows for two different ways of modeling water demands (i.e., consumption) at network junction nodes. + Demand Driven Analysis (DDA) requires that demands at each point in time are fixed values that must + be delivered no matter what nodal pressures and link flows are produced by a hydraulic solution. This + has been the classical approach used to model demands, but it can result in situations where required + demands are satisfied at nodes with negative pressures - a physical impossibility. An alternative + approach, known as Pressure Driven Analysis (PDA), allows the actual demand delivered at a node to + depend on the node's pressure. Below some minimum pressure demand is zero, above some service pressure + the full required demand is supplied and in between demand varies as a power law function of pressure. Using + PDA is one way to avoid having positive demands at nodes with negative pressures. + + EPANET's :ref:`Hydraulic Analysis Options` are used to select a choice of demand model and to supply the parameters used by PDA. .. _sec-wq_sim_model: @@ -907,6 +909,7 @@ Water Quality Simulation Model re-ordered from front to back. **Water Quality Sources** + Water quality sources are nodes where the quality of external flow entering the network is specified. They can represent the main treatment works, a well-head or satellite treatment facility, or an unwanted contaminant intrusion. diff --git a/User_Manual/docs/8_analyzing_network.rst b/User_Manual/docs/8_analyzing_network.rst index 3a87463..56c925b 100644 --- a/User_Manual/docs/8_analyzing_network.rst +++ b/User_Manual/docs/8_analyzing_network.rst @@ -49,212 +49,219 @@ Setting Analysis Options .. tabularcolumns:: |p{3cm}|p{11.5cm}| .. _table-hyd_ops: -.. table:: Hydraulic Options for Hydraulic Analysis +.. table:: Hydraulic Analysis Options :class: longtable - +-----------------------------------+-----------------------------------+ - | *OPTION* | *DESCRIPTION* | - +===================================+===================================+ - | | Units in which nodal demands and | - | Flow Units | link flow rates are expressed. | - | | Choosing units in gallons, cubic | - | | feet, or acre-feet implies that | - | | the units for all other network | - | | quantities are Customary US. | - | | Selecting liters or cubic meters | - | | causes all other units to be SI | - | | metric. Use caution when changing | - | | flow units as it might affect all | - | | other data supplied to the | - | | project. (See Appendix A, Units | - | | of Measurement.) | - +-----------------------------------+-----------------------------------+ - | Headloss Formula | Formula used to compute headloss | - | | as a function of flow rate in a | - | | pipe. Choices are: | - | | | - | | - Hazen-Williams | - | | - Darcy-Weisbach | - | | - Chezy-Manning | - | | | - |   | Because each formula measures | - | | pipe roughness differently, | - | | switching formulas might require | - | | that all pipe roughness | - | | coefficients be updated. | - +-----------------------------------+-----------------------------------+ - | Specific Gravity | Ratio of the density of the fluid | - | | being modeled to that of water at | - | | 4 deg. C (unitless). | - +-----------------------------------+-----------------------------------+ - | Relative Viscosity | Ratio of the kinematic viscosity | - | | of the fluid to that of water at | - | | 20 deg. C (1.0 centistokes or | - | | 0.94 sq ft/day) (unitless). | - +-----------------------------------+-----------------------------------+ - | Maximum Trials | Maximum number of trials used to | - | | solve the nonlinear equations | - | | that govern network hydraulics at | - | | a given point in time. Suggested | - | | value is 40. | - +-----------------------------------+-----------------------------------+ - | Accuracy | Convergence criterion used to | - | | signal that a solution has been | - | | found to the nonlinear equations | - | | that govern network hydraulics. | - | | Trials end when the sum of all | - | | flow changes divided by the sum | - | | of all link flows is less than | - | | this number. Suggested value is | - | | 0.001. | - +-----------------------------------+-----------------------------------+ - | If Unbalanced | Action to take if a hydraulic | - | | solution is not found within the | - | | maximum number of trials. Choices | - | | are STOP to stop the simulation | - | | at this point or CONTINUE to use | - | | another 10 trials, with no link | - | | status changes allowed, in an | - | | attempt to achieve convergence. | - +-----------------------------------+-----------------------------------+ - | Default Pattern | ID label of a time pattern to be | - | | applied to demands at those | - | | junctions where no time pattern | - | | is specified. If no such pattern | - | | exists then demands will not vary | - | | at these locations. | - +-----------------------------------+-----------------------------------+ - | Demand Multiplier | Global multiplier applied to all | - | | demands to make total system | - | | consumption vary up or down by a | - | | fixed amount (e.g., 2.0 doubles | - | | all demands, 0.5 halves them, and | - | | 1.0 leaves them as is). | - +-----------------------------------+-----------------------------------+ - | Emitter Exponent | Power to which pressure is raised | - | | when computing the flow through | - | | an emitter device. The textbook | - | | value for nozzles and sprinklers | - | | is 0.5. This may not apply to | - | | pipe leakage. Consult the | - | | discussion of Emitters in | - | | Section 3.1 for more details. | - +-----------------------------------+-----------------------------------+ - | Status Report | Amount of status information to | - | | report after an analysis is made. | - |   | Choices are: | - | | | - | | - NONE (no status report) | - | | - YES (normal status reporting | - | | - lists all changes in | - | | link status throughout | - | | the simulation and if | - | | water quality is analyzed,| - | | a final mass balance | - | | accounting) | - | | - FULL (full reporting - normal | - | | reporting plus the | - | | convergence error from | - | | each trial of the | - | | hydraulic analysis made | - | | in each timeperiod) | - | | | - |   | Full status reporting is only | - | | useful for debugging purposes. | - +-----------------------------------+-----------------------------------+ - | Max. Head Error | Another convergence criterion | - | | requiring that the head loss | - | | computed by the head loss | - | | formula compared to the | - | | difference in nodal heads | - | | across each link be less than | - | | the specified value (in ft or m). | - | | A value of 0 indicates that this | - | | criterion will not be used. | - +-----------------------------------+-----------------------------------+ - | Max. Flow Change | A third convergence criterion | - | | requiring that the largest | - | | absolute flow change between | - | | the current and previous | - | | solutions be less than the | - | | specified value (in flow | - | | units). A value of 0 | - | | indicates that this criterion | - | | will not be used. | - +-----------------------------------+-----------------------------------+ - | Demand Model | Selects between demand or | - | | pressure driven analysis -- DDA | - | | or PDA, respectively. DDA assumes | - | | demands are fixed at a given | - | | point in time, while PDA assumes | - | | demands are a function of | - | | pressure. The PDA option can be | - | | used to find a solution when | - | | negative pressures are present | - | | in a DDA. | - +-----------------------------------+-----------------------------------+ - | Minimum Pressure | In a PDA, the pressure below | - | | which demand is assumed to be | - | | zero. | - +-----------------------------------+-----------------------------------+ - | Required Pressure | In a PDA, the pressure required | - | | to deliver the full demand. | - +-----------------------------------+-----------------------------------+ - | Pressure Exponent | PDA assumes a pressure demand | - | | relation raised to an exponent. | - | | Standard value is 0.5. | - +-----------------------------------+-----------------------------------+ - | CHECKFREQ | This sets the number of solution | - | | trials that pass during hydraulic | - | | balancing before the status of | - | | pumps, check valves, flow control | - | | valves and pipes connected to | - | | tanks are once again updated. The | - | | default value is 2, meaning that | - | | status checks are made every | - | | other trial. A value equal to the | - | | maximum number of trials would | - | | mean that status checks are made | - | | only after a system has | - | | converged. (Whenever a status | - | | change occurs the trials must | - | | continue since the current | - | | solution may not be balanced.) | - | | The frequency of status checks on | - | | pressure reducing and pressure | - | | sustaining valves (PRVs and PSVs) | - | | is determined by the DAMPLIMIT | - | | option (see below). | - +-----------------------------------+-----------------------------------+ - | MAXCHECK | This is the number of solution | - | | trials after which periodic | - | | status checks on pumps, check | - | | valves, flow control valves and | - | | pipes connected to tanks are | - | | discontinued. Instead, a status | - | | check is made only after | - | | convergence is achieved. The | - | | default value is 10, meaning that | - | | after 10 trials, instead of | - | | checking status every CHECKFREQ | - | | trials, status is checked only at | - | | convergence. | - +-----------------------------------+-----------------------------------+ - | DAMPLIMIT | This is the accuracy value at | - | | which solution damping and status | - | | checks on PRVs and PSVs should | - | | begin. Damping limits all flow | - | | changes to 60% of what they would | - | | otherwise be as future trials | - | | unfold. The default is 0 which | - | | indicates that no damping should | - | | be used and that status checks on | - | | control valves are made at every | - | | iteration. Damping might be | - | | needed on networks that have | - | | trouble converging, in which case | - | | a limit of 0.01 is suggested. | - +-----------------------------------+-----------------------------------+ + +-----------------------------------+-------------------------------------+ + | *OPTION* | *DESCRIPTION* | + +===================================+=====================================+ + | | Units in which nodal demands and | + | Flow Units | link flow rates are expressed. | + | | Choosing units in gallons, cubic | + | | feet, or acre-feet implies that | + | | the units for all other network | + | | quantities are Customary US. | + | | Selecting liters or cubic meters | + | | causes all other units to be SI | + | | metric. Use caution when changing | + | | flow units as it might affect all | + | | other data supplied to the | + | | project. (See Appendix A, Units | + | | of Measurement.) | + +-----------------------------------+-------------------------------------+ + | Headloss Formula | Formula used to compute headloss | + | | as a function of flow rate in a | + | | pipe. Choices are: | + | | | + | | - Hazen-Williams | + | | - Darcy-Weisbach | + | | - Chezy-Manning | + | | | + |   | Because each formula measures | + | | pipe roughness differently, | + | | switching formulas might require | + | | that all pipe roughness | + | | coefficients be updated. | + +-----------------------------------+-------------------------------------+ + | Specific Gravity | Ratio of the density of the fluid | + | | being modeled to that of water at | + | | 4 deg. C (unitless). | + +-----------------------------------+-------------------------------------+ + | Relative Viscosity | Ratio of the kinematic viscosity | + | | of the fluid to that of water at | + | | 20 deg. C (1.0 centistokes or | + | | 0.94 sq ft/day) (unitless). | + +-----------------------------------+-------------------------------------+ + | Maximum Trials | Maximum number of trials used to | + | | solve the nonlinear equations | + | | that govern network hydraulics at | + | | a given point in time. Suggested | + | | value is 40. | + +-----------------------------------+-------------------------------------+ + | Accuracy | Convergence criterion used to | + | | signal that a solution has been | + | | found to the nonlinear equations | + | | that govern network hydraulics. | + | | Trials end when the sum of all | + | | flow changes divided by the sum | + | | of all link flows is less than | + | | this number. Suggested value is | + | | 0.001. | + +-----------------------------------+-------------------------------------+ + | If Unbalanced | Action to take if a hydraulic | + | | solution is not found within the | + | | maximum number of trials. Choices | + | | are STOP to stop the simulation | + | | at this point or CONTINUE to use | + | | another 10 trials, with no link | + | | status changes allowed, in an | + | | attempt to achieve convergence. | + +-----------------------------------+-------------------------------------+ + | Default Pattern | ID label of a time pattern to be | + | | applied to demands at those | + | | junctions where no time pattern | + | | is specified. If no such pattern | + | | exists then demands will not vary | + | | at these locations. | + +-----------------------------------+-------------------------------------+ + | Demand Multiplier | Global multiplier applied to all | + | | demands to make total system | + | | consumption vary up or down by a | + | | fixed amount (e.g., 2.0 doubles | + | | all demands, 0.5 halves them, and | + | | 1.0 leaves them as is). | + +-----------------------------------+-------------------------------------+ + | Emitter Exponent | Power to which pressure is raised | + | | when computing the flow through | + | | an emitter device. The textbook | + | | value for nozzles and sprinklers | + | | is 0.5. This may not apply to | + | | pipe leakage. Consult the | + | | discussion of Emitters in | + | | Section 3.1 for more details. | + +-----------------------------------+-------------------------------------+ + | Status Report | Amount of status information to | + | | report after an analysis is made. | + |   | Choices are: | + | | | + | | - NONE (no status report) | + | | - YES (normal status reporting - | + | | lists all changes in link status | + | | throughout the simulation and if | + | | water quality is analyzed,a final | + | | mass balance accounting) | + | | - FULL (full reporting - normal | + | | reporting plus the convergence | + | | error from each trial of the | + | | hydraulic analysis made in each | + | | time period) | + | | | + |   | Full status reporting is only | + | | useful for debugging purposes. | + +-----------------------------------+-------------------------------------+ + | Max. Head Error | Another convergence criterion | + | | requiring that the head loss | + | | computed by the head loss | + | | formula compared to the | + | | difference in nodal heads | + | | across each link be less than | + | | the specified value (in ft or m). | + | | A value of 0 indicates that this | + | | criterion will not be used. | + +-----------------------------------+-------------------------------------+ + | Max. Flow Change | A third convergence criterion | + | | requiring that the largest | + | | absolute flow change between | + | | the current and previous | + | | solutions be less than the | + | | specified value (in flow | + | | units). A value of 0 | + | | indicates that this criterion | + | | will not be used. | + +-----------------------------------+-------------------------------------+ + | Demand Model | Specifies whether a demand driven | + | | analysis (DDA) or a pressure driven | + | | analysis (PDA) should be made. Under| + | | DDA full nodal demands are always | + | | met even if negative pressures | + | | result. PDA assumes that demand | + | | varies between 0 and its full value | + | | as a power function of nodal | + | | pressure. The default demand model | + | | is DDA | + +-----------------------------------+-------------------------------------+ + | Minimum Pressure | The pressure below which no demand | + | | can be delivered under a pressure | + | | driven analysis. It has no effect on| + | | a demand driven analysis. Its | + | | default value is 0. | + +-----------------------------------+-------------------------------------+ + | Required Pressure | The pressure required to supply a | + | | node's full demand under a pressure | + | | driven analysis. It has no effect on| + | | a demand driven analysis. To avoid | + | | numerical issues it must be at least| + | | 0.1 psi or meters above the Minimum | + | | Pressure. Its default value is 0.1. | + +-----------------------------------+-------------------------------------+ + | Pressure Exponent | The power to which pressure is | + | | raised when computing the demand | + | | delivered to a node under a | + | | pressure driven analysis. It has no | + | | effect on a demand driven analysis. | + | | Its suggested value is 0.5. | + +-----------------------------------+-------------------------------------+ + | CHECKFREQ | This sets the number of solution | + | | trials that pass during hydraulic | + | | balancing before the status of | + | | pumps, check valves, flow control | + | | valves and pipes connected to | + | | tanks are once again updated. The | + | | default value is 2, meaning that | + | | status checks are made every | + | | other trial. A value equal to the | + | | maximum number of trials would | + | | mean that status checks are made | + | | only after a system has | + | | converged. (Whenever a status | + | | change occurs the trials must | + | | continue since the current | + | | solution may not be balanced.) | + | | The frequency of status checks on | + | | pressure reducing and pressure | + | | sustaining valves (PRVs and PSVs) | + | | is determined by the DAMPLIMIT | + | | option (see below). | + +-----------------------------------+-------------------------------------+ + | MAXCHECK | This is the number of solution | + | | trials after which periodic | + | | status checks on pumps, check | + | | valves, flow control valves and | + | | pipes connected to tanks are | + | | discontinued. Instead, a status | + | | check is made only after | + | | convergence is achieved. The | + | | default value is 10, meaning that | + | | after 10 trials, instead of | + | | checking status every CHECKFREQ | + | | trials, status is checked only at | + | | convergence. | + +-----------------------------------+-------------------------------------+ + | DAMPLIMIT | This is the accuracy value at | + | | which solution damping and status | + | | checks on PRVs and PSVs should | + | | begin. Damping limits all flow | + | | changes to 60% of what they would | + | | otherwise be as future trials | + | | unfold. The default is 0 which | + | | indicates that no damping should | + | | be used and that status checks on | + | | control valves are made at every | + | | iteration. Damping might be | + | | needed on networks that have | + | | trouble converging, in which case | + | | a limit of 0.01 is suggested. | + +-----------------------------------+-------------------------------------+ .. @@ -298,7 +305,7 @@ Setting Analysis Options .. tabularcolumns:: |p{3cm}|p{11cm}| .. _table-wq_ops: -.. table:: Water Quality Options for Water Quality Analysis +.. table:: Water Quality Analysis Options +-----------------------------------+-----------------------------------+ | *OPTION* | *DESCRIPTION* | @@ -366,7 +373,7 @@ Setting Analysis Options .. tabularcolumns:: |p{4cm}|p{10.5cm}| .. _table-rxn_ops: -.. table:: Reaction Options for Water Quality Analysis +.. table:: Water Quality Reaction Options +-----------------------------------+-----------------------------------+ | *OPTION* | *DESCRIPTION* | @@ -451,7 +458,7 @@ Setting Analysis Options .. tabularcolumns:: |p{3.5cm}|p{11cm}| .. _table-time_ops: -.. table:: Times Options for Hydraulic and Water Quality Analysis +.. table:: Simulation Time Options +-----------------------------------+-----------------------------------+ | *OPTION* | *DESCRIPTION* | @@ -505,7 +512,8 @@ Setting Analysis Options |   | - AVERAGE (time-averaged results) | |   | - MINIMUM (minimum value results) | |   | - MAXIMUM (maximum value results) | - |   | - RANGE (diff between min and max)| + |   | - RANGE (difference between min | + | | and max) | | | | |   | Statistical processing is applied | | | to all node and link results | @@ -531,7 +539,7 @@ Setting Analysis Options .. tabularcolumns:: |p{4cm}|p{10cm}| .. _table-energy_ops: -.. table:: Energy Options for Hydraulic Analysis +.. table:: Energy Analysis Options +-----------------------------------+-----------------------------------+ | *OPTION* | *DESCRIPTION* | diff --git a/User_Manual/docs/conf.py b/User_Manual/docs/conf.py index 20cf9f2..f39c045 100644 --- a/User_Manual/docs/conf.py +++ b/User_Manual/docs/conf.py @@ -15,7 +15,7 @@ #import os #import sys #sys.path.insert(0, os.path.abspath('.')) - +import sphinx_rtd_theme # -- Project information ----------------------------------------------------- @@ -46,6 +46,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + "sphinx_rtd_theme", 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', diff --git a/User_Manual/docs/front_matter.rst b/User_Manual/docs/front_matter.rst index 9792c3c..64c63a9 100644 --- a/User_Manual/docs/front_matter.rst +++ b/User_Manual/docs/front_matter.rst @@ -20,13 +20,13 @@ This manual describes how to run version 2.2 of the EPANET water distribution system simulation model. Notable improvements made by this version include: -- the ability to use pressure-dependent demands in hydraulic analyses -- an option to allow full tanks to overflow -- options that insure a more accurate hydraulic analysis is made -- more robust handling of low and zero flow hydraulic conditions -- faster solution times for single period hydraulic analyses -- improved mass balance results for water quality analyses -- an enhanced API function library for customizing EPANET (see http://wateranalytics.org/EPANET/). +- The ability to use pressure-dependent demands in hydraulic analyses. +- An option to allow full tanks to overflow. +- Options that insure a more accurate hydraulic analysis is made. +- More robust handling of low and zero flow hydraulic conditions. +- Faster solution times for single period hydraulic analyses. +- Improved mass balance results for water quality analyses. +- An enhanced API function library for customizing EPANET (see http://wateranalytics.org/EPANET/). The following topics are covered in this Manual: @@ -93,15 +93,13 @@ coefficients, etc.). It also discusses how to save a project’s entire database to a readable text file and how to export the network map to a variety of formats. +:ref:`analysis_algorithms` provides details of the procedures and +formulas used by EPANET in its hydraulic and water quality analysis algorithms. + :ref:`questions` answers questions about how EPANET can be used to model special kinds of situations, such as modeling pneumatic tanks, finding the maximum flow available at a specific pressure, and modeling the growth of disinfection by-products. - -:ref:`analysis_algorithms` provides details of the procedures and -formulas used by EPANET in its hydraulic and water quality analysis algorithms. - - The manual also contains several appendixes. | :ref:`units` provides a table of units of expression for all diff --git a/User_Manual/docs/index.rst b/User_Manual/docs/index.rst index cb82c2a..e788a7c 100644 --- a/User_Manual/docs/index.rst +++ b/User_Manual/docs/index.rst @@ -26,8 +26,8 @@ 9_viewing_results 10_printing_copying 11_importing_exporting - 12_questions - analysis_algorithms + 12_analysis_algorithms + 13_questions references .. toctree:: diff --git a/User_Manual/docs/index_latex.rst b/User_Manual/docs/index_latex.rst index 010e1f6..8bc74b0 100644 --- a/User_Manual/docs/index_latex.rst +++ b/User_Manual/docs/index_latex.rst @@ -19,7 +19,7 @@ EPANET documentation 9_viewing_results 10_printing_copying 11_importing_exporting - 12_questions - analysis_algorithms + 12_analysis_algorithms + 13_questions references \ No newline at end of file diff --git a/User_Manual/docs/references.rst b/User_Manual/docs/references.rst index 9c826f8..879b135 100644 --- a/User_Manual/docs/references.rst +++ b/User_Manual/docs/references.rst @@ -18,7 +18,7 @@ Bhave, P. R. 1991. *Analysis of Flow in Water Distribution Networks*. Technomic Publishing. Lancaster, PA. Clark, R. M. 1998. “Chlorine demand and Trihalomethane formation -kinetics: a second-order model”, *Jour. Env. Eng*., Vol. 124, No. 1, +kinetics: a second-order model”, *J. Environ. Eng*., Vol. 124, No. 1, pp. 16-24. Davis, M. J., Janke, R., and Taxon, T. N. 2018. "Mass imbalances in @@ -43,23 +43,23 @@ algorithm by multiple elimination". *ACM Transactions on Mathematical Software*, 11(2), 141-153 Notter, R. H. and Sleicher, C. A. 1971. “The eddy diffusivity in the -turbulent boundary layer near a wall”, *Chem. Eng. Sci.,* Vol. 26, +turbulent boundary layer near a wall”, *Chem. Eng. Sci*., Vol. 26, pp. 161-171. Rossman, L. A., Boulos, P. F., and Altman, T. (1993). “Discrete volume-element method for network water-quality models”, *J. Water -Resour. Plng. and Mgmt*, Vol. 119, No. 5, 505-517. +Resour. Plan. and Manage*., Vol. 119, No. 5, 505-517. Rossman, L. A., Clark, R. M., and Grayman, W. M. (1994). “Modeling -chlorine residuals in drinking-water distribution systems”, *Jour. -Env. Eng*., Vol. 120, No. 4, 803-820. +chlorine residuals in drinking-water distribution systems”, *J. +Environ. Eng*., Vol. 120, No. 4, 803-820. Rossman, L. A. and Boulos, P. F. (1996). “Numerical methods for modeling water quality in distribution systems: A comparison”, *J. -Water Resour. Plng. and Mgmt*, Vol. 122, No. 2, 137-146. +Water Resour. Plan. and Manage*., Vol. 122, No. 2, 137-146. Rossman, L. A. and Grayman, W. M. 1999. “Scale-model studies of mixing -in drinking water storage tanks”, *Jour. Env. Eng*., Vol. 125, No. 8, +in drinking water storage tanks”, *J. Environ. Eng*., Vol. 125, No. 8, pp. 755-761. Todini E. and Pilati S. (1988). “A gradient method for the solution @@ -69,8 +69,8 @@ and Simulation, John Wiley & Sons, pp. 1-20. Todini E. and Rossman L.A. (2013). “Unified Framework for Deriving Simultaneous Equation Algorithms for Water Distribution Networks.” -J. Hydraul. Eng., 139(5), 511-526. +*J. Hydraul. Eng*., 139(5), 511-526. Wagner, J. M., Shamir, U., and Marks, D. H. 1988. "Water distribution -reliability: Simulation methods." *Jour. Water Resour. Plan. Manage*., +reliability: Simulation methods." *J. Water Resour. Plan. Manage*., Vol. 114, No. 3, 253-275.