Skip to content

Index

subsurfaceio.soil_structure_interaction

Soil-structure interaction API.

Compute SSI period lengthening and foundation stiffnesses:

from subsurfaceio.soil_structure_interaction import SoilStructureInteraction

SoilStructureInteraction(metadata=metadata, data=profile).calculate_effects()

Classes:

Name Description
Data

Shear-velocity profile row for SSI.
NodeData

Foundation node location and pile layout.
SSIEffectsResults

SSI period-lengthening effects results.
SSIFootingStiffnessIntensitiesResults

SSI footing stiffness-intensity results.
SSIFootingStiffnessResults

SSI footing stiffness results.
SSIIntermediateResults

SSI intermediate soil and structure results.
SSINodeDataResults

SSI per-node stiffness results.
SSIPileStiffnessInGroupResults

SSI pile-in-group stiffness results.
SSIPileStiffnessResults

SSI single-pile stiffness results.
SoilStructureInteraction

Soil-structure interaction calculations based on NIST (2012) report.
SoilStructureInteractionMetadata

Structure, footing, soil, and pile inputs for SSI.
TributaryAreas

Node tributary-area results.
TributaryAreasData

Node tributary-area result row.

Attributes:

Name Type Description
SSIEffectsResultsMetadata
SSIFootingStiffnessIntensitiesResultsData
SSIFootingStiffnessIntensitiesResultsMetadata
SSIFootingStiffnessResultsData
SSIIntermediateResultsMetadata
SSINodeDataResultsData
SSIPileStiffnessInGroupResultsData
SSIPileStiffnessResultsData

SSIEffectsResultsMetadata module-attribute 

SSIEffectsResultsMetadata = create_model(
    "SSIEffectsResultsMetadata",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIEffects.return_names(
            scalar=True
        )
    )
)

SSIFootingStiffnessIntensitiesResultsData module-attribute 

SSIFootingStiffnessIntensitiesResultsData = create_model(
    "SSIFootingStiffnessIntensitiesResultsData",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIFootingStiffnessIntensities.return_names(
            scalar=False
        )
    )
)

SSIFootingStiffnessIntensitiesResultsMetadata module-attribute 

SSIFootingStiffnessIntensitiesResultsMetadata = create_model(
    "SSIFootingStiffnessIntensitiesResultsMetadata",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIFootingStiffnessIntensities.return_names(
            scalar=True
        )
    )
)

SSIFootingStiffnessResultsData module-attribute 

SSIFootingStiffnessResultsData = create_model(
    "SSIFootingStiffnessResultsData",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIFootingStiffness.return_names(
            scalar=False
        )
    )
)

SSIIntermediateResultsMetadata module-attribute 

SSIIntermediateResultsMetadata = create_model(
    "SSIIntermediateResultsMetadata",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIIntermediate.return_names(
            scalar=True
        )
    )
)

SSINodeDataResultsData module-attribute 

SSINodeDataResultsData = create_model(
    "SSINodeDataResultsData",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSINodeData.return_names(
            scalar=False
        )
    )
)

SSIPileStiffnessInGroupResultsData module-attribute 

SSIPileStiffnessInGroupResultsData = create_model(
    "SSIPileStiffnessInGroupResultsData",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIPileStiffnessInGroup.return_names(
            scalar=False
        )
    )
)

SSIPileStiffnessResultsData module-attribute 

SSIPileStiffnessResultsData = create_model(
    "SSIPileStiffnessResultsData",
    __base__=BaseModel,
    **as_fields(
        FunctionSequences.SSIPileStiffness.return_names(
            scalar=False
        )
    )
)

Data pydantic-model

Bases: BaseModel

Shear-velocity profile row for SSI.

Fields:

depth pydantic-field 

depth: NullableFloat = None

shear_velocity pydantic-field 

shear_velocity: NullableFloat = None

NodeData pydantic-model

Bases: BaseModel

Foundation node location and pile layout.

Fields:

coordinate_x pydantic-field 

coordinate_x: float

coordinate_y pydantic-field 

coordinate_y: float

