Data tree

The following sections break down the data tree into manageable components, offering insights into their roles, parameters, and practical application.

Execution Settings

This section defines the basic computational settings for the simulation.

Number of Threads

Specifies the number of CPU threads to be used for the simulation. Increasing this value can enhance performance for larger models but may lead to diminishing returns depending on the hardware configuration.

Dimensions and Units

This section defines the spatial and dimensional settings for the model

Problem Dimensions

The selection of the problem dimension depends on the geometry and physics of the problem.

2D (Plane-Strain): Used for problems that assume deformation occurs in a plane.

2D Axisymmetric:Suitable for problems with rotational symmetry around a central axis, such as cylindrical soil layers or tunnel excavations. This option significantly reduces computational costs while maintaining accuracy for symmetric problems.

3D:Used for fully three-dimensional problems, offering the most accurate representation of geometry and loads but requiring more computational resources.

Units

Allows users to define consistent physical units for parameters such as length, force, and time. The default units are kilonewtons (kN), meters (m), and seconds (sec). Ensures that all input values conform to the selected units, preventing calculation errors.

Assign element type

Element types determine how geometry and physics are discretized. Examples include linear/quadratic quadrilaterals (u4-solid), 3D bricks (u8-solid-3D), and multi-phase elements (e.g., u-p). Please refer to element types for more details.

Integration

Options include Full or Reduced integration:

Full: Ensures higher accuracy and is suitable for general use.

Reduced: Avoids locking issues but may require stabilization.

Assign the element type to either:

Surfaces for 2D geometry
Volumes for 3D geometry

Materials

The Materials section defines the physical and mechanical properties necessary for simulations.

Number of Phases

The material behaviour depends on the number of phases present:

1: Solid-only simulations.
2: Solid-fluid interaction (e.g., fully saturated soil).
3: Solid-air-water interaction (e.g., unsaturated soil).

Note that the number of active phases affects some of the subsequent commands. For more details please click here

Density

Defines the density for each phase:

Phase 1: Density of Soild phase.
Phase 2: Density of Fluid phase (e.g., water).
Phase 3: Density of Second fluid phase (e.g., air).

Kindly make sure that all input values use consistent units (e.g. \(g/cm^3\)). For more details, click here

Stress-Strain Models

The Stress-Strain section defines the material's constitutive behaviour under mechanical loading. Various models are available, each suited to different material behaviours and loading conditions. This section outlines the available options:

Linear Elasticity
HCA Linear Elasticity
Mohr-Coulomb
Mohr-Coulomb-2
Hypoplastic+IGS
HCA-Hypoplasticity
Hypo-ISA
HCA Hypo-ISA
SANISAND
HCA-SANISAND
Modified-Cam-Clay
Barotropic Elasticity
Matsuoka-Nakai
AVHP (Anisotropic Visco-Hypoplasticity)

Reducible Strength

The Reducible Strength parameter is used to model materials whose strength diminishes with progressive deformation, a behaviour commonly seen in brittle materials or soils undergoing strain-softening. By default, reducible strength is disabled. When enabled, this feature allows the material's strength, such as cohesion or internal friction angle, to decrease as a function of deformation or plastic strain. For more information, refer to the detailed description of reducible strength

Rayleigh damping

Rayleigh damping is used to simulate energy dissipation in dynamic or transient simulations, helping to stabilize vibratory responses. When enabled, it incorporates mass damping and stiffness damping coefficients, which control the dissipation of kinetic and strain energy, respectively. This is particularly beneficial in preventing unrealistic oscillations in dynamic analyses. By default, Rayleigh damping is disabled but can be activated as needed. Users should carefully calibrate the damping coefficients (𝛼 for mass damping and 𝛽 for stiffness damping) to ensure that the damping behaviour aligns with the physical characteristics of the material and the simulation's objectives. Proper tuning of these parameters ensures realistic and stable results in simulations involving dynamic loading. For more information please click here

Stabilization Parameters

Additional controls for numerical stabilization and improved simulation accuracy. These include:

Minimum Pressure: This parameter prevents unrealistic negative pressures in numerical calculations. It can be activated or adjusted by specifying a threshold value. It is particularly useful for materials that are prone to tensile instability, ensuring that the simulation remains physically realistic. For more information please click here
Mechanical Viscosity: This introduces numerical damping to stabilize simulations involving high strain rates. For more information please click here
Phantom Elasticity: This feature adds artificial elasticity to stabilize poorly constrained simulations. It should be enabled only when necessary, as it can potentially reduce the accuracy of the simulation results. Use this option judiciously for situations where other stabilization measures are insufficient. For more information please click here
Hourglass Stiffness: This parameter is critical for stabilizing under-integrated elements by counteracting zero-energy deformation modes. It is particularly useful when working with reduced-integration elements, as it helps avoid spurious deformations. Users can enable this feature and adjust the stiffness value as required to ensure stability and accuracy. For more information please click here

