soil_lab.py

subsurfaceio.functions.soil_lab

Soil lab functions.

Functions:

Name	Description
get_a_parameter	Calculation function.
get_corrected_hydrometer_reading	Calculation function.
get_cumulative_mass_retained	Calculation function.
get_curvature_coefficient	Calculation function.
get_dry_soil_mass	Calculation function.
get_effective_length	Calculation function.
get_effective_length_corrected_reading	Calculation function.
get_hydrometer_percent_finer	Calculation function.
get_liquid_limit	Calculation function.
get_liquidity_index	Calculation function.
get_moisture_mass	Calculation function.
get_particle_size	Calculation function.
get_particle_size_from_sieve_number	Calculation function.
get_percent_clay	Calculation function.
get_percent_finer	Calculation function.
get_percent_finer_at_sieve_number	Calculation function.
get_percent_finer_diameters	Calculation function.
get_percent_finer_uncorrected	Calculation function.
get_percent_fraction	Calculation function.
get_percent_silt	Calculation function.
get_plastic_limit	Calculation function.
get_plasticity_index	Calculation function.
get_specific_gravity_correction	Calculation function.
get_temperature_correction	Calculation function.
get_uniformity_coefficient	Calculation function.
get_water_content	Calculation function.
get_water_content_liquid_limit_ratio	Calculation function.
get_water_content_trials	Calculation function.

get_a_parameter

get_a_parameter(temperature, specific_gravity)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_a\_parameter}(T, G_s) \\ \hspace{1em} A \gets \mathrm{ReferenceDataSets}.\mathrm{HydrometerDFactor}.\mathrm{grid\_interpolation} \mathopen{}\left( \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ A \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
temperature	float	Temperature during testing	required
specific_gravity	float	Specific gravity of soil solids	required

Returns:

Name	Type	Description
a_parameter	float	Hydrometer parameter dependent on temperature and specific gravity

get_corrected_hydrometer_reading

get_corrected_hydrometer_reading(
    hydrometer_reading,
    temperature_correction,
    zero_correction,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_corrected\_hydrometer\_reading}(R, F_T, F_z) \\ \hspace{1em} R_{cp} \gets R + F_T - F_z \\ \hspace{1em} \mathbf{return} \ R_{cp} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
hydrometer_reading	float	Hydrometer reading (151H: specific gravity, 152H: grams per liter)	required
temperature_correction	float	Correction for hydrometer test temperature (not 20°C)	required
zero_correction	float	Hydrometer zero correction for deflocculating agent	required

Returns:

Name	Type	Description
corrected_hydrometer_reading	float	Corrected hydrometer reading for percent finer calculation

get_cumulative_mass_retained

get_cumulative_mass_retained(mass_retained_sieve)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_cumulative\_mass\_retained}(W_n) \\ \hspace{1em} W_{n\ cum} \gets \mathrm{np}.\mathrm{cumsum} \mathopen{}\left( W_n \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ W_{n\ cum} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
mass_retained_sieve	float	Mass of soil retained on each sieve	required

Returns:

Name	Type	Description
cumulative_mass_retained	float	Cumulative mass of soil retained on sieves

get_curvature_coefficient

get_curvature_coefficient(
    diameter_at_10_percent_finer,
    diameter_at_30_percent_finer,
    diameter_at_60_percent_finer,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_curvature\_coefficient}(D_{10}, D_{30}, D_{60}) \\ \hspace{1em} C_c \gets \frac{D_{30}^{2}}{D_{10} \cdot D_{60}} \\ \hspace{1em} \mathbf{return} \ C_c \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
diameter_at_10_percent_finer	float	Diameter at 10% finer from sieve analysis	required
diameter_at_30_percent_finer	float	Diameter at 30% finer from sieve analysis	required
diameter_at_60_percent_finer	float	Diameter at 60% finer from sieve analysis	required

Returns:

Name	Type	Description
curvature_coefficient	float	Curvature coefficient for particle size distribution

get_dry_soil_mass

get_dry_soil_mass(can_mass, can_plus_dry_soil_mass)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_dry\_soil\_mass}(W_{can}, W_{can+drysoil}) \\ \hspace{1em} W_{dry\ soil} \gets W_{can+drysoil} - W_{can} \\ \hspace{1em} \mathbf{return} \ W_{dry\ soil} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
can_mass	float	Mass of soil sample can	required
can_plus_dry_soil_mass	float	Mass of soil sample can plus dry soil	required

