Skip to content

Index

subsurfaceio.site_investigation.in_situ_tests

In-situ test models (CPT, DMT, borehole, IST, UDT).

Modules:

Name Description
mixins

In-situ test calculation mixins and result types.

Classes:

Name Description
BoreholeMetadata

Borehole test-specific metadata (rig, water table, corrections).
BoreholeTest

Borehole with Standard Penetration Test support.
CPTData

CPT depth record (tip, sleeve, pore pressure).
CPTFootingSettings

CPT footing method selectors and capacity knobs.
CPTInterpretationSettings

CPT interpretation inputs and method selector.
CPTLiquefactionSettings

CPT liquefaction inputs and method selector.
CPTMetadata

CPT test-specific metadata (equipment, water table, cone factors).
CPTPileSettings

CPT pile method selector and capacity knobs.
CPTTest

Cone Penetration Test (CPT/CPTu).
DMTData

DMT depth record (raw A/B/C readings).
DMTFootingSettings

DMT footing method selector.
DMTInterpretationSettings

DMT interpretation inputs and method selector.
DMTLiquefactionSettings

DMT liquefaction inputs and method selector.
DMTMetadata

DMT test-specific metadata (equipment, water table, calibrations).
DMTTest

Flat Dilatometer Test.
DataCustom

Optional depth-aligned custom inputs for calculations.
FootingSettings

Shared footing geometry and load inputs across test types.
ISTData

In-situ seismic depth record (Vs/Vp).
ISTMetadata

In-situ seismic test metadata.
ISTTest

In-situ seismic test (Vs/Vp).
InSituTestBase

Base model for a single in-situ test.
InSituTestMetadata

Shared location and elevation metadata for an in-situ test.
InSituTestPlotSettings

Default Plotly styling for an in-situ test series.
InterpretationSettings

Per-type interpretation inputs (no shared CPT/DMT/SPT fields).
LiquefactionSettings

Shared liquefaction inputs across test types.
LiquefactionShearInducedBuildingSettlementSettings

Shared shear-induced building settlement inputs (independent of footing analysis).
PileSettings

Shared pile geometry inputs across test types.
SPTData

SPT depth record used for interpretation and liquefaction.
SPTInterpretationSettings

SPT interpretation inputs and method selector.
SPTLiquefactionSettings

SPT liquefaction inputs and method selector.
SPTNHandler

SPT N-value and refusal text from seating + main interval blows.
SampleSPTRaw

Standard Penetration Test (ASTM D1586).
TestFootingSettings

Per-type footing inputs (method selectors and test-specific knobs).
TestLiquefactionSettings

Per-type liquefaction inputs (method selector and test-specific knobs).
TestPileSettings

Per-type pile inputs (method selector and test-specific knobs).
UDTData

User-defined depth record of soil parameters.
UDTMetadata

User-defined test metadata.
UDTTest

User-defined in-situ test (arbitrary depth parameters).
WaterTable

Water-table measurement collection.
WaterTableData

Single water-table measurement.

Attributes:

Name Type Description
DiscriminatedInSituTest TypeAlias

InSituTest discriminated on type.
InSituTest TypeAlias

Any in-situ test model.
InSituTestAdapter

Pydantic adapter for a discriminated in-situ test payload.
InSituTestWithCustomData TypeAlias

Tests that accept interpolated custom depth-series inputs.
InSituTestWithFootingCapacity TypeAlias

Tests that run shallow-foundation capacity.
InSituTestWithFootingSettlements TypeAlias

Tests that run shallow-foundation settlement.
InSituTestWithInterpretation TypeAlias

Tests that run interpretation (SPT, CPT, DMT).
InSituTestWithLiquefaction TypeAlias

Tests that run liquefaction triggering.
InSituTestWithLogPlot TypeAlias

Tests that can build a graphical log (LogPlotMixin).
InSituTestWithPile TypeAlias

Tests that run pile capacity.
SPTDataDepth TypeAlias

Stored SPTData.depth for an inferred row.

DiscriminatedInSituTest module-attribute 

DiscriminatedInSituTest: TypeAlias = Annotated[
    InSituTest, Field(discriminator="type")
]

InSituTest discriminated on type.

InSituTest module-attribute 

InSituTest: TypeAlias = (
    BoreholeTest | CPTTest | DMTTest | ISTTest | UDTTest
)

Any in-situ test model.

InSituTestAdapter module-attribute 

InSituTestAdapter = TypeAdapter(DiscriminatedInSituTest)

Pydantic adapter for a discriminated in-situ test payload.

InSituTestWithCustomData module-attribute 

InSituTestWithCustomData: TypeAlias = (
    BoreholeTest | CPTTest | DMTTest
)

Tests that accept interpolated custom depth-series inputs.

InSituTestWithFootingCapacity module-attribute 

InSituTestWithFootingCapacity: TypeAlias = CPTTest

Tests that run shallow-foundation capacity.

InSituTestWithFootingSettlements module-attribute 

InSituTestWithFootingSettlements: TypeAlias = (
    CPTTest | DMTTest
)

Tests that run shallow-foundation settlement.

InSituTestWithInterpretation module-attribute 

InSituTestWithInterpretation: TypeAlias = (
    BoreholeTest | CPTTest | DMTTest
)

