Skip to main content
Version: 14

viktor.external.dsettlement

CalculationModel​

class viktor.external.dsettlement.CalculationModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ISOTACHE: CalculationModel = 2
NEN_BJERRUM: CalculationModel = 1
NEN_KOPPEJAN: CalculationModel = 0

ConsolidationModel​

class viktor.external.dsettlement.ConsolidationModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

DARCY: ConsolidationModel = 0
TERZAGHI: ConsolidationModel = 1

DSettlementAnalysis​

class viktor.external.dsettlement.DSettlementAnalysis(input_file)

Bases: ExternalProgram

DSettlementAnalysis can be used to perform an analysis using DSettlement on a third-party worker. To start an analysis call the method execute(), with an appropriate timeout (in seconds). To retrieve the results call the method get_output_file(), after execute().

Usage:

input_file = File.from_data("dsettlement input file body")
dsettlement_analysis = DSettlementAnalysis(input_file=input_file)
dsettlement_analysis.execute(timeout=10)
output_file = dsettlement_analysis.get_output_file()  # obtain output file in BytesIO
sld_file = dsettlement_analysis.get_sld_file()  # obtain sld file in StringIO (to post-process)

Exceptions which can be raised during calculation: - viktor.errors.ExecutionError: generic error. Error message provides more information

Parameters:

input_file (Union[BytesIO, File]) – .sli input file.

get_output_file(extension='.sld', *, as_file=False)

Method can be used to retrieve the results generated by running an external analysis. Call method execute() first and get_output_file() afterwards.

Parameters:

  • extension (str) – extension of the file you want to return; one of: ‘.sld’, ‘.slo’, ‘.error.log’, ‘.err’

  • as_file (bool) – return as BytesIO (default) or File

    New in v13.5.0

Return type:

Union[BytesIO, File, None]

get_sld_file(*, as_file=False)

Method to retrieve the sld (result) file.

Parameters:

as_file (bool) – return as StringIO (default) or File

New in v13.5.0

Raises:

ValueError – if file can not be obtained.

Return type:

Union[StringIO, File]

DrainGrid​