Permeability

Permeability defines the ease with which a fluid can flow through a porous medium. Users can configure this property to simulate various fluid flow conditions in geotechnical applications.

This option is applicable only when the number of phases is set to 2 (solid-fluid interaction) or 3 (solid-air-water interaction). Ensure that the phase setting in the material definition aligns with this requirement.

Model

Isotropic: Assumes uniform permeability in all directions, commonly used for homogeneous materials.
Kozeny-Carman: Implements the Kozeny-Carman equation, suitable for materials where permeability is a function of porosity and grain characteristics.

Value Specify the permeability value

Bulk Modulus of fluid phases

The Bulk Modulus of Fluid Phases defines the compressibility of the fluid phases in multi-phase systems. This parameter is essential for accurately simulating the behaviour of fluids under pressure changes, especially in saturated or partially saturated conditions. Please refer to Bulk modulus for more information. This option is applicable only when the number of phases is set to 2 (solid-fluid interaction) or 3 (solid-air-water interaction). Ensure that the phase setting in the material definition aligns with this requirement.

Dynamic viscosity of fluid phases

The Dynamic Viscosity parameter defines the resistance of fluid phases to flow, a critical property for simulating fluid behaviour. Please refer to Bulk modulus for more information. This option is applicable only when the number of phases is set to 2 (solid-fluid interaction) or 3 (solid-air-water interaction). Ensure that the phase setting in the material definition aligns with this requirement.

Saturation-Suction

Saturation-Suction defines the relationship between the degree of saturation (\(S_w\)) and matric suction (\(\varphi\)) in porous materials. This property is essential for modeling unsaturated soils in geotechnical applications where the interaction between air, water, and the solid skeleton is critical. Please click here for more information. This option is applicable only when the number of phases is set to 3 (solid-air-water interaction). Ensure that the phase setting in the material definition aligns with this requirement.

Model

Van Genuchten: Commonly used for fine-grained soils, offering flexibility in describing the soil-water retention curve.
Brooks & Corey: Best for coarse-grained soils and soils with well-defined air entry values.

Permeability-Saturation

Permeability-Saturation defines the relationship between the degree of saturation and the relative permeability of a porous medium. This property is crucial for modeling unsaturated soils in geotechnical applications, where the fluid flow depends on the saturation level. Please click here for more information.

This option is applicable only when the number of phases is set to 3 (solid-air-water interaction). Ensure that the phase setting in the material definition aligns with this requirement.

Model

Van Genuchten: Commonly used for fine-grained soils, offering flexibility in describing the soil-water retention curve.
Brooks & Corey: Best for coarse-grained soils and soils with well-defined air entry values.

Bishop Effective Stress

The Bishop Effective Stress parameter is used to define the effective stress in unsaturated soils by incorporating the effects of matric suction and saturation. Please click here for more information.

This option is applicable only when the number of phases is set to 3 (solid-air-water interaction). Ensure the phase setting aligns with this requirement.

Model

Saturation:
Crude-Switch:
Liakos:

Assign Material

The Assign Material feature allows users to link predefined materials to specific geometric entities in the model, such as surfaces or volumes. While materials are defined in the Materials section. Ensure that the correct material is assigned to the appropriate selection (surfaces or volumes). Incorrect assignments may lead to inaccurate simulation results.

Material Selection Users can choose a material from the list of predefined materials in the dropdown menu. These materials are created and configured in the Materials section, including properties such as density, stress-strain behavior, and phase interaction. Ensure that the selected material aligns with the physical properties required for the specific surface or volume.

How to Use

Select the material from the Material dropdown list.
Choose whether to assign it to Surfaces or Volumes.
(Optional) Specify a group for better organization.
Click Select to pick the target geometry in the model.
Confirm the assignment by clicking OK.

Contact

Contact settings define surface interactions in simulations, crucial for modeling friction, separation, and penetration. Please click here for more information . By default, Contact Required is set to No and must be enabled for defining contact behaviors. Once enabled:

Master and Slave Surfaces: Assign the stiffer or larger body as the master, and the softer or smaller body as the slave for numerical stability.

Normal Contact: Governs interactions in the normal direction using methods like the penalty approach. Options include:

Separation: Allows or restricts surfaces from separating.
Penalty Stiffness: Defines the stiffness parameter for penetration.

Tangential Contact: Controls friction behavior with three models available:

Frictionless: Assumes no resistance in the tangential direction.
Mohr-Coulomb (MC): Models tangential resistance using coefficients like tan δ and cohesion (default: 0 kN/m²).
Hypoplastic: Advanced model for complex geotechnical applications.

Contact Options: Include settings for clearance, displacement checks, and distance validations, offering enhanced accuracy and control.

Amplitude

Amplitude settings define the variation of applied loads, body forces or boundary conditions over time. They are critical for simulations involving static, dynamic or transient analyses, allowing users to specify how forces, displacements, or other parameters change during the simulation. Please click here for more information.

Amplitude Types

Ramp

Linearly increases or decreases the load over time.
Suitable for gradual load applications to avoid sudden impacts.

Rising Sin

Represents a sine wave that rises in amplitude.
Commonly used in dynamic simulations where smooth oscillatory loading is required.

Rising Cos

Represents a cosine wave with increasing amplitude.
Similar applications as Rising Sin but starts from a maximum value.

Periodic

Creates a cyclic, repeating amplitude pattern.
Useful for simulations involving cyclic loading or vibrations.

Equally Spaced

Defines amplitude based on equally spaced time intervals.
Provides flexibility for custom non-linear variations.

Tabular

Allows users to input custom amplitude values directly in a table format.
Ideal for simulations with complex, non-standard amplitude variations.

User Defined

Enables users to programmatically define amplitude using a script.

How to Configure Amplitude

Select the Amplitude option from the tree.
Choose the desired amplitude type from the dropdown menu.
Configure parameters as needed (e.g., intervals for equally spaced or values for tabular).
Once defined, the amplitude is saved for later use and can be assigned to loads or boundary conditions during their configuration, ensuring consistent and accurate application throughout the simulation.

Initial conditions

Initial conditions establish the starting state of various parameters in a simulation, such as stress, pressure, and material state. These conditions are essential for setting a realistic baseline for simulations, especially in geotechnical analyses. Please click here The following initial conditions are available:

Initial Void Ratio (\(e\))

Represents the initial void ratio, which is the ratio of void volume to solid volume in the material.
Critical for defining the initial state of soil or granular materials.

Initial Stress (\(\sigma\))

Specifies the pre-existing stress state within the model. Please click here for more information.
Used to simulate in-situ stresses, such as those caused by gravity or overburden pressure.

Pore Water Pressure (\(p_w\))

Defines the initial pore water pressure of the material.
Essential for models involving saturated or partially saturated conditions, such as groundwater or seepage simulations.

Pore Air Pressure (\(p_a\))

Sets the initial pore air pressure.
Applicable in unsaturated soil models where air occupies part of the pore volume.

State Variables (SV)

Initializes material-specific state variables required by advanced constitutive models.
Examples include plastic strain, damage parameters, or internal variables for hypoplasticity.

Contact

Contact defines the initial interaction parameters between surfaces in the model. Proper configuration of contact ensures that surfaces interact realistically during the simulation, reflecting physical behaviors such as friction, separation, and penetration.

How to Configure Initial Conditions

Select Initial Condition Type: - Choose from the available options: Void Ratio, Stress, Pore Water Pressure, Pore Air Pressure, or State Variables.

Define Parameters: - Input the required values specific to the chosen initial condition:

Void Ratio: Specify the initial value for void space.
Stress: Define the stress tensor components.
Pore Pressures: Input the water or air pressure values for relevant regions.
State Variables: Set custom variable values as required by the material model.

Assign to Geometry: - Link the defined initial conditions to specific geometry, elements or nodes in the model.

Steps

The Steps section defines the stages of a simulation and controls the analysis process, including time integration, solution settings, boundary conditions, and output configurations. Each step represents a phase in the simulation where specific loads, boundary conditions, and analysis settings are applied.

Step Configuration

Active: Indicates if the step is active for the simulation. By default, the first step is set to Yes.

Analysis Type: Select the type of analysis:

Static: Time-independent simulations.
Geostatic: Establishes initial stress due to self-weight.
Transient: Time-dependent simulations.
Dynamic: Simulates inertia and damping effects.
Reduction: Gradually reduces material strength to failure.

Updated Lagrangian:

Set to Yes if large deformation is expected. Default is No for small deformation.

Solution Settings

Controls numerical solver parameters (e.g., tolerance values, iteration limits) to ensure accuracy and convergence during analysis.

Linear Solver

Specifies the solver used to solve the system of equations.
Default: Pardiso (recommended for large and complex models).