Tests that run interpretation (SPT, CPT, DMT).

InSituTestWithLiquefaction module-attribute 

InSituTestWithLiquefaction: TypeAlias = (
    BoreholeTest | CPTTest | DMTTest
)

Tests that run liquefaction triggering.

InSituTestWithLogPlot module-attribute 

InSituTestWithLogPlot: TypeAlias = BoreholeTest | CPTTest

Tests that can build a graphical log (LogPlotMixin).

InSituTestWithPile module-attribute 

InSituTestWithPile: TypeAlias = CPTTest

Tests that run pile capacity.

SPTDataDepth module-attribute 

SPTDataDepth: TypeAlias = Literal[
    "main_drive_mid", "interval_base"
]

Stored SPTData.depth for an inferred row.

main_drive_mid is the main-drive midpoint. interval_base is the sample base when a sample is present, or the drive bottom for an unpaired SPT. This does not change which specimen is joined.

BoreholeMetadata pydantic-model

Bases: BaseModel

Borehole test-specific metadata (rig, water table, corrections).

Fields:

associated_file pydantic-field 

associated_file: str | None = None

borehole_diameter pydantic-field 

borehole_diameter: NullableFloat = 75.0

boring_type pydantic-field 

boring_type: str | None = None

crew pydantic-field 

crew: str | None = None

date_end pydantic-field 

date_end: datetime | None = None

date_start pydantic-field 

date_start: datetime | None = None

hammer_drop_system pydantic-field 

hammer_drop_system: str | None = None

method pydantic-field 

method: str | None = None

remarks pydantic-field 

remarks: str | None = None

rig_model pydantic-field 

rig_model: str | None = None

rod_length pydantic-field 

rod_length: NullableFloat = 1.5

sampler_correction pydantic-field 

sampler_correction: NullableFloat = 1.0

water_table pydantic-field 

water_table: NullableFloat = 0.0

water_table_present pydantic-field 

water_table_present: bool = True

BoreholeTest pydantic-model

Bases: InSituTestBase[BoreholeMetadata, SPTData], CalculationDataMixin, InterpretationMixin, LiquefactionMixin, LiquefactionShearInducedBuildingSettlementMixin, LogPlotMixin, LaboratoryTestsReportMixin

Borehole with Standard Penetration Test support.

Fields:

Validators:

data pydantic-field 

data: list[SPTData]

data_custom pydantic-field 

data_custom: list[DataCustom]

interpretation pydantic-field 

interpretation: SPTInterpretationResults | None = None

Calculation results

liquefaction pydantic-field 

liquefaction: (
    SPTLiquefactionCetin2004Results
    | SPTLiquefactionIdriss2008Results
    | SPTLiquefactionBoulanger2014Results
    | SPTLiquefactionCetin2018Results
    | None
) = None

Calculation results

liquefaction_settings pydantic-field 

liquefaction_settings: LiquefactionSettings

liquefaction_shear_induced_building_settlement pydantic-field 

liquefaction_shear_induced_building_settlement: (
    LiquefactionShearInducedBuildingSettlementBray2017Results
    | None
) = None

Calculation results

liquefaction_shear_induced_building_settlement_settings pydantic-field 

liquefaction_shear_induced_building_settlement_settings: (
    LiquefactionShearInducedBuildingSettlementSettings
)

plot_settings pydantic-field 

plot_settings: InSituTestPlotSettings

samples pydantic-field 

samples: list[Sample]

spt pydantic-field 

spt: list[SampleSPTRaw]

strata pydantic-field 

strata: list[StrataData]

test_interpretation_settings pydantic-field 

test_interpretation_settings: SPTInterpretationSettings

test_liquefaction_settings pydantic-field 

test_liquefaction_settings: SPTLiquefactionSettings

test_metadata pydantic-field 

test_metadata: BoreholeMetadata

type pydantic-field 

type: Literal['BORH']

use_custom_data pydantic-field 

use_custom_data: bool = False

add_sample 

add_sample(sample: Sample) -> Self

Append a sample. sample_id must be unique on this site.

Parameters:

Name Type Description Default
sample Sample

Sample to add.

 required

Returns:

Type Description
Self

This borehole test.

Raises:

Type Description
ValueError

When sample_id is missing or duplicated.

correlate_null_unit_weight 

correlate_null_unit_weight() -> Self

Fill missing SPT unit weights from the SPT correlation sequence.

Returns:

Type Description
Self

This borehole test.

get_sample_by_id 

get_sample_by_id(sample_id: str) -> Sample

Return the sample with sample_id.

Parameters:

Name Type Description Default
sample_id str

metadata.sample_id to look up.

 required

Returns:

Type Description
Sample

The matching sample.

Raises:

Type Description
KeyError

When no sample has that id.

get_spt_for_sample 

get_spt_for_sample(sample: Sample) -> SampleSPTRaw | None

Return the SPT drive paired with sample (depth-only match).

Same drive start at logging precision (2 dp); positive overlap of sample [depth_top, depth) with the drive when drive_length is set. See sample_spt_pair.

infer_data 

infer_data(
    spt_data_depth: SPTDataDepth = "main_drive_mid",
) -> Self

Build SPT data rows from samples, specimens, and matching drives.

