epus

Class summary

CurveFittingSWCC(wsat, a, b, wr, sl)	Curve fitting soil water characteristic curve for collapsible pores.
DataResults(npts)	Container for stress, suction, void ratio, water content, saturation.
EPUS(SimpleSWCC, stp[, logDS, logRS, Ccs, ...])	Elasto-Plastic for Unsaturated Soils
EpusProfile(epus_object, H[, zw, q0, gamw, ...])	1D initial conditons (stress etc.) distribution for EPUS unsaturated
PoresizeDistribution([Npoint])	Pore size distribution curve
StressPath(path_dicts)	Stress paths to follow

Module listing

Elasto-Plastic for Unsaturated Soils, adapted from VB code in Phd thesis of Pham (2005).

class geotecha.constitutive_models.epus.CurveFittingSWCC(wsat, a, b, wr, sl)

Bases: object

Curve fitting soil water characteristic curve for collapsible pores.

i.e. wc(suction)

Note that that when suction is less than 1, results are not meaningful. At low suction values we expect wc approx equal to wsat-wr, but the sl * log10(suction) /Gs term gives large negative numbers for suctions less than 1, whereas at suction =1 it dissapears as expected.

Parameters:

wsat : float

Gravimetric water condent at 100% saturation.

a : float

Curve fitting parameter.

b : float

Curve fitting parameter.

wr : float

Residual gravimetric water content.

sl : float

Initial slope of SWCC*Gs. This is actually the saturated virgin compressibility index Cc.

Attributes

wsat	(float) Gravimetric water condent at 100% saturation.
a	(float) Curve fitting parameter.
b	(float) Curve fitting parameter.
wr	(float) Residual gravimetric water content.
sl	(float) Initial slope of SWCC.

Methods

DWc(s[, Gs])	Derivative of collapsible water content function
Wc(s[, Gs])	Collapsible water content function

DWc(s, Gs=2.7)

Derivative of collapsible water content function

Parameters:

s : float

Suction.

Gs : float, optional

Specific gravity of solids. Default Gs=2.7

Returns:

out : float

derivative of water content Wc w.r.t. suction

Examples

>>> SWCC = CurveFittingSWCC(wsat=0.262,
...                        a = 3.1 * 10 ** 6,
...                        b = 3.377,
...                        wr = 0.128,
...                        sl = 0.115)
>>> SWCC.DWc(500, Gs=2.7)
-2.367...e-05

Wc(s, Gs=2.7)

Collapsible water content function

Parameters:

s : float

Suction.

Gs : float, optional

Specific gravity of solids. Default Gs=2.7

Returns:

out : float

water content Wc

Examples

>>> SWCC = CurveFittingSWCC(wsat=0.262,
...                        a = 3.1 * 10 ** 6,
...                        b = 3.377,
...                        wr = 0.128,
...                        sl = 0.115)
>>> SWCC.Wc(500, Gs=2.7)
4.525...e-05

class geotecha.constitutive_models.epus.DataResults(npts)

Bases: object

Container for stress, suction, void ratio, water content, saturation.

Parameters:

npts : int

Number of data points.

Attributes

npts	(int) Numer of data points.
n	(int) Counter
st	(1d array of float) Net normal stress. len is npts
ss	(1d array of float) Suction.
e	(1d array of float) Void Ratio
w	(1d array of float) gravimetric water content
Sr	(1d array of float) Degree of saturation
vw	(1d array of float) Volumetric water content.

class geotecha.constitutive_models.epus.EPUS(SimpleSWCC, stp, logDS=0.0, logRS=0.0, Ccs=None, Css=None, Ccd=0.0, Gs=2.7, Assumption=1, beta=0.0, pm=1.0, Pore_shape=1.0, K0=1.0, soilname='unknown', username='unknown', Npoint=1000, NumSr=400, MaxSuction=6, MinSuction=-3, implementation='fortran')

Bases: object

Elasto-Plastic for Unsaturated Soils

This code is adapted from visual basic code in Appendix E of thesis of Pham (2005) [R76]. Journal article is [R75].

Parameters:

SimpleSWCC : CurveFittingSWCC object

Soil water characteristic curve.

stp : StressPath object

object containing info abount the stress path.

logDS : float, optional

Distance ratio between boundary drying and boundary drying curve. In log cycles. default logDS=0.

logRS : float, optional

