Civil Engineering

civil-engineering-ai999x

Pipe and open-channel hydraulics, hydrology, groundwater flow, soil mechanics and foundations, water networks and surveying.

Engineering Question Answering Sentence Similarity Feature Extraction

Hugging Face ↗GitHub ↗See it on the capability orb

88capabilities

7topics

88formulas typeset

8worked examples below

1.0.0version

About this model

What Civil Engineering does

Civil Engineering (civil-engineering-ai999x) is an offline Python package for civil engineering. It covers pipe and open-channel hydraulics, hydrology, groundwater flow, soil mechanics and foundations, water networks and surveying.

It has 88 capabilities — 88 computational procedures — in 7 topics, the largest being Open-channel hydraulics, Soil mechanics, Hydrology, Foundations, Groundwater and Surveying. Ask a question in words with ask(), or call a capability by name with typed inputs with solve(). Every answer carries its value and unit, the steps that produced it and the formula in LaTeX.

When a question is not determined — a value is missing, an input is out of range, or the request is outside the package — it says so and names what it needs, instead of guessing. It runs on an ordinary CPU without a network connection (Python >=3.10), and the same question always gets the same answer.

Install

pip install civil-engineering-ai999x
hf download AI999X/civil-engineering-ai999x --local-dir civil-engineering-ai999x

What it covers

Foundations9Coulomb active thrust on a rough wall with sloping backfill · Coulomb passive thrust on a rough wall · Rankine active earth pressure and thrust on a wall …Groundwater8Darcy flow across soil layers in series; equivalent conductivities · Drawdown from several wells by superposition (Theis) · Hydraulic conductivity from a falling-head test …Hydrology17Areal rainfall by Thiessen polygons · Direct runoff hydrograph by unit-hydrograph convolution · Green-Ampt cumulative infiltration under ponding …Open-channel hydraulics23Broad-crested weir discharge · Chezy coefficient from Manning's n · Chezy velocity …Pipe flow and water networks5Flow division among parallel pipes (Hazen-Williams) · Hazen-Williams head loss in a pipe · Pipe flow from a head loss (Hazen-Williams) …Soil mechanics20Average degree of consolidation after a time (Terzaghi) · Coefficient of consolidation from a consolidation time · Cohesion and friction angle from direct shear tests …Surveying6Area between a survey line and a boundary from offsets · Closed traverse: misclosure and Bowditch (compass rule) adjustment · Earthwork volume from cross-section areas …

Try it

Worked examples

Each question below was put to civil-engineering-ai999x and the answer shown is the one it returned, with the steps it took.

Open-channel hydraulicsm.ask(…)

Manning discharge in a rectangular channel with b = 3 m, y = 1.2 m, S = 0.001 and n = 0.013.

Q = 6.682900203 m^3/s

V = 1.856361167 m/s

A = 3.6 m^2

R = 0.6666666667 m

Show the steps

Manning discharge in a rectangular channel
Q = \frac{1}{n}A R^{2/3} S^{1/2},\quad A = by,\ R = \frac{by}{b+2y}
with b = 3 m, y = 1.2 m, S = 0.001, n = 0.013
→ Q = 6.682900203 m^3/s, V = 1.856361167 m/s, A = 3.6 m^2, R = 0.6666666667 m

Capability: Manning discharge in a rectangular channel

Groundwaterm.ask(…)

Theis drawdown with pumping rate = 2500 m^3/d, transmissivity = 500 m^2/d, storativity = 0.0002, distance = 100 m and time = 24 h.

s = 2.519239468 m

u = 0.001

W = 6.331539364

Show the steps

Theis drawdown around a pumped well
s = \frac{Q}{4\pi T}W(u),\quad u = \frac{r^2S}{4Tt},\quad W(u) = \int_u^\infty \frac{e^{-x}}{x}\,dx
with Q = 0.02893518519 m^3/s, T = 0.005787037037 m^2/s, S = 0.0002, r = 100 m, t = 86400 s
→ s = 2.519239468 m, u = 0.001 m, W = 6.331539364 m

Capability: Theis drawdown around a pumped well

Soil mechanicsm.solve(…)

m.solve("consolidation_settlement_nc", Cc=0.32, e0=0.92, H="4 m", s0="80 kPa", ds="60 kPa")

Sc = 0.1620253658 m

de = 0.07777217558

e_final = 0.8422278244

Show the steps

Primary consolidation settlement of a normally consolidated clay
S_c = \frac{C_c H}{1+e_0}\log_{10}\frac{\sigma'_0+\Delta\sigma}{\sigma'_0}
with Cc = 0.32, e0 = 0.92, H = 4 m, s0 = 80 kPa, ds = 60 kPa
→ Sc = 0.1620253658 m, de = 0.07777217558 m, e_final = 0.8422278244 m

Capability: Primary consolidation settlement of a normally consolidated clay

Pipe flow and water networksm.ask(…)

Hardy cross network with pipes = [1-2, 2-3, 3-4, 4-1, 2-4], L = [600, 500, 600, 500, 780], D = [300, 250, 200, 250, 200], C = [120, 120, 120, 120, 120] and demands = [0, 0.04, 0.05, 0.03].

flows = [0.07143998453, 0.03313438395, -0.01686561605, -0.04856001547, -0.001694399424] m^3/s

head_loss = [0, 2.398748344, 3.569736308, 2.376754232] m

loops = 2

iterations = 14

Show the steps

Pipe network flows by the Hardy Cross method (Hazen-Williams)
\Delta Q = -\frac{\sum k\,Q|Q|^{0.852}}{1.852\sum k|Q|^{0.852}},\quad k = \frac{10.67L}{C^{1.852}D^{4.871}}
with pipes = 1-2, 2-3, 3-4, 4-1, 2-4, L = [600, 500, 600, 500, 780], D = [300, 250, 200, 250, 200], C = [120, 120, 120, 120, 120], demands = [0, 0.04, 0.05, 0.03]
→ flows = [0.07143998453, 0.03313438395, -0.01686561605, -0.04856001547, -0.001694399424] m^3/s, head_loss = [0, 2.398748344, 3.569736308, 2.376754232] m, loops = 2 m^3/s, iterations = 14 m^3/s

Capability: Pipe network flows by the Hardy Cross method (Hazen-Williams)

Surveyingm.ask(…)

Horizontal circular curve with radius = 300 m, deflection angle = 40 degrees and PI chainage = 1250 m.

T = 109.1910703 m

L = 209.4395102 m

LC = 205.212086 m

E = 19.25333174 m

M = 18.09221376 m

PC = 1140.80893 m

Show the steps

Elements of a simple horizontal circular curve
T = R\tan\frac{\Delta}{2},\quad L = R\Delta,\quad LC = 2R\sin\frac{\Delta}{2}
with R = 300 m, Delta = 40, PI = 1250 m
→ T = 109.1910703 m, L = 209.4395102 m, LC = 205.212086 m, E = 19.25333174 m, M = 18.09221376 m, PC = 1140.80893 m, PT = 1350.24844 m

Capability: Elements of a simple horizontal circular curve

Foundationsm.ask(…)

Coulomb active thrust with friction angle = 30 degrees, wall friction angle = 20 degrees, backfill slope = 10 degrees, unit weight = 18 kN/m^3 and height = 6 m.

Ka = 0.3400223954

Pa = 110167.2561 N/m

Pa_h = 103523.3576 N/m

Pa_v = 37679.42072 N/m

Show the steps

Coulomb active thrust on a rough wall with sloping backfill
K_a = \frac{\cos^2\phi}{\cos\delta\left[1+\sqrt{\frac{\sin(\phi+\delta)\sin(\phi-\beta)}{\cos\delta\cos\beta}}\right]^2}
with phi = 30, delta = 20, beta = 10, gam = 18000 N/m^3, H = 6 m
→ Ka = 0.3400223954, Pa = 110167.2561 N/m, Pa_h = 103523.3576 N/m, Pa_v = 37679.42072 N/m

Capability: Coulomb active thrust on a rough wall with sloping backfill

Hydrologym.ask(…)

Design return period for a risk with risk = 0.1 and design life = 50 years.

T = 475.0612547

p_annual = 0.002104991704

Show the steps

Return period for an acceptable risk over a design life
T = \frac{1}{1-(1-R)^{1/n}}
with R = 0.1, n = 50
→ T = 475.0612547, p_annual = 0.002104991704

Capability: Return period for an acceptable risk over a design life

Foundationsm.ask(…)

Coulomb passive thrust with friction angle = 30 degrees, wall friction angle = 15 degrees, backfill slope = 0 degrees, unit weight = 18 kN/m^3 and height = 2 m.

Kp = 4.976500223

Pp = 179154.008 N/m

Pp_h = 173049.4832 N/m

Pp_v = 46368.46928 N/m

Show the steps

Coulomb passive thrust on a rough wall
K_p = \frac{\cos^2\phi}{\cos\delta\left[1-\sqrt{\frac{\sin(\phi+\delta)\sin(\phi+\beta)}{\cos\delta\cos\beta}}\right]^2}
with phi = 30, delta = 15, beta = 0, gam = 18000 N/m^3, H = 2 m
→ Kp = 4.976500223, Pp = 179154.008 N/m, Pp_h = 173049.4832 N/m, Pp_v = 46368.46928 N/m

Capability: Coulomb passive thrust on a rough wall

Use it

From Python or the command line

Every snippet was run as shown; the output under it is what it printed.

import civil_engineering_ai999x as m

a = m.ask("Manning discharge in a rectangular channel with b = 3 m, y = 1.2 m, S = 0.001 and n = 0.013.")
print(a.outcome)
print(a.values)
for step in a.steps:
    print(step["name"])

Output

SOLVED
{'Q': 6.68290020277, 'V': 1.85636116744, 'A': 3.6, 'R': 0.666666666667}
Manning discharge in a rectangular channel

import civil_engineering_ai999x as m

a = m.solve("consolidation_settlement_nc", Cc=0.32, e0=0.92, H="4 m", s0="80 kPa", ds="60 kPa")
print(a.outcome)
print(a.values)

Output

SOLVED
{'Sc': 0.162025365791, 'de': 0.0777721755796, 'e_final': 0.84222782442}

import civil_engineering_ai999x as m

# an input is missing: the answer says what it needs instead of guessing
a = m.solve("consolidation_settlement_nc")
print(a.outcome)
print(a.message)

Output

NEEDS_INPUT
consolidation_settlement_nc needs Cc, e0, H, s0, ds (compression index; initial void ratio; clay layer thickness; initial effective vertical stress at mid-depth; added vertical stress at mid-depth). Example: solve('consolidation_settlement_nc', Cc=0.32, e0=0.92, H='4 m', s0='80000 Pa', ds='60000 Pa').

civil-engineering-ai999x "Manning discharge in a rectangular channel with b = 3 m, y = 1.2 m, S = 0.001 and n = 0.013."

Output

Q = 6.6829 m^3/s, V = 1.85636 m/s, A = 3.6 m^2, R = 0.666667 m
1. Manning discharge in a rectangular channel: A = b y, R = A/(b + 2y), Q = A R^(2/3) S^(1/2)/n  with b = 3 m, y = 1.2 m, S = 0.001, n = 0.013  ->  Q = 6.6829 m^3/s, V = 1.85636 m/s, A = 3.6 m^2, R = 0.666667 m
Assumptions: b, y > 0; 0 < S < 1; 0.005 <= n <= 0.2
…

Figures

Computed, not drawn by hand

Every value in these figures was computed by the package, each point a run of solve(); in a notebook, plot() and plot_relation() draw a capability's curves the same way.

Drawdown cone around a pumped well

s = \frac{Q}{4\pi T}W(u),\quad u = \frac{r^2S}{4Tt},\quad W(u) = \int_u^\infty \frac{e^{-x}}{x}\,dx

Drawdown cone around a well pumping Q = 2500 m³/d from a confined aquifer (T = 500 m²/d, S = 0.0002) after 1, 10 and 100 days, drawdown computed by the package at 41 distances from 5 m to 1 km (shown on both sides of the well): 4.90277 m at r = 5 m after 1 d; 5.81894 m at r = 5 m after 10 d; 6.73511 m at r = 5 m after 100 d. Marked: r = 100 m, t = 1 d, s = 2.51924 m.

Specific-energy diagram and alternate depths

E = y + \frac{q^2}{2 g y^2},\quad y_2^3 - E\,y_2^2 + \frac{q^2}{2g} = 0

Specific-energy diagram of a rectangular channel carrying Q = 6 m³/s in b = 2 m (E computed by the package at 81 depths). Depth y = 0.4 m (supercritical, Fr = 3.78614) has E = 3.26697 m and the alternate depth 3.22281 m; marked: critical depth yc = 0.971683 m at the minimum energy E = 1.45752 m.

Active earth pressure on a retaining wall

K_a = \frac{1-\sin\phi}{1+\sin\phi},\quad \sigma_a = K_a(\gamma z + q) - 2c\sqrt{K_a}

Rankine active earth pressure on a 6 m wall retaining soil with φ = 30° and γ = 18 kN/m³ (Ka = 0.333333), drawn as the pressure diagram against the wall: the pressure at each of 40 depths is the base pressure the package returns for a wall of that height. Without surcharge it grows to 36 kPa at the base, resultant Pa = 108 kN/m acting 2 m above the base (arrow); with a 20 kPa surcharge (dashed) the base pressure is 42.6667 kPa and Pa = 148 kN/m.

Flood routing: inflow and outflow hydrographs

O_{j+1} = C_0 I_{j+1} + C_1 I_j + C_2 O_j,\quad C_0 = \frac{\Delta t-2KX}{2K(1-X)+\Delta t}

A flood wave routed through a river reach by the Muskingum method (K = 12 h, X = 0.2, Δt = 6 h; C0 = 0.047619, C1 = 0.428571, C2 = 0.52381): inflow per interval as bars, the outflow returned by the package as stems — lower and later; peak inflow 68 m³/s, marked: peak outflow t = 24 h, Q = 45.836 m³/s (attenuation 22.164 m³/s).