One row per sample (including tubes with no N, so interpretation correlations that use LL, PI, and water content still have a node) plus one row per unpaired SPT drive. Lab fields come from the specimen whose interval contains the join depth (main-drive mid when a drive is paired, otherwise sample base). spt_data_depth (SPTDataDepth) only changes the stored SPTData.depth; it does not change which specimen is joined. Rows are always sorted by depth (None last).

Parameters:

Name Type Description Default
spt_data_depth SPTDataDepth

Where to store SPTData.depth. main_drive_mid uses the main-drive midpoint (sample base if mid is missing). interval_base uses the sample base (paired) or drive bottom (unpaired SPT).

 'main_drive_mid'

Returns:

Type Description
Self

This borehole test.

infer_strata_from_specimens 

infer_strata_from_specimens(depth_top: float = 0.0) -> Self

Build strata from specimen USCS symbols and depths.

Parameters:

Name Type Description Default
depth_top float

Depth of the first stratum top.

 0.0

Returns:

Type Description
Self

This borehole test.

CPTData pydantic-model

Bases: BaseModel

CPT depth record (tip, sleeve, pore pressure).

Fields:

cone_tip_resistance pydantic-field 

cone_tip_resistance: NullableFloat = None

depth pydantic-field 

depth: NullableFloat = None

pore_pressure pydantic-field 

pore_pressure: NullableFloat = None

sleeve_friction pydantic-field 

sleeve_friction: NullableFloat = None

CPTFootingSettings pydantic-model

Bases: TestFootingSettings

CPT footing method selectors and capacity knobs.

Fields:

bearing_capacity_factor pydantic-field 

bearing_capacity_factor: NullableFloat = 0.2

footing_influence_width_factor pydantic-field 

footing_influence_width_factor: NullableFloat = 1.5

function_sequence_footing_capacity pydantic-field 

function_sequence_footing_capacity: Literal[
    "CPTFootingCapacityRobertson"
] = "CPTFootingCapacityRobertson"

Function sequence used for footing capacity

function_sequence_footing_settlements pydantic-field 

function_sequence_footing_settlements: Literal[
    "CPTFootingSettlementsRobertson"
] = "CPTFootingSettlementsRobertson"

Function sequence used for footing settlements

CPTInterpretationSettings pydantic-model

Bases: InterpretationSettings

CPT interpretation inputs and method selector.

Fields:

constant_volume_friction_angle pydantic-field 

constant_volume_friction_angle: NullableFloat = 32.0

function_sequence pydantic-field 

function_sequence: Literal["CPTInterpretationRobertson"] = (
    "CPTInterpretationRobertson"
)

Function sequence used for interpretation

is_fine_soil_criteria pydantic-field 

is_fine_soil_criteria: IsFineSoilCriteria = 'sbtn'

moving_average_window_size pydantic-field 

moving_average_window_size: NullableInt = 3

overburden_correction_limit pydantic-field 

overburden_correction_limit: float = 1.7

relative_density_constant pydantic-field 

relative_density_constant: NullableFloat = 350.0

remove_loose_sand_criteria pydantic-field 

remove_loose_sand_criteria: bool = True

sensitivity_constant pydantic-field 

sensitivity_constant: NullableFloat = 7.0

soil_behavior_type_index_cutoff pydantic-field 

soil_behavior_type_index_cutoff: NullableFloat = 2.6

soil_transition_detection pydantic-field 

soil_transition_detection: bool = False

soil_transition_max_index pydantic-field 

soil_transition_max_index: NullableFloat = 3.0

soil_transition_min_index pydantic-field 

soil_transition_min_index: NullableFloat = 1.7

soil_transition_min_points pydantic-field 

soil_transition_min_points: NullableInt = 4

soil_transition_min_rate_of_change pydantic-field 

soil_transition_min_rate_of_change: NullableFloat = 0.001

CPTLiquefactionSettings pydantic-model

Bases: TestLiquefactionSettings

CPT liquefaction inputs and method selector.

Fields:

function_sequence pydantic-field 

function_sequence: Literal[
    "CPTLiquefactionRobertson",
    "CPTLiquefactionIdriss2008",
    "CPTLiquefactionBoulanger2014",
    "CPTLiquefactionSaye2021",
] = "CPTLiquefactionRobertson"

Function sequence used for liquefaction

void_redistribution_is_significant pydantic-field 

void_redistribution_is_significant: bool = True

CPTMetadata pydantic-model

Bases: BaseModel

CPT test-specific metadata (equipment, water table, cone factors).

Fields:

associated_file pydantic-field 

associated_file: str | None = None

cone_area_ratio pydantic-field 

cone_area_ratio: NullableFloat = 0.8

crew pydantic-field 

crew: str | None = None

date_end pydantic-field 

date_end: datetime | None = None

date_start pydantic-field 

date_start: datetime | None = None

method pydantic-field 

method: str | None = None

penetration_rate pydantic-field 

penetration_rate: NullableFloat = None

remarks pydantic-field 

remarks: str | None = None

water_table pydantic-field 

water_table: NullableFloat = 0.0

water_table_present pydantic-field 

water_table_present: bool = True

CPTPileSettings pydantic-model

Bases: TestPileSettings

