stem.solver module

class stem.solver.Amgcl(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000, krylov_type: str = 'cg', smoother_type: str = 'ilu0', preconditioner_type: str = 'amg', coarsening_type: str = 'aggregation')

Bases: LinearSolverSettingsABC

Class containing information about the Algebraic multigrid iterative linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

  • krylov_type (str): type of the Krylov solver. Default value is “cg”, other options are “gmres” and “bicgstab”.

  • smoother_type (str): type of the smoother. Default value is “ilu0”, other options are “spai0”, “spai1”, “ilut”, “iluk”, “damped_jacobi”, “gauss_seidel” and “chebyshev”

  • preconditioner_type (str): type of the preconditioner. Default value is “amg”, other options are “relaxation” and “none”

  • coarsening_type (str): type of the coarsening. Default value is “aggregation”, other options are

    “ruge_stuben”,”smoothed_aggregation” and “smoothed_aggr_emin”

coarsening_type: str = 'aggregation'
krylov_type: str = 'cg'
max_iteration: int = 1000
preconditioner_type: str = 'amg'
scaling: bool = False
smoother_type: str = 'ilu0'
property solver_type

Property that returns the solver type name of the amgcl iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
class stem.solver.AnalysisType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the analysis type

Attributes:

  • MECHANICAL_GROUNDWATER_FLOW (int): coupled mechanical and groundwater flow analysis

  • MECHANICAL (int): mechanical analysis

  • GROUNDWATER_FLOW (int): groundwater flow analysis

GROUNDWATER_FLOW = 3
MECHANICAL = 2
MECHANICAL_GROUNDWATER_FLOW = 1
class stem.solver.ArcLengthStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, desired_iterations: int = 10, max_radius_factor: float = 1.0, min_radius_factor: float = 0.1)

Bases: StrategyTypeABC

Class containing information about the arc length strategy

Inheritance:
Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • desired_iterations (int): This is used to calculate the radius of the next step. Default value is 10.

  • max_radius_factor (float): maximum radius factor of the arc. Default value is 1.0.

  • min_radius_factor (float): minimum radius factor of the arc. Default value is 0.1.

desired_iterations: int = 10
max_iterations: int = 15
max_radius_factor: float = 1.0
min_iterations: int = 6
min_radius_factor: float = 0.1
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the arc length strategy

Returns:

  • str: strategy type name

class stem.solver.BackwardEulerScheme

Bases: SchemeABC

Class containing information about the backward Euler scheme

Inheritance:
property scheme_type

Property for returning the type of the backward Euler scheme

Returns:

  • str: The type of the backward Euler scheme

class stem.solver.Cg(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000, preconditioner_type: str = 'diagonal')

Bases: LinearSolverSettingsABC

Class containing information about the conjugate gradient iterative linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

  • preconditioner_type (str): type of the preconditioner. Default value is “diagonal”, other options are “ilu0” and “none”.

max_iteration: int = 1000
preconditioner_type: str = 'diagonal'
scaling: bool = False
property solver_type

Property that returns the solver type name of the conjugate gradient iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
validate_settings()

Validates the cg linear solver settings

Raises:

  • ValueError: if the preconditioner type is not valid

class stem.solver.ConvergenceCriteriaABC

Bases: ABC

Abstract class for the convergence criteria

abstract property convergence_criterion

Abstract property for returning the type of the convergence criterion

Raises:

  • Exception: abstract class of convergence criteria is called

