Soil lab

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_passing_at_standard_sieves`	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,
    extrapolate_max_percent_finer=None,
)

Calculation function.

$$ \begin{array}{l} \mathbf{function} \ \mathrm{get_percent_finer_diameters}(D, \mathrm{percent_finer}, FC, \mathrm{extrapolate_max_percent_finer}) \ \hspace{1em} \textrm{"Compute D60, D50, D30, and D10 from sieve data.

Each D-value is the particle size where the PSD polyline crosses the target
percent finer (see ``\_diameter\_at\_percent\_finer\_on\_polyline``). Segment-wise
crossing matches what is plotted and is required whenever plateaus exist;
deduplicating percent-finer values before inverse interpolation is incorrect.
"} \\ \hspace{1em} \mathrm{percent\_finer\_targets} \gets \mathrm{np}.\mathrm{asarray} \mathopen{}\left( \mathopen{}\left[ 60.0, 50.0, 30.0, 10.0 \mathclose{}\right] \mathclose{}\right) \\ \hspace{1em} \mathbf{if} \ \lnot \mathopen{}\left( FC \le 50 \mathclose{}\right) \\ \hspace{2em} \mathbf{return} \ \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} \mathrm{percent\_finer} \gets \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{percent\_finer} \mathclose{}\right) \\ \hspace{1em} D \gets \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( D \mathclose{}\right) \\ \hspace{1em} \mathrm{diameters} \gets \mathrm{np}.\mathrm{array} \mathopen{}\left( \mathopen{}\left[ \mathrm{\_diameter\_at\_percent\_finer\_on\_polyline} \mathopen{}\left( D, \mathrm{percent\_finer}, \mathrm{target} \mathclose{}\right) \mid \mathrm{target} \in \mathrm{percent\_finer\_targets} \mathclose{}\right] \mathclose{}\right) \\ \hspace{1em} \mathrm{min\_percent\_finer} \gets \mathrm{np}.\mathrm{nanmin} \mathopen{}\left( \mathrm{percent\_finer} \mathclose{}\right) \\ \hspace{1em} \mathbf{if} \ \mathrm{extrapolate\_max\_percent\_finer} \not\equiv \mathrm{None} \land \mathrm{min\_percent\_finer} \le \mathrm{extrapolate\_max\_percent\_finer} \\ \hspace{2em} \mathrm{fine\_end\_miss} \gets \mathrm{np}.\mathrm{isnan} \mathopen{}\left( \mathrm{diameters} \mathclose{}\right) \mathbin{\&} \mathopen{}\left( \mathrm{percent\_finer\_targets} < \mathrm{min\_percent\_finer} \mathclose{}\right) \\ \hspace{2em} \mathbf{for} \ i \in \mathrm{np}.\mathrm{flatnonzero} \mathopen{}\left( \mathrm{fine\_end\_miss} \mathclose{}\right) \ \mathbf{do} \\ \hspace{3em} \mathrm{diameters}_{i} \gets \mathrm{\_extrapolate\_diameter\_below\_fine\_end} \mathopen{}\left( D, \mathrm{percent\_finer}, \mathrm{percent\_finer\_targets}_{i} \mathclose{}\right) \\ \hspace{2em} \mathbf{end \ for} \\ \hspace{1em} \mathbf{end \ if} \\ \hspace{1em} \mathbf{return} \ \mathrm{tuple} \mathopen{}\left( \mathrm{diameters} \mathclose{}\right) \\ \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
`extrapolate_max_percent_finer`	`float`	Maximum measured percent finer at which fine-end diameter extrapolation is allowed when resolving D-sizes (e.g. D10). None disables extrapolation. Typical near-miss value: 12.	`None`

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_passing_at_standard_sieves

get_percent_passing_at_standard_sieves(
    particle_size, percent_finer
)

Calculation function.

\[ \begin{array}{l} \mathbf{function} \ \mathrm{get\_percent\_passing\_at\_standard\_sieves}(D, \mathrm{percent\_finer}) \\ \hspace{1em} \textrm{"Interpolate percent finer at standard ASTM sieve openings from a PSD curve."} \\ \hspace{1em} D \gets \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( D \mathclose{}\right) \\ \hspace{1em} \mathrm{percent\_finer} \gets \mathrm{np}.\mathrm{atleast\_1d} \mathopen{}\left( \mathrm{percent\_finer} \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{particle\_size\_targets} \gets \mathrm{np}.\mathrm{array} \mathopen{}\left( \mathopen{}\left[ \mathrm{SIEVES\_SI\_TO\_PARTICLE\_SIZE\_MAP}_{\mathrm{sieve\_number}} \mid \mathrm{sieve\_number} \in \mathrm{sieve\_number\_targets} \mathclose{}\right] \mathclose{}\right) \\ \hspace{1em} f \gets \mathrm{interpolate1d} \mathopen{}\left( D, \mathrm{percent\_finer} \mathclose{}\right) \\ \hspace{1em} \mathbf{return} \ \mathrm{tuple} \mathopen{}\left( f \mathopen{}\left( \mathrm{particle\_size\_targets} \mathclose{}\right) \mathclose{}\right) \\ \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

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_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{round\_half\_up} \mathopen{}\left( \mathrm{np}.\mathrm{nanmean} \mathopen{}\left( w_c \mathclose{}\right) \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} LL \gets \mathrm{round\_half\_up} \mathopen{}\left( LL \mathclose{}\right) \\ \hspace{1em} PL \gets \mathrm{round\_half\_up} \mathopen{}\left( PL \mathclose{}\right) \\ \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