CPT pile method selector and capacity knobs.

Fields:

careful_execution pydantic-field 

careful_execution: bool = False

function_sequence pydantic-field 

function_sequence: Literal[
    "CPTPileBustamante1982",
    "CPTPileBustamante1982Fellenius",
    "CPTPileEslami1997",
] = "CPTPileBustamante1982"

Function sequence used for pile capacity

pile_toe_transition pydantic-field 

pile_toe_transition: PileToeTransition = 'weak_to_dense'

pile_type_category pydantic-field 

pile_type_category: PileTypeCategory = 'IA'

unit_side_friction_clip pydantic-field 

unit_side_friction_clip: bool = True

CPTTest pydantic-model

Bases: InSituTestBase[CPTMetadata, CPTData], CalculationDataMixin, InterpretationMixin, LiquefactionMixin, LiquefactionShearInducedBuildingSettlementMixin, FootingSettlementsMixin, FootingCapacityMixin, PileMixin, LogPlotMixin

Cone Penetration Test (CPT/CPTu).

Fields:

data pydantic-field 

data: list[CPTData]

data_custom pydantic-field 

data_custom: list[DataCustom]

footing_capacity pydantic-field 

footing_capacity: (
    CPTFootingCapacityRobertsonResults | None
) = None

Calculation results

footing_settings pydantic-field 

footing_settings: FootingSettings

footing_settlements pydantic-field 

footing_settlements: (
    CPTFootingSettlementsRobertsonResults | None
) = None

Calculation results

interpretation pydantic-field 

interpretation: CPTInterpretationRobertsonResults | None = (
    None
)

Calculation results

liquefaction pydantic-field 

liquefaction: (
    CPTLiquefactionRobertsonResults
    | CPTLiquefactionIdriss2008Results
    | CPTLiquefactionBoulanger2014Results
    | CPTLiquefactionSaye2021Results
    | None
) = None

Calculation results

liquefaction_settings pydantic-field 

liquefaction_settings: LiquefactionSettings

liquefaction_shear_induced_building_settlement pydantic-field 

liquefaction_shear_induced_building_settlement: (
    LiquefactionShearInducedBuildingSettlementBray2017Results
    | None
) = None

Calculation results

liquefaction_shear_induced_building_settlement_settings pydantic-field 

liquefaction_shear_induced_building_settlement_settings: (
    LiquefactionShearInducedBuildingSettlementSettings
)

pile_capacity pydantic-field 

pile_capacity: (
    CPTPileBustamante1982Results
    | CPTPileBustamante1982FelleniusResults
    | CPTPileEslami1997Results
    | None
) = None

Calculation results

pile_settings pydantic-field 

pile_settings: PileSettings

strata pydantic-field 

strata: list[StrataData]

test_footing_settings pydantic-field 

test_footing_settings: CPTFootingSettings

test_interpretation_settings pydantic-field 

test_interpretation_settings: CPTInterpretationSettings

test_liquefaction_settings pydantic-field 

test_liquefaction_settings: CPTLiquefactionSettings

test_metadata pydantic-field 

test_metadata: CPTMetadata

test_pile_settings pydantic-field 

test_pile_settings: CPTPileSettings

type pydantic-field 

type: Literal['CPT']

use_custom_data pydantic-field 

use_custom_data: bool = False

create_dummy_u2 

create_dummy_u2() -> Self

Fill pore pressure from hydrostatic profile and return self.

get_cross_correlation 

get_cross_correlation(
    plot_module: Literal["plotly", "mpl"] = "plotly",
) -> tuple[int, Any]

Return tip/sleeve lag and a cross-correlation figure.

Parameters:

Name Type Description Default
plot_module Literal['plotly', 'mpl']

Figure backend.

 'plotly'

Returns:

Type Description
tuple[int, Any]

Integer lag (samples) and the backend figure.

Raises:

Type Description
ValueError

When plot_module is not plotly or mpl.

shift_sleeve_friction 

shift_sleeve_friction(shift: int) -> Self

Shift sleeve friction by lag (samples) and return self.

DMTData pydantic-model

Bases: BaseModel

DMT depth record (raw A/B/C readings).

Fields:

depth pydantic-field 

depth: NullableFloat = None

raw_a_reading pydantic-field 

raw_a_reading: NullableFloat = None

raw_b_reading pydantic-field 

raw_b_reading: NullableFloat = None

raw_c_reading pydantic-field 

raw_c_reading: NullableFloat = None

DMTFootingSettings pydantic-model

Bases: TestFootingSettings

DMT footing method selector.

Fields:

function_sequence_footing_settlements pydantic-field 

function_sequence_footing_settlements: Literal[
    "DMTFootingSettlementsRobertson"
] = "DMTFootingSettlementsRobertson"

Function sequence used for footing settlements

DMTInterpretationSettings pydantic-model

Bases: InterpretationSettings

DMT interpretation inputs and method selector.

Fields:

elasticity_to_constrained_modulus_ratio pydantic-field 

elasticity_to_constrained_modulus_ratio: NullableFloat = 0.8

function_sequence pydantic-field 

function_sequence: Literal["DMTInterpretationMarchetti"] = (
    "DMTInterpretationMarchetti"
)

Function sequence used for interpretation