Extrapolation

Controls the extrapolation of the solution between increments.
Default: Extrapolation: Default (can be adjusted based on the problem type).

Maximum Number of Increments

Sets the maximum number of increments allowed for the solution to progress.
Default: 1e4 (10,000 increments).

Maximum and Minimum Number of Iterations

Maximum Number of Iterations: Limits the number of iterations for each increment to ensure convergence.
Default: 32 iterations.
Minimum Number of Iterations: Ensures the solver performs at least a set number of iterations before convergence is checked.
Default: 1 iteration.

Controls Controls allow users to monitor and adjust specific parameters during the solution process.

Displacement:
Monitors the displacement convergence during the simulation.
Status: Set to Default but can be customized based on convergence criteria.
Pore Water Pressure:
Monitors the convergence of pore water pressure in simulations involving fluid phases.
Status: Set to Default but can be adjusted for specific hydraulic problems.

Line Search The Line Search method is used to improve convergence in non-linear problems.

Method: Can be set to Active or Deactive.
Deactive: The default setting.
Active: Useful for problems with high non-linearity to stabilize convergence.

Time Integration

Relevant for transient and dynamic simulations to control time progression.
Initial Time Step Specifies the time increment for the initial step.
Default: 0.01 s. Step Time (Total) Sets the total duration of the simulation step.
Default: 1 s. Minimum Time Step Defines the smallest allowable time step to ensure stability.
Default: 0.001 s. Maximum Time Step Defines the largest allowable time step to maintain efficiency.
Default: 0.1 s.

Proper time integration ensures that the simulation progresses smoothly without instability or excessive computational time.

Factor of Safety

Used to calculate the stability of the structure or material under various loads.
Essential for geotechnical problems like slope stability analysis.

Reset

The Reset option allows users to reset the step to its initial state.

Options Available for Reset:

Reset: Set to Yes to enable the reset feature.
Displacement: Resets displacement values to their initial state. Default is No.
Strain: Resets strain values. Default is No.
Stress: Resets stress values. Default is No.
Void Ratio: Resets the void ratio values. Default is No.

The reset option is useful for restarting simulations from a clean initial state or applying different load conditions in subsequent steps.

Reaction Forces (RF)

The Reaction Forces option calculates and outputs reaction forces at specified points to verify boundary condition accuracy and ensure equilibrium.

Options for Reaction Forces:

Save Reaction Forces: Saves the calculated reaction forces for use in subsequent steps.
Use Saved Reaction Forces: Utilizes previously saved reaction forces in the current step.

Dirichlet Boundary Conditions

The Dirichlet Boundary Conditions control fixed variables at the boundaries of the model.

Types of Dirichlet Boundary Conditions:

Solid Displacement: Fixes displacement values at the boundary.
Pore Water Pressure: Fixes pore water pressure values.
Pore Air Pressure: Fixes air pressure values in unsaturated soils.
Water Displacement: Controls the movement of water at the boundary.
User Boundary: Allows users to define custom boundary conditions as needed.

Proper boundary condition setup is crucial to ensure the simulation behaves as expected under applied loads and constraints.

Constraints

The Constraints section defines relationships between different degrees of freedom in the model.

Equal Degree of Freedom

Enforces equal displacements or rotations between different nodes.
Used to apply symmetry or coupling conditions in the model.

Neumann Boundary Conditions

The Neumann Boundary Conditions section specifies loads or fluxes applied to the model boundaries.

Types of Neumann Boundary Conditions:

Gravity: Applies gravitational acceleration to the entire model.
Point Load: Applies a concentrated load at a specific point.
Distributed Load: Applies a load distributed over a surface or edge.
Pressure: Applies pressure on surfaces.
Water Pressure: Defines fluid pressure in geotechnical models.
Drainage: Sets boundary conditions for fluid drainage.
Compliant Base: Used to simulate flexible or elastic boundary supports.

Outputs

The Outputs section specifies what results will be saved or displayed at the end of each simulation step.

Field Output Specifies field variables (e.g., displacements, stresses) to be saved during the simulation.

Frequency: Determines how often the output is saved. Default is 1.
Format: Specifies the file format for the output. Common format is VTK.
Node Output: Saves field variables at nodes.
Element Output: Saves field variables at elements.

Print Output Specifies what variables will be printed in the output files.

Frequency: Determines how often the output is printed. Default is 1.
Print Node Output: Prints node-specific results (e.g., displacements, forces).
Element Output: Prints element-specific results (e.g., stresses, strains).
Integration Points: Prints values at the integration points within each element.