Slope ratio between boundary drying and boundary drying curve. In log cycles. Default logRS=0.

Ccs : float, optional

semi-log slope of saturated compression curve. Default=None, i.e. Ccs will be equal to SimpleSWCC.sl.

Css : float, optional

semi-log slope of saturated recompression curve. Default Css=None i.e Css=Ccs*0.1

Ccd : float, optional

semi-log slope of dry compression curve, default Ccd=0.

Gs : float, optional

Specific gravity of solids default Gs=2.7.

Assumption : int, optional

Assumption=0 dry pores are incompressible, Assumption=1 dry pores are compressible. Default Assumption=1.

beta : float, optionalB

air entrapped in a collapsible pore is proportional to the volume of the pore and can be denoted by an entrapped air parameter beta. Default beta=0.

pm : float, optional

Soil parameter (Sr)^pm for calculating the yield stress of dry pores. Default pm=1.

Pore_shape : float, optional

For describing the change in AEV/WEV of the soil. Default Pore_shape=1.

K0 : float, optional

Lateral earth pressure coefficient. Default K0=1 i.e. isotropic.

soilname : str, optional

Default soilname=’unknown’.

username : str, optional

Default username=’unknown’

Npoint : int, optional

Number of data points along the pore size distribution curve. Default Npoint=1000

NumSr : int, optional

Number points divided along the wetting and drying Sr. Default NumSr=400

MaxSuction : int, optional

log Scale or 1000000. Default MaxSuction=6

MinSuction : int, optional

log scale or 0.001. Default MinSuction=-3

implementation : [‘fortran’, ‘scalar’, ], optional

Functional implementation: ‘scalar’ = python loops (slow), ‘fortran’ = fortran code (fastest). Currently there is no ‘vectorized’ = numpy(fast) version. Default implementation=’fortran’. If fortran extention module cannot be imported then ‘scalar’ version will be used. If anything other than ‘scalar’ is used then default fortran version will be used.

References

[R75]

(1, 2) Pham, H. Q., and Fredlund, D. G. (2011). ‘Volume-mass unsaturated soil constitutive model for drying-wetting under isotropic loading-unloading conditions. Canadian Geotechnical Journal, 48(2), 280-313.

[R76]

(1, 2) Pham, H. Q. (2005). ‘A volume-mass constitutive model for unsaturated soils’. PhD Thesis, University of Saskatchewan, Saskatoon, Saskatchewan, Canada.

Attributes

f	(PoresizeDistribution object) Pore size distribution function at initial condition.
Suction	(float) Current value of suction.
Stress	(float) Current value of net normal stress.
RefSr	(float) Reference value of Saturation.
Curveon	(int) = 1: on drying; = 2: on horizontal scanning; = 3: on wetting
errocc	(bool) Some sort of error code.
Srdry	(1d array of float (size is NumSr)) Drying degree of saturation SWCC (zero net mean stress)
Srwet	(1d array of float (size is NumSr)) Wetting degree of saturation SWCC (zero net mean stress)

Methods

CVStress()	K0 to isotropic stress conversion factor
Calresults()	Calculate the results ie calculate the response to the stress path
ChangeSuction(MaxSumStress, Initialsuction)	‘ = suction(0)/suction(p)
ChangeWetSuction(MaxSumStress, ...)	‘ = suction(0)/suction(p)
Changevolume(InitialVolume, Yieldstress, ...)
DWc(s)	Derivative of collapsible water content function
DegreeofsaturationSWCC()	This procedure is used to calculate Srdry and Srwet
DryPoreSize()	Set PoresizeDistribution self.f to slurry state
Drying(ss_new)	‘Increase soil suction at a certain net mean/vertical stress
Loading(st_new)	Increase net mean stress at a certain soil suction
RfSr_value(curvetype, ssvalue)	Parameters:
SlurryPoreSize()	Set PoresizeDistribution self.f to slurry state
Unloading(st_new)	Decrease net mean stress at a certain soil suction
Wc(s)	Collapsible water content function
Wetting(ss_new)	Decrease soil suction at a certain net mean/vertical Stress

CVStress()

K0 to isotropic stress conversion factor

Returns:

out : float

(2 * K0 + 1) / 3

Calresults()

Calculate the results ie calculate the response to the stress path

ChangeSuction(MaxSumStress, Initialsuction)