DMTLiquefactionSettings pydantic-model

Bases: TestLiquefactionSettings

DMT liquefaction inputs and method selector.

Fields:

function_sequence pydantic-field 

function_sequence: Literal["DMTLiquefactionMarchetti"] = (
    "DMTLiquefactionMarchetti"
)

Function sequence used for liquefaction

DMTMetadata pydantic-model

Bases: BaseModel

DMT test-specific metadata (equipment, water table, calibrations).

Fields:

associated_file pydantic-field 

associated_file: str | None = None

crew pydantic-field 

crew: str | None = None

date_end pydantic-field 

date_end: datetime | None = None

date_start pydantic-field 

date_start: datetime | None = None

free_air_correction_a_reading pydantic-field 

free_air_correction_a_reading: NullableFloat = 15.0

free_air_correction_b_reading pydantic-field 

free_air_correction_b_reading: NullableFloat = 40.0

method pydantic-field 

method: str | None = None

penetration_rate pydantic-field 

penetration_rate: NullableFloat = None

remarks pydantic-field 

remarks: str | None = None

vented_control_unit_reading_a pydantic-field 

vented_control_unit_reading_a: NullableFloat = 3.0

vented_control_unit_reading_b pydantic-field 

vented_control_unit_reading_b: NullableFloat = 24.0

water_table pydantic-field 

water_table: NullableFloat = 0.0

water_table_present pydantic-field 

water_table_present: bool = True

DMTTest pydantic-model

Bases: InSituTestBase[DMTMetadata, DMTData], CalculationDataMixin, InterpretationMixin, LiquefactionMixin, LiquefactionShearInducedBuildingSettlementMixin, FootingSettlementsMixin

Flat Dilatometer Test.

Fields:

data pydantic-field 

data: list[DMTData]

data_custom pydantic-field 

data_custom: list[DataCustom]

footing_settings pydantic-field 

footing_settings: FootingSettings

footing_settlements pydantic-field 

footing_settlements: (
    DMTFootingSettlementsRobertsonResults | None
) = None

Calculation results

interpretation pydantic-field 

interpretation: DMTInterpretationMarchettiResults | None = (
    None
)

Calculation results

liquefaction pydantic-field 

liquefaction: DMTLiquefactionMarchettiResults | None = None

Calculation results

liquefaction_settings pydantic-field 

liquefaction_settings: LiquefactionSettings

liquefaction_shear_induced_building_settlement pydantic-field 

liquefaction_shear_induced_building_settlement: (
    LiquefactionShearInducedBuildingSettlementBray2017Results
    | None
) = None

Calculation results

liquefaction_shear_induced_building_settlement_settings pydantic-field 

liquefaction_shear_induced_building_settlement_settings: (
    LiquefactionShearInducedBuildingSettlementSettings
)

strata pydantic-field 

strata: list[StrataData]

test_footing_settings pydantic-field 

test_footing_settings: DMTFootingSettings

test_interpretation_settings pydantic-field 

test_interpretation_settings: DMTInterpretationSettings

test_liquefaction_settings pydantic-field 

test_liquefaction_settings: DMTLiquefactionSettings

test_metadata pydantic-field 

test_metadata: DMTMetadata

type pydantic-field 

type: Literal['DMT']

use_custom_data pydantic-field 

use_custom_data: bool = False

DataCustom pydantic-model

Bases: BaseModel

Optional depth-aligned custom inputs for calculations.

Fields:

cyclic_stress_ratio pydantic-field 

cyclic_stress_ratio: NullableFloat = None

depth pydantic-field 

depth: NullableFloat = None

peak_ground_acceleration pydantic-field 

peak_ground_acceleration: NullableFloat = None

FootingSettings pydantic-model

Bases: BaseModel

Shared footing geometry and load inputs across test types.

Fields:

apply_20_percent_rule pydantic-field 

apply_20_percent_rule: bool = True

consider_creep_settlement pydantic-field 

consider_creep_settlement: bool = False

consolidation_time pydantic-field 

consolidation_time: NullableFloat = 12.0

footing_applied_load pydantic-field 

footing_applied_load: NullableFloat = 100.0

footing_embedment pydantic-field 

footing_embedment: NullableFloat = 1.0

footing_length pydantic-field 

footing_length: NullableFloat = 2.0

footing_shape pydantic-field 

footing_shape: FootingShape = 'square'

footing_width pydantic-field 

footing_width: NullableFloat = 1.0

primary_consolidation_time pydantic-field 

primary_consolidation_time: NullableFloat = 6.0

ISTData pydantic-model

Bases: BaseModel

In-situ seismic depth record (Vs/Vp).

Fields:

compressional_velocity pydantic-field 

compressional_velocity: NullableFloat = None

depth pydantic-field 

depth: NullableFloat = None

shear_velocity pydantic-field 

shear_velocity: NullableFloat = None

ISTMetadata pydantic-model

Bases: BaseModel

In-situ seismic test metadata.

Fields:

associated_file pydantic-field 

associated_file: str | None = None

crew pydantic-field 

crew: str | None = None

date_end pydantic-field 

date_end: datetime | None = None

date_start pydantic-field 

date_start: datetime | None = None

ist_test_type pydantic-field 

ist_test_type: str | None = None

