speccon1d_unsat

Class summary

Speccon1dUnsat([reader, pkg_for_version])

Multilayer consolidation of unsaturated soil

Function summary

main()

Run speccon1d_unsat as scipt

Module listing

Multilayer consolidation of unsaturated soil using the spectral Galerkin method.

class geotecha.speccon.speccon1d_unsat.Speccon1dUnsat(reader=None, pkg_for_version='geotecha')

Bases: geotecha.speccon.speccon1d.Speccon1d

Multilayer consolidation of unsaturated soil

Features:

• Multiple layers.
• Unsaturated vertical drainage only.
• Water and air phases.
• Material properties that are constant in time but piecewsie linear with depth.
• Surcharge loading.
• Independent non-zero top and bottom pore air and pore water pressure boundary conditions.
• Surcharge/Boundary Conditions vary with time in a piecewise-linear function multiplied by a cosine function of time.
  • Surcharge can also vary piecewise linear with depth. The depth dependence does not vary with time.
  • Mulitple loads will be combined using superposition.
• Subset of Python syntax available in input files/strings allowing basic calculations within input files.
• Output:
  • Excess pore air and pore water pressure at depth
  • Average excess pore air and pore water pressure between depths.
  • Settlement between depths of air phase, water phase and overall.
  • Charts and csv output available.
• Program can be run as script or in a python interpreter.
• Note there is no pumping or fixed pore pressure functionality.

Warning

The ‘Parameters’ and ‘Attributes’ sections below require further explanation. The parameters listed below are not used to explicitly initialize the object. Rather they are defined in either a multi-line string or a file-like object using python syntax; the file/string is then used to initialize the object using the reader parameter. As well as simple assignment statements (H = 1, drn = 0 etc.), the input file/string can contain basic calculations (z = np.linspace(0, H, 20) etc.). Not all of the listed parameters are needed. The user should pick an appropriate combination of attributes for their analysis (minimal explicit checks on input data will be performed). Each ‘parameter’ will be turned into an attribute that can be accessed using conventional python dot notation, after the object has been initialised. The attributes listed below are calculated values (i.e. they could be interpreted as results) which are accessible using dot notation after all calculations are complete.

Parameters:

H : float, optional

Total height of soil profile. Default H=1.0. Note that even though this program deals with normalised depth values it is important to enter the correct H valu, as it is used when plotting, outputing data and in normalising gradient boundary conditions (see bot_vs_time below)

mvref : float, optional

Reference value of volume compressibility mv (used with H in settlement calculations). Default mvref=1.0. Note this is used to normalise all the unsaturated volume compressibilities. It is also used in the porosity/saturation term.

kwref : float, optional

Reference value of water phase vertical permeability kw in soil (only used for pretty output). Default kwref=1.0.

Daref : float, optional

Reference value of coefficeint of transmission for the air phase (only used for pretty output). Default Daref=1.0. (note ka=Da*g).

drn : {0, 1}, optional

drainage boundary condition. Default drn=0. 0 = Pervious top pervious bottom (PTPB). 1 = Pervious top impoervious bottom (PTIB).

dT : float, optional

Convienient normaliser for time factor multiplier. Default dT=1.0.

neig : int, optional

Number of series terms to use in solution. Default neig=2. Don’t use neig=1.

dTw : float

Vertical reference time factor multiplier for water phase. dTw is calculated with the chosen reference values of kw and mv: dTw = kwref /(mvref*gamw) / H ^ 2

dTa : float