Returns:

Name	Type	Description
dry_soil_mass	float	Dry soil mass in sample

get_effective_length

get_effective_length(
    effective_length_corrected_reading, hydrometer_type
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_effective\_length}(R_{cL}, \mathrm{hydrometer\_type}) \\ \hspace{1em} L \gets \mathrm{None} \\ \hspace{1em} \mathbf{if} \ \mathrm{hydrometer\_type} = \textrm{"152H"} \\ \hspace{2em} L \gets -0.164 R_{cL} + 16.295 \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} \mathbf{if} \ \mathrm{hydrometer\_type} = \textrm{"151H"} \\ \hspace{3em} L \gets -0.2645 R_{cL} + 16.295 \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ L \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
effective_length_corrected_reading	float	Corrected reading for effective length determination	required
hydrometer_type	str	Type of hydrometer used	required

Returns:

Name	Type	Description
effective_length	float	Effective length for hydrometer particle size calculation

get_effective_length_corrected_reading

get_effective_length_corrected_reading(
    hydrometer_reading, meniscus_correction
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_effective\_length\_corrected\_reading}(R, F_m) \\ \hspace{1em} R_{cL} \gets R + F_m \\ \hspace{1em} \mathbf{return} \ R_{cL} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
hydrometer_reading	float	Hydrometer reading (151H: specific gravity, 152H: grams per liter)	required
meniscus_correction	float	Meniscus correction for hydrometer readings (always positive)	required

Returns:

Name	Type	Description
effective_length_corrected_reading	float	Corrected reading for effective length determination

get_hydrometer_percent_finer

get_hydrometer_percent_finer(
    percent_finer_uncorrected, fines_content
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_hydrometer\_percent\_finer}(\mathrm{percent\_finer\_uncorrected}, FC) \\ \hspace{1em} \mathbf{if} \ FC < 90 \\ \hspace{2em} \mathrm{percent\_finer} \gets \mathrm{percent\_finer\_uncorrected} \cdot \frac{FC}{100} \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} \mathrm{percent\_finer} \gets \mathrm{percent\_finer\_uncorrected} \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ \mathrm{percent\_finer} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
percent_finer_uncorrected	float	Uncorrected percentage finer from sieve analysis	required
fines_content	float	Percentage of fines passing No. 200 sieve	required

Returns:

Name	Type	Description
percent_finer	float	Percentage of material finer than a given size

get_liquid_limit