method pydantic-field 

method: str | None = None

remarks pydantic-field 

remarks: str | None = None

water_table pydantic-field 

water_table: NullableFloat = 0.0

water_table_present pydantic-field 

water_table_present: bool = True

ISTTest pydantic-model

Bases: InSituTestBase[ISTMetadata, ISTData]

In-situ seismic test (Vs/Vp).

Fields:

data pydantic-field 

data: list[ISTData]

plot_settings pydantic-field 

plot_settings: InSituTestPlotSettings

test_metadata pydantic-field 

test_metadata: ISTMetadata

type pydantic-field 

type: Literal['IST']

filter_consecutive_data_runs 

filter_consecutive_data_runs() -> Self

Keep the last sample of each consecutive equal-Vs run.

InSituTestBase pydantic-model

Bases: Model, Generic[TTestMetadata, TData, T]

Base model for a single in-situ test.

Fields:

data pydantic-field 

data: list[TData]

metadata pydantic-field 

metadata: InSituTestMetadata

plot_settings pydantic-field 

plot_settings: InSituTestPlotSettings

test_metadata pydantic-field 

test_metadata: TTestMetadata

type pydantic-field 

type: str

water_table_measurements pydantic-field 

water_table_measurements: WaterTable

InSituTestMetadata pydantic-model

Bases: BaseModel

Shared location and elevation metadata for an in-situ test.

Fields:

easting pydantic-field 

easting: NullableFloat = None

final_depth pydantic-field 

final_depth: NullableFloat = None

latitude pydantic-field 

latitude: NullableFloat = None

longitude pydantic-field 

longitude: NullableFloat = None

northing pydantic-field 

northing: NullableFloat = None

remarks pydantic-field 

remarks: str | None = None

surface_elevation pydantic-field 

surface_elevation: NullableFloat = None

test_id pydantic-field 

test_id: str

zone_letter pydantic-field 

zone_letter: str | None = None

zone_number pydantic-field 

zone_number: NullableInt = None

set_latitude_and_longitude_from_utm 

set_latitude_and_longitude_from_utm() -> Self

Fill latitude and longitude from UTM fields.

set_utm_from_latitude_and_longitude 

set_utm_from_latitude_and_longitude() -> Self

Fill UTM fields from latitude and longitude.

InSituTestPlotSettings pydantic-model

Bases: BaseModel

Default Plotly styling for an in-situ test series.

Fields:

color pydantic-field 

color: Color | None = None

line_shape pydantic-field 

line_shape: LineShape | None = 'linear'

line_width pydantic-field 

line_width: NullableFloat = None

marker_symbol pydantic-field 

marker_symbol: MarkerSymbol | None = 'circle'

mode pydantic-field 

mode: TraceMode = 'lines'

InterpretationSettings pydantic-model

Bases: BaseModel

Per-type interpretation inputs (no shared CPT/DMT/SPT fields).

Fields:

function_sequence pydantic-field 

function_sequence: str | None = None

LiquefactionSettings pydantic-model

Bases: BaseModel

Shared liquefaction inputs across test types.

Fields:

free_face_height pydantic-field 

free_face_height: NullableFloat = 2.0

free_face_length pydantic-field 

free_face_length: NullableFloat = 10.0

ground_slope pydantic-field 

ground_slope: NullableFloat = 1.0

lateral_displacement_min_thickness pydantic-field 

lateral_displacement_min_thickness: NullableFloat = 0.6

liquefaction_max_depth pydantic-field 

liquefaction_max_depth: NullableFloat = 20.0

liquefaction_potential_index_method pydantic-field 

liquefaction_potential_index_method: (
    LiquefactionPotentialIndexMethod
) = "iwasaki1978"

liquefaction_severity_number_max_depth pydantic-field 

liquefaction_severity_number_max_depth: NullableFloat = 20.0

moment_magnitude pydantic-field 

moment_magnitude: NullableFloat = 7.0

peak_ground_acceleration pydantic-field 

peak_ground_acceleration: NullableFloat = 0.24

shear_modulus_ratio pydantic-field 

shear_modulus_ratio: NullableFloat = 12.0

site_ground_condition pydantic-field 

site_ground_condition: SiteGroundCondition = 'level_ground'

stone_column_arrangement pydantic-field 

stone_column_arrangement: StoneColumnArrangement | None = (
    None
)

stone_column_bottom_depth pydantic-field 

stone_column_bottom_depth: NullableFloat = 10.0

stone_column_diameter pydantic-field 

stone_column_diameter: NullableFloat = 0.3

stone_column_spacing pydantic-field 

stone_column_spacing: NullableFloat = 1.0

stone_column_top_depth pydantic-field 

stone_column_top_depth: NullableFloat = 0.0

LiquefactionShearInducedBuildingSettlementSettings pydantic-model

Bases: BaseModel

Shared shear-induced building settlement inputs (independent of footing analysis).

Fields:

footing_embedment pydantic-field 

footing_embedment: NullableFloat = 1.0

footing_width pydantic-field 

footing_width: NullableFloat = 1.0

foundation_contact_pressure pydantic-field 

foundation_contact_pressure: NullableFloat = 100.0

function_sequence pydantic-field 