class viktor.external.dsettlement.DrainGrid(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

RECTANGULAR: DrainGrid = 1
TRIANGULAR: DrainGrid = 0
UNDETERMINED: DrainGrid = 2

DrainType​

class viktor.external.dsettlement.DrainType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

COLUMN: DrainType = 1
SAND_WALL: DrainType = 2
STRIP: DrainType = 0

DrainageSimpleMode​

class viktor.external.dsettlement.DrainageSimpleMode(begin_time, end_time, underpressure, dewatering_head_or_pressure)

Simple drainage schema; to be used in VerticalDrain.

Parameters:

  • begin_time (float) – [days]

  • end_time (float) – [days]

  • underpressure (float) – [kPa]

  • dewatering_head_or_pressure (float) – water head [m] or tube pressure (if VerticalDrain.drain_type = SAND_WALL) [kPa]

Metadata​

class viktor.external.dsettlement.Metadata(file_name='-', company='-', created_by='-', title_1='-', title_2='-', title_3='-', write_date=False, write_time=False)

Data-class for defining metadata.

Parameters:

  • file_name (str)

  • company (str)

  • created_by (str)

  • title_1 (str) – max. 50 characters

  • title_2 (str) – max. 50 characters

  • title_3 (str) – max. 50 characters

  • write_date (bool) – True to write the current date to the sli file; False for dummy (‘01/01/1900’)

  • write_time (bool) – True to write the current date to the sli file; False for dummy (‘00:00:00’)

Raises:

ModelError – if title_1, title_2 or title_3 has more than 50 characters

Model1D​

class viktor.external.dsettlement.Model1D(calculation_model, consolidation_model, create_default_materials=True, *, natural_strain=False, water_unit_weight=9.81, verticals_discretization=100, verticals_z_coordinate=0.0, maintain_profile=False, profile_unit_weight_above_phreatic_level=10.0, profile_unit_weight_below_phreatic_level=10.0, end_of_settlement_calculation=10000, vertical_drain=None)

Bases: _Model

Model for a 1D D-Settlement analysis.

Example usage:

# instantiate 1D model
model = Model1D(CalculationModel.NEN_KOPPEJAN, ConsolidationModel.TERZAGHI)

# update the geometry
model.create_material("my_mat", 21.0, 19.0, color=Color(0, 0, 0))
model.update_geometry(-1.0, [(1.0, "Loam"), (0.0, "my_mat")], phreatic_level=-3.0)

# add load(s)
model.create_uniform_load("my_load", 0, 0.001, 0.0, 0.0)

# generate the input file
input_file = model.generate_input_file()
Parameters:

  • calculation_model (CalculationModel)

  • consolidation_model (ConsolidationModel)

  • create_default_materials (bool) – start with default materials or none

  • natural_strain (bool) – if False -> linear strain

  • water_unit_weight (float) – in [kN/m³]

  • vertical_drain (VerticalDrain) – parameters for vertical drains, or None (default) to disable option

materials
create_material(name, gam_dry, gam_wet, color=None, *, initial_void_ratio=0.0, cohesion=0.0, phi=0.0, precon_isotache_type=0, precon_koppejan_type=0, use_equivalent_age=0, equivalent_age=0.0, pc=0.0, ocr=1.0, pop=0.0, limit_stress=1.0, drained=0, ap_as_approximation_by_cp_cs=0, cv=10.0, permeability_ver=0.05, permeability_hor_factor=1.0, storage_type=0, permeability_strain_modulus=1000000000000000.0, use_prob_defaults=1, std_gam_dry=0.0, std_gam_wet=0.0, std_cv=0.0, std_pc=0.0, std_pri_comp_index=0.0, std_sec_comp_index=0.0, std_sec_comp_rate=0.0, std_ocr=0.0, std_permeability_ver=0.0, std_pop=0.0, std_permeability_hor_factor=0.0, std_initial_void_ratio=0.0, std_permeability_strain_modulus=0.0, std_limit_stress=0.0, std_cp=0.0, std_cp1=0.0, std_cs=0.0, std_cs1=0.0, std_ap=0.0, std_asec=0.0, std_car=0.0, std_ca=0.0, std_r_ratio=0.0, std_c_ratio=0.0, std_s_ratio=0.0, std_cr_index=0.0, std_cc_index=0.0, std_csw_index=0.0, dist_gam_dry=2, dist_gam_wet=2, dist_cv=2, dist_pc=2, dist_pri_comp_index=2, dist_sec_comp_index=2, dist_sec_comp_rate=2, dist_ocr=2, dist_permeability_ver=2, dist_pop=2, dist_permeability_hor_factor=2, dist_initial_void_ratio=2, dist_permeability_strain_modulus=2, dist_limit_stress=2, dist_cp=2, dist_cp1=2, dist_cs=2, dist_cs1=2, dist_ap=2, dist_asec=2, dist_car=2, dist_ca=2, dist_r_ratio=2, dist_c_ratio=2, dist_s_ratio=2, dist_cr_index=2, dist_cc_index=2, dist_csw_index=2, cor_cp_cp1=0.0, cor_cs_cp1=0.0, cor_cs1_cp1=0.0, cor_ap_cp1=0.0, cor_asec_cp1=0.0, cor_cr_index_cc_index=0.0, cor_r_ratio_c_ratio=0.0, cor_ca_cc_index_or_c_ratio=0.0, cor_pri_comp_index_sec_comp_index=0.0, cor_sec_comp_rate_sec_comp_index=0.0, cp=1.0, cp1=1.0, cs=1.0, cs1=1.0, ap=1.0, asec=1.0, car=0.0, ca=1.0, comp_ratio=1, r_ratio=1.0, c_ratio=1.0, s_ratio=0.0, cr_index=1.0, cc_index=1.0, csw_index=0.0, pri_comp_index=0.01, sec_comp_index=0.1, sec_comp_rate=0.005, horizontal_behaviour_type=2, elasticity=1000.0, default_elasticity=1)

Create a material with the given name and properties.

Parameters:

  • name (str) – name of the material to create (max. 25 characters)

  • color (Color) – color for visualization in deltares software (None for random color)

  • gam_dry (float) – unit weight above phreatic level in [kN/m³]

  • gam_wet (float) – unit weight below phreatic level in [kN/m³]

  • .... – etc.

Raises:

ModelError –

  • if material with given name already exists in the model

  • if name is longer than 25 characters

Return type:

None

create_uniform_load(name, time, unit_weight, height, y_application)

Create a uniform load with the given name and properties.

Parameters:

  • name (str) – name of the uniform load to create

  • time (int) – in [days], -1 for initial load

  • unit_weight (float) – in [kN/m³]

  • height (float) – in [m]

  • y_application (float) – in [m]

Return type:

None

set_calculation_times(*time)

(Re)set calculation time(s)

Parameters:

time (int) – one or more calculation times at which results will be obtained # todo: days

Raises:

ModelError –

  • if time < 0 or > end time

  • if duplicates exist

Return type:

None

generate_input_file(metadata=None, *, dissipation_calculation=None, as_file=False)

Generate a D-Settlement input file.

Note

This method needs to be mocked in (automated) unit and integration tests.

Parameters:

  • metadata (Metadata) – Metadata which will be written to the input file. If no metadata is provided, default data will be used.

  • dissipation_calculation (_Vertical) – select vertical to add dissipation calculation; ‘None’ to disable.

  • as_file (bool) – return as BytesIO (default) or File

    New in v13.5.0

Return type:

Union[BytesIO, File]

property bottom_level: float
property layers: List[Tuple[float, str]]
property phreatic_level: float | None
property top_level: float
update_geometry(bottom_level, layers, phreatic_level=None)

Overwrite the current (default if not updated before) geometry with the given data.

Parameters:

  • bottom_level (float) – bottom level of the bottom-most layer [m]

  • layers (List[Tuple[float, str]]) – list of layers defined by top level [m] and material name (must be created beforehand with create_material() or one of the default materials). Should be defined from top to bottom.

  • phreatic_level (float) – in [m]

Raises:

ModelError –

  • if layers are not defined from top to bottom

  • if lowest layer top level is below given bottom level

  • if material with given name does not exist

Return type:

None

Example usage:

model.update_geometry(-1, [(1.0, "Loam"), (0.0, "Sand")], phreatic_level=-3)

Model2D​

class viktor.external.dsettlement.Model2D(calculation_model, consolidation_model, boundary_bottom, create_default_materials=True, *, natural_strain=False, limits=(0.0, 100.0), water_unit_weight=9.81, verticals_discretization=100, verticals_z_coordinate=0.0, maintain_profile=False, profile_time=0, profile_unit_weight_above_phreatic_level=10.0, profile_unit_weight_below_phreatic_level=10.0, end_of_settlement_calculation=10000, stress_distribution_loads=False, vertical_drain=None)

Bases: _Model

Model for a 2D D-Settlement analysis.

Example usage:

# Initialize parameters for vertical drainage, to be used in the init of Model2D.
vertical_drain = VerticalDrain(DrainType.SAND_WALL, 5.0, 90.0, 0.0, 2.0, 4.0,
                               start_of_drainage=2.0, phreatic_level_in_drain=4.0)

# Create the model (NEN - Koppejan / Terzaghi) with a starting bottom boundary, vertical drainage and
# miscellaneous default parameters.
model = Model2D(CalculationModel.NEN_KOPPEJAN, ConsolidationModel.TERZAGHI,
                boundary_bottom=[(0.0, 0.0), (100.0, 0.0)], vertical_drain=vertical_drain)

# Create points for defining boundaries and pl-lines.
points_boundary1 = [model.create_point(x, y) for (x, y) in [(0.0, 5.0), (50.0, 5.0), (100.0, 2.5)]]
points_boundary2 = [model.create_point(x, y) for (x, y) in [(0.0, 5.0), (50.0, 5.0), (100.0, 7.5)]]
points_boundary3 = [model.create_point(x, y) for (x, y) in [(0.0, 10.0), (25, 10.0), (75, 10.0), (100.0, 10.0)]]
points_plline1 = [model.create_point(x, y) for (x, y) in [(0.0, 4.0), (100.0, 4.0)]]
points_plline2 = [model.create_point(x, y) for (x, y) in [(0.0, 6.0), (100.0, 6.0)]]

# Create the pl-lines.
plline1 = model.create_pl_line(points_plline1, is_phreatic=True)
plline2 = model.create_pl_line(points_plline2)

# Create the layers.
model.create_layer(points_boundary1, 'Sand', pl_line_top=99, pl_line_bottom=plline2)
model.create_layer(points_boundary2, 'Soft Clay', pl_line_top=99, pl_line_bottom=99)
model.create_layer(points_boundary3, 'Loam', pl_line_top=plline1, pl_line_bottom=99)

# Create verticals.
model.create_vertical(45.0)
model.create_vertical(50.0)
model.create_vertical(55.0)

# Create loads.
model.create_non_uniform_load('load1', [(25, 10.0), (50.0, 12.0), (75, 10.0)])

# Create calculation/residual times.
model.set_calculation_times(1, 4, 2, 5)

# Generate the input file for the model as if it was generated by D-Settlement.
input_file = model.generate_input_file()
Parameters:

  • calculation_model (CalculationModel) – Specifies which calculation model is used.

  • consolidation_model (ConsolidationModel) – Specifies which consolidation model is used.

  • boundary_bottom (List[Tuple[float, float]]) – The bottom boundary of the geometry.

  • create_default_materials (bool) – start with default materials or none

  • natural_strain (bool) – Indicates if natural strain is used. If False, linear strain is used.

  • water_unit_weight (float) – in [kN/m³]

  • stress_distribution_loads (bool) – True for ‘Simulate’, False for ‘None’ (default).

  • vertical_drain (VerticalDrain) – parameters for vertical drains, or None (default) to disable option

materials
create_material(name, gam_dry, gam_wet, color=None, *, initial_void_ratio=0.0, cohesion=0.0, phi=0.0, precon_isotache_type=0, precon_koppejan_type=0, use_equivalent_age=0, equivalent_age=0.0, pc=0.0, ocr=1.0, pop=0.0, limit_stress=1.0, drained=0, ap_as_approximation_by_cp_cs=0, cv=10.0, permeability_ver=0.05, permeability_hor_factor=1.0, storage_type=0, permeability_strain_modulus=1000000000000000.0, use_prob_defaults=1, std_gam_dry=0.0, std_gam_wet=0.0, std_cv=0.0, std_pc=0.0, std_pri_comp_index=0.0, std_sec_comp_index=0.0, std_sec_comp_rate=0.0, std_ocr=0.0, std_permeability_ver=0.0, std_pop=0.0, std_permeability_hor_factor=0.0, std_initial_void_ratio=0.0, std_permeability_strain_modulus=0.0, std_limit_stress=0.0, std_cp=0.0, std_cp1=0.0, std_cs=0.0, std_cs1=0.0, std_ap=0.0, std_asec=0.0, std_car=0.0, std_ca=0.0, std_r_ratio=0.0, std_c_ratio=0.0, std_s_ratio=0.0, std_cr_index=0.0, std_cc_index=0.0, std_csw_index=0.0, dist_gam_dry=2, dist_gam_wet=2, dist_cv=2, dist_pc=2, dist_pri_comp_index=2, dist_sec_comp_index=2, dist_sec_comp_rate=2, dist_ocr=2, dist_permeability_ver=2, dist_pop=2, dist_permeability_hor_factor=2, dist_initial_void_ratio=2, dist_permeability_strain_modulus=2, dist_limit_stress=2, dist_cp=2, dist_cp1=2, dist_cs=2, dist_cs1=2, dist_ap=2, dist_asec=2, dist_car=2, dist_ca=2, dist_r_ratio=2, dist_c_ratio=2, dist_s_ratio=2, dist_cr_index=2, dist_cc_index=2, dist_csw_index=2, cor_cp_cp1=0.0, cor_cs_cp1=0.0, cor_cs1_cp1=0.0, cor_ap_cp1=0.0, cor_asec_cp1=0.0, cor_cr_index_cc_index=0.0, cor_r_ratio_c_ratio=0.0, cor_ca_cc_index_or_c_ratio=0.0, cor_pri_comp_index_sec_comp_index=0.0, cor_sec_comp_rate_sec_comp_index=0.0, cp=1.0, cp1=1.0, cs=1.0, cs1=1.0, ap=1.0, asec=1.0, car=0.0, ca=1.0, comp_ratio=1, r_ratio=1.0, c_ratio=1.0, s_ratio=0.0, cr_index=1.0, cc_index=1.0, csw_index=0.0, pri_comp_index=0.01, sec_comp_index=0.1, sec_comp_rate=0.005, horizontal_behaviour_type=2, elasticity=1000.0, default_elasticity=1)

Create a material with the given name and properties.

Parameters:

  • name (str) – name of the material to create (max. 25 characters)

  • color (Color) – color for visualization in deltares software (None for random color)

  • gam_dry (float) – unit weight above phreatic level in [kN/m³]

  • gam_wet (float) – unit weight below phreatic level in [kN/m³]

  • .... – etc.

Raises:

ModelError –

  • if material with given name already exists in the model

  • if name is longer than 25 characters

Return type:

None

create_uniform_load(name, time, unit_weight, height, y_application)

Create a uniform load with the given name and properties.

Parameters:

  • name (str) – name of the uniform load to create

  • time (int) – in [days], -1 for initial load

  • unit_weight (float) – in [kN/m³]

  • height (float) – in [m]

  • y_application (float) – in [m]

Return type:

None

set_calculation_times(*time)

(Re)set calculation time(s)

Parameters:

time (int) – one or more calculation times at which results will be obtained # todo: days

Raises:

ModelError –

  • if time < 0 or > end time

  • if duplicates exist

Return type:

None

generate_input_file(metadata=None, *, dissipation_calculation=None, as_file=False)

Generate a D-Settlement input file.

Note

This method needs to be mocked in (automated) unit and integration tests.

Parameters:

  • metadata (Metadata) – Metadata which will be written to the input file. If no metadata is provided, default data will be used.

  • dissipation_calculation (_Vertical) – select vertical to add dissipation calculation; ‘None’ to disable.

  • as_file (bool) – return as BytesIO (default) or File

    New in v13.5.0

Return type:

Union[BytesIO, File]

create_layer(boundary_top, material, pl_line_top, pl_line_bottom)

Define layers from bottom to top.

Parameters:

  • boundary_top (List[_Point]) – boundary at top of layer

  • material (str) – name of the material to be used (must be created beforehand)

  • pl_line_top (Union[_PlLine, int]) – pl-line at top, or 0 for no pressure, or 99 for interpolation

  • pl_line_bottom (Union[_PlLine, int]) – pl-line at bottom, or 0 for no pressure, or 99 for interpolation

Raises:

ModelError –

  • if material with given name does not exist

  • if boundary_bottom is provided for layer other than first

  • if pl_line_top or pl_line_bottom are not valid

  • if ‘points’ contains duplicates

  • if start and end ‘points’ are not on the left and right boundary limit respectively

  • if ‘points’ are not in ascending X-direction

  • if ‘is_phreatic’ is True but was already set before

Return type:

_Layer

create_non_uniform_load(name, points, time=0, end_time=0, gamma_dry=10.0, gamma_wet=10.0, temporary=False)

Create a non-uniform load.

DSettlement assumes that a non-uniform load is caused by soil self weight. Initial loads only affects the initial stresses and do not cause creep or consolidation.

Parameters:

  • name (str) – Name of the load.

  • points (List[Tuple[float, float]]) – Points, as x-y coordinates, of the load. The first and last points must be located on a layer or another non-uniform load.

  • time (int) – The moment the load is laid down [days]. If time is set to -1 days, the load is considered an initial load.

  • end_time (int) – The moment the load is removed (only in the case of temporary loads) [days].

  • temporary (bool) – Bool which indicates if the load is a temporary load.

  • gamma_dry (float) – Total unit weight above phreatic level [kN/m3].

  • gamma_wet (float) – Total unit weight below phreatic level [kN/m3].

Return type:

_NonUniformLoad

create_pl_line(points, is_phreatic=False)

Create a piezometric level line (pl-line) from the given points.

Parameters:

  • points (List[_Point]) – list of points that define the pl-line

  • is_phreatic (bool) – whether to set the current pl-line as the phreatic line (overwrites previous!)

Return type:

_PlLine

Returns:

pl-line

Raises:

ModelError –

  • if ‘points’ contains duplicates

  • if start and end ‘points’ are not on the left and right boundary limit respectively

  • if ‘points’ are not in ascending X-direction

  • if ‘is_phreatic’ is True but was already set before

create_point(x, y)

Create a point with given x and y coordinates.

Parameters:

  • x (float) – in [m]

  • y (float) – in [m]

Return type:

_Point

Returns:

_Point which can be used to create boundaries for layers or pl-lines.

create_vertical(x)

Create vertical based on x-coordinate.

Parameters:

x (float) – [m]

Raises:

ModelError – if x < left boundary limit or > right boundary limit

Return type:

_Vertical

OutputFileParser​

class viktor.external.dsettlement.OutputFileParser(sld_file)

Helper class to extract results from a D-Settlement output file (.sld).

Example usage:

parser = OutputFileParser(sld_file)
vertical_results = parser.vertical_results
residual_times = parser.residual_times
property raw_results: str

Raw result data. For convenience, specific data can also be extracted using available methods.

property residual_times: Dict[int, Dict[str, List[float]]]

Returns the residual times.

Structure of dictionary:

{
    vertical number: int: {

        Time: List[float]
        Settlement: List[float]
        ...
    }
}
property vertical_results: Dict[int, Dict[str, Any]]

Returns results for all verticals.

Structure of dictionary:

{
    vertical number: int: {

        coordinates: {
            x: float
            z: float
        },

        time_settlement_per_load: {
            time_step_count: int
            load_step_count: int
            time: List[float] [days]
            load_1: List[float] [kPa]
            load_2: List[float] [kPa]
            ... (depending on model)
        },

        depths: List[float]
        leakages: List[float] -> empty for some models
        drained_layers: List[float] -> empty for some models

        stresses: { -> empty for some models
            initial_total_stress: List[float]
            ... (depending on model)
        },

        vertical_data: {
            time: float: {
                settlement: List[float]
                ... (depending on model)
            }
        },
    }
}

VerticalDrain​

class viktor.external.dsettlement.VerticalDrain(drain_type, range_from, range_to, bottom_position, center_to_center, width_diameter, thickness=None, position_drain=None, grid=None, start_of_drainage=None, phreatic_level_in_drain=None, schedule=None)

Data-class for setting vertical drain options.

Parameters:

  • drain_type (DrainType) – drain type.

  • range_from (float) – range [m] from which drainage takes place.

  • range_to (float) – range [m] to which drainage takes place.

  • bottom_position (float) – position of bottom (depth) of drains [m].

  • center_to_center (float) – center-to-center distance of drains [m].

  • width_diameter (float) – width (or diameter for drain_type = COLUMN) of drains [m].

  • thickness (float) – thickness of strip [m]. Must be set for drain_type = STRIP.

  • position_drain (float) – drain position [m]. Must be set for drain_type = SAND_WALL (only if schedule is defined).

  • grid (DrainGrid) – drain grid type. Must be set for drain_type = STRIP | COLUMN.

  • start_of_drainage (float) – start time of drainage [days]. Must be set for simple and no schedule.

  • phreatic_level_in_drain (float) – phreatic level in drain [m]. Must be set for simple and no schedule.

  • schedule (Union[DrainageSimpleMode, List[Tuple[float, float, float]]]) – DrainageSimpleMode for simple schedule; list of (time [days], underpressure [kPa], water head [m] (if drain_type = STRIP | COLUMN) / tube pressure [kPa] (if drain_type = SAND_WALL)) for detailed schedule (default: no schedule).

property position_drain: float | None