get_liquid_limit(
    liquid_limit_method,
    liquid_limit_blows,
    water_content_trials,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_liquid\_limit}(LL_{method}, N, w_c) \\ \hspace{1em} \mathbf{if} \ LL_{method} = \textrm{"single\_point"} \\ \hspace{2em} \mathbf{if} \ N < 20 \lor N > 30 \\ \hspace{3em} \mathrm{raise\_value\_error} \mathopen{}\left( \textrm{"\{\} must be between 20 and 30 for single point liquid limit method"}.\mathrm{format} \mathopen{}\left( N \mathclose{}\right) \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{2em} LL \gets w_c \cdot \mathopen{}\left( \frac{N}{25} \mathclose{}\right)^{0.121} \\ \hspace{2em} \mathbf{return} \ \mathopen{}\left( LL, \mathrm{None} \mathclose{}\right) \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} \mathbf{if} \ LL_{method} = \textrm{"multi\_point"} \\ \hspace{3em} \mathrm{fit} \gets \mathrm{np}.\mathrm{polyfit} \mathopen{}\left( \log_{10} N, w_c, 1 \mathclose{}\right) \\ \hspace{3em} I_F \gets \mathopen{}\left| \mathrm{fit}_{0} \mathclose{}\right| \\ \hspace{3em} f \gets \mathrm{np}.\mathrm{poly1d} \mathopen{}\left( \mathrm{fit} \mathclose{}\right) \\ \hspace{3em} LL \gets f \mathopen{}\left( \log_{10} 25 \mathclose{}\right) \\ \hspace{3em} \mathbf{return} \ \mathopen{}\left( LL, I_F \mathclose{}\right) \\ \hspace{2em} \mathbf{else} \\ \hspace{3em} \mathrm{raise\_value\_error} \mathopen{}\left( \textrm{"\{\} method not valid"}.\mathrm{format} \mathopen{}\left( LL_{method} \mathclose{}\right) \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ \mathrm{None} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
liquid_limit_method	str	Method used for liquid limit determination	required
liquid_limit_blows	int	Number of blows in liquid limit test	required
water_content_trials	float	Natural water content for each trial	required

Returns:

Name	Type	Description
liquid_limit	float	Liquid limit of soil
flow_index	float	Slope of liquid limit flow line

get_liquidity_index

get_liquidity_index(
    water_content,
    liquid_limit,
    plasticity_index,
    is_fine_soil,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_liquidity\_index}(w_c, LL, PI, \mathrm{is\_fine\_soil}) \\ \hspace{1em} LI \gets \frac{w_c - \mathopen{}\left( LL - PI \mathclose{}\right)}{PI} \\ \hspace{1em} LI \gets \mathrm{np}.\mathrm{asarray} \mathopen{}\left( LI \mathclose{}\right) \\ \hspace{1em} \mathrm{np}.\mathrm{putmask} \mathopen{}\left( LI, \mathord{\sim} \mathrm{is\_fine\_soil}, \mathrm{np}.\mathrm{nan} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ LI \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
water_content	float	Natural water content of soil	required
liquid_limit	float	Liquid limit of soil	required
plasticity_index	float	Plasticity index of soil	required
is_fine_soil	bool	Indicates if soil is fine-grained	required

Returns:

Name	Type	Description
liquidity_index	float	Liquidity index of soil

get_moisture_mass

get_moisture_mass(
    can_plus_wet_soil_mass, can_plus_dry_soil_mass
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_moisture\_mass}(W_{can+wetsoil}, W_{can+drysoil}) \\ \hspace{1em} W_{moisture} \gets W_{can+wetsoil} - W_{can+drysoil} \\ \hspace{1em} \mathbf{return} \ W_{moisture} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
can_plus_wet_soil_mass	float	Mass of soil sample can plus wet soil	required
can_plus_dry_soil_mass	float	Mass of soil sample can plus dry soil	required

Returns:

Name	Type	Description
moisture_mass	float	Mass of moisture in soil sample

get_particle_size

get_particle_size(
    effective_length, hydrometer_time, a_parameter
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_particle\_size}(L, \mathrm{hydrometer\_time}, A) \\ \hspace{1em} D \gets A \cdot \sqrt{ \frac{L}{\mathrm{hydrometer\_time}} } \\ \hspace{1em} \mathbf{return} \ D \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
effective_length	float	Effective length for hydrometer particle size calculation	required
hydrometer_time	float	Elapsed time for hydrometer test	required
a_parameter	float	Hydrometer parameter dependent on temperature and specific gravity	required

Returns:

Name	Type	Description
particle_size	float	Particle size from sieve or hydrometer analysis

get_particle_size_from_sieve_number

get_particle_size_from_sieve_number(sieve_number)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_particle\_size\_from\_sieve\_number}(\mathrm{sieve\_number}) \\ \hspace{1em} D \gets \mathrm{replace\_from\_mapping} \mathopen{}\left( \mathrm{sieve\_number}, \mathrm{SIEVES\_SI\_TO\_PARTICLE\_SIZE\_MAP} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ D \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
sieve_number	str	Sieve number for particle size analysis (SI units)	required

Returns:

Name	Type	Description
particle_size	float	Particle size from sieve or hydrometer analysis

get_percent_clay

get_percent_clay(
    particle_size,
    percent_finer,
    silt_clay_particle_size_breakpoint=0.005,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_clay}(D, \mathrm{percent\_finer}, D_{silt\ clay}) \\ \hspace{1em} f \gets \mathrm{interpolate1d} \mathopen{}\left( \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( D \mathclose{}\right), \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{percent\_finer} \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathrm{percent\_clay} \gets f \mathopen{}\left( D_{silt\ clay} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{percent\_clay} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
particle_size	float	Particle size from sieve or hydrometer analysis	required
percent_finer	float	Percentage of material finer than a given size	required
silt_clay_particle_size_breakpoint	float	Breakpoint for silt and clay particle size	0.005

Returns:

Name	Type	Description
percent_clay	float	Clay percentage for USDA classification

get_percent_finer

get_percent_finer(dry_soil_mass, cumulative_mass_retained)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_finer}(W_{dry\ soil}, W_{n\ cum}) \\ \hspace{1em} \mathrm{percent\_finer} \gets \frac{100 \mathopen{}\left( W_{dry\ soil} - W_{n\ cum} \mathclose{}\right)}{W_{dry\ soil}} \\ \hspace{1em} \mathbf{return} \ \mathrm{percent\_finer} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
dry_soil_mass	float	Dry soil mass in sample	required
cumulative_mass_retained	float	Cumulative mass of soil retained on sieves	required

Returns:

Name	Type	Description
percent_finer	float	Percentage of material finer than a given size

get_percent_finer_at_sieve_number

get_percent_finer_at_sieve_number(
    sieve_number, percent_finer
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_finer\_at\_sieve\_number}(\mathrm{sieve\_number}, \mathrm{percent\_finer}) \\ \hspace{1em} \mathrm{percent\_finer\_map} \gets \mathrm{dict} \mathopen{}\left( \mathrm{zip} \mathopen{}\left( \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{sieve\_number} \mathclose{}\right), \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{percent\_finer} \mathclose{}\right) \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathrm{sieve\_number\_targets} \gets \mathopen{}\left( \textrm{"3/4 ""}, \textrm{"No. 4"}, \textrm{"No. 10"}, \textrm{"No. 40"}, \textrm{"No. 200"} \mathclose{}\right) \\ \hspace{1em} \mathrm{percent\_finer\_at\_sieve\_number} \gets \mathopen{}\left[ \mathclose{}\right] \\ \hspace{1em} \mathbf{for} \ \mathrm{sieve\_number\_target} \in \mathrm{sieve\_number\_targets} \ \mathbf{do} \\ \hspace{2em} \mathrm{percent\_finer\_at\_sieve\_number}.\mathrm{append} \mathopen{}\left( \mathrm{percent\_finer\_map}.\mathrm{get} \mathopen{}\left( \mathrm{sieve\_number\_target}, \mathrm{float} \mathopen{}\left( \textrm{"nan"} \mathclose{}\right) \mathclose{}\right) \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ for} \\ \hspace{1em} \mathbf{return} \ \mathrm{tuple} \mathopen{}\left( \mathrm{percent\_finer\_at\_sieve\_number} \mathclose{}\right) \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
sieve_number	str	Sieve number for particle size analysis (SI units)	required
percent_finer	float	Percentage of material finer than a given size	required

Returns:

Name	Type	Description
percent_passing_3in4	float	Percentage passing 3/4 " sieve
percent_passing_no4	float	Percentage passing No. 4 sieve
percent_passing_no10	float	Percentage passing No. 10 sieve
percent_passing_no40	float	Percentage passing No. 40 sieve
fines_content	float	Percentage of fines passing No. 200 sieve

get_percent_finer_diameters

get_percent_finer_diameters(
    particle_size, percent_finer, fines_content
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_finer\_diameters}(D, \mathrm{percent\_finer}, FC) \\ \hspace{1em} \mathrm{percent\_finer\_targets} \gets \mathopen{}\left( 60, 50, 30, 10 \mathclose{}\right) \\ \hspace{1em} \mathbf{if} \ FC \le 50 \\ \hspace{2em} f \gets \mathrm{interpolate1d} \mathopen{}\left( \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{percent\_finer} \mathclose{}\right), \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( D \mathclose{}\right) \mathclose{}\right) \\ \hspace{2em} \mathrm{percent\_finer\_diameters} \gets f \mathopen{}\left( \mathrm{percent\_finer\_targets} \mathclose{}\right) \\ \hspace{2em} \mathrm{to\_return} \gets \mathrm{tuple} \mathopen{}\left( \mathrm{percent\_finer\_diameters} \mathclose{}\right) \\ \hspace{1em} \mathbf{else} \\ \hspace{2em} \mathrm{to\_return} \gets \mathopen{}\left( \mathrm{np}.\mathrm{nan} \mathclose{}\right) \mathrm{len} \mathopen{}\left( \mathrm{percent\_finer\_targets} \mathclose{}\right) \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ \mathrm{to\_return} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
particle_size	float	Particle size from sieve or hydrometer analysis	required
percent_finer	float	Percentage of material finer than a given size	required
fines_content	float	Percentage of fines passing No. 200 sieve	required

Returns:

Name	Type	Description
diameter_at_60_percent_finer	float	Diameter at 60% finer from sieve analysis
diameter_at_50_percent_finer	float	Diameter at 50% finer from sieve analysis
diameter_at_30_percent_finer	float	Diameter at 30% finer from sieve analysis
diameter_at_10_percent_finer	float	Diameter at 10% finer from sieve analysis

get_percent_finer_uncorrected

get_percent_finer_uncorrected(
    corrected_hydrometer_reading,
    dry_soil_mass,
    specific_gravity_correction,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_finer\_uncorrected}(R_{cp}, W_{dry\ soil}, a) \\ \hspace{1em} \mathrm{percent\_finer\_uncorrected} \gets \frac{100 a \cdot R_{cp}}{W_{dry\ soil}} \\ \hspace{1em} \mathbf{return} \ \mathrm{percent\_finer\_uncorrected} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
corrected_hydrometer_reading	float	Corrected hydrometer reading for percent finer calculation	required
dry_soil_mass	float	Dry soil mass in sample	required
specific_gravity_correction	float	Correction for specific gravity (hydrometer calibrated for G_s = 2.65)	required

Returns:

Name	Type	Description
percent_finer_uncorrected	float	Uncorrected percentage finer from sieve analysis

get_percent_fraction

get_percent_fraction(
    percent_passing_3in4,
    percent_passing_no4,
    percent_passing_no10,
    percent_passing_no40,
    fines_content,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_fraction}(P_{3/4}, P_{4}, P_{10}, P_{40}, FC) \\ \hspace{1em} \mathrm{percent\_gravel} \gets 100 - P_{4} \\ \hspace{1em} \mathrm{percent\_coarse\_gravel} \gets 100 - P_{3/4} \\ \hspace{1em} \mathrm{percent\_fine\_gravel} \gets P_{3/4} - P_{4} \\ \hspace{1em} \mathrm{percent\_sand} \gets P_{4} - FC \\ \hspace{1em} \mathrm{percent\_coarse\_sand} \gets P_{4} - P_{10} \\ \hspace{1em} \mathrm{percent\_medium\_sand} \gets P_{10} - P_{40} \\ \hspace{1em} \mathrm{percent\_fine\_sand} \gets P_{40} - FC \\ \hspace{1em} \mathbf{return} \ \mathopen{}\left( \mathrm{percent\_gravel}, \mathrm{percent\_coarse\_gravel}, \mathrm{percent\_fine\_gravel}, \mathrm{percent\_sand}, \mathrm{percent\_coarse\_sand}, \mathrm{percent\_medium\_sand}, \mathrm{percent\_fine\_sand} \mathclose{}\right) \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
percent_passing_3in4	float	Percentage passing 3/4 " sieve	required
percent_passing_no4	float	Percentage passing No. 4 sieve	required
percent_passing_no10	float	Percentage passing No. 10 sieve	required
percent_passing_no40	float	Percentage passing No. 40 sieve	required
fines_content	float	Percentage of fines passing No. 200 sieve	required

Returns:

Name	Type	Description
percent_gravel	float	Gravel percentage (% retained on No. 4 sieve)
percent_coarse_gravel	float	Coarse gravel percentage (% retained on 3/4 " sieve)
percent_fine_gravel	float	Fine gravel percentage (% passing 3/4 " sieve, retained on No. 4)
percent_sand	float	Sand percentage (% passing No. 4 sieve)
percent_coarse_sand	float	Coarse sand percentage (% passing No. 4 sieve, retained on No. 10)
percent_medium_sand	float	Medium sand percentage (% passing No. 10 sieve, retained on No. 40)
percent_fine_sand	float	Fine sand percentage (% passing No. 40 sieve, retained on No. 200)

get_percent_silt

get_percent_silt(fines_content, percent_clay)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_silt}(FC, \mathrm{percent\_clay}) \\ \hspace{1em} \mathrm{percent\_silt} \gets FC - \mathrm{percent\_clay} \\ \hspace{1em} \mathbf{return} \ \mathrm{percent\_silt} \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
fines_content	float	Percentage of fines passing No. 200 sieve	required
percent_clay	float	Clay percentage for USDA classification	required

Returns:

Name	Type	Description
percent_silt	float	Silt percentage for USDA classification

get_plastic_limit

get_plastic_limit(water_content_trials)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_plastic\_limit}(w_c) \\ \hspace{1em} PL \gets \mathrm{np}.\mathrm{nanmean} \mathopen{}\left( w_c \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ PL \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
water_content_trials	float	Natural water content for each trial	required

Returns:

Name	Type	Description
plastic_limit	float	Plastic limit of soil

get_plasticity_index

get_plasticity_index(liquid_limit, plastic_limit)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_plasticity\_index}(LL, PL) \\ \hspace{1em} PI \gets LL - PL \\ \hspace{1em} \mathbf{return} \ PI \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
liquid_limit	float	Liquid limit of soil	required
plastic_limit	float	Plastic limit of soil	required

Returns:

Name	Type	Description
plasticity_index	float	Plasticity index of soil

get_specific_gravity_correction

get_specific_gravity_correction(specific_gravity)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_specific\_gravity\_correction}(G_s) \\ \hspace{1em} a \gets \frac{\frac{1.65}{2.65} \cdot G_s}{G_s - 1} \\ \hspace{1em} \mathbf{return} \ a \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
specific_gravity	float	Specific gravity of soil solids	required

Returns:

Name	Type	Description
specific_gravity_correction	float	Correction for specific gravity (hydrometer calibrated for G_s = 2.65)

get_temperature_correction

get_temperature_correction(temperature)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_temperature\_correction}(T) \\ \hspace{1em} F_T \gets -4.85 + 0.25 T \\ \hspace{1em} \mathbf{return} \ F_T \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
temperature	float	Temperature during testing	required

Returns:

Name	Type	Description
temperature_correction	float	Correction for hydrometer test temperature (not 20°C)

get_uniformity_coefficient

get_uniformity_coefficient(
    diameter_at_10_percent_finer,
    diameter_at_60_percent_finer,
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_uniformity\_coefficient}(D_{10}, D_{60}) \\ \hspace{1em} C_u \gets \frac{D_{60}}{D_{10}} \\ \hspace{1em} \mathbf{return} \ C_u \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
diameter_at_10_percent_finer	float	Diameter at 10% finer from sieve analysis	required
diameter_at_60_percent_finer	float	Diameter at 60% finer from sieve analysis	required

Returns:

Name	Type	Description
uniformity_coefficient	float	Uniformity coefficient for particle size distribution

get_water_content

get_water_content(water_content_trials)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_water\_content}(w_c) \\ \hspace{1em} w_c \gets \mathrm{np}.\mathrm{nanmean} \mathopen{}\left( w_c \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ w_c \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
water_content_trials	float	Natural water content for each trial	required

Returns:

Name	Type	Description
water_content	float	Natural water content of soil

get_water_content_liquid_limit_ratio

get_water_content_liquid_limit_ratio(
    water_content, liquid_limit
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_water\_content\_liquid\_limit\_ratio}(w_c, LL) \\ \hspace{1em} w_c\ /\ LL \gets \frac{w_c}{LL} \\ \hspace{1em} \mathbf{return} \ w_c\ /\ LL \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
water_content	float	Natural water content of soil	required
liquid_limit	float	Liquid limit of soil	required

Returns:

Name	Type	Description
water_content_liquid_limit_ratio	float	Ratio of water content to liquid limit

get_water_content_trials

get_water_content_trials(moisture_mass, dry_soil_mass)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_water\_content\_trials}(W_{moisture}, W_{dry\ soil}) \\ \hspace{1em} w_c \gets \frac{W_{moisture} \cdot 100}{W_{dry\ soil}} \\ \hspace{1em} \mathbf{return} \ w_c \\ \mathbf{end \ function} \end{array} \]

Parameters:

Name	Type	Description	Default
moisture_mass	float	Mass of moisture in soil sample	required
dry_soil_mass	float	Dry soil mass in sample	required

Returns:

Name	Type	Description
water_content_trials	float	Natural water content for each trial