‘ = suction(0)/suction(p)

Parameters:

MaxSumStress : float

Not sure.

Initialsuction : float

Not sure.

Returns:

out : float

not sure

ChangeWetSuction(MaxSumStress, Airentryvalue, Waterentryvalue)

‘ = suction(0)/suction(p)

Parameters:

MaxSumStress : float

Not sure.

Airentryvalue : float

Not sure.

Waterentryvalue : float

Not sure.

Returns:

out : float

not sure

Changevolume(InitialVolume, Yieldstress, CurrentStress, CompIndex, UnloadIndex)

DWc(s)

Derivative of collapsible water content function

Calls CurveFittingSWCC.DWc with self.Gs

Parameters:

s : float

Suction.

Returns:

out : float

Derivative of water content Wc w.r.t. suction

See also

CurveFittingSWCC.DWc

actual function called.

DegreeofsaturationSWCC()

This procedure is used to calculate Srdry and Srwet

DryPoreSize()

Set PoresizeDistribution self.f to slurry state

Examples

>>> SWCC = CurveFittingSWCC(wsat=0.262,
...                         a = 3.1e6,
...                         b = 3.377,
...                         wr = 0.128,
...                         sl = 0.115)
>>> stp = StressPath([dict(ist=True, vl=20, name="1. Load to 20kPa")])
>>> pdict=dict(
...      SimpleSWCC=SWCC,
...      stp=stp,
...      logDS=0.6,
...      logRS=2,
...      Css=0.019,
...      beta=0.1,
...      soilname='Artificial silt',
...      username='Hung Pham')
>>> a=EPUS(**pdict)
>>> a.DryPoreSize()
>>> a.f.AEV[24]
-2.78...
>>> a.f.WEV[24]
-8.09...
>>> a.f.RVC[24]
4.24...e-08
>>> a.f.RV[24]
4.24...e-08
>>> a.f.Ccp[24]
1.04...e-18
>>> a.f.Csp[24]
1.71...e-19
>>> a.f.Ccd[24]
0.0

Drying(ss_new)

‘Increase soil suction at a certain net mean/vertical stress ‘If increase soil suction at a certain net mean stress. All pores that has air

Loading(st_new)

Increase net mean stress at a certain soil suction

RfSr_value(curvetype, ssvalue)

Parameters:

Curvetype : int

curvetype=1: drying; = 2: scanning; =3: wetting

ssvalue : double

Don’t know

Returns:

out : float

Reference saturation value

SlurryPoreSize()

Set PoresizeDistribution self.f to slurry state

Zero soil suction - Mean kPa net mean stress.

Examples

>>> SWCC = CurveFittingSWCC(wsat=0.262,
...                         a = 3.1e6,
...                         b = 3.377,
...                         wr = 0.128,
...                         sl = 0.115)
>>> stp = StressPath([dict(ist=True, vl=20, name="1. Load to 20kPa")])
>>> pdict=dict(
...      SimpleSWCC=SWCC,
...      stp=stp,
...      logDS=0.6,
...      logRS=2,
...      Css=0.019,
...      beta=0.1,
...      soilname='Artificial silt',
...      username='Hung Pham')
>>> a=EPUS(**pdict)
>>> a.SlurryPoreSize()
>>> a.f.RV[24]
4.24...e-08
>>> a.f.RVC[24]
4.24...e-08
>>> a.f.AEVC[24]
-2.78...
>>> a.f.WEVC[24]
-8.09...
>>> a.f.YieldSt[24]
0.0001
>>> a.f.Airentrapped[24]
False

Unloading(st_new)

Decrease net mean stress at a certain soil suction

Wc(s)

Collapsible water content function

Calls CurveFittingSWCC.Wc with self.Gs

Parameters:

s : float

Suction.

Returns:

out : float

water content Wc

See also

CurveFittingSWCC.Wc

actual function called.

Wetting(ss_new)

Decrease soil suction at a certain net mean/vertical Stress

class geotecha.constitutive_models.epus.EpusProfile(epus_object, H, zw=None, q0=1.0, gamw=10, nz=10, Npoint=1000, npp=100, nz_refine=[1], Npoint_refine=[1], npp_refine=[1], atol=0.01, rtol=1e-06, max_iter=100, initial_stress=None)

Bases: object

1D initial conditons (stress etc.) distribution for EPUS unsaturated soil model.