function_sequence: Literal[
    "LiquefactionShearInducedBuildingSettlementBray2017"
] = "LiquefactionShearInducedBuildingSettlementBray2017"

Function sequence used for liquefaction shear induced building settlement

spectral_acceleration_at_1_sec pydantic-field 

spectral_acceleration_at_1_sec: NullableFloat = None

standardized_cumulative_absolute_velocity pydantic-field 

standardized_cumulative_absolute_velocity: NullableFloat = (
    None
)

PileSettings pydantic-model

Bases: BaseModel

Shared pile geometry inputs across test types.

Fields:

pile_diameter pydantic-field 

pile_diameter: NullableFloat = 1.0

pile_shape pydantic-field 

pile_shape: PileShape = 'circle'

SPTData pydantic-model

Bases: BaseModel

SPT depth record used for interpretation and liquefaction.

Fields:

blow_count pydantic-field 

blow_count: NullableInt = None

depth pydantic-field 

depth: NullableFloat = None

diameter_at_10_percent_finer pydantic-field 

diameter_at_10_percent_finer: NullableFloat = None

diameter_at_50_percent_finer pydantic-field 

diameter_at_50_percent_finer: NullableFloat = None

energy_ratio pydantic-field 

energy_ratio: NullableFloat = 60.0

fines_content pydantic-field 

fines_content: NullableFloat = None

liquid_limit pydantic-field 

liquid_limit: NullableFloat = None

plastic_limit pydantic-field 

plastic_limit: NullableFloat = None

plasticity_index pydantic-field 

plasticity_index: NullableFloat = None

sample_id pydantic-field 

sample_id: str | None = None

uniformity_coefficient pydantic-field 

uniformity_coefficient: NullableFloat = None

unit_weight pydantic-field 

unit_weight: NullableFloat = None

uscs_symbol pydantic-field 

uscs_symbol: USCSSymbol | None = None

water_content pydantic-field 

water_content: NullableFloat = None

SPTInterpretationSettings pydantic-model

Bases: InterpretationSettings

SPT interpretation inputs and method selector.

Fields:

default_moist_unit_weight pydantic-field 

default_moist_unit_weight: NullableFloat = 18

default_saturated_unit_weight pydantic-field 

default_saturated_unit_weight: NullableFloat = 20

function_sequence pydantic-field 

function_sequence: Literal["SPTInterpretation"] = (
    "SPTInterpretation"
)

Function sequence used for interpretation

shansep_method_m pydantic-field 

shansep_method_m: NullableFloat = 0.8

shansep_method_s pydantic-field 

shansep_method_s: NullableFloat = 0.22

use_simplified_blows_correction pydantic-field 

use_simplified_blows_correction: bool = False

SPTLiquefactionSettings pydantic-model

Bases: TestLiquefactionSettings

SPT liquefaction inputs and method selector.

Fields:

average_shear_velocity_12m pydantic-field 

average_shear_velocity_12m: NullableFloat = 150.0

exclude_clay_like_sands pydantic-field 

exclude_clay_like_sands: bool = True

function_sequence pydantic-field 

function_sequence: Literal[
    "SPTLiquefactionCetin2004",
    "SPTLiquefactionIdriss2008",
    "SPTLiquefactionBoulanger2014",
    "SPTLiquefactionCetin2018",
] = "SPTLiquefactionBoulanger2014"

Function sequence used for liquefaction

site_to_seismic_source_distance pydantic-field 

site_to_seismic_source_distance: NullableFloat = 10.0

void_redistribution_is_significant pydantic-field 

void_redistribution_is_significant: bool = True

SPTNHandler pydantic-model

Bases: BaseModel

SPT N-value and refusal text from seating + main interval blows.

Interval penetrations and drive_length are in metres. refusal_length is the refusing increment (m), e.g. /0.10. When that pen is missing, it may be inferred from drive_length and SPT_INTERVAL_LENGTH_M for completed intervals (report-time only).

Fields:

blow_count property 

blow_count: float | None

N from mains 1+2, or 50 when any interval refuses.

drive_length pydantic-field 

drive_length: NullableFloat = None

main_blow_count_1 pydantic-field 

main_blow_count_1: NullableFloat = None

main_blow_count_2 pydantic-field 

main_blow_count_2: NullableFloat = None

main_blow_count_3 pydantic-field 

main_blow_count_3: NullableFloat = None

main_penetration_1 pydantic-field 

main_penetration_1: NullableFloat = None

main_penetration_2 pydantic-field 

main_penetration_2: NullableFloat = None

main_penetration_3 pydantic-field 

main_penetration_3: NullableFloat = None

refusal_length property 

refusal_length: float | None

Refusing-interval penetration (m).

Prefer measured interval pen. Else, if drive_length is known, subtract prior logged intervals (measured pen or SPT_INTERVAL_LENGTH_M). Never raises; returns None when length cannot be justified.

seating_blow_count pydantic-field 

seating_blow_count: NullableFloat = None

seating_penetration pydantic-field 

seating_penetration: NullableFloat = None

summary_blow_count pydantic-field 

summary_blow_count: NullableFloat = None

text property 

text: str | None

Log-plot SPT N string (interval blows and refusal length).

from_sample_spt classmethod 

from_sample_spt(spt: SampleSPTRaw) -> Self