node_id pydantic-field 

node_id: int

pile_count pydantic-field 

pile_count: int = 1

pile_group_configuration pydantic-field 

pile_group_configuration: PileGroupConfiguration = '2X2'

SSIEffectsResults pydantic-model

Bases: BaseModel

SSI period-lengthening effects results.

Fields:

metadata pydantic-field 

metadata: SSIEffectsResultsMetadata

SSIFootingStiffnessIntensitiesResults pydantic-model

Bases: BaseModel

SSI footing stiffness-intensity results.

Fields:

data pydantic-field 

data: list[SSIFootingStiffnessIntensitiesResultsData]

metadata pydantic-field 

metadata: SSIFootingStiffnessIntensitiesResultsMetadata

SSIFootingStiffnessResults pydantic-model

Bases: BaseModel

SSI footing stiffness results.

Fields:

data pydantic-field 

data: list[SSIFootingStiffnessResultsData]

SSIIntermediateResults pydantic-model

Bases: BaseModel

SSI intermediate soil and structure results.

Fields:

metadata pydantic-field 

metadata: SSIIntermediateResultsMetadata

SSINodeDataResults pydantic-model

Bases: BaseModel

SSI per-node stiffness results.

Fields:

data pydantic-field 

data: list[SSINodeDataResultsData]

SSIPileStiffnessInGroupResults pydantic-model

Bases: BaseModel

SSI pile-in-group stiffness results.

Fields:

data pydantic-field 

data: list[SSIPileStiffnessInGroupResultsData]

SSIPileStiffnessResults pydantic-model

Bases: BaseModel

SSI single-pile stiffness results.

Fields:

data pydantic-field 

data: list[SSIPileStiffnessResultsData]

SoilStructureInteraction pydantic-model

Bases: Model

Soil-structure interaction calculations based on NIST (2012) report.

References
  • nist2012soil

Fields:

data pydantic-field 

data: list[Data]

effects pydantic-field 

effects: SSIEffectsResults | None = None

footing_stiffness pydantic-field 

footing_stiffness: SSIFootingStiffnessResults | None = None

footing_stiffness_intensities pydantic-field 

footing_stiffness_intensities: (
    SSIFootingStiffnessIntensitiesResults | None
) = None

intermediate pydantic-field 

intermediate: SSIIntermediateResults | None = None

metadata pydantic-field 

metadata: SoilStructureInteractionMetadata

node_data pydantic-field 

node_data: list[NodeData]

node_data_results pydantic-field 

node_data_results: SSINodeDataResults | None = None

pile_stiffness pydantic-field 

pile_stiffness: SSIPileStiffnessResults | None = None

pile_stiffness_in_group pydantic-field 

pile_stiffness_in_group: (
    SSIPileStiffnessInGroupResults | None
) = None

tributary_areas pydantic-field 

tributary_areas: TributaryAreas | None = None

calculate_effects 

calculate_effects() -> Self

Compute SSI period lengthening and related effect factors.

Returns:

Type Description
Self

self with effects populated.

calculate_footing_stiffness 

calculate_footing_stiffness() -> Self

Compute footing stiffnesses from intermediate results.

Returns:

Type Description
Self

self with footing_stiffness populated.

Raises:

Type Description
ValueError

If intermediate has not been calculated.

calculate_footing_stiffness_intensities 

calculate_footing_stiffness_intensities() -> Self

Distribute footing stiffness into intensity zones.

Returns:

Type Description
Self

self with footing_stiffness_intensities populated.

Raises:

Type Description
ValueError

If intermediate or footing_stiffness is missing.

calculate_intermediate 

calculate_intermediate() -> Self

Compute intermediate SSI profile quantities.

Returns:

Type Description
Self

self with intermediate populated.

calculate_node_data 

calculate_node_data() -> Self

Assemble per-node stiffness from tributary areas and intensities.

Returns:

Type Description
Self

self with node_data_results populated.

Raises:

Type Description
ValueError

If pile-in-group, footing intensities, or tributary areas are missing.

calculate_pile_stiffness 