Flows in a looped pipe network

\Delta Q = -\frac{\sum k\,Q|Q|^{0.852}}{1.852\sum k|Q|^{0.852}},\quad k = \frac{10.67L}{C^{1.852}D^{4.871}}

A looped pipe network (5 pipes, 2 loops; lengths [600, 500, 600, 500, 780] m, diameters [300, 250, 200, 250, 200] mm, Hazen–Williams C = 120) balanced by the Hardy Cross method in 14 iterations: arrows show the direction and size of each pipe flow returned by the package (L/s, a negative value flows against the stated pipe direction: 1→2: 71.44, 2→3: 33.1344, 3→4: -16.8656, 4→1: -48.56, 2→4: -1.6944); boxes give each node's demand. The node positions are a layout, not to scale.

Formulas

The mathematics inside

12 of its 88 formulas; every one is in the capability browser below.

Manning discharge in a rectangular channel

Q = \frac{1}{n}A R^{2/3} S^{1/2},\quad A = by,\ R = \frac{by}{b+2y}

Theis drawdown around a pumped well

s = \frac{Q}{4\pi T}W(u),\quad u = \frac{r^2S}{4Tt},\quad W(u) = \int_u^\infty \frac{e^{-x}}{x}\,dx

Primary consolidation settlement of a normally consolidated clay

S_c = \frac{C_c H}{1+e_0}\log_{10}\frac{\sigma'_0+\Delta\sigma}{\sigma'_0}

Pipe network flows by the Hardy Cross method (Hazen-Williams)

\Delta Q = -\frac{\sum k\,Q|Q|^{0.852}}{1.852\sum k|Q|^{0.852}},\quad k = \frac{10.67L}{C^{1.852}D^{4.871}}

Elements of a simple horizontal circular curve

T = R\tan\frac{\Delta}{2},\quad L = R\Delta,\quad LC = 2R\sin\frac{\Delta}{2}

Coulomb active thrust on a rough wall with sloping backfill

K_a = \frac{\cos^2\phi}{\cos\delta\left[1+\sqrt{\frac{\sin(\phi+\delta)\sin(\phi-\beta)}{\cos\delta\cos\beta}}\right]^2}

Return period for an acceptable risk over a design life

T = \frac{1}{1-(1-R)^{1/n}}

Coulomb passive thrust on a rough wall

K_p = \frac{\cos^2\phi}{\cos\delta\left[1-\sqrt{\frac{\sin(\phi+\delta)\sin(\phi+\beta)}{\cos\delta\cos\beta}}\right]^2}

Rankine active earth pressure and thrust on a wall

K_a = \frac{1-\sin\phi}{1+\sin\phi},\quad \sigma_a = K_a(\gamma z + q) - 2c\sqrt{K_a}

Darcy flow across soil layers in series; equivalent conductivities

K_v = \frac{\sum H_i}{\sum H_i/K_i},\quad K_h = \frac{\sum K_iH_i}{\sum H_i},\quad Q = K_v\frac{\Delta h}{\sum H_i}A

Areal rainfall by Thiessen polygons

\bar P = \sum_i \frac{A_i}{A} P_i

Broad-crested weir discharge

Q = C_d\,b\sqrt{g}\left(\tfrac{2}{3}H\right)^{3/2}

Capabilities

Every capability, with an example

Search by name, formula, input or topic. Each capability opens to show what it takes, what it returns, when it applies, and a question it answered.

88 capabilities

Foundations 9

Coulomb active thrust on a rough wall with sloping backfillcoulomb_active_thrust

Coulomb active earth pressure coefficient and thrust per metre on a rough vertical wall (wall friction delta) retaining a cohesionless backfill sloping at beta, with the horizontal and vertical components of the thrust.

K_a = \frac{\cos^2\phi}{\cos\delta\left[1+\sqrt{\frac{\sin(\phi+\delta)\sin(\phi-\beta)}{\cos\delta\cos\beta}}\right]^2}

Inputs

phi friction angle of the backfill (degrees)
delta wall friction angle (degrees)
beta backfill slope angle above horizontal (degrees)
gam unit weight of the backfill [N/m^3]
H wall height [m]

Returns

Ka Coulomb active coefficient
Pa active thrust per metre, inclined at delta (N/m) [N/m]
Pa_h horizontal component (N/m) [N/m]
Pa_v vertical component (N/m) [N/m]

Applies when

vertical wall back
cohesionless dry backfill
0 <= delta <= phi
0 <= beta < phi

Example

m.ask("Coulomb active thrust with friction angle = 30 degrees, wall friction angle = 20 degrees, backfill slope = 10 degrees, unit weight = 18 kN/m^3 and height = 6 m.")

→ Ka = 0.340022, Pa = 110167 N/m, Pa_h = 103523 N/m, Pa_v = 37679.4 N/m

Coulomb passive thrust on a rough wallcoulomb_passive_thrust

Coulomb (plane-wedge) passive earth pressure coefficient and thrust per metre on a rough vertical wall with wall friction delta and a soil surface rising at beta (plane wedges overestimate the passive resistance when delta is large; keep delta below about phi/2 in design).

K_p = \frac{\cos^2\phi}{\cos\delta\left[1-\sqrt{\frac{\sin(\phi+\delta)\sin(\phi+\beta)}{\cos\delta\cos\beta}}\right]^2}

Inputs

phi friction angle of the backfill (degrees)
delta wall friction angle (degrees)
beta backfill slope angle above horizontal (degrees)
gam unit weight of the backfill [N/m^3]
H wall height [m]

Returns

Kp Coulomb passive coefficient
Pp passive thrust per metre, inclined at delta (N/m) [N/m]
Pp_h horizontal component (N/m) [N/m]
Pp_v vertical component (N/m) [N/m]

Applies when

vertical wall back
cohesionless dry soil
plane wedge (phi + delta + beta < 90)

Example

m.ask("Coulomb passive thrust with friction angle = 30 degrees, wall friction angle = 15 degrees, backfill slope = 0 degrees, unit weight = 18 kN/m^3 and height = 2 m.")

→ Kp = 4.9765, Pp = 179154 N/m, Pp_h = 173049 N/m, Pp_v = 46368.5 N/m

Rankine active earth pressure and thrust on a wallrankine_active_thrust

Rankine active pressure coefficient, active pressure at the base, total active thrust per metre of a smooth vertical wall retaining a horizontal backfill (with optional cohesion and surcharge; the tension zone is ignored), the tension-crack depth and the height of the resultant above the base. Dry backfill.

K_a = \frac{1-\sin\phi}{1+\sin\phi},\quad \sigma_a = K_a(\gamma z + q) - 2c\sqrt{K_a}

Inputs

phi friction angle of the backfill (degrees)
gam unit weight of the backfill [N/m^3]
H wall height [m]
c cohesion (default 0) [Pa] optional
q uniform surcharge (default 0) [Pa] optional

Returns

Ka active earth pressure coefficient
sigma_base active pressure at the base (Pa) [Pa]
Pa active thrust per metre of wall (N/m) [N/m]
z_crack tension-crack depth (m) [m]
ybar height of the resultant above the base (m) [m]

Applies when

smooth vertical wall, horizontal backfill
dry backfill
tension zone ignored

Example

m.ask("Rankine active thrust with friction angle = 30 degrees, unit weight = 18 kN/m^3 and height = 6 m.")

→ Ka = 0.333333, sigma_base = 36000 Pa, Pa = 108000 N/m, z_crack = 0 m, ybar = 2 m

Rankine passive earth pressure and thrustrankine_passive_thrust

Rankine passive pressure coefficient, passive pressure at the base, total passive thrust per metre on a smooth vertical wall with a horizontal soil surface (optional cohesion and surcharge) and the height of the resultant.

K_p = \frac{1+\sin\phi}{1-\sin\phi},\quad \sigma_p = K_p(\gamma z+q) + 2c\sqrt{K_p}

Inputs

phi friction angle of the soil (degrees)
gam unit weight of the soil [N/m^3]
H height of the wall in contact [m]
c cohesion (default 0) [Pa] optional
q uniform surcharge (default 0) [Pa] optional

Returns

Kp passive earth pressure coefficient
sigma_base passive pressure at the base (Pa) [Pa]
Pp passive thrust per metre of wall (N/m) [N/m]
ybar height of the resultant above the base (m) [m]

Applies when

smooth vertical wall, horizontal soil surface
dry soil

Example

m.ask("Rankine passive thrust with friction angle = 32 degrees, unit weight = 18 kN/m^3 and height = 2 m.")

→ Kp = 3.25459, sigma_base = 117165 Pa, Pp = 117165 N/m, ybar = 0.666667 m

Terzaghi bearing capacity with stated factorsterzaghi_bearing_capacity

Ultimate, allowable and net bearing capacity of a strip, square or circular footing by Terzaghi's equation with the bearing capacity factors Nc, Nq and Ngamma stated (from a table): qu = s_c c Nc + q Nq + s_g gamma B Ngamma, s_c = 1.3 and s_g = 0.4 (square) or 0.3 (circular, B = diameter).

q_u = s_c\,c N_c + \gamma D_f N_q + s_\gamma\,\gamma B N_\gamma

Inputs

c cohesion [Pa]
gam unit weight of the soil [N/m^3]
B footing width (diameter of a circular footing) [m]
Df embedment depth [m]
Nc bearing capacity factor Nc (stated)
Nq bearing capacity factor Nq (stated)
Ngamma bearing capacity factor Ngamma (stated)
shape footing shape: strip, square or circular (default strip) choice optional
FS factor of safety (default 3) optional

Returns

qu ultimate bearing capacity (Pa) [Pa]
qa allowable bearing capacity qu/FS (Pa) [Pa]
q_net net ultimate bearing capacity qu - gamma Df (Pa) [Pa]

Applies when