Proceedure:

• Determine pore water pressure, uw, at depth based on depth of water table, zw, i.e. uw is negative above water table. This gives suction (psi) profile above water table.
• Guess an initial stress (sig) distribution, including an initial surcharge of q0.
• Assume a stress path starting from slurry to stress increase to sig and then suction to psi. Use EPUS to calculate void ratio (e) and saturation (Sr).
• Use Gs, e, Sr to calc unit weight (gamma) profile. Numerically integrate unit weight profile to with sig at z=0 equals q0 to give new stress profile.
• Check convergence of new stress vs old stress profile. If not equal then iterate.
• Once solutin converged, record stress, void ratio, saturation profiles.

Note initial EPUS loading steps begin from 0 net normal stress (sig-ua). Below the water table there is a bouyant force so the sig-ua stress input is actually an effective stress.

Parameters:

epus_object : instance of EPUS object

An EPUS object from which all relevant paramters can be taken. Use a dummy stress path for this; it will be ignored. Also Npoint will be ignored. Basically just using and EPUS object as a convienient container.

H : float

Height of soil profile.

zw : float, optional

Depth of water table. Default zw=None, i.e. will be set to H.

q0 : float, optional

Existing surcharge. Default q0=1.

gamw : float, optional

Unit weight of water. Default gamw=10.

nz : int, optional

Final number of depth values in profile. default nz=10.

Npoint : int, optional

Number of data points along the pore size distribution curve. Default Npoint=1000

npp : float, optional

Number of points per stress path step. Default npp=100

nz_refine : list of float, optional

Allows progressive refinement of the number of points in the profile. Initially stress profile will be calcuated at int(nz*nz_refine[0]) evenly spaced depth values. Once convergence is reached a new stress profile will be interpolated at int(nz*nz_refine[1]) and the convergence process is run again. The refinement is repeated untill the final value of nz_refine (which should be 1) is used. Default nz_refine=[1] i.e. no successvie refinement.

Npoint_refine : list of float, optional

Similar to nz_refine. Last value whould be 1. Sould be same length as nz_refine. Default Npoint_refine=[1]

npp_refine : list of float

Similar to nz_refine. Last value should be 1. Should be same length as nz_refine. Default npp_refine = [1]

rtol, atol : float, optional

Relative and absolute tolerance for checking convergence of stress. See numpy.allclose . Default atol=0.01, rtol=1e-6

max_iter : int, optional

Maxmum number of convergence iterations at each refinement step. Default max_iter=100 .

initial_stress : tuple of two 1d arrays

Initial stress to use to start of iteration. 1st element of tuple is list/array of z values, 2nd element is list/array. Default intial_stress=None i.e. make up an initial guess using unit weight = 15. Values will be interpolated.

Notes

“stress” below water table is effective stress. “stress” avbove water table is net normal stress.

Attributes

_nz, _Npoint, _npp	(int) Current ‘refined’ value of nz, Npoint, and _npp.
profile	(DataResults object) Contains information about each data point in the profile. In addition to normal DataResults attributes ( ss, st, e, w, Sr, vw) it has unit weight (gam), depth (z), pore water pressure (uw)
_epus_dict	(dictionary) dict containing common keywords from the epus_object to initialize other epus objects at each depth. Basically just need to add Npoints, and stp stress path objects at each depth and refinement.
niter	(list of int) number of iterations to converge at each refinement level.

Methods

air_permeability([e_ksat, qfit])	Calculate the Air permeability based on saturation
calc()	do all the calculations
compression_indexes([dsig, dpsi])	Calculate the compression indexes
plot_profile([fig])
save_profile_to_file(fpath)	Save profile data to a csv file
water_permeability([e_ksat, npp_swcc])	Calculate the water permeability

air_permeability(e_ksat=None, qfit=0.5)

Calculate the Air permeability based on saturation

ka = kd * (1-Sr)**0.5*(1-Sr**(1/qfit))**(2*qfit)

kd = fn(e)

Parameters:

e_ksat : PermeabilityVoidRatioRelationship object

PermeabilityVoidRatioRelationship object defining dependence of dry air permeability on void ratio. Default e_ksat=ConstantPermeabilityModel(ka=1) i.e. constant saturated permeability with value one.

qfit : float, optional

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

See also

geotecha.constitutive_models.void_ratio_permeability