calculate_pile_stiffness() -> Self

Compute pile stiffnesses from intermediate results.

Returns:

Type Description
Self

self with pile_stiffness populated.

Raises:

Type Description
ValueError

If intermediate has not been calculated.

calculate_pile_stiffness_in_group 

calculate_pile_stiffness_in_group() -> Self

Apply group interaction to pile stiffnesses.

Returns:

Type Description
Self

self with pile_stiffness_in_group populated.

Raises:

Type Description
ValueError

If intermediate or pile_stiffness is missing.

calculate_stiffness 

calculate_stiffness() -> Self

Run the full stiffness pipeline (intermediate through pile-in-group).

Returns:

Type Description
Self

self with stiffness result slots populated.

get_footing_intensities_poly_map 

get_footing_intensities_poly_map() -> dict[str, Any]

Return the footing intensity-zone polygon map.

Returns:

Type Description
dict[str, Any]

Cached polygon map for the footing plan.

get_node_tributary_areas 

get_node_tributary_areas() -> Self

Compute node tributary areas from Voronoi and intensity zones.

Returns:

Type Description
Self

self with tributary_areas populated.

get_voronoi 

get_voronoi() -> Any

Return the node Voronoi partition.

Returns:

Type Description
Any

Cached Voronoi partition of the footing plan.

plot_basement 

plot_basement(
    plot_module: Literal["plotly", "mpl"] = "plotly",
) -> Any

Draw the basement plan with optional node stiffness labels.

Parameters:

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

Figure backend.

 'plotly'

Returns:

Type Description
Any

Plotted 3-D or plan figure.

plot_effects 

plot_effects(
    plot_module: Literal["plotly", "mpl"] = "plotly",
) -> Any

Overlay SSI effects on the published period-lengthening chart.

Parameters:

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

Figure backend.

 'plotly'

Returns:

Type Description
Any

Plotted reference figure.

Raises:

Type Description
ValueError

If effects is missing or period lengthening is null.

SoilStructureInteractionMetadata pydantic-model

Bases: BaseModel

Structure, footing, soil, and pile inputs for SSI.

Fields:

elasticity_modulus pydantic-field 

elasticity_modulus: NullableFloat = 50.0

end_length_ratio pydantic-field 

end_length_ratio: NullableFloat = 0.4

footing_embedment pydantic-field 

footing_embedment: NullableFloat = 1.0

footing_length pydantic-field 

footing_length: NullableFloat = 2.0

footing_width pydantic-field 

footing_width: NullableFloat = 1.0

pile_diameter pydantic-field 

pile_diameter: NullableFloat = 1.0

pile_elasticity_modulus pydantic-field 

pile_elasticity_modulus: NullableFloat = 10318.04

pile_embedment_length pydantic-field 

pile_embedment_length: NullableFloat = 10.0

pile_unit_weight pydantic-field 

pile_unit_weight: NullableFloat = 24.0

poisson_ratio pydantic-field 

poisson_ratio: NullableFloat = 0.3

shear_modulus_reduction_factor pydantic-field 

shear_modulus_reduction_factor: NullableFloat = 0.5

soil_damping_ratio pydantic-field 

soil_damping_ratio: NullableFloat = 0.05

structure_flexible_period pydantic-field 

structure_flexible_period: NullableFloat = None

structure_rigid_period pydantic-field 

structure_rigid_period: NullableFloat = None

structure_total_height pydantic-field 

structure_total_height: NullableFloat = None

unit_weight pydantic-field 

unit_weight: NullableFloat = 16.0

TributaryAreas pydantic-model

Bases: BaseModel

Node tributary-area results.

Fields:

data pydantic-field 

data: list[TributaryAreasData]

TributaryAreasData pydantic-model

Bases: BaseModel

Node tributary-area result row.

Fields:

center pydantic-field 

center: float | None

corner pydantic-field 

corner: float | None

node_id pydantic-field 

node_id: int

tributary_area pydantic-field 

tributary_area: float | None

x_edge pydantic-field 

x_edge: float | None

y_edge pydantic-field 

y_edge: float | None