Build an SPT N handler from a sample SPT record.

SampleSPTRaw pydantic-model

Bases: BaseModel

Standard Penetration Test (ASTM D1586).

depth_top is AGS-like top of test (sampler start), metres. drive_length is total sampler drive (seating + main), metres. Interval pens sync drive_length when present; sparse imports (NGL) may set drive_length without per-main pens.

Field order: blow counts then blow_count; penetrations then drive_length; then energy/method/remarks (AGS/RSLog-style grouping).

Fields:

Validators:

blow_count pydantic-field 

blow_count: NullableInt = None

depth_top pydantic-field 

depth_top: NullableFloat = None

drive_length pydantic-field 

drive_length: NullableFloat = None

energy_ratio pydantic-field 

energy_ratio: NullableFloat = None

main_blow_count_1 pydantic-field 

main_blow_count_1: NullableInt = None

main_blow_count_2 pydantic-field 

main_blow_count_2: NullableInt = None

main_blow_count_3 pydantic-field 

main_blow_count_3: NullableInt = None

main_drive_mid_depth property 

main_drive_mid_depth: float | None

Mid-depth of the main drive (m).

Requires explicit seating_penetration. When drive is longer than seating, mid of the main portion; otherwise mid of the full drive.

main_penetration_1 pydantic-field 

main_penetration_1: NullableFloat = None

main_penetration_2 pydantic-field 

main_penetration_2: NullableFloat = None

main_penetration_3 pydantic-field 

main_penetration_3: NullableFloat = None

method pydantic-field 

method: str | None = None

remarks pydantic-field 

remarks: str | None = None

reported_blow_count property 

reported_blow_count: str | None

N string for logs: interval text, else the stored blow_count.

seating_blow_count pydantic-field 

seating_blow_count: NullableInt = None

seating_penetration pydantic-field 

seating_penetration: NullableFloat = None

calculate_blow_count 

calculate_blow_count() -> Self

Set blow_count from main intervals 1 and 2.

sync_drive_length_from_pens pydantic-validator 

sync_drive_length_from_pens() -> Self

Set drive_length from interval pens when mains are present.

TestFootingSettings pydantic-model

Bases: BaseModel

Per-type footing inputs (method selectors and test-specific knobs).

TestLiquefactionSettings pydantic-model

Bases: BaseModel

Per-type liquefaction inputs (method selector and test-specific knobs).

Fields:

function_sequence pydantic-field 

function_sequence: str

TestPileSettings pydantic-model

Bases: BaseModel

Per-type pile inputs (method selector and test-specific knobs).

Fields:

function_sequence pydantic-field 

function_sequence: str

UDTData pydantic-model

Bases: BaseModel

User-defined depth record of soil parameters.

Fields:

coefficient_of_earth_pressure_at_rest pydantic-field 

coefficient_of_earth_pressure_at_rest: NullableFloat = None

depth pydantic-field 

depth: NullableFloat = None

diameter_at_50_percent_finer pydantic-field 

diameter_at_50_percent_finer: NullableFloat = None

fines_content pydantic-field 

fines_content: NullableFloat = None

friction_angle pydantic-field 

friction_angle: NullableFloat = None

overconsolidation_ratio pydantic-field 

overconsolidation_ratio: NullableFloat = None

peak_friction_angle pydantic-field 

peak_friction_angle: NullableFloat = None

plasticity_index pydantic-field 

plasticity_index: NullableFloat = None

relative_density pydantic-field 

relative_density: NullableFloat = None

shear_velocity pydantic-field 

shear_velocity: NullableFloat = None

undrained_shear_strength pydantic-field 

undrained_shear_strength: NullableFloat = None

uniformity_coefficient pydantic-field 

uniformity_coefficient: NullableFloat = None

unit_weight pydantic-field 

unit_weight: NullableFloat = None

uscs_symbol pydantic-field 

uscs_symbol: USCSSymbol | None = None

UDTMetadata pydantic-model

Bases: BaseModel

User-defined test metadata.

Fields:

associated_file pydantic-field 

associated_file: str | None = None

crew pydantic-field 

crew: str | None = None

date_end pydantic-field 

date_end: datetime | None = None

date_start pydantic-field 

date_start: datetime | None = None

remarks pydantic-field 

remarks: str | None = None

water_table pydantic-field 

water_table: NullableFloat = 0.0

water_table_present pydantic-field 

water_table_present: bool = True

UDTTest pydantic-model

Bases: InSituTestBase[UDTMetadata, UDTData]

User-defined in-situ test (arbitrary depth parameters).

Fields:

data pydantic-field 

data: list[UDTData]

plot_settings pydantic-field 

plot_settings: InSituTestPlotSettings

test_metadata pydantic-field 

test_metadata: UDTMetadata

type pydantic-field 

type: Literal['UDT']

WaterTable pydantic-model

Bases: BaseModel

Water-table measurement collection.

Fields:

data pydantic-field 

data: list[WaterTableData]

WaterTableData pydantic-model

Bases: BaseModel

Single water-table measurement.

Fields:

date pydantic-field 

date: datetime | None = None

remarks pydantic-field 

remarks: str | None = None

water_table pydantic-field 

water_table: NullableFloat = None