c, Df >= 0
factors as stated (Terzaghi's table for the friction angle)
general shear failure, vertical central load

Example

m.ask("Terzaghi bearing capacity with cohesion = 20 kPa, unit weight = 18 kN/m^3, width = 2 m, depth = 1.5 m, Nc = 37.16, Nq = 22.46, Ngamma = 19.13 and footing shape = square.")

→ qu = 1.84805e+06 Pa, qa = 616017 Pa, q_net = 1.82105e+06 Pa

Ultimate bearing capacity of a strip footingstrip_footing_bearing_capacity

Ultimate and allowable bearing capacity of a strip footing from the general bearing capacity equation with Prandtl-Reissner factors Nc, Nq and Vesic's (1973) Ngamma (no shape, depth or inclination factors; drained parameters, water table well below the footing).

q_u = cN_c + \gamma D_f N_q + \tfrac12\gamma B N_\gamma

Inputs

c cohesion [Pa]
phi friction angle (degrees)
gam unit weight of the soil [N/m^3]
B footing width [m]
Df embedment depth [m]
FS factor of safety for the allowable pressure (default 3) optional

Returns

qu ultimate bearing capacity (Pa) [Pa]
qa allowable bearing pressure qu/FS (Pa) [Pa]
Nc bearing capacity factor Nc
Nq bearing capacity factor Nq
Ngamma bearing capacity factor Ngamma (Vesic)

Applies when

20 <= phi <= 45 degrees
general shear failure
strip footing, vertical central load

Example

m.ask("Strip footing bearing capacity with cohesion = 10 kPa, friction angle = 30 degrees, unit weight = 18 kN/m^3, width = 1.5 m and depth = 1 m.")

→ qu = 935050 Pa, qa = 311683 Pa, Nc = 30.1396, Nq = 18.4011, Ngamma = 22.4025

Vertical stress below a uniformly loaded rectangle (Newmark)stress_below_rectangular_load

Increase in vertical stress at depth z below the corner (or the centre, by superposition of four corners) of a flexible rectangular area B x L under a uniform pressure q (Boussinesq integrated by Newmark).

\Delta\sigma_z = q\,I(m,n),\quad m = \frac{B}{z},\ n = \frac{L}{z}

Inputs

q uniform applied pressure [Pa]
B width of the loaded area [m]
L length of the loaded area [m]
z depth below the surface [m]
position point below the 'corner' (default) or the 'centre' choice optional

Returns

dsigma vertical stress increase (Pa) [Pa]
I influence factor dsigma/q

Applies when

elastic, homogeneous, isotropic half-space
flexible uniform load

Example

m.ask("Stress below a rectangular load with pressure = 200 kPa, width = 2 m, length = 3 m and depth = 4 m.")

→ dsigma = 21414.6 Pa, I = 0.107073

Vertical stress below a uniformly loaded stripstress_below_strip_load

Increase in vertical stress at depth z and horizontal offset x from the centreline of an infinitely long strip of width B under a uniform pressure q (elastic half-space).

\Delta\sigma_z = \frac{q}{\pi}\left[\alpha + \sin\alpha\cos(\alpha+2\delta)\right]

Inputs

q uniform applied pressure [Pa]
B strip width [m]
z depth below the surface [m]
x horizontal offset from the strip centreline (default 0) [m] optional

Returns

dsigma vertical stress increase (Pa) [Pa]
I influence factor dsigma/q

Applies when

elastic, homogeneous, isotropic half-space
flexible uniform load, plane strain

Example

m.ask("Stress below a strip load with pressure = 100 kPa, width = 2 m and depth = 3 m.")

→ dsigma = 39581.9 Pa, I = 0.395819

Vertical stress below the centre of a uniformly loaded circlestress_below_circular_load

Increase in vertical stress at depth z below the centre of a flexible circular area of radius a carrying a uniform pressure q (Boussinesq, elastic half-space).

\Delta\sigma_z = q\left[1-\left(\frac{1}{1+(a/z)^2}\right)^{3/2}\right]

Inputs

q uniform applied pressure [Pa]
a radius of the loaded area [m]
z depth below the surface [m]

Returns

dsigma vertical stress increase (Pa) [Pa]
I influence factor dsigma/q

Applies when

elastic, homogeneous, isotropic half-space
flexible uniform load
below the centre

Example

m.ask("Stress below a circular load with pressure = 150 kPa, radius = 2 m and depth = 3 m.")

→ dsigma = 63594.8 Pa, I = 0.423965

Groundwater 8

Darcy flow across soil layers in series; equivalent conductivitiesdarcy_flow_layered_soil

Flow rate, specific discharge and the heads at the layer interfaces for one-dimensional Darcy flow across one or more soil layers in series (flow perpendicular to the layering), with the equivalent vertical (series) and horizontal (parallel) conductivities. Heads are measured from the downstream face.

K_v = \frac{\sum H_i}{\sum H_i/K_i},\quad K_h = \frac{\sum K_iH_i}{\sum H_i},\quad Q = K_v\frac{\Delta h}{\sum H_i}A

Inputs

H layer thicknesses in m, in flow order vector
K hydraulic conductivity of each layer in m/s vector
A flow cross-section area [m^2]
dh head difference across all layers [m]

Returns

Q flow rate (m^3/s) [m^3/s]
q specific discharge (Darcy velocity, m/s) [m/s]
Kv equivalent conductivity across the layers (m/s) [m/s]
Kh equivalent conductivity along the layers (m/s) [m/s]
heads head at each interior interface above the outlet (m) [m]

Applies when

steady, saturated, laminar flow
flow perpendicular to the layers

Example

m.ask("Darcy flow through layered soil with thicknesses = [2], conductivities = [1e-05], area = 10 m^2 and head difference = 0.5 m.")

→ Q = 2.5e-05 m^3/s, q = 2.5e-06 m/s, Kv = 1e-05 m/s, Kh = 1e-05 m/s, heads = [0.0] m

Drawdown from several wells by superposition (Theis)well_field_drawdown

Total drawdown at a point from several wells pumping (positive rate) or injecting (negative rate) at constant rates in a confined aquifer, by superposing Theis solutions; with each well's contribution. Coordinates in m, rates in m^3/day.

s = \sum_i \frac{Q_i}{4\pi T}W\!\left(\frac{r_i^2S}{4Tt}\right)

Inputs

wx well x coordinates in m vector
wy well y coordinates in m vector
Qs pumping rates in m^3/day (negative for injection) vector
T transmissivity [m^2/s]
S storativity
t time since pumping began (all wells together) [s]
x0 x coordinate of the point [m]
y0 y coordinate of the point [m]

Returns

s total drawdown (m) [m]
parts drawdown from each well (m) [m]

Applies when

confined, homogeneous, infinite aquifer
all wells started together
point at least 5 cm from any well

Example

m.ask("Well field drawdown with well x = [0, 200], well y = [0, 0], pumping rates = [2000, 1500], transmissivity = 400 m^2/d, storativity = 0.0003, time = 5 d, point x = 100 m and point y = 50 m.")

→ s = 4.93588 m, parts = [2.82050172973, 2.1153762973] m

Hydraulic conductivity from a falling-head testfalling_head_permeability

Hydraulic conductivity of a soil sample from a falling-head permeameter: standpipe diameter d, sample diameter D and length L, the standpipe head falling from h1 to h2 in time t.

K = \frac{aL}{At}\ln\frac{h_1}{h_2}

Inputs

d standpipe diameter [m]
D sample diameter [m]
L sample length [m]
h1 initial head [m]
h2 final head [m]
t elapsed time [s]

Returns

K hydraulic conductivity (m/s) [m/s]
K_cm_s hydraulic conductivity (cm/s)

Applies when

h2 < h1
saturated sample, laminar flow

Example

m.ask("Falling head permeability with standpipe diameter = 10 mm, sample diameter = 75 mm, sample length = 150 mm, initial head = 100 cm, final head = 60 cm and time = 600 s.")

→ K = 2.27034e-06 m/s, K_cm_s = 0.000227034

Hydraulic conductivity from steady pumping (unconfined aquifer)thiem_unconfined_conductivity

Hydraulic conductivity of an unconfined aquifer from the steady saturated thicknesses h1 < h2 in two observation wells at distances r1 < r2 from a well pumped at Q (Thiem-Dupuit equation).

K = \frac{Q\ln(r_2/r_1)}{\pi(h_2^2-h_1^2)}

Inputs

Q pumping rate [m^3/s]
r1 distance of the nearer observation well [m]
r2 distance of the farther observation well [m]
h1 saturated thickness at r1 [m]
h2 saturated thickness at r2 [m]

Returns

K hydraulic conductivity (m/s) [m/s]
K_m_d hydraulic conductivity (m/day)

Applies when

steady state
unconfined aquifer, Dupuit assumptions
r1 < r2, h1 < h2

Example

m.ask("Thiem unconfined conductivity with pumping rate = 1500 m^3/d, first distance = 20 m, second distance = 80 m, first head = 18.2 m and second head = 19.6 m.")

→ K = 0.000144765 m/s, K_m_d = 12.5077

Theis drawdown around a pumped welltheis_drawdown

Transient drawdown at distance r and time t from a well pumped at a constant rate in a confined aquifer (Theis), with u and the well function W(u) = E1(u).

s = \frac{Q}{4\pi T}W(u),\quad u = \frac{r^2S}{4Tt},\quad W(u) = \int_u^\infty \frac{e^{-x}}{x}\,dx

Inputs

Q pumping rate [m^3/s]
T transmissivity [m^2/s]
S storativity (storage coefficient)
r distance from the pumped well [m]
t time since pumping began [s]

Returns

s drawdown (m) [m]
u u = r^2 S/(4 T t)
W well function W(u)

Applies when

confined, homogeneous, infinite aquifer
fully penetrating well, constant rate
u <= 50

Example

m.ask("Theis drawdown with pumping rate = 2500 m^3/d, transmissivity = 500 m^2/d, storativity = 0.0002, distance = 100 m and time = 24 h.")

→ s = 2.51924 m, u = 0.001, W = 6.33154

Transmissivity and storativity by the Cooper-Jacob straight linecooper_jacob_analysis

Transmissivity and storativity of a confined aquifer from a pumping test by the Cooper-Jacob method: a least-squares straight line through drawdown against log10(time) (late-time data, u < 0.05, chosen by the user). Times are in minutes, drawdowns in m.

T = \frac{2.303\,Q}{4\pi\,\Delta s},\quad S = \frac{2.25\,T\,t_0}{r^2}

Inputs

times times since pumping began, in minutes vector
drawdowns drawdowns at those times, in m vector
Q pumping rate [m^3/s]
r distance of the observation well [m]

Returns

T transmissivity (m^2/s) [m^2/s]
S storativity
ds_per_cycle drawdown per log cycle of time (m) [m]
t0_min zero-drawdown intercept time (min)
T_m2_d transmissivity (m^2/day)

Applies when

late-time data on the straight line (u < 0.05)
confined aquifer

Example

m.ask("Cooper jacob analysis with times = [10, 20, 50, 100, 200, 500], drawdowns = [0.62, 0.79, 1.02, 1.19, 1.36, 1.59], pumping rate = 2000 m^3/d and distance = 50 m.")

→ T = 0.00743434 m^2/s, S = 0.000329649, ds_per_cycle = 0.570634 m, t0_min = 0.821137, T_m2_d = 642.327

Transmissivity from steady pumping (Thiem, confined aquifer)thiem_confined_transmissivity

Transmissivity (and conductivity, if the aquifer thickness is given) of a confined aquifer from the steady drawdowns in two observation wells at distances r1 < r2 from a well pumped at Q (Thiem equation).

T = \frac{Q\ln(r_2/r_1)}{2\pi(s_1-s_2)}

Inputs

Q pumping rate [m^3/s]
r1 distance of the nearer observation well [m]
r2 distance of the farther observation well [m]
s1 drawdown at r1 [m]
s2 drawdown at r2 [m]
b aquifer thickness (optional) [m] optional

Returns

T transmissivity (m^2/s) [m^2/s]
T_m2_d transmissivity (m^2/day)
K hydraulic conductivity T/b (m/s) [m/s]

Applies when

steady state
confined aquifer, fully penetrating well
r1 < r2, s1 > s2

Example

m.ask("Thiem confined transmissivity with pumping rate = 2500 m^3/d, first distance = 15 m, second distance = 60 m, first drawdown = 2.8 m and second drawdown = 1.1 m.")

→ T = 0.00375537 m^2/s, T_m2_d = 324.464

Unconfined flow between two water bodies with recharge (Dupuit)dupuit_flow_with_recharge

Steady unconfined flow per unit width between two water bodies (heads h1 at x = 0 and h2 at x = L above the base) with uniform recharge W: the flows at both ends (positive toward x = L), the groundwater divide and the highest water table (Dupuit-Forchheimer).

h^2 = h_1^2 - \frac{(h_1^2-h_2^2)x}{L} + \frac{W}{K}(L-x)x,\quad q(x) = \frac{K(h_1^2-h_2^2)}{2L} - W\left(\frac L2 - x\right)

Inputs

K hydraulic conductivity [m/s]
h1 head at x = 0 (above the impermeable base) [m]
h2 head at x = L [m]
L distance between the water bodies [m]
W recharge rate [m/s]

Returns

q0 flow per unit width at x = 0 (m^2/s, positive toward x = L) [m^2/s]
qL flow per unit width at x = L (m^2/s) [m^2/s]
x_divide position of the groundwater divide (m); outside 0..L means no divide [m]
h_max highest water table between the water bodies (m) [m]

Applies when

steady, unconfined, homogeneous aquifer on a horizontal base
Dupuit assumptions
W > 0

Example

m.ask("Dupuit recharge flow with hydraulic conductivity = 10 m/d, first head = 12 m, second head = 9 m, distance = 600 m and recharge = 300 mm/yr.")

→ q0 = 3.22446e-06 m^2/s, qL = 8.92832e-06 m^2/s, x_divide = -339.188 m, h_max = 12 m

Hydrology 17

Areal rainfall by Thiessen polygonsthiessen_polygon_rainfall

Mean areal rainfall over a catchment by the Thiessen (Voronoi) polygon method: each gauge represents the part of the catchment nearer to it than to any other gauge; the areas, weights and the arithmetic mean are also given. Coordinates in km (areas in km^2), rainfall in mm; the boundary is a simple polygon listed vertex by vertex.

\bar P = \sum_i \frac{A_i}{A} P_i

Inputs

gx gauge x coordinates in km vector
gy gauge y coordinates in km vector
rain rainfall at each gauge in mm vector
bx catchment boundary x coordinates in km vector
by catchment boundary y coordinates in km vector

Returns

mean Thiessen mean rainfall (mm)
areas area represented by each gauge (km^2)
weights Thiessen weight of each gauge
arithmetic_mean arithmetic mean (mm)
catchment_area catchment area (km^2)

Applies when

distinct gauge locations
simple (non-self-intersecting) boundary polygon

Example

m.ask("Thiessen polygon rainfall with gauge x = [2, 8, 5], gauge y = [2, 3, 9], rainfall = [45, 60, 38], boundary x = [0, 10, 10, 0] and boundary y = [0, 0, 10, 10].")

→ mean = 47.24, areas = [29.6650641026, 32.5608974359, 37.7740384615], weights = [0.296650641026, 0.325608974359, 0.377740384615], arithmetic_mean = 47.6667, catchment_area = 100

Direct runoff hydrograph by unit-hydrograph convolutionunit_hydrograph_convolution

The direct runoff (and total) hydrograph of a storm: the convolution of the excess-rainfall depths of successive periods with the unit hydrograph of the same period, plus a constant base flow.

Q_n = \sum_{m=1}^{\min(n,M)} P_m\,U_{n-m+1}

Inputs

excess excess rainfall in cm per period (one per period) vector
uh unit-hydrograph ordinates in m^3/s per cm of excess, one per period vector
baseflow constant base flow (default 0) [m^3/s] optional

Returns

DRO direct runoff ordinates (m^3/s) [m^3/s]
total total flow ordinates (m^3/s) [m^3/s]
peak peak total flow (m^3/s) [m^3/s]
peak_period period of the peak (1-based)

Applies when

excess depths and the unit hydrograph share one period
linear, time-invariant catchment

Example

m.ask("Unit hydrograph convolution with excess rainfall = [1.5, 2.5, 1] and unit hydrograph = [0, 10, 30, 22, 12, 5, 0].")

→ DRO = [0.0, 15.0, 70.0, 118.0, 103.0, 59.5, 24.5, 5.0, 0.0] m^3/s, total = [0.0, 15.0, 70.0, 118.0, 103.0, 59.5, 24.5, 5.0, 0.0] m^3/s, peak = 118 m^3/s, peak_period = 4

Green-Ampt cumulative infiltration under pondinggreen_ampt_infiltration

Cumulative infiltration and infiltration rate at time t for a soil ponded from t = 0, by the Green-Ampt model (implicit equation solved to full precision).

F - \psi\Delta\theta\,\ln\!\left(1+\frac{F}{\psi\Delta\theta}\right) = Kt,\quad f = K\left(1+\frac{\psi\Delta\theta}{F}\right)

Inputs

K saturated hydraulic conductivity [m/s]
psi wetting-front suction head [m]
dtheta moisture deficit (porosity minus initial water content)
t time since ponding began [s]

Returns

F cumulative infiltration (m) [m]
f infiltration rate (m/s) [m/s]
F_mm cumulative infiltration (mm)
f_mm_h infiltration rate (mm/h)

Applies when

ponded surface from t = 0
homogeneous soil, sharp wetting front

Example

m.ask("Green ampt infiltration with hydraulic conductivity = 10.9 mm/h, suction head = 110.1 mm, moisture deficit = 0.247 and time = 1 h.")

→ F = 0.0320967 m, f = 5.59314e-06 m/s, F_mm = 32.0967, f_mm_h = 20.1353

Gumbel (EV1) design floodgumbel_design_flood

The T-year flood from a series of annual maximum discharges by the Gumbel (extreme value type I) distribution fitted by the method of moments (Chow's frequency factor for a long record; sample standard deviation with n - 1).

Q_T = \bar Q + K_T s,\quad K_T = -\frac{\sqrt6}{\pi}\left[0.5772 + \ln\ln\frac{T}{T-1}\right]

Inputs

peaks annual maximum discharges in m^3/s vector
T return period (years)

Returns

Q_T T-year flood (m^3/s) [m^3/s]
K_T frequency factor
mean mean annual maximum (m^3/s) [m^3/s]
std sample standard deviation (m^3/s) [m^3/s]

Applies when

at least five annual maxima
T > 1 year
method of moments (no sample-size correction table)

Example

m.ask("Gumbel design flood with annual maxima = [420, 380, 510, 290, 640, 455, 370, 520, 600, 330] and return period = 100 years.")

→ Q_T = 812.637 m^3/s, K_T = 3.13667, mean = 451.5 m^3/s, std = 115.134 m^3/s

Horton infiltration rate and cumulative infiltrationhorton_infiltration

Infiltration capacity at time t and cumulative infiltration from the start of ponding by Horton's equation.

f = f_c + (f_0-f_c)e^{-kt},\quad F = f_c t + \frac{f_0-f_c}{k}\left(1-e^{-kt}\right)

Inputs

f0 initial infiltration capacity [m/s]
fc final (constant) infiltration capacity [m/s]
k Horton decay constant
t time since ponding began [s]

Returns

f infiltration capacity at t (m/s) [m/s]
F cumulative infiltration (m) [m]
f_mm_h infiltration capacity (mm/h)
F_mm cumulative infiltration (mm)

Applies when

0 <= fc < f0
ponded surface from t = 0

Example

m.ask("Horton infiltration with initial rate = 75 mm/h, final rate = 10 mm/h, decay constant = 4 1/h and time = 1 h.")

→ f = 3.10848e-06 m/s, F = 0.0259524 m, f_mm_h = 11.1905, F_mm = 25.9524

Kling-Gupta efficiencykling_gupta_efficiency

Kling-Gupta efficiency of simulated against observed values (Gupta et al. 2009) with its components: the correlation r, the variability ratio alpha (population standard deviations) and the bias ratio beta.

KGE = 1-\sqrt{(r-1)^2+(\alpha-1)^2+(\beta-1)^2}

Inputs

obs observed values (any unit) vector
sim simulated values, same unit and order vector

Returns

KGE Kling-Gupta efficiency
r Pearson correlation
alpha ratio of standard deviations sim/obs
beta ratio of means sim/obs

Applies when

paired series of equal length
both series vary

Example

m.ask("Kling gupta efficiency with observed = [12, 30, 55, 41, 22, 15] and simulated = [10, 34, 50, 44, 20, 17].")

→ KGE = 0.962739, r = 0.97687, alpha = 0.970787, beta = 1

Log-Pearson type III design floodlog_pearson_iii_design_flood

The T-year flood by the log-Pearson type III distribution fitted by moments of the base-10 logarithms (station skew only, no regional skew weighting or outlier tests), frequency factor from the exact Pearson III quantile.

\log Q_T = \bar y + K_T(G, T)\,s_y

Inputs

peaks annual maximum discharges in m^3/s vector
T return period (years)

Returns

Q_T T-year flood (m^3/s) [m^3/s]
K_T Pearson III frequency factor
mean_log mean of log10 Q
std_log standard deviation of log10 Q
skew skew coefficient of log10 Q (unbiased)

Applies when

at least ten annual maxima
station skew only
no outlier screening

Example

m.ask("Log pearson iii design flood with annual maxima = [420, 380, 510, 290, 640, 455, 370, 520, 600, 330, 880, 410] and return period = 100 years.")

→ Q_T = 1083.77 m^3/s, K_T = 2.75391, mean_log = 2.66461, std_log = 0.134473, skew = 0.598211

Muskingum flood routingmuskingum_routing

Routes an inflow hydrograph through a river reach by the Muskingum method (storage S = K[X I + (1 - X) O]), giving the outflow ordinates, routing coefficients, peak outflow and attenuation. The first outflow equals the first inflow unless stated.

O_{j+1} = C_0 I_{j+1} + C_1 I_j + C_2 O_j,\quad C_0 = \frac{\Delta t-2KX}{2K(1-X)+\Delta t}

Inputs

inflow inflow ordinates in m^3/s at equal intervals vector
K storage (travel-time) constant [s]
X weighting factor (0 to 0.5)
dt routing interval [s]
O1 initial outflow (default: the first inflow) [m^3/s] optional

Returns

outflow outflow ordinates (m^3/s) [m^3/s]
C0 coefficient C0
C1 coefficient C1
C2 coefficient C2
peak_outflow peak outflow (m^3/s) [m^3/s]
attenuation peak attenuation (m^3/s) [m^3/s]

Applies when

0 <= X <= 0.5
2 K X <= dt <= 2 K (1 - X) (no negative coefficient)

Example

m.ask("Muskingum routing with inflow = [10, 30, 68, 50, 40, 31, 23, 15, 10], storage constant = 12 h, weighting factor = 0.2 and interval = 6 h.")

→ outflow = [10.0, 10.9523809524, 21.8321995465, 42.959723572, 45.8360456806, 42.6284048803, 36.7101168421, 29.8005373935, 22.5145672061] m^3/s, C0 = 0.047619, C1 = 0.428571, C2 = 0.52381, peak_outflow = 45.836 m^3/s, attenuation = 22.164 m^3/s

Nash-Sutcliffe efficiency, RMSE and percent biasnash_sutcliffe_efficiency

Goodness of fit of simulated to observed flows: Nash-Sutcliffe efficiency, root-mean-square error and percent bias (positive when the model underestimates, as hydroeval defines it).

NSE = 1 - \frac{\sum (O_i-S_i)^2}{\sum (O_i-\bar O)^2}

Inputs

obs observed values (any unit) vector
sim simulated values, same unit and order vector

Returns

NSE Nash-Sutcliffe efficiency
RMSE root-mean-square error (unit of the data)
PBIAS percent bias 100 sum(obs - sim)/sum(obs)

Applies when

paired series of equal length
observed values not all equal

Example

m.ask("Nash sutcliffe efficiency with observed = [12, 30, 55, 41, 22, 15] and simulated = [10, 34, 50, 44, 20, 17].")

→ NSE = 0.954238, RMSE = 3.21455, PBIAS = 0

Peak runoff by the rational methodrational_method_peak_runoff

The peak runoff Q = C i A of a small catchment from the runoff coefficient, the rainfall intensity for a duration equal to the time of concentration, and the catchment area.

Q = C\,i\,A

Inputs

C runoff coefficient (0 to 1)
i rainfall intensity [m/s]
A catchment area [m^2]

Returns

Q peak runoff (m^3/s) [m^3/s]
Q_Ls peak runoff (L/s)

Applies when

0 < C <= 1
A <= 800 ha (small catchments)
intensity for a duration equal to the time of concentration

Example

m.ask("Rational method peak runoff with runoff coefficient = 0.6, rainfall intensity = 50 mm/h and catchment area = 20 ha.")

→ Q = 1.66667 m^3/s, Q_Ls = 1666.67

Phi-index of a stormphi_index

The constant loss rate (phi-index) that, subtracted from every interval of a rainfall hyetograph, leaves exactly the observed runoff depth; with the excess rainfall of each interval.

\sum_i \max(P_i - \phi\,\Delta t,\,0) = R

Inputs

rain rainfall depth in each interval in mm vector
dt duration of one interval [s]
R observed direct runoff depth [m]

Returns

phi phi-index (mm/h)
excess excess rainfall in each interval (mm)
contributing number of intervals producing runoff

Applies when

0 < runoff < total rainfall
equal intervals

Example

m.ask("Phi index with rainfall = [4, 9, 18, 12, 3, 1], interval = 1 h and runoff = 20 mm.")

→ phi = 6.33333, excess = [0.0, 2.66666666667, 11.6666666667, 5.66666666667, 0.0, 0.0], contributing = 3

Return period for an acceptable risk over a design lifedesign_return_period_for_risk

The design return period whose event has only the stated probability R of being exceeded during an n-year life.

T = \frac{1}{1-(1-R)^{1/n}}

Inputs

R acceptable risk of exceedance (fraction, or % in a question)
n design life (whole years) integer

Returns

T required return period (years)
p_annual annual exceedance probability

Applies when

0 < R < 1
independent years

Example

m.ask("Design return period for a risk with risk = 0.1 and design life = 50 years.")

→ T = 475.061, p_annual = 0.00210499

Return periods by the Weibull plotting positionweibull_plotting_positions

Ranks annual maxima from largest to smallest and gives each its exceedance probability m/(n + 1) and return period (n + 1)/m (Weibull plotting position).

P = \frac{m}{n+1},\quad T = \frac{n+1}{m}

Inputs

peaks annual maxima (any unit; the ranking keeps it) vector

Returns

ranked values ranked from largest to smallest
T return period of each (years)
P exceedance probability of each

Applies when

annual series
ties keep distinct ranks

Example

m.ask("Weibull plotting position with annual maxima = [420, 380, 510, 290, 640].")

→ ranked = [640.0, 510.0, 420.0, 380.0, 290.0], T = [6.0, 3.0, 2.0, 1.5, 1.2], P = [0.166666666667, 0.333333333333, 0.5, 0.666666666667, 0.833333333333]

Risk of exceedance over a design lifeflood_exceedance_risk

Probability that an event of return period T is equalled or exceeded at least once in n years (independent years), with the annual exceedance probability.

R = 1 - \left(1 - \frac{1}{T}\right)^n

Inputs

T return period (years)
n design life or period (whole years) integer

Returns

risk probability of at least one exceedance in n years
p_annual annual exceedance probability 1/T
p_none probability of no exceedance

Applies when

T > 1 year
independent years

Example

m.ask("Flood exceedance risk with return period = 100 years and design life = 50 years.")

→ risk = 0.394994, p_annual = 0.01, p_none = 0.605006

SCS curve-number runoff depthscs_curve_number_runoff

Direct runoff depth from a storm rainfall depth by the SCS (NRCS) curve-number method, with the potential retention S and the initial abstraction Ia = lambda S (lambda = 0.2 unless stated).

Q = \frac{(P-I_a)^2}{P-I_a+S},\quad S = \frac{25400}{CN}-254,\quad I_a = \lambda S

Inputs

P storm rainfall depth [m]
CN curve number (30 to 100)
lam initial-abstraction ratio (default 0.2) optional

Returns

Q runoff depth (mm)
S potential maximum retention (mm)
Ia initial abstraction (mm)
C runoff ratio Q/P

Applies when

30 <= CN <= 100
rainfall depth in mm
0 <= lambda <= 0.3

Example

m.ask("Scs curve number runoff with rainfall = 100 mm and curve number = 80.")

→ Q = 50.5391, S = 63.5, Ia = 12.7, C = 0.505391

Time of concentration by the Kirpich formulakirpich_time_of_concentration

The time of concentration tc = 0.0078 L^0.77 S^-0.385 minutes (L in feet; equivalent to 0.0195 L^0.77 S^-0.385 with L in metres) of a small rural catchment from the flow length and the average slope.

t_c = 0.0078\,L^{0.77}S^{-0.385}\ \text{(min, L in ft)}

Inputs

L length of the longest flow path [m]
S average slope (m/m)

Returns

tc time of concentration (s) [s]
tc_min time of concentration (min)
tc_h time of concentration (h)

Applies when

0 < S <= 1
L <= 100 km
small rural catchments (Kirpich's data: 0.4 to 45 ha)

Example

m.ask("Kirpich time of concentration with flow length = 1500 m and slope = 0.02.")

→ tc = 1469.77 s, tc_min = 24.4961, tc_h = 0.408268

Unit hydrograph from a storm by least-squares deconvolutionunit_hydrograph_derivation

The unit hydrograph that best reproduces an observed direct-runoff hydrograph from its excess-rainfall depths (least-squares solution of the convolution equations), with the RMS misfit.

\min_u \lVert A u - Q\rVert_2,\quad A_{kj} = P_{k-j+1}

Inputs

dro observed direct runoff ordinates in m^3/s (base flow removed) vector
excess excess rainfall in cm per period vector

Returns

uh unit-hydrograph ordinates (m^3/s per cm) [m^3/s]
rms_residual RMS misfit of the reconstructed runoff (m^3/s) [m^3/s]
peak unit-hydrograph peak (m^3/s per cm) [m^3/s]

Applies when

len(dro) >= len(excess) + 1
the same period for both

Example

m.ask("Unit hydrograph derivation with direct runoff = [0, 15, 61, 77, 52, 29, 11, 3] and excess rainfall = [1.5, 2].")

→ uh = [-0.502834815065, 11.0475725314, 25.6537253747, 17.3404996047, 11.3869004489, 4.27012446017, 1.55034025912] m^3/s, rms_residual = 0.401139 m^3/s, peak = 25.6537 m^3/s

Open-channel hydraulics 23

Broad-crested weir dischargebroad_crested_weir_discharge

Discharge over a broad-crested weir for a stated discharge coefficient (critical depth 2H/3 on the crest, approach velocity head included in H).

Q = C_d\,b\sqrt{g}\left(\tfrac{2}{3}H\right)^{3/2}

Inputs

Cd discharge coefficient (stated, e.g. 0.95)
b crest width [m]
H upstream head over the crest [m]

Returns

Q discharge (m^3/s) [m^3/s]
yc critical depth on the crest 2H/3 (m) [m]

Applies when

Cd stated
critical flow on the crest
H includes the approach velocity head

Example

m.ask("Broad crested weir discharge with discharge coefficient = 0.95, crest width = 5 m and head = 0.6 m.")

→ Q = 3.76373 m^3/s, yc = 0.4 m

Chezy coefficient from Manning's nchezy_from_manning

The Chezy coefficient equivalent to a Manning roughness n at hydraulic radius R (SI units).

C = \frac{R^{1/6}}{n}

Inputs

n Manning roughness coefficient
R hydraulic radius [m]

Returns

C Chezy coefficient (m^(1/2)/s) [m^0.5/s]

Applies when

0.005 <= n <= 0.2
R > 0

Example

m.ask("Chezy coefficient from manning with Manning n = 0.013 and hydraulic radius = 0.75 m.")

→ C = 73.3219 m^0.5/s

Chezy velocitychezy_velocity

Mean velocity of uniform flow from the Chezy equation for a Chezy coefficient C (m^(1/2)/s), hydraulic radius R and slope S.

V = C\sqrt{R S}

Inputs

C Chezy coefficient (m^(1/2)/s) [m^0.5/s]
R hydraulic radius [m]
S channel (energy) slope, m/m

Returns

V mean velocity (m/s) [m/s]

Applies when

C, R > 0
0 < S < 1

Example

m.ask("Chezy velocity with Chezy C = 55 m^0.5/s, hydraulic radius = 1.1 m and slope = 0.0004.")

→ V = 1.15369 m/s

Critical depth in a circular conduitcritical_depth_circular

Critical depth, area, velocity and minimum specific energy for a discharge Q in a circular pipe or culvert flowing part full (refused when the critical depth would exceed 0.95 D).

\frac{Q^2\,T}{g\,A^3} = 1,\quad A = \frac{D^2}{8}(\theta-\sin\theta),\ T = D\sin\frac{\theta}{2}

Inputs

Q discharge [m^3/s]
D pipe diameter [m]

Returns

yc critical depth (m) [m]
Ac critical flow area (m^2) [m^2]
Vc critical velocity (m/s) [m/s]
Emin minimum specific energy (m) [m]

Applies when

Q, D > 0
critical depth below 0.95 D

Example

m.ask("Critical depth in a circular pipe with discharge = 0.5 m^3/s and diameter = 1 m.")

→ yc = 0.398841 m, Ac = 0.292235 m^2, Vc = 1.71095 m/s, Emin = 0.548044 m

Critical depth in a rectangular channelcritical_depth_rectangular

Critical depth, critical velocity and minimum specific energy for a discharge Q in a rectangular channel.

y_c = \left(\frac{q^2}{g}\right)^{1/3},\quad E_{min} = \tfrac{3}{2}y_c

Inputs

Q discharge [m^3/s]
b channel width [m]

Returns

yc critical depth (m) [m]
Vc critical velocity (m/s) [m/s]
Emin minimum specific energy 1.5 yc (m) [m]
q discharge per unit width (m^2/s) [m^2/s]

Applies when

Q, b > 0

Example

m.ask("Critical depth in a rectangular channel with discharge = 8 m^3/s and width = 3 m.")

→ yc = 0.898303 m, Vc = 2.96856 m/s, Emin = 1.34745 m, q = 2.66667 m^2/s

Critical depth in a trapezoidal channelcritical_depth_trapezoidal

Critical depth, area, velocity and minimum specific energy for a discharge Q in a trapezoidal (or triangular, b = 0) channel, from Q^2 T = g A^3.

\frac{Q^2\,T}{g\,A^3} = 1,\quad A = (b+zy)y,\ T = b+2zy

Inputs

Q discharge [m^3/s]
b bottom width [m]
z side slope, horizontal per unit vertical

Returns

yc critical depth (m) [m]
Ac critical flow area (m^2) [m^2]
Vc critical velocity (m/s) [m/s]
Emin minimum specific energy (m) [m]

Applies when

Q > 0
b >= 0
z > 0

Example

m.ask("Critical depth in a trapezoidal channel with discharge = 15 m^3/s, width = 3 m and side slope = 2.")

→ yc = 1.07108 m, Ac = 5.50766 m^2, Vc = 2.72348 m/s, Emin = 1.44913 m

Discharge through a small orifice under a headorifice_discharge

Discharge through a small sharp-edged orifice of diameter d under a constant head h for a stated discharge coefficient (Torricelli's velocity times Cd times the orifice area).

Q = C_d\,\frac{\pi d^2}{4}\sqrt{2gh}

Inputs

Cd discharge coefficient (stated, e.g. 0.61)
d orifice diameter [m]
h head above the orifice centre [m]

Returns

Q discharge (m^3/s) [m^3/s]
V_ideal ideal jet velocity sqrt(2 g h) (m/s) [m/s]
area orifice area (m^2) [m^2]

Applies when

small orifice (d much smaller than h)
free jet
Cd stated

Example

m.ask("Orifice discharge with discharge coefficient = 0.61, diameter = 50 mm and head = 3 m.")

→ Q = 0.00918903 m^3/s, V_ideal = 7.67203 m/s, area = 0.0019635 m^2

Froude number of flow in a rectangular channelchannel_froude_number

Froude number V/sqrt(g y) of flow at depth y in a rectangular channel, and whether the flow is subcritical, critical or supercritical.

Fr = \frac{V}{\sqrt{g\,y}}

Inputs

Q discharge [m^3/s]
b channel width [m]
y flow depth [m]

Returns

Fr Froude number
V mean velocity (m/s) [m/s]
regime flow regime: subcritical, critical or supercritical

Applies when

Q, b, y > 0

Example

m.ask("Froude number in a rectangular channel with discharge = 12 m^3/s, width = 4 m and depth = 0.5 m.")

→ Fr = 2.70914, V = 6 m/s, regime = supercritical

Hydraulic jump in a rectangular channelhydraulic_jump_rectangular

Sequent (conjugate) depth, energy loss and dissipated power of a hydraulic jump in a horizontal rectangular channel (Belanger's equation from the momentum balance).

\frac{y_2}{y_1} = \tfrac12\left(\sqrt{1+8Fr_1^2}-1\right),\quad \Delta E = \frac{(y_2-y_1)^3}{4y_1y_2}

Inputs

Q discharge [m^3/s]
b channel width [m]
y1 upstream (supercritical) depth [m]

Returns

y2 sequent depth after the jump (m) [m]
Fr1 upstream Froude number
Fr2 downstream Froude number
dE head lost in the jump (m) [m]
power_loss power dissipated gamma Q dE (W) [W]
ratio depth ratio y2/y1

Applies when

horizontal, frictionless bed
Fr1 > 1

Example

m.ask("Hydraulic jump in a rectangular channel with discharge = 10 m^3/s, width = 2 m and upstream depth = 0.4 m.")

→ y2 = 3.37521 m, Fr1 = 6.31023, Fr2 = 0.257445, dE = 4.87676 m, power_loss = 478410 W, ratio = 8.43802

Length of a gradually varied flow profile (rectangular channel)gradually_varied_flow_length

Distance along a prismatic rectangular channel between two sections of a gradually varied flow profile, by integrating dx/dy = (1 - Fr^2)/(S0 - Sf) exactly (not the direct-step approximation), with the profile type (M1, M2, M3, S1, S2, S3). Positive L: the section at depth y2 lies downstream of the one at depth y1.

\frac{dx}{dy} = \frac{1-Fr^2}{S_0-S_f},\quad S_f = \frac{n^2V^2}{R^{4/3}}

Inputs

Q discharge [m^3/s]
b channel width [m]
S0 bed slope, m/m (positive)
n Manning roughness coefficient
y1 depth at the first section [m]
y2 depth at the second section [m]

Returns

L distance from section 1 to section 2, positive downstream (m) [m]
yn normal depth (m) [m]
yc critical depth (m) [m]
profile profile type (M1 ... S3)

Applies when

S0 > 0 (mild or steep slope)
prismatic rectangular channel
both depths in one zone, 2% from yn and yc

Example

m.ask("Gradually varied flow length with discharge = 20 m^3/s, width = 5 m, slope = 0.0004, Manning n = 0.015, first depth = 4 m and second depth = 3 m.")

→ L = -4594.59 m, yn = 2.56382 m, yc = 1.17711 m, profile = M1

Manning discharge in a rectangular channelmanning_rectangular_discharge

Uniform-flow discharge and velocity in a rectangular channel from Manning's equation.

Q = \frac{1}{n}A R^{2/3} S^{1/2},\quad A = by,\ R = \frac{by}{b+2y}

Inputs

b bottom width [m]
y flow depth [m]
S bed slope, m/m
n Manning roughness coefficient

Returns

Q discharge (m^3/s) [m^3/s]
V mean velocity (m/s) [m/s]
A flow area (m^2) [m^2]
R hydraulic radius (m) [m]

Applies when

b, y > 0
0 < S < 1
0.005 <= n <= 0.2

Example

m.ask("Manning discharge in a rectangular channel with width = 3 m, depth = 1.2 m, slope = 0.001 and Manning n = 0.013.")

→ Q = 6.6829 m^3/s, V = 1.85636 m/s, A = 3.6 m^2, R = 0.666667 m

Manning discharge in a trapezoidal channelmanning_trapezoidal_discharge

Uniform-flow discharge and velocity in a trapezoidal channel (side slopes z H:1V) from Manning's equation.

Q = \frac{1}{n}A R^{2/3} S^{1/2},\quad A=(b+zy)y,\ P=b+2y\sqrt{1+z^2}

Inputs

b bottom width [m]
y flow depth [m]
z side slope, horizontal per unit vertical
S bed slope, m/m
n Manning roughness coefficient

Returns

Q discharge (m^3/s) [m^3/s]
V mean velocity (m/s) [m/s]
A flow area (m^2) [m^2]
R hydraulic radius (m) [m]

Applies when

y > 0
b >= 0
z >= 0
0 < S < 1
0.005 <= n <= 0.2

Example

m.ask("Manning discharge in a trapezoidal channel with width = 4 m, depth = 1.5 m, side slope = 2, slope = 0.0008 and Manning n = 0.025.")

→ Q = 11.7249 m^3/s, V = 1.11666 m/s, A = 10.5 m^2, R = 0.980557 m

Manning flow in a part-full circular pipemanning_partially_full_pipe

Gravity (open-channel) discharge and velocity in a circular sewer or culvert flowing at depth y, from Manning's equation, with the full-bore capacity and the ratio Q/Q_full (n taken as constant with depth).

Q = \frac{1}{n}A R^{2/3} S^{1/2},\quad Q_{full} = \frac{1}{n}\frac{\pi D^2}{4}\left(\frac{D}{4}\right)^{2/3}S^{1/2}

Inputs

D pipe diameter [m]
y flow depth [m]
S pipe slope, m/m
n Manning roughness coefficient

Returns

Q discharge (m^3/s) [m^3/s]
V mean velocity (m/s) [m/s]
A flow area (m^2) [m^2]
R hydraulic radius (m) [m]
Q_full full-bore capacity (m^3/s) [m^3/s]
ratio Q/Q_full

Applies when

0 < y <= D
0 < S < 1
n constant with depth

Example

m.ask("Manning flow in a partially full pipe with diameter = 0.6 m, depth = 0.3 m, slope = 0.005 and Manning n = 0.013.")

→ Q = 0.217086 m^3/s, V = 1.53557 m/s, A = 0.141372 m^2, R = 0.15 m, Q_full = 0.434172 m^3/s, ratio = 0.5

Manning velocity from hydraulic radiusmanning_velocity

Mean velocity of uniform flow from Manning's equation (SI) for a hydraulic radius R, slope S and roughness n.

V = \frac{1}{n}R^{2/3}S^{1/2}

Inputs

R hydraulic radius [m]
S channel (energy) slope, m/m
n Manning roughness coefficient

Returns

V mean velocity (m/s) [m/s]

Applies when

R > 0
0 < S < 1
0.005 <= n <= 0.2

Example

m.ask("Manning velocity with hydraulic radius = 0.8 m, slope = 0.0005 and Manning n = 0.015.")

→ V = 1.28466 m/s

Manning's n from a Chezy coefficientmanning_from_chezy

The Manning roughness n equivalent to a Chezy coefficient C at hydraulic radius R (SI units).

n = \frac{R^{1/6}}{C}

Inputs

C Chezy coefficient (m^(1/2)/s) [m^0.5/s]
R hydraulic radius [m]

Returns

n Manning roughness coefficient

Applies when

C, R > 0

Example

m.ask("Manning n from chezy with Chezy C = 60 m^0.5/s and hydraulic radius = 1.2 m.")

→ n = 0.0171809

Normal depth in a rectangular channelnormal_depth_rectangular

The uniform-flow (normal) depth that carries a discharge Q in a rectangular channel (Manning), with the velocity and Froude number at that depth.

Q = \frac{1}{n}\,b y\left(\frac{by}{b+2y}\right)^{2/3}S^{1/2}

Inputs

Q discharge [m^3/s]
b bottom width [m]
S bed slope, m/m
n Manning roughness coefficient

Returns

yn normal depth (m) [m]
V velocity at normal depth (m/s) [m/s]
Fr Froude number at normal depth

Applies when

Q, b > 0
0 < S < 1

Example

m.ask("Normal depth in a rectangular channel with discharge = 10 m^3/s, width = 4 m, slope = 0.0005 and Manning n = 0.015.")

→ yn = 1.75442 m, V = 1.42498 m/s, Fr = 0.343484

Normal depth in a trapezoidal channelnormal_depth_trapezoidal

The uniform-flow (normal) depth that carries a discharge Q in a trapezoidal channel (Manning), with the velocity, area and Froude number (on the hydraulic depth A/T).

Q = \frac{1}{n}A R^{2/3}S^{1/2},\quad A=(b+zy)y,\ P=b+2y\sqrt{1+z^2}

Inputs

Q discharge [m^3/s]
b bottom width [m]
z side slope, horizontal per unit vertical
S bed slope, m/m
n Manning roughness coefficient

Returns

yn normal depth (m) [m]
V velocity at normal depth (m/s) [m/s]
A flow area (m^2) [m^2]
Fr Froude number on the hydraulic depth

Applies when

Q > 0
b >= 0
z >= 0
0 < S < 1

Example

m.ask("Normal depth in a trapezoidal channel with discharge = 20 m^3/s, width = 5 m, side slope = 2, slope = 0.0004 and Manning n = 0.025.")

→ yn = 2.16558 m, V = 0.989735 m/s, A = 20.2074 m^2, Fr = 0.259831

Part-full circular conduit: area, wetted perimeter, hydraulic radiuscircular_channel_section

Flow area, wetted perimeter, hydraulic radius, top width and hydraulic depth of a circular pipe or culvert flowing part full at depth y, with the central angle of the wetted arc.

\theta = 2\cos^{-1}\!\left(1-\frac{2y}{D}\right),\quad A = \frac{D^2}{8}(\theta-\sin\theta),\quad P = \frac{D\theta}{2}

Inputs

D pipe diameter [m]
y flow depth [m]

Returns

A flow area (m^2) [m^2]
P wetted perimeter (m) [m]
R hydraulic radius A/P (m) [m]
T top width (m) [m]
Dh hydraulic depth A/T (m) [m]
theta central angle of the wetted arc (degrees)

Applies when

0 < y < D

Example

m.ask("Circular channel section with diameter = 1 m and depth = 0.6 m.")

→ A = 0.492028 m^2, P = 1.77215 m, R = 0.277644 m, T = 0.979796 m, Dh = 0.502174 m, theta = 203.074

Rectangular channel: area, wetted perimeter, hydraulic radiusrectangular_channel_section

Flow area, wetted perimeter, hydraulic radius, top width and hydraulic depth of a rectangular channel flowing at depth y.

A = b\,y,\quad P = b + 2y,\quad R = \frac{A}{P}

Inputs

b bottom width [m]
y flow depth [m]

Returns

A flow area (m^2) [m^2]
P wetted perimeter (m) [m]
R hydraulic radius A/P (m) [m]
T top width (m) [m]
Dh hydraulic depth A/T (m) [m]

Applies when

b > 0
y > 0

Example

m.ask("Rectangular channel section with width = 3 m and depth = 1.2 m.")

→ A = 3.6 m^2, P = 5.4 m, R = 0.666667 m, T = 3 m, Dh = 1.2 m

Sharp-crested rectangular weir dischargerectangular_weir_discharge

Discharge over a sharp-crested rectangular weir for a stated discharge coefficient Cd and head H, with Francis' allowance of 0.1 H per end contraction (0, 1 or 2 contractions).

Q = \tfrac{2}{3}\,C_d\,L_{e}\sqrt{2g}\,H^{3/2},\quad L_e = b - 0.1\,nH

Inputs

Cd discharge coefficient (stated, e.g. 0.62)
b crest length [m]
H head over the crest [m]
contractions number of end contractions (0, 1 or 2; default 0) integer optional

Returns

Q discharge (m^3/s) [m^3/s]
L_eff effective crest length (m) [m]

Applies when

Cd stated
free (unsubmerged) nappe
b - 0.1 n H > 0

Example

m.ask("Rectangular weir discharge with discharge coefficient = 0.62, crest length = 2 m and head = 0.35 m.")

→ Q = 0.758197 m^3/s, L_eff = 2 m

Specific energy and alternate depth in a rectangular channelalternate_depth_rectangular

The specific energy of flow at depth y in a rectangular channel and the alternate depth with the same specific energy on the other side of critical depth.

E = y + \frac{q^2}{2 g y^2},\quad y_2^3 - E\,y_2^2 + \frac{q^2}{2g} = 0

Inputs

Q discharge [m^3/s]
b channel width [m]
y flow depth [m]

Returns

E specific energy y + V^2/2g (m) [m]
y_alt alternate depth (m) [m]
yc critical depth (m) [m]
Fr Froude number at depth y
regime flow regime at depth y

Applies when

Q, b, y > 0
y is not the critical depth

Example

m.ask("Specific energy and alternate depth with discharge = 6 m^3/s, width = 2 m and depth = 0.4 m.")

→ E = 3.26697 m, y_alt = 3.22281 m, yc = 0.971683 m, Fr = 3.78614, regime = supercritical

Trapezoidal channel: area, wetted perimeter, hydraulic radiustrapezoidal_channel_section

Flow area, wetted perimeter, hydraulic radius, top width and hydraulic depth of a trapezoidal channel with bottom width b and side slopes z (horizontal : vertical); b = 0 is a triangular channel.

A = (b + z y)\,y,\quad P = b + 2y\sqrt{1+z^2},\quad T = b + 2zy

Inputs

b bottom width [m]
y flow depth [m]
z side slope, horizontal per unit vertical

Returns

A flow area (m^2) [m^2]
P wetted perimeter (m) [m]
R hydraulic radius A/P (m) [m]
T top width (m) [m]
Dh hydraulic depth A/T (m) [m]

Applies when

y > 0
b >= 0
z >= 0

Example

m.ask("Trapezoidal channel section with width = 4 m, depth = 1.5 m and side slope = 2.")

→ A = 10.5 m^2, P = 10.7082 m, R = 0.980557 m, T = 10 m, Dh = 1.05 m

V-notch (triangular) weir dischargev_notch_weir_discharge

Discharge over a sharp-crested triangular (V-notch) weir of notch angle theta for a stated discharge coefficient.

Q = \tfrac{8}{15}\,C_d\sqrt{2g}\,\tan\frac{\theta}{2}\,H^{5/2}

Inputs

Cd discharge coefficient (stated, e.g. 0.58)
theta notch angle (degrees)
H head above the vertex [m]

Returns

Q discharge (m^3/s) [m^3/s]

Applies when

Cd stated
0 < theta < 180 degrees
free nappe

Example

m.ask("V notch weir discharge with discharge coefficient = 0.58, notch angle = 90 degrees and head = 0.25 m.")

→ Q = 0.042818 m^3/s

Pipe flow and water networks 5

Flow division among parallel pipes (Hazen-Williams)parallel_pipes_hazen_williams

How a total flow Q divides among two or more pipes in parallel between the same two junctions, and the common head loss, from the Hazen-Williams formula.

Q = \sum_i \left(\frac{h_f}{k_i}\right)^{0.54},\quad k_i = \frac{10.67L_i}{C_i^{1.852}D_i^{4.871}}

Inputs

Q total flow [m^3/s]
L pipe lengths in m (one per pipe) vector
D pipe diameters in mm (one per pipe) vector
C Hazen-Williams C of each pipe vector

Returns

hf head loss between the junctions (m) [m]
flows flow in each pipe (m^3/s) [m^3/s]

Applies when

the same head loss across every pipe
40 <= C <= 160
lists of equal length

Example

m.ask("Parallel pipes with total flow = 0.3 m^3/s, lengths = [800, 1200], diameters = [300, 400] and C factors = [120, 110].")

→ hf = 7.94407 m, flows = [0.116758581689, 0.183241418311] m^3/s

Hazen-Williams head loss in a pipehazen_williams_head_loss

Friction head loss, velocity and friction slope for water flowing at Q through a pipe, from the Hazen-Williams formula (SI form used by EPANET).

h_f = \frac{10.67\,L\,Q^{1.852}}{C^{1.852}D^{4.871}}

Inputs

Q discharge [m^3/s]
D pipe diameter [m]
L pipe length [m]
C Hazen-Williams roughness coefficient

Returns

hf friction head loss (m) [m]
V mean velocity (m/s) [m/s]
Sf friction slope hf/L (m/m)

Applies when

water near 15 C, turbulent flow
40 <= C <= 160

Example

m.ask("Hazen williams head loss with discharge = 50 L/s, diameter = 300 mm, length = 1000 m and Hazen-Williams C = 120.")

→ hf = 2.06456 m, V = 0.707355 m/s, Sf = 0.00206456

Pipe flow from a head loss (Hazen-Williams)hazen_williams_flow

The discharge a pipe carries under a given friction head loss (for example between two reservoirs), from the Hazen-Williams formula.

Q = \left(\frac{h_f\,C^{1.852}D^{4.871}}{10.67\,L}\right)^{0.54}

Inputs

hf friction head loss [m]
D pipe diameter [m]
L pipe length [m]
C Hazen-Williams roughness coefficient

Returns

Q discharge (m^3/s) [m^3/s]
V mean velocity (m/s) [m/s]

Applies when

40 <= C <= 160
hf > 0

Example

m.ask("Flow from head loss by hazen williams with head loss = 5 m, diameter = 300 mm, length = 1500 m and Hazen-Williams C = 110.")

→ Q = 0.0593637 m^3/s, V = 0.839824 m/s

Pipe network flows by the Hardy Cross method (Hazen-Williams)hardy_cross_network

Steady flows in every pipe of a looped water network and the head loss from the source to every node, by Hardy Cross loop corrections (finished with simultaneous loop corrections to full precision), Hazen-Williams friction. Nodes are numbered 1..N; node 1 is the source and supplies the total demand.

\Delta Q = -\frac{\sum k\,Q|Q|^{0.852}}{1.852\sum k|Q|^{0.852}},\quad k = \frac{10.67L}{C^{1.852}D^{4.871}}

Inputs

pipes pipes as node pairs 1-2, 2-3, ... (the flow sign follows this direction) edges
L pipe lengths in m (in pipe order) vector
D pipe diameters in mm (in pipe order) vector
C Hazen-Williams C of each pipe (in pipe order) vector
demands demand at nodes 1..N in m^3/s (node 1, the source, takes 0) vector

Returns

flows flow in each pipe, positive from its first to its second node (m^3/s) [m^3/s]
head_loss head loss from node 1 to each node (m) [m]
loops independent loops
iterations Hardy Cross sweeps before the Newton finish

Applies when

one source (node 1)
connected network
40 <= C <= 160
demands >= 0

Example

m.ask("Hardy cross network with pipe list = [1-2, 2-3, 3-4, 4-1, 2-4], lengths = [600, 500, 600, 500, 780], diameters = [300, 250, 200, 250, 200], C factors = [120, 120, 120, 120, 120] and node demands = [0, 0.04, 0.05, 0.03].")

→ flows = [0.0714399845267, 0.0331343839504, -0.0168656160496, -0.0485600154733, -0.00169439942369] m^3/s, head_loss = [0.0, 2.39874834362, 3.56973630784, 2.37675423164] m, loops = 2, iterations = 14

Three-reservoir problem (Hazen-Williams)three_reservoir_problem

Head at the junction of three pipes from three reservoirs and the flow in each pipe (positive toward the junction), with Hazen-Williams friction and no demand at the junction.

\sum_{i=1}^{3}\operatorname{sgn}(z_i-h)\left(\frac{|z_i-h|}{k_i}\right)^{0.54} = 0

Inputs

z reservoir water levels in m (three) vector
L pipe lengths in m (three) vector
D pipe diameters in mm (three) vector
C Hazen-Williams C of each pipe (three) vector

Returns

h_junction piezometric head at the junction (m) [m]
flows flow in each pipe toward the junction (m^3/s) [m^3/s]

Applies when

no demand at the junction
40 <= C <= 160

Example

m.ask("Three reservoir problem with levels = [120, 90, 40], lengths = [2000, 1500, 2500], diameters = [400, 300, 350] and C factors = [120, 120, 120].")

→ h_junction = 91.9468 m, flows = [0.299838366058, -0.0389148570849, -0.260923508973] m^3/s

Soil mechanics 20

Average degree of consolidation after a time (Terzaghi)degree_of_consolidation

Time factor and average degree of one-dimensional consolidation of a clay layer after time t (Terzaghi, uniform initial excess pore pressure), and the settlement reached if the final consolidation settlement is given. Hdr is the drainage path: half the thickness for double drainage, the full thickness for single drainage.

U = 1 - \sum_{m=0}^{\infty}\frac{2}{M^2}e^{-M^2T_v},\quad M = \frac{\pi}{2}(2m+1),\quad T_v = \frac{c_v t}{H_{dr}^2}

Inputs

cv coefficient of consolidation [m^2/s]
t time since loading [s]
Hdr drainage path length [m]
Sc final consolidation settlement (optional) [m] optional

Returns

Tv time factor cv t/Hdr^2
U average degree of consolidation
U_percent average degree of consolidation (%)
St settlement at time t (m) [m]

Applies when

1e-4 <= Tv <= 5
uniform initial excess pore pressure
Terzaghi 1-D theory

Example

m.ask("Degree of consolidation with coefficient of consolidation = 2.5 m^2/yr, time = 1 yr and drainage path = 3 m.")

→ Tv = 0.277778, U = 0.59137, U_percent = 59.137

Coefficient of consolidation from a consolidation timecoefficient_of_consolidation

Coefficient of consolidation from the time at which a degree of consolidation is reached (for example t50 by Casagrande's method or t90 by Taylor's), using the exact time factor rather than the rounded 0.197 or 0.848.

c_v = \frac{T_v(U)\,H_{dr}^2}{t}

Inputs

Hdr drainage path length (half the specimen height for double drainage) [m]
t time to reach U [s]
U degree of consolidation reached (fraction, or % in a question)

Returns

cv coefficient of consolidation (m^2/s) [m^2/s]
Tv time factor for U
cv_m2_yr coefficient of consolidation (m^2/yr)

Applies when

1% <= U <= 99%
Terzaghi 1-D theory

Example

m.ask("Coefficient of consolidation with drainage path = 10 mm, time = 12.5 min and degree of consolidation = 50 %.")

→ cv = 2.62308e-08 m^2/s, Tv = 0.196731, cv_m2_yr = 0.82778

Cohesion and friction angle from direct shear testsdirect_shear_strength_parameters

Mohr-Coulomb cohesion and friction angle from direct shear tests by a least-squares line of peak shear stress against normal stress. Stresses in kPa.

\tau_f = c + \sigma\tan\phi

Inputs

sigma normal stresses in kPa vector
tau shear stresses at failure in kPa vector

Returns

phi friction angle (degrees)
c cohesion intercept (kPa)
tan_phi slope tan(phi)

Applies when

at least two tests
shear strength rises with normal stress

Example

m.ask("Direct shear strength parameters with normal stresses = [50, 100, 200] and shear stresses = [45, 73, 131].")

→ phi = 29.8681, c = 16, tan_phi = 0.574286

Cohesion and friction angle from triaxial teststriaxial_strength_parameters

Mohr-Coulomb cohesion and friction angle from two or more triaxial tests at failure, by a least-squares line through the stress points (p, q) = ((s1 + s3)/2, (s1 - s3)/2): sin phi = slope, c = intercept/cos phi. Stresses in kPa (effective or total, consistently).

\sin\phi = \tan\alpha,\quad c = \frac{a}{\cos\phi}

Inputs

s3 confining (minor principal) stresses at failure in kPa vector
s1 major principal stresses at failure in kPa vector

Returns

phi friction angle (degrees)
c cohesion (kPa)
alpha slope angle of the Kf line (degrees)

Applies when

at least two tests
s1 > s3
a non-negative intercept

Example

m.ask("Triaxial strength parameters with confining stresses = [100, 200, 300] and major principal stresses = [330, 590, 860].")

→ phi = 26.8778, c = 19.4378, alpha = 24.3272

Consolidation settlement of a thick clay layer integrated over depththick_clay_layer_settlement

Primary consolidation settlement of a thick normally consolidated clay layer under a uniform added stress, with the initial effective stress rising linearly with depth (integrated exactly over the thickness), and the usual single-layer estimate at mid-depth for comparison.

S = \frac{C_c}{1+e_0}\int_0^H \log_{10}\frac{\sigma'_0(z)+\Delta\sigma}{\sigma'_0(z)}\,dz

Inputs

H clay layer thickness [m]
s_top initial effective vertical stress at the top of the clay [Pa]
gsub submerged unit weight of the clay [N/m^3]
ds uniform added vertical stress [Pa]
Cc compression index
e0 initial void ratio

Returns

S settlement integrated over depth (m) [m]
S_one_layer single-layer estimate at mid-depth (m) [m]

Applies when

normally consolidated clay
uniform added stress with depth
s0' = s_top + gsub z

Example

m.ask("Thick clay layer settlement with thickness = 10 m, top effective stress = 40 kPa, submerged unit weight = 8 kN/m^3, stress increase = 100 kPa, compression index = 0.45 and initial void ratio = 1.2.")

→ S = 0.753129 m, S_one_layer = 0.720373 m

Effective sizes and gradation coefficients from a sieve analysisgrain_size_coefficients

D10, D30 and D60 by log-linear interpolation of the grading curve, and the coefficients of uniformity Cu and curvature Cc. Sieve sizes in mm, percent passing in %.

C_u = \frac{D_{60}}{D_{10}},\quad C_c = \frac{D_{30}^2}{D_{10}D_{60}}

Inputs

sizes sieve sizes in mm vector
passing percent passing each sieve, in % vector

Returns

D10 D10 (mm)
D30 D30 (mm)
D60 D60 (mm)
Cu coefficient of uniformity D60/D10
Cc coefficient of curvature D30^2/(D10 D60)

Applies when

percent passing rises strictly with size
the curve spans 10% to 60%

Example

m.ask("Grain size coefficients with sieve sizes = [4.75, 2, 0.85, 0.425, 0.25, 0.15, 0.075] and percent passing = [95, 82, 64, 43, 27, 14, 6].")

→ D10 = 0.106066, D30 = 0.276153, D60 = 0.744869, Cu = 7.02269, Cc = 0.965255

Excess pore pressure at a depth during consolidationexcess_pore_pressure_isochrone

Excess pore-water pressure and local degree of consolidation at depth z and time t in a doubly drained clay layer of thickness 2 Hdr under a uniform initial excess pressure u0 (Terzaghi); z is measured from the top drainage face (for a singly drained layer of thickness Hdr, use 0 <= z <= Hdr).

u(z,t) = \sum_{m=0}^{\infty}\frac{2u_0}{M}\sin\frac{Mz}{H_{dr}}\,e^{-M^2T_v}

Inputs

u0 initial excess pore pressure [Pa]
cv coefficient of consolidation [m^2/s]
t time since loading [s]
Hdr drainage path length [m]
z depth below the top drainage face [m]

Returns

u excess pore pressure (Pa) [Pa]
Uz local degree of consolidation 1 - u/u0
Tv time factor

Applies when

0.001 <= Tv <= 3
uniform initial excess pore pressure
double drainage (or symmetric half)

Example

m.ask("Excess pore pressure during consolidation with initial excess pore pressure = 100 kPa, coefficient of consolidation = 2 m^2/yr, time = 1 yr, drainage path = 3 m and depth = 1.5 m.")

→ u = 52247.3 Pa, Uz = 0.477527, Tv = 0.222222

Factor of safety of an infinite slopeinfinite_slope_factor_of_safety

The factor of safety against translational sliding of an infinite slope on a plane at depth z, with seepage parallel to the slope and the water table at a height m z above the slip plane (m = 0 dry, m = 1 at the surface).

FS = \frac{c' + (\gamma - m\gamma_w)\,z\cos^2\beta\,\tan\phi'}{\gamma z\sin\beta\cos\beta}

Inputs

c effective cohesion [Pa]
phi effective friction angle (degrees)
gam unit weight of the soil (saturated below the water table) [N/m^3]
z depth of the slip plane (vertical) [m]
beta slope angle (degrees)
m water-table height above the slip plane as a fraction of z (default 0, dry) optional

Returns

FS factor of safety
tau driving shear stress on the slip plane (Pa) [Pa]
sigma_eff effective normal stress on the slip plane (Pa) [Pa]

Applies when

c >= 0
0 <= phi < 60 degrees
1 <= beta <= 80 degrees
0 <= m <= 1
seepage parallel to the slope

Example

m.ask("Infinite slope factor of safety with cohesion = 5 kPa, friction angle = 30 degrees, unit weight = 18 kN/m^3, depth = 3 m and slope angle = 25 degrees.")

→ FS = 1.47987, tau = 20683.2 Pa, sigma_eff = 44355.3 Pa

Liquid limit from Casagrande cup testsliquid_limit_flow_curve

Liquid limit (water content at 25 blows) and flow index from Casagrande cup tests by a least-squares line of water content against log10(blows), with the plasticity index when the plastic limit is given. Water contents in percent.

LL = w(N=25),\quad PI = LL - PL

Inputs

blows number of blows of each test vector
w water content of each test in % vector
PL plastic limit in % (optional) optional

Returns

LL liquid limit (%)
flow_index flow index (% per log cycle of blows)
PI plasticity index LL - PL (%)

Applies when

water content falls with blows
water contents in %

Example

m.ask("Liquid limit from cup tests with number of blows = [15, 22, 30, 38], water contents = [42.1, 40.3, 38.7, 37.6] and plastic limit = 21.")

→ LL = 39.6292, flow_index = 11.2179, PI = 18.6292

Major principal stress at failure (Mohr-Coulomb)mohr_coulomb_failure_stress

Major principal stress at failure for a given minor principal stress (triaxial test), with the normal and shear stresses on the failure plane and its angle to the major principal plane (45 + phi/2).

\sigma_1 = \sigma_3\tan^2\!\left(45^\circ+\frac{\phi}{2}\right) + 2c\tan\!\left(45^\circ+\frac{\phi}{2}\right)

Inputs

s3 minor principal (confining) stress [Pa]
c cohesion [Pa]
phi friction angle (degrees)

Returns

s1 major principal stress at failure (Pa) [Pa]
sigma_f normal stress on the failure plane (Pa) [Pa]
tau_f shear stress on the failure plane (Pa) [Pa]
theta failure plane angle from the major principal plane (degrees)

Applies when

0 < phi < 60 degrees
s3, c >= 0

Example

m.ask("Mohr coulomb failure stress with confining stress = 100 kPa, cohesion = 15 kPa and friction angle = 28 degrees.")

→ s1 = 326911 Pa, sigma_f = 160191 Pa, tau_f = 100175 Pa, theta = 59

Optimum water content and maximum dry density from a compaction testproctor_compaction_optimum

Optimum water content and maximum dry density from Proctor compaction points by a least-squares parabola, with the zero-air-voids dry density at the optimum when Gs is given. Water contents in %, dry densities in Mg/m^3.

w_{opt} = -\frac{c_1}{2c_2},\quad \rho_{zav} = \frac{G_s\rho_w}{1+wG_s}

Inputs

w water contents in % vector
rho_d dry densities in Mg/m^3 vector
Gs specific gravity of the solids (optional) optional

Returns

w_opt optimum water content (%)
rho_dmax maximum dry density (Mg/m^3)
rho_zav zero-air-voids dry density at the optimum (Mg/m^3)

Applies when

at least three points around the peak
a parabola opening downward

Example

m.ask("Proctor compaction optimum with water contents = [8, 10, 12, 14, 16], dry densities = [1.72, 1.8, 1.84, 1.82, 1.76] and specific gravity = 2.68.")

→ w_opt = 12.4118, rho_dmax = 1.8376, rho_zav = 2.01105

Plasticity, liquidity and consistency indicesplasticity_liquidity_index

The plasticity index PI = LL - PL, the Casagrande A-line value 0.73 (LL - 20) and, with the natural water content, the liquidity index (w - PL)/PI and consistency index (LL - w)/PI. Limits and water content in percent.

PI = LL - PL,\quad LI = \frac{w - PL}{PI},\quad CI = \frac{LL - w}{PI}

Inputs

LL liquid limit in %
PL plastic limit in %
w natural water content in % (optional) optional

Returns

PI plasticity index (%)
A_line_PI plasticity index on the A-line at this LL (%)
LI liquidity index
CI consistency index

Applies when

5 <= LL <= 1000 %
0 <= PL < LL
inputs in percent

Example

m.ask("Plasticity and liquidity index with liquid limit = 45 %, plastic limit = 22 % and water content = 30 %.")

→ PI = 23, A_line_PI = 18.25, LI = 0.347826, CI = 0.652174

Primary consolidation settlement of a normally consolidated clayconsolidation_settlement_nc

Primary consolidation settlement of a normally consolidated clay layer of thickness H from the compression index Cc, the initial void ratio and the initial and added effective stresses at mid-depth.

S_c = \frac{C_c H}{1+e_0}\log_{10}\frac{\sigma'_0+\Delta\sigma}{\sigma'_0}

Inputs

Cc compression index
e0 initial void ratio
H clay layer thickness [m]
s0 initial effective vertical stress at mid-depth [Pa]
ds added vertical stress at mid-depth [Pa]

Returns

Sc consolidation settlement (m) [m]
de change in void ratio
e_final final void ratio

Applies when

normally consolidated clay
stresses at mid-depth of the layer

Example

m.ask("Consolidation settlement of a normally consolidated clay with compression index = 0.32, initial void ratio = 0.92, thickness = 4 m, initial effective stress = 80 kPa and stress increase = 60 kPa.")

→ Sc = 0.162025 m, de = 0.0777722, e_final = 0.842228

Primary consolidation settlement of an overconsolidated clayconsolidation_settlement_oc

Primary consolidation settlement of an overconsolidated clay: recompression with the swelling index Cs up to the preconsolidation stress, then virgin compression with Cc.

S_c = \frac{H}{1+e_0}\left[C_s\log\frac{\sigma'_p}{\sigma'_0} + C_c\log\frac{\sigma'_0+\Delta\sigma}{\sigma'_p}\right]

Inputs

Cc compression index
Cs swelling (recompression) index
e0 initial void ratio
H clay layer thickness [m]
s0 initial effective vertical stress at mid-depth [Pa]
ds added vertical stress at mid-depth [Pa]
sp preconsolidation stress [Pa]

Returns

Sc consolidation settlement (m) [m]
de change in void ratio
OCR overconsolidation ratio sp/s0
case whether the load passes the preconsolidation stress

Applies when

Cs < Cc
sp >= s0
stresses at mid-depth

Example

m.ask("Consolidation settlement of an overconsolidated clay with compression index = 0.4, swelling index = 0.06, initial void ratio = 1.1, thickness = 5 m, initial effective stress = 90 kPa, stress increase = 150 kPa and preconsolidation stress = 160 kPa.")

→ Sc = 0.203403 m, de = 0.0854292, OCR = 1.77778, case = passes the preconsolidation stress

Relative density of a granular soilrelative_density_from_unit_weights

Relative density (density index) of a sand from its in-place dry unit weight and the minimum and maximum dry unit weights of the laboratory tests.

D_r = \frac{\gamma_{d,max}}{\gamma_d}\,\frac{\gamma_d-\gamma_{d,min}}{\gamma_{d,max}-\gamma_{d,min}}

Inputs

gd in-place dry unit weight [N/m^3]
gd_min minimum dry unit weight [N/m^3]
gd_max maximum dry unit weight [N/m^3]

Returns

Dr relative density (fraction)
Dr_percent relative density (%)

Applies when

gd_min <= gd <= gd_max

Example

m.ask("Relative density from unit weights with dry unit weight = 16.2 kN/m^3, minimum dry unit weight = 14.5 kN/m^3 and maximum dry unit weight = 17.8 kN/m^3.")

→ Dr = 0.566031, Dr_percent = 56.6031

Secondary compression (creep) settlement of a clay layersecondary_compression_settlement

The secondary compression settlement S_s = C_alpha H/(1 + e_p) log10(t2/t1) of a clay layer of thickness H after the end of primary consolidation t1, up to a later time t2.

S_s = \frac{C_\alpha H}{1 + e_p}\log_{10}\frac{t_2}{t_1}

Inputs

Ca secondary compression index C_alpha
H layer thickness (at the end of primary consolidation) [m]
ep void ratio at the end of primary consolidation
t1 time at the end of primary consolidation [s]
t2 later time [s]

Returns

Ss secondary compression settlement (m) [m]
Ss_mm settlement (mm)
C_alpha_mod modified secondary compression index C_alpha/(1 + e_p)

Applies when

0 < C_alpha <= 0.2
t2 > t1 (t1 = end of primary consolidation)

Example

m.ask("Secondary compression settlement with secondary compression index = 0.02, thickness = 5 m, void ratio = 1.1, end of primary = 1 yr and later time = 20 yr.")

→ Ss = 0.0619538 m, Ss_mm = 61.9538, C_alpha_mod = 0.00952381

Soil phase relations from void ratio and water contentsoil_phase_relations

Porosity, degree of saturation and the dry, bulk, saturated and submerged unit weights of a soil from its specific gravity of solids Gs, void ratio e and water content w (unit weight of water 9.81 kN/m^3).

S e = w G_s,\quad \gamma = \frac{G_s(1+w)}{1+e}\gamma_w,\quad \gamma_{sat} = \frac{G_s+e}{1+e}\gamma_w

Inputs

Gs specific gravity of the solids
e void ratio
w water content (fraction, or % in a question)

Returns

n porosity e/(1 + e)
S degree of saturation w Gs/e
gamma_d dry unit weight (N/m^3) [N/m^3]
gamma bulk (moist) unit weight (N/m^3) [N/m^3]
gamma_sat saturated unit weight (N/m^3) [N/m^3]
gamma_sub submerged (buoyant) unit weight (N/m^3) [N/m^3]

Applies when

w Gs <= e (not oversaturated)
2.0 <= Gs <= 3.0

Example

m.ask("Soil phase relations with specific gravity = 2.7, void ratio = 0.65 and water content = 18 %.")

→ n = 0.393939, S = 0.747692, gamma_d = 16052.7 N/m^3, gamma = 18942.2 N/m^3, gamma_sat = 19917.3 N/m^3, gamma_sub = 10107.3 N/m^3

Soil properties from a weighed samplesoil_phase_from_lab_masses

Water content, bulk and dry densities and unit weights, void ratio, porosity and degree of saturation of a soil sample from its wet mass, oven-dry mass, volume and the specific gravity of the solids.

w = \frac{M-M_d}{M_d},\quad e = \frac{G_s\rho_w}{\rho_d}-1,\quad S = \frac{wG_s}{e}

Inputs

M wet (moist) mass of the sample [kg]
Md oven-dry mass of the sample [kg]
V volume of the sample [m^3]
Gs specific gravity of the solids

Returns

w water content
rho bulk density (kg/m^3) [kg/m^3]
rho_d dry density (kg/m^3) [kg/m^3]
e void ratio
n porosity
S degree of saturation
gamma bulk unit weight (N/m^3) [N/m^3]
gamma_d dry unit weight (N/m^3) [N/m^3]

Applies when

M >= Md
consistent data (0 < e, S <= 1)

Example

m.ask("Soil properties from a weighed sample with wet mass = 1850 g, dry mass = 1600 g, volume = 1000 cm^3 and specific gravity = 2.7.")

→ w = 0.15625, rho = 1850 kg/m^3, rho_d = 1600 kg/m^3, e = 0.6875, n = 0.407407, S = 0.613636, gamma = 18148.5 N/m^3, gamma_d = 15696 N/m^3

Time to reach a degree of consolidationconsolidation_time

Time needed for a clay layer to reach an average degree of consolidation U (Terzaghi), with the time factor.

t = \frac{T_v(U)\,H_{dr}^2}{c_v}

Inputs

cv coefficient of consolidation [m^2/s]
Hdr drainage path length [m]
U average degree of consolidation (fraction, or % in a question)

Returns

Tv time factor
t time (s) [s]
t_days time (days)

Applies when

1% <= U <= 99%
Terzaghi 1-D theory

Example

m.ask("Consolidation time with coefficient of consolidation = 3 m^2/yr, drainage path = 2.5 m and degree of consolidation = 90 %.")

→ Tv = 0.848085, t = 5.57574e+07 s, t_days = 645.34

Total, pore-water and effective vertical stress at a deptheffective_stress_at_depth

Total vertical stress, hydrostatic pore-water pressure and effective vertical stress at depth z in a layered soil with a water table at depth zw (no capillary rise, hydrostatic water). Each layer's unit weight is the one that applies there (moist above the water table, saturated below), in kN/m^3.

\sigma'_v = \sum \gamma_i h_i - \gamma_w (z - z_w)

Inputs

H layer thicknesses in m, from the surface down vector
gam unit weight of each layer in kN/m^3 vector
zw depth of the water table [m]
z depth of the point [m]

Returns

sigma total vertical stress (Pa) [Pa]
u pore-water pressure (Pa) [Pa]
sigma_eff effective vertical stress (Pa) [Pa]
sigma_eff_kPa effective vertical stress (kPa)

Applies when

hydrostatic pore water
no capillary rise
0 < z <= total thickness

Example

m.ask("Effective stress at depth with thicknesses = [3, 5], unit weights = [17.5, 19.5], water table depth = 3 m and depth = 8 m.")

→ sigma = 150000 Pa, u = 49050 Pa, sigma_eff = 100950 Pa, sigma_eff_kPa = 100.95

Surveying 6

Area between a survey line and a boundary from offsetsarea_from_offsets

Area between a chain line and an irregular boundary from offsets at a regular interval, by the trapezoidal rule and, for an odd number of offsets, Simpson's one-third rule. Offsets in m.

A = \frac{d}{3}\left(y_1 + y_n + 4\sum y_{even} + 2\sum y_{odd}\right)

Inputs

offsets offsets in m at the regular interval vector
d interval between offsets [m]

Returns

A_trapezoidal area by the trapezoidal rule (m^2) [m^2]
A_simpson area by Simpson's rule (m^2) [m^2]

Applies when

regular interval
Simpson's rule only for an odd number of offsets

Example

m.ask("Area from offsets with offsets = [0, 2.5, 3.5, 5, 4.6, 3.2, 0] and interval = 10 m.")

→ A_trapezoidal = 188 m^2, A_simpson = 196.667 m^2

Closed traverse: misclosure and Bowditch (compass rule) adjustmenttraverse_bowditch_adjustment

Latitudes and departures of a closed loop traverse from whole-circle bearings (azimuths clockwise from north, degrees) and distances (m), the misclosure and relative precision (1 in X), the coordinates adjusted by the Bowditch (compass) rule, and the enclosed area. The last leg returns to the starting station.

\delta E_i = -e_E\frac{d_i}{\sum d},\quad \delta N_i = -e_N\frac{d_i}{\sum d}

Inputs

az azimuths (whole-circle bearings) of the legs in degrees vector
d leg lengths in m vector
E0 easting of the starting station (default 0) [m] optional
N0 northing of the starting station (default 0) [m] optional

Returns

misclosure_E misclosure in departure (m) [m]
misclosure_N misclosure in latitude (m) [m]
linear_misclosure linear misclosure (m) [m]
precision relative precision X in 1:X (0 if it closes exactly)
E adjusted eastings of the stations (m) [m]
N adjusted northings of the stations (m) [m]
area enclosed area (m^2) [m^2]

Applies when

closed loop traverse
azimuths 0 to 360 degrees

Example

m.ask("Traverse bowditch adjustment with azimuths = [45, 135.01, 225, 315] and distances = [100, 100.02, 99.98, 100].")

→ misclosure_E = 0.0159394 m, misclosure_N = -0.0123427 m, linear_misclosure = 0.0201595 m, precision = 19841.7, E = [0.0, 70.7066932726, 141.415182997, 70.7146629647] m, N = [0.0, 70.7137638018, -0.020312884737, -70.7137638018] m, area = 10000 m^2

Earthwork volume from cross-section areasearthwork_volume_end_areas

Volume of cut or fill between equally spaced cross-sections by the average-end-area method, and by the prismoidal (Simpson) rule when the number of sections is odd. Areas in m^2.

V = d\left(\frac{A_1+A_n}{2}+\sum_{i=2}^{n-1}A_i\right)

Inputs

areas cross-section areas in m^2, in order vector
d spacing between sections [m]

Returns

V_end_area volume by average end areas (m^3) [m^3]
V_prismoidal volume by the prismoidal rule (m^3) [m^3]

Applies when

equally spaced sections
prismoidal rule only for an odd number of sections

Example

m.ask("Earthwork volume from cross sections with areas = [12.5, 18.2, 25.6, 20.1, 15.8] and spacing = 20 m.")

→ V_end_area = 1561 m^3, V_prismoidal = 1551.33 m^3

Elements of a simple horizontal circular curvehorizontal_circular_curve

Tangent length, curve length, long chord, external distance, middle ordinate and the chainages of the tangent points of a simple circular curve of radius R joining tangents that deflect by Delta at the intersection point PI.

T = R\tan\frac{\Delta}{2},\quad L = R\Delta,\quad LC = 2R\sin\frac{\Delta}{2}

Inputs

R curve radius [m]
Delta deflection (intersection) angle (degrees)
PI chainage of the intersection point (default 0) [m] optional

Returns

T tangent length (m) [m]
L curve length (m) [m]
LC long chord (m) [m]
E external distance (m) [m]
M middle ordinate (m) [m]
PC chainage of the start of the curve (m) [m]
PT chainage of the end of the curve (m) [m]

Applies when

0 < Delta < 180 degrees
chainage measured along the tangents then the curve

Example

m.ask("Horizontal circular curve with radius = 300 m, deflection angle = 40 degrees and PI chainage = 1250 m.")

→ T = 109.191 m, L = 209.44 m, LC = 205.212 m, E = 19.2533 m, M = 18.0922 m, PC = 1140.81 m, PT = 1350.25 m

Elevations on a vertical parabolic curvevertical_parabolic_curve

Elevation at a station on an equal-tangent parabolic vertical curve, with the highest (crest) or lowest (sag) point on the curve and the rate of change of grade. Grades are fractions or percentages; stations and lengths in m.

y = y_{BVC} + g_1x + \frac{g_2-g_1}{2L}x^2,\quad x_t = -\frac{g_1L}{g_2-g_1}

Inputs

g1 entering grade (fraction, or %)
g2 leaving grade (fraction, or %)
L curve length (horizontal) [m]
PVI station of the intersection point [m]
elev_PVI elevation of the intersection point [m]
x station where the elevation is wanted [m]

Returns

elev elevation at the station (m) [m]
x_turn station of the highest/lowest point on the curve (m) [m]
elev_turn elevation of that point (m) [m]
r rate of change of grade (% per m)
BVC station of the beginning of the curve (m) [m]
elev_BVC elevation of the BVC (m) [m]

Applies when

equal-tangent parabola
BVC <= station <= EVC

Example

m.ask("Vertical parabolic curve with entering grade = 3 %, leaving grade = -2 %, curve length = 200 m, PVI station = 1500 m, PVI elevation = 120 m and station = 1450 m.")

→ elev = 118.188 m, x_turn = 1520 m, elev_turn = 118.8 m, r = -0.025, BVC = 1400 m, elev_BVC = 117 m

Reduced levels by the rise-and-fall methodlevelling_rise_and_fall

Reduced levels of every station of a levelling run from staff readings (m) and their sight types (BS, IS, FS in reading order; a BS after an FS is the new set-up on the same change point), with the total rise and fall and the arithmetic check sum BS - sum FS (= last RL - first RL).

\sum \text{BS} - \sum \text{FS} = \sum\text{rise} - \sum\text{fall} = RL_{last} - RL_{first}

Inputs

readings staff readings in m, in reading order vector
sights sight type of each reading: BS, IS or FS text
RL0 reduced level of the first station (benchmark) [m]

Returns

RL reduced level of each station (m) [m]
rise sum of rises (m) [m]
fall sum of falls (m) [m]
last_RL reduced level of the last station (m) [m]
check sum BS - sum FS (m) [m]

Applies when

first reading BS, last FS
a BS after the first follows an FS (change point)

Example

m.ask("Levelling rise and fall with readings = [1.525, 2.105, 1.64, 0.985, 2.32], sight types = [BS, IS, FS, BS, FS] and benchmark level = 100 m.")

→ RL = [100.0, 99.42, 99.885, 98.55] m, rise = 0.465 m, fall = 1.915 m, last_RL = 98.55 m, check = -1.45 m

Versions & files

Releases and repository files

Files

15 files, 34.9 MB in total. The largest:

File	Size
model.safetensors	18.9 MB
dist/civil_engineering_ai999x-1.0.0-py3-none-any.whl	6 MB
onnx/search/encoder.int8.onnx	4.9 MB
docs/civil_engineering_ai999x_capabilities.pdf	3.9 MB
onnx/search/index.json	403.3 KB
docs/civil_engineering_ai999x_capabilities.html	324.5 KB
docs/civil_engineering_ai999x_capabilities.md	253.9 KB
onnx/search/tokenizer.json	176.4 KB
README.md	22.1 KB
LICENSE	11.4 KB
evaluation/release_gate.md	2.3 KB
evaluation/KNOWLEDGE_CARD.md	1.4 KB

Browse every file ↗

Questions

Frequently asked

What does civil-engineering-ai999x do?

Civil Engineering answers questions in civil engineering: pipe and open-channel hydraulics, hydrology, groundwater flow, soil mechanics and foundations, water networks and surveying. Each answer gives the value with its unit, the steps and the formula in LaTeX.

How do I install civil-engineering-ai999x?

With pip: pip install civil-engineering-ai999x. The same files are on Hugging Face (hf download AI999X/civil-engineering-ai999x --local-dir civil-engineering-ai999x) and GitHub.

Does it run offline?

Yes. It is a Python package that runs on an ordinary CPU without a network connection (Python >=3.10); no GPU and no API key are needed.

How many capabilities does civil-engineering-ai999x have?

88 capabilities in 7 topics, including Open-channel hydraulics, Soil mechanics, Hydrology, Foundations, Groundwater.

Which field and tasks does it cover?

Field: Engineering. Tasks: Question Answering, Sentence Similarity, Feature Extraction.

What does an answer look like?

Asked "Manning discharge in a rectangular channel with b = 3 m, y = 1.2 m, S = 0.001 and n = 0.013.", it answers: Q = 6.6829 m^3/s, V = 1.85636 m/s, A = 3.6 m^2, R = 0.666667 m.

What happens when a question cannot be answered?

It says so and names what is missing or out of range, instead of guessing a number.

Explore every model.

More in Engineering All models Capability orb