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 soil model.
`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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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')[source]¶

Bases: object

Elasto-Plastic for Unsaturated Soils

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

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

[1]	(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.

[2]	(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)

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 ‘If increase soil suction at a certain net mean 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

Changevolume

CVStress()[source]¶

K0 to isotropic stress conversion factor

Returns:	out : float (2 * K0 + 1) / 3

Calresults()[source]¶: Calculate the results ie calculate the response to the stress path

ChangeSuction(MaxSumStress, Initialsuction)[source]¶

‘ = suction(0)/suction(p)

Parameters:	MaxSumStress : float Not sure. Initialsuction : float Not sure.
Returns:	out : float not sure

ChangeWetSuction(MaxSumStress, Airentryvalue, Waterentryvalue)[source]¶

‘ = 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)[source]¶

DWc(s)[source]¶

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()[source]¶: This procedure is used to calculate Srdry and Srwet

DryPoreSize()[source]¶

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)[source]¶: ‘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)[source]¶: Increase net mean stress at a certain soil suction

RfSr_value(curvetype, ssvalue)[source]¶

Parameters:	Curvetype : int curvetype=1: drying; = 2: scanning; =3: wetting ssvalue : double Don’t know
Returns:	out : float Reference saturation value

SlurryPoreSize()[source]¶

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)[source]¶: Decrease net mean stress at a certain soil suction

Wc(s)[source]¶

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)[source]¶: 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)[source]¶

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 parameters 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
`save_profile_to_file`(fpath)	Save profile data to a csv file
`water_permeability`([e_ksat, npp_swcc])	Calculate the water permeability

plot_profile

air_permeability(e_ksat=None, qfit=0.5)[source]¶

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

[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.

calc()[source]¶: do all the calculations

compression_indexes(dsig=1.0, dpsi=1.0)[source]¶

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)[source]¶

save_profile_to_file(fpath)[source]¶

Save profile data to a csv file

Parameters:	fpath : str path of file to save to

water_permeability(e_ksat=None, npp_swcc=500)[source]¶

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

[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.

class geotecha.constitutive_models.epus.PoresizeDistribution(Npoint=1000)[source]¶

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)[source]¶

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()[source]¶: Make datapoints_combined i.e. join all the datapoints

Table Of Contents

Related Topics

This Page

epus¶

Class summary¶

Module listing¶