void ratio saturated permeability relationship.

References

[R77]

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.

calc()

do all the calculations

compression_indexes(dsig=1.0, dpsi=1.0)

Calculate the compression indexes

m1s, m2s, m1w, m2w, m1a, m2a

Calculation is volume change indexes after a) net normal stress change of dsig, and b) or suction change of dpsi.

m1a + m1w = m1s m2a + m2w = m2s

Parameters:

dsig : float, optional

Change in net normal stress (sig-ua), Default dsig=1.0

dpsi : float, optional

Change in suction (ua-uw)

plot_profile(fig=None)

save_profile_to_file(fpath)

Save profile data to a csv file

Parameters:

fpath : str

path of file to save to

water_permeability(e_ksat=None, npp_swcc=500)

Calculate the water permeability

First saturated permeability at depth is determined based on e_ksat. Then unsaturated water permeability is determined by a) working out a volumetric water content vs suction curve (i.e. epus stress path of load to stress and then dry to get a SWCC) and b) use _[1] to numerically integrate and determine relative permeability at the relevatnt profile suction value.

Parameters:

e_ksat : PermeabilityVoidRatioRelationship object

PermeabilityVoidRatioRelationship object defining dependence of saturated permebility on void ratio. Default e_ksat=ConstantPermeabilityModel(ka=1) i.e. constant saturated permeability with value one.

npp_swcc : int, optional

number of sterss path intervals to use when determining the volumetric water content vs suction curve that will be used to calculate the relative permeability. Defulat npp_swcc=500

See also

geotecha.constitutive_models.void_ratio_permeability

void ratio saturated permeability relationship.

References

[R78]

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.

class geotecha.constitutive_models.epus.PoresizeDistribution(Npoint=1000)

Bases: object

Pore size distribution curve

Basically a container for data.

Parameters:

Npoint : int, optional

Number of data points along the pore size distribution curve. Default Npoint=1000

Attributes

Npoint	(int) Number of data points along the pore size distrubution curve.
AEV	(1d array of float) Value of Air Entry Value that the function F represents.
WEV	(1d array of float) Value of Water Entry Value that the function F represents.
Ccp	(1d array of float) Virgin compression index of the group of pore at saturated.
Csp	(1d array of float) Unloading-Reloading index of the group of pore at saturated.
Ccd	(1d array of float) Virgin compression index of the group of pore at completely dry condition (10^6 kPa).
RV	(1d array of float) Ratio of Volume of the group of pore/ volume of solid phase.
YieldSt	(1d array of float) Equivalent maximum stress acted on the pores at water-filled state.
Filled	(1d array of bool) State of the pore - either filled or empty.
RVC	(1d array of float) Actual ratio of volume of the group of pore/ volume of solid phase.
AEVC	(1d array of float) Actual Air Entry Value of the group of pores [i] which has AEV at dried slurry = AEV[i].
WEVC	(1d array of float) Actual water entry value.
Airentrapped	(1d array of bool) If experienced dried state = True, if did not = False.

class geotecha.constitutive_models.epus.StressPath(path_dicts)

Bases: object

Stress paths to follow

Parameters:

path_dicts : list of dict

Each dict describes a step in the stress path. Each dict in the list has the following.

key	description
vl	Value of net normal stress or suction at end of stress path step.
ist	bool. Optional. If change in stress...ist=True else ist=False. Default ist=True.
npp	int. Optional. Number of points to subdivide stress path step into. default npp=100.
name	str. Optional. Description of step. Default name=’Step 0’ etc.

Attributes

ist	(1d array of bool) Loading type for each step in stress path. True indicates a net normal stress change. False indicates a suction change.
vl	(1d array of float) Value of stress or suction at end of step.
npp	(1d array of int) Number of points to subdivide each stress path step into.
name	(list of str) Name of each stress path step
n	(int) Counter indicating current subdivision.
nsteps	(int) Number of stress path steps. i.e. len(path_dicts)
datapoints	(list of DataResults objects) Results data for each stress path step. (ss, st, e, w, sr, vw)
datapoints_combined	(DataResults object) datapoints joined end to end. e.g. access ss from all steps using datapoints_combined.ss (only exists after running combine_datapoints).

Methods

combine_datapoints()

Make datapoints_combined i.e.

combine_datapoints()

Make datapoints_combined i.e. join all the datapoints