Skip to content

Spatial slope units

Spatial schemas, input readers, distributed simulations, and result exports.

Both spatial runners accept column_mapping, a dictionary from expected field names to names in the input table or GeoPackage. See GIS column mapping for an example and unit conventions.

Spatial simulations over slope units with reusable material properties.

SlopeUnitSchema dataclass

Column names for required geometry and optional per-unit overrides.

Material properties are inherited from the material_id mapping. Optional non-null row properties override those defaults. Rainfall pairs int_0, dur_0, ... use mm/h and hours unless run-level units specify otherwise.

SlopeUnitsResult dataclass

Column results indexed by slope-unit identifier.

summary 

summary() -> pd.DataFrame

Return input attributes with deterministic stability diagnostics.

result_for 

result_for(unit_id: Hashable) -> ColumnResult

Return the time/depth result for one slope unit.

to_geopackage 

to_geopackage(path: str | Path, *, layer: str = 'unsatstab_results') -> None

Write summary attributes and geometry to a GeoPackage.

read_slope_units 

read_slope_units(path: str | Path, *, layer: str | None = None)

Read a GeoPackage layer with one record per slope unit.

materials_from_dataframe 

materials_from_dataframe(table: DataFrame) -> dict

Build material_id -> {hydro, strength, optional boundary} objects.

Geometry is omitted from hydraulic templates; each SU supplies it. Required hydraulic columns are saturated_hydraulic_conductivity_m_s, alpha_m_inv, theta_s and theta_r; strength columns are cohesion_pa, friction_angle_deg and unit_weight_soil_n_m3. Background infiltration defaults to zero and water unit weight to 9810 N/m³. Optional boundary and drainage_efficiency columns configure a material-level boundary.

run_slope_units 

run_slope_units(slope_units: DataFrame, materials: Mapping | DataFrame, *, output_times: ndarray, rainfall: RainfallSeries | None = None, schema: SlopeUnitSchema | None = None, column_mapping: Mapping[str, str] | None = None, default_boundary: BasalBoundary | None = None, n_roots: int | None = None, n_depths: int | None = None, n_jobs: int = -1, storage_time_step: float | None = None, antecedent: AntecedentRainfall | None = None, equation_set: str | None = None, rainfall_intensity_units: str = 'mm/h', rainfall_duration_units: str = 'h') -> SlopeUnitsResult

Evaluate full-column responses for spatially variable slope units.

Required SU columns are su_id, material_id, slope_angle_deg, maximum_depth_m, and initial_water_table_depth_m. column_mapping maps expected names to input names, e.g. {"su_id": "OBJECTID", "slope_angle_deg": "SLOPE"}. Unlisted names retain their defaults. Optional property and int_N/dur_N rainfall columns can also be mapped. Mapping changes names only, not units. Input attributes, geometry and column names are preserved in results and exports. Use either column_mapping or schema, not both. materials maps each ID to HydraulicProperties and StrengthProperties objects under hydro and strength. A material table is also accepted and converted with materials_from_dataframe. Geometry always comes from the SU.

Optional non-null property columns override material defaults. Rainfall precedence is SU int_N/dur_N pairs, material rainfall, then run rainfall. Defaults for the pairs are mm/h and hours; durations are accumulated into breakpoints automatically. A row with all rainfall-pair values missing inherits forcing; a partly specified history is rejected.

Optional failure_depth_m selects the pressure/FS time-series plane; omission selects the maximum depth. Full hydraulic and stability profiles are always returned. n_roots, n_depths and equation_set optionally override every material's corresponding hydraulic setting; otherwise templates retain their values. Output times (hours) and storage_time_step follow run_single_column.

run_slope_units_from_gpkg 

run_slope_units_from_gpkg(path: str | Path, materials: Mapping | DataFrame, *, output_times: ndarray, rainfall: RainfallSeries | None = None, layer: str | None = None, schema: SlopeUnitSchema | None = None, column_mapping: Mapping[str, str] | None = None, default_boundary: BasalBoundary | None = None, n_roots: int | None = None, n_depths: int | None = None, n_jobs: int = -1, storage_time_step: float | None = None, antecedent: AntecedentRainfall | None = None, equation_set: str | None = None, rainfall_intensity_units: str = 'mm/h', rainfall_duration_units: str = 'h') -> SlopeUnitsResult

Read a GeoPackage and run the material/override/forcing workflow.

Parameters and precedence are the same as run_slope_units; layer selects the GeoPackage layer. column_mapping maps expected names to layer column names and is forwarded unchanged; schema is an alternative.