class stem.solver.DisplacementAndWaterPressureConvergenceCriteria(displacement_relative_tolerance: float = 0.0001, displacement_absolute_tolerance: float = 1e-09, water_pressure_relative_tolerance: float = 0.0001, water_pressure_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the displacement and water pressure convergence criteria

Inheritance:
Attributes:

  • displacement_relative_tolerance (float): The relative tolerance for the displacement. Default value is 1e-4.

  • displacement_absolute_tolerance (float): The absolute tolerance for the displacement. Default values is 1e-9.

  • water_pressure_relative_tolerance (float): The relative tolerance for the water pressure. Default value is 1e-4.

  • water_pressure_absolute_tolerance (float): The absolute tolerance for the water pressure. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the displacement and water pressure convergence criterion

Returns:

  • str: The type of the displacement and water pressure convergence criterion

displacement_absolute_tolerance: float = 1e-09
displacement_relative_tolerance: float = 0.0001
water_pressure_absolute_tolerance: float = 1e-09
water_pressure_relative_tolerance: float = 0.0001
class stem.solver.DisplacementConvergenceCriteria(displacement_relative_tolerance: float = 0.0001, displacement_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the displacement convergence criteria

Inheritance:
Attributes:

  • displacement_relative_tolerance (float): The relative tolerance for the displacement. Default value is 1e-4.

  • displacement_absolute_tolerance (float): The absolute tolerance for the displacement. Default values is 1e-9.

property convergence_criterion

Property for returning the type of the displacement convergence criterion

Returns:

  • str: The type of the displacement convergence criterion

displacement_absolute_tolerance: float = 1e-09
displacement_relative_tolerance: float = 0.0001
class stem.solver.LineSearchStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, max_line_search_iterations: int = 10, first_alpha_value: float = 1.0, second_alpha_value: float = 0.5, min_alpha: float = 0.0001, max_alpha: float = 10000.0, line_search_tolerance: float = 0.0001, echo_level: int = 0)

Bases: StrategyTypeABC

Class containing information about the line search strategy

Inheritance:
Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • max_line_search_iterations (int): maximum number of line search iterations. Default value is 10.

  • first_alpha_value (float): first alpha guess value used for the first iteration. Default value is 1.0.

  • second_alpha_value (float): second alpha guess value used for the first iteration. Default value is 0.5.

  • min_alpha (float): minimum possible alpha value at the end of the algorithm. Default value is 1e-4.

  • max_alpha (float): maximum possible alpha value at the end of the algorithm. Default value is 1e4.

  • line_search_tolerance (float): Tolerance of the line search algorithm, defined as the ratio between maximum residual*alpha*dx and current iteration residual*alpha*dx. Default value is 1e-4.

  • echo_level (int): echo level. Default value is 0.

echo_level: int = 0
first_alpha_value: float = 1.0
line_search_tolerance: float = 0.0001
max_alpha: float = 10000.0
max_iterations: int = 15
max_line_search_iterations: int = 10
min_alpha: float = 0.0001
min_iterations: int = 6
number_cycles: int = 100
second_alpha_value: float = 0.5
property strategy_type: str

Returns the strategy type name of the line search strategy

Returns:

  • str: strategy type name

class stem.solver.LinearNewtonRaphsonStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, initialize_acceleration: bool = False)

Bases: StrategyTypeABC

Class containing information about the Newton-Raphson strategy for linear systems

Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • initialize_acceleration (bool): if true, the acceleration is re-calculated at the beginning of the stage. Default value is False. This is important for a changing external force at stage transition in dynamic

    analysis. However, the model needs a displacement constraint in each direction, i.e. absorbing boundaries can not be used for all directions.

Inheritance:
initialize_acceleration: bool = False
max_iterations: int = 15
min_iterations: int = 6
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the Linear Newton-Raphson strategy

Returns:

  • str: strategy type name

class stem.solver.LinearSolverSettingsABC

Bases: ABC

Class containing information about the linear solver settings

abstract property solver_type

Abstract property for returning the solver type

Raises:

  • Exception: abstract class of linear solver settings is called

validate_settings()

Validates the linear solver settings, can be overridden in child classes

class stem.solver.Lu(scaling: bool = False)

Bases: LinearSolverSettingsABC

Class containing information about the LU decomposition direct linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

scaling: bool = False
property solver_type

Property that returns the solver type name of the LU decomposition direct linear solver settings

Returns:

  • str: solver type name

class stem.solver.NewmarkScheme(newmark_beta: float = 0.25, newmark_gamma: float = 0.5, newmark_theta: float = 0.5)

Bases: SchemeABC

Class containing information about the Newmark scheme

