swcc

Class summary

SWCC	Base class for defining soil water characteristic curve
SWCC_FredlundAndXing1994(a, n, m[, ws, …])	Soil water characteristic curve from Fredlund and Xing 1994
SWCC_PhamAndFredlund2008(ws, a, b, wr, s1[, …])	Soil water characteristic curve from Fredlund and Xing 2008

Function summary

karel_air_from_saturation(Sr[, qfit])	Relative air peremability (w.r.t.
kwrel_from_discrete_swcc(psi, psi_swcc, vw_swcc)	Relative permeability from integrating discrete soil water characteristic curve.

Module listing

Some soil water characteristic curves (SWCC) for unsaturated soil

class geotecha.constitutive_models.swcc.SWCC

Bases: object

Base class for defining soil water characteristic curve

Methods

dw_dpsi(psi, **kwargs)	Slope of SWCC dw/dpsi
plot_model(**kwargs)	Plot the void ratio-permeability
psi_and_w_for_plotting(**kwargs)	Suction and water content for plotting that plot the method
psi_from_w(w, **kwargs)	Suction from water content
w_from_psi(psi, **kwargs)	Water content from suction

dw_dpsi(psi, **kwargs)

Slope of SWCC dw/dpsi

plot_model(**kwargs)

Plot the void ratio-permeability

psi_and_w_for_plotting(**kwargs)

Suction and water content for plotting that plot the method

psi_from_w(w, **kwargs)

Suction from water content

w_from_psi(psi, **kwargs)

Water content from suction

class geotecha.constitutive_models.swcc.SWCC_FredlundAndXing1994(a, n, m, ws=1.0, psir=1000000.0, correction=None)

Bases: geotecha.constitutive_models.swcc.SWCC

Soil water characteristic curve from Fredlund and Xing 1994

Parameters:

a : float

Fitting parameter corresponding to soil suction at the inflection point.

n : float

Fitting parameter designating th rate of desaturation.

m : float

Third fitting parameter

ws : float, optional

Saturated water content. Default ws=1.0 i.e. basically a degree of saturation.

psir : float, optional

Residual suction. Default psir=1e6.

correction : float, optional

Manual correction factor. Default correction=None i.e. correction factor is caclulated.

Notes

The equation for the soil water charcteristic curve is given by:

\[w(\psi) = C(\psi) \frac{w_s} {\left[{\ln\left[{\exp(1)+ \left({\psi/a}\right)^n}\right]}\right]^m}\]

where the correction factor is given by:

\[C(\psi) = \left[{1 - \frac{\ln\left({1+\psi/\psi_r}\right)} {\ln\left({1+10^6/\psi_r}\right)}}\right]\]

SWCC_FredlundAndXing1994()

References

[1]	Fredlund, D.G., Anqing Xing, and Shangyan Huang. “Predicting the Permeability Function for Unsaturated Soils Using the Soil-Water Characteristic Curve.” Canadian Geotechnical Journal 31, no. 4 (1994): 533-46. doi:10.1139/t94-062.

Methods

dw_dpsi(psi, **kwargs)	Slope of SWCC dw/dpsi
k_from_psi(psi, **kwargs)	Relative permeability from suction
plot_model(**kwargs)	Plot the void ratio-permeability
psi_and_w_for_plotting(**kwargs)	Suction and water content for plotting
psi_from_w(w, **kwargs)	Suction from water content
w_from_psi(psi, **kwargs)	water content from suction

dw_dpsi(psi, **kwargs)

Slope of SWCC dw/dpsi

Parameters:

psi : float

Suction

Returns:

dw_dpsi : float

Suction corresponding to psi

Examples

>>> a = SWCC_FredlundAndXing1994(a=3000, n=1.5, m=1, ws=60, correction=1)
>>> a.dw_dpsi(2000)
-0.00536...
>>> b = SWCC_FredlundAndXing1994(a=100, n=2, m=4, correction=1)
>>> b.dw_dpsi(90)
-0.00640...
>>> c = SWCC_FredlundAndXing1994(a=427, n=0.794, m=0.613, psir=3000)
>>> c.dw_dpsi(10000)
-1.317...e-05

k_from_psi(psi, **kwargs)

Relative permeability from suction

Parameters ———_ psi : float

Soil suction. Can be a 1d array.

aev : float, optional

Air entry soil suction. Default aev=1.0

npts : int, optional

Numper of intervals to break integral into. Default npts=500.

Returns:

k : float

Relative permeability.

Notes

The permability relative to the saturated value is given by:

\[k_r(\psi) = \left. \int_{\ln(\psi)}^{b} {\frac{\theta(e^y) - \theta(\psi)}{e^y} \theta^{\prime}(e^y)\,dy} \middle/ \int_{\ln(\psi_{\textrm{aev}})}^{b} {\frac{\theta(e^y) - \theta_s}{e^y} \theta^{\prime}(e^y)\,dy} \right.\]

where, \(b=\ln(10^6)\), \(\theta(\psi)\) is the volumetric water content at a given soil suction. \(\psi_{\textrm{aev}}\) is the air entry value of soil suction (must be positive for the log integral to work). Each integral is performed by dividing the integration inteval into N sections, evaluating the integrand at the mid point of each inteval, then summing the areas of each section.

If you enter a single elment array you will get a scalar returned.

References

[1]	Fredlund, D.G., Anqing Xing, and Shangyan Huang. “Predicting the Permeability Function for Unsaturated Soils Using the Soil-Water Characteristic Curve. Canadian Geotechnical Journal 31, no. 4 (1994): 533-46. doi:10.1139/t94-062.

Examples

>>> b = SWCC_FredlundAndXing1994(a=2.77, n=11.2, m=0.45, psir=300)
>>> b.k_from_psi(4)
0.0520...

psi_and_w_for_plotting(**kwargs)

Suction and water content for plotting

Parameters:

npts : int, optional

Number of points to return. Default npts=100.

xmin, xmax : float, optional

Range of x (i.e. effective stress) values from which to return points. Default xmin=1, xmax=1e6.

Returns:

x, y : 1d ndarray

npts permeability, and void ratio values between xmin and xmax.

w_from_psi(psi, **kwargs)

water content from suction

Parameters:

psi : float

Suction

Returns:

w : float

Suction corresponding to psi

Examples

>>> a = SWCC_FredlundAndXing1994(a=3000, n=1.5, m=1, ws=60, correction=1)
>>> a.w_from_psi(2000)
50.73...
>>> b = SWCC_FredlundAndXing1994(a=100, n=2, m=4, correction=1)
>>> b.w_from_psi(90)
0.395...
>>> c = SWCC_FredlundAndXing1994(a=427, n=0.794, m=0.613, psir=3000)
>>> c.w_from_psi(10000)
0.40...

class geotecha.constitutive_models.swcc.SWCC_PhamAndFredlund2008(ws, a, b, wr, s1, psir=None, correction=None)

Bases: geotecha.constitutive_models.swcc.SWCC

Soil water characteristic curve from Fredlund and Xing 2008

Be careful interpreting results when suction is less than 1. At low suction values we expect wc approx equal to wsat-wr, but the s1 * log10(psi) term gives large negative numbers for psi<<1, whereas at psi=1 the term dissapears as expected.

Parameters:

a : float

Curve fitting parameter.

b : float

Curve fitting parameter.

wr : float

Residual gravimetric water content.

s1 : float

Initial slope of SWCC (i.e. Cc/Gs)

ws : float

Saturated water content. Default ws=1.0 i.e. basically a degree of saturation.

psir : float, optional

Residual suction. Default psir=None, i.e. psir = (2.7*a) **(1/b).

correction : float, optional

Manual correction factor. Default correction=None i.e. correction factor is caclulated.

Notes

The equation for the soil water charcteristic curve is given by:

\[w(\psi) = C(\psi) \left[{\left({w_{sat} - S_l \log(\psi) -w_r}\right) \frac{a}{\psi^{b}+a} + w_r}\right]\]

where the correction factor is given by:

\[C(\psi) = \left[{1 - \frac{\ln\left({1+\psi/\psi_r}\right)} {\ln\left({1+10^6/\psi_r}\right)}}\right]\]

SWCC_PhamAndFredlund2008()

References

[1]	Pham, Hung Q., and Delwyn G. Fredlund. “Equations for the Entire Soil-Water Characteristic Curve of a Volume Change Soil.” Canadian Geotechnical Journal 45, no. 4 (April 1, 2008): 443-53. doi:10.1139/T07-117.

Methods

dw_dpsi(psi, **kwargs)	Slope of SWCC dw/dpsi
k_from_psi(psi, **kwargs)	Relative permeability from suction
plot_model(**kwargs)	Plot the void ratio-permeability
psi_and_w_for_plotting(**kwargs)	Suction and water content for plotting
psi_from_w(w, **kwargs)	Suction from water content
w_from_psi(psi, **kwargs)	water content from suction

dw_dpsi(psi, **kwargs)

Slope of SWCC dw/dpsi

Parameters:

psi : float

Suction

Returns:

dw_dpsi : float

Suction corresponding to psi

# Examples

# ——–

# >>> a = SWCC_FredlundAndXing1994(a=3000, n=1.5, m=1, ws=60, correction=1)

# >>> a.dw_dpsi(2000)

# -0.00536…

# >>> b = SWCC_FredlundAndXing1994(a=100, n=2, m=4, correction=1)

# >>> b.dw_dpsi(90)

# -0.00640…

# >>> c = SWCC_FredlundAndXing1994(a=427, n=0.794, m=0.613, psir=3000)

# >>> c.dw_dpsi(10000)

# -1.317…e-05

k_from_psi(psi, **kwargs)

Relative permeability from suction

If k_from_psi returns a number greater than zero then try reducing aev.

psi : float

Soil suction. Can be a 1d array.

aev : float, optional

Air entry soil suction. Default aev=0.001

npts : int, optional

Numper of intervals to break integral into. Default npts=500.

Returns:

k : float

Relative permeability.

# Examples

# ——–

# >>> b = SWCC_FredlundAndXing1994(a=2.77, n=11.2, m=0.45, psir=300)

# >>> b.k_from_psi(4)

# 0.0520…

Notes

The permability relative to the saturated value is given by:

\[k_r(\psi) = \left. \int_{\ln(\psi)}^{b} {\frac{\theta(e^y) - \theta(\psi)}{e^y} \theta^{\prime}(e^y)\,dy} \middle/ \int_{\ln(\psi_{\textrm{aev}})}^{b} {\frac{\theta(e^y) - \theta_s}{e^y} \theta^{\prime}(e^y)\,dy} \right.\]

where, \(b=\ln(10^6)\), \(\theta(\psi)\) is the volumetric water content at a given soil suction. \(\psi_{\textrm{aev}}\) is the air entry value of soil suction (must be positive for the log integral to work). Each integral is performed by dividing the integration inteval into N sections, evaluating the integrand at the mid point of each inteval, then summing the areas of each section.

If you enter a single element array you will get a scalar returned.

psi_and_w_for_plotting(**kwargs)

Suction and water content for plotting

Parameters:

npts : int, optional

Number of points to return. Default npts=100.

xmin, xmax : float, optional

Range of x (i.e. effective stress) values from which to return points. Default xmin=1, xmax=1e6.

Returns:

x, y : 1d ndarray

npts permeability, and void ratio values between xmin and xmax.

w_from_psi(psi, **kwargs)

water content from suction

Parameters:

psi : float

Suction

Returns:

w : float

Suction corresponding to psi

# Examples

# ——–

# >>> a = SWCC_FredlundAndXing1994(a=3000, n=1.5, m=1, ws=60, correction=1)

# >>> a.w_from_psi(2000)

# 50.73…

# >>> b = SWCC_FredlundAndXing1994(a=100, n=2, m=4, correction=1)

# >>> b.w_from_psi(90)

# 0.395…

# >>> c = SWCC_FredlundAndXing1994(a=427, n=0.794, m=0.613, psir=3000)

# >>> c.w_from_psi(10000)

# 0.40…

geotecha.constitutive_models.swcc.karel_air_from_saturation(Sr, qfit=0.5)

Relative air peremability (w.r.t. dry_ka)

krel = (1-Sr)**0.5*(1-Sr**(1 / qfit))**(2*qfit)

Parameters:

Sr : 1d array of float

Degree of saturation at which to calc relative permeability of air.

qfit : float, optional

Fitting parameter. Generally between between 0 and 1. Default qfit=1

References

[1]	Ba-Te, B., Limin Zhang, and Delwyn G. Fredlund. “A General Air-Phase Permeability Function for Airflow through Unsaturated Soils.” In Proceedings of Geofrontiers 2005 Cngress, 2961-85. Austin, Tx: ASCE, 2005. doi:10.1061/40787(166)29.

geotecha.constitutive_models.swcc.kwrel_from_discrete_swcc(psi, psi_swcc, vw_swcc)

Relative permeability from integrating discrete soil water characteristic curve.

Parameters:

psi: float

Suction values to calculate relative permeability at. Suction is positve.

psi_swcc : 1d array of float

Suction values defining soil water charteristic curve.

vw_swcc : 1d array of float

Volumetric water content corresponding to psi_swcc

Returns:

krel : 1d array of float

relative permeability values corresponding to psi.

Notes

This integrates the whole SWCC. Initial slope of SWCC is non-zero then peremability reduction with suction will commence straight from first value of psi_swcc.

Uses _[1] method but does it assuming taht you already have all the SWCC points (_[1] can calculate volumetric water content from suction). Main differnce is that in _[1] vw and dvw/dpsi at the midpoint are calculated analytically, whereas here midpoint value is half the segment endpoint values, and slope is approx value at segmetn endpoint.

Will return scalar if scalar or single elemtn array is input.

If you get some sort of index error then probably your pis input is beyond your data range.

References

[1]	Fredlund, D.G., Anqing Xing, and Shangyan Huang. “Predicting the Permeability Function for Unsaturated Soils Using the Soil-Water Characteristic Curve. Canadian Geotechnical Journal 31, no. 4 (1994): 533-46. doi:10.1139/t94-062.

Examples

>>> b = SWCC_FredlundAndXing1994(a=2.77, n=11.2, m=0.45, psir=300)
>>> x = np.logspace(-3,6,500)
>>> y = b.w_from_psi(x)
>>> kwrel_from_discrete_swcc(4, x, y)
0.0550...