Vertical reference time factor multiplier for air phase. dTa is calculated with the chosen reference values of Da and mv: dTa = Daref / (mvref) / (wa/(R*T)/ua_ / H ^ 2. Where wa=molecular mass of air= 28.966e-3 kg/mol for air, R=universal gas constant=8.31432 J/(mol.K), T = absolute temperature in Kelvin=273.16+t0 (K), t0=temperature in celsius, ua_= absolute air pressure=ua+uatm (kPa), ua=guage air pressure, uatm= atmospheric air pressure=101 kPa. When ua is small or rapidly dissipates during consolidation ua_ can be considered a constant; so let ua_=uatm

m1ka : PolyLine

Normalised coefficient of air volume change with respect to a change in the net normal stress (dsig-dua), PolyLine(depth, m1ka).

m1kw : PolyLine

Normalised coefficient of water volume change with respect to a change in the net normal stress (dsig-dua), PolyLine(depth, m1kw).

m2a : PolyLine

Normalised coefficient of air volume change with respect to a change in the matirx suction (duw-dua), PolyLine(depth, m2a).

m2w : PolyLine

Normalised coefficient of water volume change with respect to a change in the matirx suction (duw-dua), PolyLine(depth, m2w).

kw : PolyLine

Normalised vertical permeability PolyLine(depth, kw).

Da : PolyLine

Normalised coefficeint of transmission for the air phase PolyLine(depth, Da).

n : PolyLine

Porosity PolyLine(depth, n). Porosity must be between 0 and 1.

S : PolyLine

Degree of saturation, PolyLine(depth, S). Degree of saturation must be between 0 and 1.

ua_ : float, optional

Absolute pore air pressure, assumed constant usually at atmospheric pressure. Default ua_=101 kPa. This is used in the porosity-saturation term.

surcharge_vs_depth : list of Polyline, optional

Surcharge variation with depth. PolyLine(depth, multiplier).

surcharge_vs_time : list of Polyline, optional

Surcharge magnitude variation with time. PolyLine(time, magnitude).

surcharge_omega_phase : list of 2 element tuples, optional

(omega, phase) to define cyclic variation of surcharge. i.e. mag_vs_time * cos(omega*t + phase). If surcharge_omega_phase is None then cyclic component will be ignored. If surcharge_omega_phase is a list then if any member is None then cyclic component will not be applied for that load combo.

atop_vs_time, wtop_vs_time : list of Polyline, optional

Top air and water p.press variation with time. Polyline(time, magnitude).

atop_omega_phase, wtop_omega_phase : list of 2 element tuples, optional

(omega, phase) to define cyclic variation of top air and water BC. i.e. mag_vs_time * cos(omega*t + phase). If top_omega_phase is None then cyclic component will be ignored. If top_omega_phase is a list then if any member is None then cyclic component will not be applied for that load combo.

abot_vs_time, wbot_vs_time : list of Polyline, optional

Bottom air and water p.press variation with time. Polyline(time, magnitude). When drn=1, i.e. PTIB, bot_vs_time is equivilent to saying D[u(H,t), z] = bot_vs_time. Within the program the actual gradient will be normalised with depth by multiplying H.

abot_omega_phase, wbot_omega_phase : list of 2 element tuples, optional

(omega, phase) to define cyclic variation of bot air and water BC. i.e. mag_vs_time * cos(omega*t + phase). If bot_omega_phase is None then cyclic component will be ignored. If bot_omega_phase is a list then if any member is None then cyclic component will not be applied for that load combo.

ppress_z : list_like of float, optional

Normalised z to calculate pore pressure at.

avg_ppress_z_pairs : list of two element list of float, optional

Nomalised zs to calculate average pore pressure between e.g. average of all profile is [[0,1]].

settlement_z_pairs : list of two element list of float, optional

Normalised depths to calculate normalised settlement between. e.g. surface settlement would be [[0, 1]].

tvals : list of float

Times to calculate output at.

ppress_z_tval_indexes : list/array of int, slice, optional

Indexes of tvals at which to calculate ppress_z. i.e. only calculate ppress_z at a subset of the tvals values. Default ppress_z_tval_indexes=slice(None, None) i.e. use all the tvals.

avg_ppress_z_pairs_tval_indexes : list/array of int, slice, optional

Indexes of tvals at which to calculate avg_ppress_z_pairs. i.e. only calc avg_ppress_z_pairs at a subset of the tvals values. Default avg_ppress_z_pairs_tval_indexes=slice(None, None) i.e. use all the tvals.

settlement_z_pairs_tval_indexes : list/array of int, slice, optional

Indexes of tvals at which to calculate settlement_z_pairs. i.e. only calc settlement_z_pairs at a subset of the tvals values. Default settlement_z_pairs_tval_indexes=slice(None, None) i.e. use all the tvals.

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

Where possible use the stated implementation type. ‘scalar’= python loops (slowest), ‘vectorized’ = numpy (fast), ‘fortran’ = fortran extension (fastest). Note only some functions have multiple implementations.

RLzero : float, optional

Reduced level of the top of the soil layer. If RLzero is not None then all depths (in plots and results) will be transformed to an RL by RL = RLzero - z*H. If RLzero is None (i.e. the default) then all depths will be reported z*H (i.e. positive numbers).

plot_properties : dict of dict, optional

Dictionary that overrides some of the plot properties. Each member of plot_properties will correspond to one of the plots.

plot_properties	description
porw	dict of prop to pass to water pore pressure plot.
pora	dict of prop to pass to air pore pressure plot.
avpw	dict of prop to pass to average water pore pressure plot.
avpa	dict of prop to pass to average air pore pressure plot.
set	dict of prop to pass to settlement plot.
seta	dict of prop to pass to air settlement plot.
setw	dict of prop to pass to water settlement plot.
load	dict of prop to pass to loads plot.
material	dict of prop to pass to materials plot.

see geotecha.plotting.one_d.plot_vs_depth and geotecha.plotting.one_d.plot_vs_time for options to specify in each plot dict.

save_data_to_file : True/False, optional

If True data will be saved to file. Default save_data_to_file=False

save_figures_to_file : True/False

If True then figures will be saved to file. Default save_figures_to_file=False

show_figures : True/False, optional

If True the after calculation figures will be shown on screen. Default show_figures=False.

directory : string, optional

Path to directory where files should be stored. Default directory=None which will use the current working directory. Note if you keep getting directory does not exist errors then try putting an r before the string definition. i.e. directory = r’C:Users...’

overwrite : True/False, optional

If True then existing files will be overwritten. Default overwrite=False.

prefix : string, optional

Filename prefix for all output files. Default prefix= ‘out’

create_directory : True/Fase, optional

If True a new sub-folder with name based on prefix and an incremented number will contain the output files. Default create_directory=True.

data_ext : string, optional

File extension for data files. Default data_ext=’.csv’

input_ext : string, optional

File extension for original and parsed input files. default = ”.py”

figure_ext : string, optional

File extension for figures. Can be any valid matplotlib option for savefig. Default figure_ext=”.eps”. Others include ‘pdf’, ‘png’.

title : str, optional

A title for the input file. This will appear at the top of data files. Default title=None, i.e. no title.

author : str, optional

Author of analysis. Default author=’unknown’.

Notes

Gotchas

All the loading terms e.g. surcharge_vs_time, surcharge_vs_depth, surcharge_omega_phase can be either a single value or a list of values. The corresponding lists that define a load must have the same length e.g. if specifying multiple surcharge loads then surcharge_vs_time and surcharge_vs_depth must be lists of the same length such that surcharge_vs_time[0] can be paired with surcharge_vs_depth[0], surcharge_vs_time[1] can be paired with surcharge_vs_depth[1], etc.

Material and geometric properties

• \(\sigma - u_a\) is net normal stress.
• \(u_a - u_w\) is matric suction.
• \(u_a\) is air pressure.
• \(u_w\) is water pressure.
• \(m_{1k}^a\) is coefficient of air volume change with respect to a change in the net normal stress.
• \(m_{1k}^w\) is coefficient of awater volume change with respect to a change in the net normal stress.
• \(m_2^a\) is coefficient of air volume change with respect to a change in the matric suction.
• \(m_2^a\) is coefficient of air volume change with respect to a change in the matric suction.
• \(k_w\) is vertical water permeability.
• \(D_a\) is coefficeint of transmission for the air phase. \(D_a = k_a g\).
• \(n\) is porosity \(0>n>1\).
• \(S\) is degree of saturation \(0>S>1\).
• \(\overline{u}_a\) is the absolute air pressure. \(\overline{u}_a = u_{atm}+u_a\).
• \(u_{atm}\) is absolute atmospheric air pressure.
• \(\gamma_w\) is the unit weight of water.
• \(Z\) is the nomalised depth (\(Z=z/H\)).
• \(H\) is the total height of the soil profile.
• \(T\) is the absolute temperature in kelvin.
• \(\omega\) is the molecular mass of air often taken as 29e-3 kg/mol.
• \(R\) is the universal gas constant 8.314 J/(mol.K).

Governing equation

Overall strain \(\varepsilon\) is the sum of the air strain, \(\varepsilon_a\) and the water strain \(\varepsilon_w\):

\[\varepsilon = \varepsilon_a + \varepsilon_w\]

The water and air strain components are:

\[\varepsilon_a = m_{1k}^a\left({\sigma - u_a}\right) + m_2^a\left({u_a - u_w}\right)\]

\[\varepsilon_w = m_{1k}^w\left({\sigma - u_a}\right) + m_2^w\left({u_a - u_w}\right)\]

Both pore air and pore water pressures are functions of normalised depth \(Z\) and time \(t\), \(u\left({Z, t}\right)\). The water and air phase partial differential equations are:

\[\left({\overline{m}_{1k}^w - \overline{m}_2^w}\right) u_a,_t + \overline{m}_2^w u_w,_t + dT_w\left({\overline{k}_w u_w,_Z}\right),_Z = \overline{m}_{1k}^w \sigma,_t\]

\[\left({\overline{m}_{1k}^a - \overline{m}_2^a - \frac{\left({1-S}\right)n}{\overline{u}_a m_{\textrm{ref}}} }\right) u_a,_t + \overline{m}_2^a u_w,_t + dT_a\left({\overline{D}_a u_a,_Z}\right),_Z = \overline{m}_{1k}^a \sigma,_t\]

where

\[dT_w = \frac{k_{w\textrm{ref}}} {H^2 m_{v\textrm{ref}} \gamma_w}\]

\[dT_a = \frac{D_{a\textrm{ref}}} {\left({\omega R T}\right) \overline{u}_a m_{\textrm{ref}}}\]

The overline notation represents a depth dependent property normalised by the relevant reference property. e.g. \(\overline{k}_w = k_w\left({z}\right) / k_{w\textrm{ref}}\).

A comma followed by a subscript represents differentiation with respect to the subscripted variable e.g. \(u,_Z = u\left({Z,t}\right) / \partial Z\).

Non-zero Boundary conditions

The following two sorts of boundary conditions for the air and water phases can be modelled independently using:

\[\left.u\left({Z,t}\right)\right|_{Z=0} = u^{\textrm{top}}\left({t}\right) \textrm{ and } \left.u\left({Z,t}\right)\right|_{Z=1} = u^{\textrm{bot}}\left({t}\right)\]

\[\left.u\left({Z,t}\right)\right|_{Z=0} = u^{\textrm{top}}\left({t}\right) \textrm{ and } \left.u\left({Z,t}\right),_Z\right|_{Z=1} = u^{\textrm{bot}}\left({t}\right)\]

The boundary conditions are incorporated by homogenising the governing equation with the following substitution:

\[u\left({Z,t}\right) = \hat{u}\left({Z,t}\right) + u_b\left({Z,t}\right)\]

where for the two types of non zero boundary boundary conditions:

\[u_b\left({Z,t}\right) = u^{\textrm{top}}\left({t}\right) \left({1-Z}\right) + u^{\textrm{bot}}\left({t}\right) Z\]

\[u_b\left({Z,t}\right) = u^{\textrm{top}}\left({t}\right) + u^{\textrm{bot}}\left({t}\right) Z\]

Time and depth dependence of loads/material properties

Soil properties do not vary with time.

Loads are formulated as the product of separate time and depth dependant functions as well as a cyclic component:

\[\sigma\left({Z,t}\right)= \sigma\left({Z}\right) \sigma\left({t}\right) \cos\left(\omega t + \phi\right)\]

\(\sigma\left(t\right)\) is a piecewise linear function of time that within the kth loading stage is defined by the load magnitude at the start and end of the stage:

\[\sigma\left(t\right) = \sigma_k^{\textrm{start}} + \frac{\sigma_k^{\textrm{end}} - \sigma_k^{\textrm{start}}} {t_k^{\textrm{end}} - t_k^{\textrm{start}}} \left(t - t_k^{\textrm{start}}\right)\]

The depth dependence of loads and material property \(a\left(Z\right)\) is a piecewise linear function with respect to \(Z\), that within a layer are defined by:

\[a\left(z\right) = a_t + \frac{a_b - a_t}{z_b - z_t}\left(z - z_t\right)\]

with \(t\) and \(b\) subscripts representing ‘top’ and ‘bottom’ of each layer respectively.

References

The genesis of this work is from research carried out by Dr. Rohan Walker, Prof. Buddhima Indraratna and others at the University of Wollongong, NSW, Austrlia, [R129], [R130], [R131], [R132].

[R129]

(1, 2) Walker, Rohan. 2006. ‘Analytical Solutions for Modeling Soft Soil Consolidation by Vertical Drains’. PhD Thesis, Wollongong, NSW, Australia: University of Wollongong.

[R130]

(1, 2) Walker, R., and B. Indraratna. 2009. ‘Consolidation Analysis of a Stratified Soil with Vertical and Horizontal Drainage Using the Spectral Method’. Geotechnique 59 (5) (January): 439-449. doi:10.1680/geot.2007.00019.

[R131]

(1, 2) Walker, Rohan, Buddhima Indraratna, and Nagaratnam Sivakugan. 2009. ‘Vertical and Radial Consolidation Analysis of Multilayered Soil Using the Spectral Method’. Journal of Geotechnical and Geoenvironmental Engineering 135 (5) (May): 657-663. doi:10.1061/(ASCE)GT.1943-5606.0000075.

[R132]

(1, 2) Walker, Rohan T. 2011. Vertical Drain Consolidation Analysis in One, Two and Three Dimensions’. Computers and Geotechnics 38 (8) (December): 1069-1077. doi:10.1016/j.compgeo.2011.07.006.

Attributes

porw, pora	(ndarray, only present if ppress_z is input) Calculated pore pressure at depths corresponding to ppress_z and times corresponding to tvals. This is an output array of size (len(ppress_z), len(tvals[ppress_z_tval_indexes])). porw and pora are pore pressure in water and air.
avpw, avpa	(ndarray, only present if avg_ppress_z_pairs is input) Calculated average pore pressure between depths corresponding to avg_ppress_z_pairs and times corresponding to tvals. This is an output array of size (len(avg_ppress_z_pairs), len(tvals[avg_ppress_z_pairs_tval_indexes])). avpw and avas are average pore pressure in water and air.
set, setw, seta	(ndarray, only present if settlement_z_pairs is input) Settlement between depths corresponding to settlement_z_pairs and times corresponding to tvals. This is an output array of size (len(avg_ppress_z_pairs), len(tvals[settlement_z_pairs_tval_indexes])). setw and sets are settlement in water and air. set is water + air.

Methods

check_input_attributes()	Perform checks on attributes
make_E_Igamv_the()	sum contributions from all loads
make_all()	Run checks, make all arrays, make output
make_output()	make all output
make_time_dependent_arrays()	make all time dependent arrays
make_time_independent_arrays()	make all time independent arrays
print_eigs()	print eigenvalues to stdout
produce_plots()	produce plots of analysis

make_E_Igamv_the()

sum contributions from all loads

Calculates all contributions to E*inverse(gam*v)*theta part of solution u=phi*vE*inverse(gam*v)*theta. i.e. surcharge, vacuum, top and bottom pore pressure boundary conditions. make_load_matrices will create `self.E_Igamv_the. self.E_Igamv_the is an array of size (neig, len(tvals)). So the columns are the column array E*inverse(gam*v)*theta calculated at each output time. This will allow us later to do u = phi*v*self.E_Igamv_the

See also

_make_E_Igamv_the_surcharge

surchage contribution

_make_E_Igamv_the_BC

top boundary pore pressure contribution

_make_E_Igamv_the_bot

bottom boundary pore pressure contribution

make_output()

make all output

make_time_dependent_arrays()

make all time dependent arrays

See also

self.make_E_Igamv_the

make_time_independent_arrays()

make all time independent arrays

See also

self._make_m

make the basis function eigenvalues

self._make_gam

make the mv dependent gamma matrix

self._make_psi

make the kv, kh, et dependent psi matrix

self._make_eigs_and_v

make eigenvalues, eigenvectors and I_gamv

print_eigs()

print eigenvalues to stdout

produce_plots()

produce plots of analysis

geotecha.speccon.speccon1d_unsat.main()

Run speccon1d_unsat as scipt