Inheritance:
Attributes:

  • newmark_beta (float): The beta parameter of the Newmark scheme. Default value is 0.25.

  • newmark_gamma (float): The gamma parameter of the Newmark scheme. Default value is 0.5.

  • newmark_theta (float): The theta parameter of the Newmark scheme, which is used for water pressure. Default value is 0.5.

newmark_beta: float = 0.25
newmark_gamma: float = 0.5
newmark_theta: float = 0.5
property scheme_type

Property for returning the type of the Newmark scheme

Returns:

  • str: The type of the newmark scheme

class stem.solver.NewtonRaphsonStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100)

Bases: StrategyTypeABC

Class containing information about the Newton-Raphson strategy

Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

Inheritance:
max_iterations: int = 15
min_iterations: int = 6
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the Newton-Raphson strategy

Returns:

  • str: strategy type name

class stem.solver.Problem(problem_name: str, number_of_threads: int, settings: SolverSettings)

Bases: object

Class containing information about the problem settings and the solver settings

Attributes:

  • problem_name (str): name of the problem

  • number_of_threads (int): number of threads used for the analysis

  • settings (SolverSettings): dictionary containing the solver settings

number_of_threads: int
problem_name: str
settings: SolverSettings
class stem.solver.ResidualConvergenceCriteria(residual_relative_tolerance: float = 0.0001, residual_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the residual convergence criteria

Inheritance:
Attributes:

  • residual_relative_tolerance (float): The relative tolerance for the residual. Default value is 1e-4.

  • residual_absolute_tolerance (float): The absolute tolerance for the residual. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the residual convergence criterion

Returns:

  • str: The type of the residual convergence criterion

residual_absolute_tolerance: float = 1e-09
residual_relative_tolerance: float = 0.0001
class stem.solver.SchemeABC

Bases: ABC

Abstract class for the scheme

abstract property scheme_type

Abstract property for returning the type of the scheme

Raises:

  • Exception: abstract class of scheme is called

class stem.solver.SolutionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the solution types

Attributes:

  • QUASI_STATIC (int): quasi-static solution type

  • DYNAMIC (int): dynamic solution type

DYNAMIC = 2
QUASI_STATIC = 1
class stem.solver.SolverSettings(analysis_type: ~stem.solver.AnalysisType, solution_type: ~stem.solver.SolutionType, stress_initialisation_type: ~stem.solver.StressInitialisationType, time_integration: ~stem.solver.TimeIntegration, is_stiffness_matrix_constant: bool, are_mass_and_damping_constant: bool, convergence_criteria: ~stem.solver.ConvergenceCriteriaABC, reset_displacements: bool = False, calculate_stresses_on_nodes: bool = True, strategy_type: ~stem.solver.StrategyTypeABC = <factory>, scheme: ~stem.solver.SchemeABC = <factory>, linear_solver_settings: ~stem.solver.LinearSolverSettingsABC = <factory>, rayleigh_m: float | None = None, rayleigh_k: float | None = None, echo_level: int = 1, _inititalize_acceleration: bool = False)

Bases: object

Class containing information about the time integration, builder, strategy, scheme and linear solver.

Attributes:

  • solution_type (SolutionType): solution type, QUASI_STATIC or DYNAMIC

  • stress_initialisation_type (StressInitialisationType): stress initialisation type, NONE, GRAVITY_LOADING OR K0_PROCEDURE

  • time_integration (TimeIntegration): time integration settings

  • is_stiffness_matrix_constant (bool): if true, the lhs matrix is only built once, else, the lhs matrix is rebuilt at each non-linear iteration

  • are_mass_and_damping_constant (bool): if true, the mass and damping matrices are prebuilt and directly used to calculate the rhs. If false, the mass and damping matrices are built at each non-linear iteration for calculating the rhs and possibly the lhs

  • convergence_criteria (ConvergenceCriteriaABC): convergence criteria, DisplacementConvergenceCriteria, ResidualConvergenceCriteria, WaterPressureConvergenceCriteria or DisplacementAndWaterPressureConvergenceCriteria

  • reset_displacements (bool): if true, the displacements are reset at the beginning of the phase

  • calculate_stresses_on_nodes (bool): if true, the stresses are also calculated on the nodes and not only on the gauss points. Default value is True.

  • strategy_type (StrategyTypeABC): strategy type, NewtonRaphsonStrategy, LineSearchStrategy or ArcLengthStrategy. Default value is NewtonRaphsonStrategy.

  • scheme (SchemeABC): scheme, NewmarkScheme or BackwardEulerScheme. Default value is NewmarkScheme.

  • linear_solver_settings (LinearSolverSettingsABC): linear solver settings, Amgcl Cg, Lu. Default value is Amgcl.

  • rayleigh_m (Optional[float]): mass proportional damping parameter

  • rayleigh_k (Optional[float]): stiffness proportional damping parameter

  • echo_level (int): echo level. Default value is 1. If 0, only time information is printed. If 1, time information and convergence information are printed. If 2, time information, convergence information, intermediate rhs results and linear solver settings are printed.

  • _inititalize_acceleration (bool): if true, the acceleration is initialized at the beginning of the stage, this value should not be changed by the user.

analysis_type: AnalysisType
are_mass_and_damping_constant: bool
calculate_stresses_on_nodes: bool = True
convergence_criteria: ConvergenceCriteriaABC
echo_level: int = 1
is_stiffness_matrix_constant: bool
linear_solver_settings: LinearSolverSettingsABC
rayleigh_k: float | None = None
rayleigh_m: float | None = None
reset_displacements: bool = False
scheme: SchemeABC
solution_type: SolutionType
strategy_type: StrategyTypeABC
stress_initialisation_type: StressInitialisationType
time_integration: TimeIntegration
validate_settings()

Validates all solver settings

class stem.solver.SparseCg(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000)

Bases: LinearSolverSettingsABC

Class containing information about the Eigen library implementation of conjugate gradient iterative linear solver settings. Compared to the Cg class, this class uses the Eigen library’s conjugate gradient solver, which is optimized for sparse matrices and can be more efficient for large systems.

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

max_iteration: int = 1000
scaling: bool = False
property solver_type

Property that returns the solver type name of the Eigen library implementation of conjugate gradient iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
class stem.solver.StaticScheme

Bases: SchemeABC

Class containing information about the static scheme

Inheritance:
property scheme_type: str

Property for returning the type of the static scheme

Returns:

  • str: The type of the static scheme

class stem.solver.StrategyTypeABC

Bases: ABC

Abstract class for the strategy type

abstract property strategy_type: str

Abstract property for returning the type of the strategy

Raises:

  • Exception: abstract class of strategy type is called

class stem.solver.StressInitialisationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the stress initialisation types

Attributes:

  • NONE (int): no stress initialisation

  • GRAVITY_LOADING (int): gravity loading stress initialisation

  • K0_PROCEDURE (int): K0-procedure stress initialisation

GRAVITY_LOADING = 2
K0_PROCEDURE = 3
NONE = 1
class stem.solver.TimeIntegration(start_time: float, end_time: float, delta_time: float, reduction_factor: float, increase_factor: float, max_delta_time_factor: float = 1000)

Bases: object

Class containing information about the time integration

Attributes:

  • start_time (float): start time of the analysis

  • end_time (float): end time of the analysis

  • delta_time (float): initial time step

  • reduction_factor (float): factor used to reduce the time step when the solution diverges

  • increase_factor (float): factor used to increase the time step when the solution converges within the minimum number of iterations

  • max_delta_time_factor (float): maximum time step factor, used to limit the time step increase. Default value is 1000.

delta_time: float
end_time: float
increase_factor: float
max_delta_time_factor: float = 1000
reduction_factor: float
start_time: float
class stem.solver.WaterPressureConvergenceCriteria(water_pressure_relative_tolerance: float = 0.0001, water_pressure_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the water pressure convergence criteria

Inheritance:
Attributes:

  • water_pressure_relative_tolerance (float): The relative tolerance for the water pressure. Default value is 1e-4.

  • water_pressure_absolute_tolerance (float): The absolute tolerance for the water pressure. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the water pressure convergence criterion

Returns:

  • str: The type of the water pressure convergence criterion

water_pressure_absolute_tolerance: float = 1e-09
water_pressure_relative_tolerance: float = 0.0001