Calculation Options

The following options are available to control the calculation of the micromechanical models. These options can be set and get with Model[option_name] = value, Model.option_name = value, Model[option_name], and Model.option_name, respectively. ModelBase.setCalculationOptions and ModelBase.calculationOptions can also be used to set and get the multiple options.

Integration

npv (1e9)

Number of particles per volume.

radius (0.65e-3)

Particle radius.

integration_type (BazantOh37)

Type of the integration. Possible values are:

• BazantOh{num}: Integration points by Bazant and Oh (1984) with {num}x2 points (num can be 37 or 61).
• FliegeMaier{num}: Integration points by Fliege and Maier (1984) with {num} points (num can be 2^2, 3^2, ..., 30^2 for Python or C++ with MICROMECHANICAL_FULL_INTEGRATION_POINTS=ON, num can only be 2^2, 5^2, 8^2, 12^2, 16^2, 24^2, 30^2 for C++ with MICROMECHANICAL_FULL_INTEGRATION_POINTS=OFF).
• Lebedev{num}: Integration points by Lebedev with {num} points. Please check the source code for possible {num}.

Fabric tensor

fabric_type (chang1990-ext)

Type of the fabric tensor. See Fabric Tensors for more information.

fabric_evolution_type (li2012)

Type of the fabric evolution rule. See Fabric Tensors for more information.

fabric_coefs ({})

Coefficients of the fabric evolution rule. The coefficients are specific to the fabric type and fabric evolution rule.

Elastoplastic model options

elastoplastic_finite_difference_increment (1e-4)

Finite difference increment for numerical derivatives in elastoplastic models.

elastoplastic_finite_difference_central (false)

Whether to use central finite difference for numerical derivatives in elastoplastic models.

elastoplastic_check_stiffness_matrix_positive_definite (false)

Whether to check the positive definiteness of the elastoplastic stiffness matrix.

elastoplastic_check_stiffness_matrix_non_singularity (false)

Whether to check the non-singularity of the elastoplastic stiffness matrix.

elastoplastic_critical_state_line_use_initial_stress_state (false)

Whether to use the initial stress state to calculate critical state line.

elastoplastic_critical_state_line_shape (logarithmic)

Shape of critical state line, linear, logarithmic or exponential.

elastoplastic_critical_state_line_use_anisotropic_mean_stress (false)

Whether to use anisotropic mean stress in critical state line.

elastoplastic_critical_stress_ratio_type (mohr-coulomb)

Method to calculate critical stress ratio, modified-mohr-coulomb, mohr-coulomb, gtheta_li2002, gtheta_sheng2000, or gtheta_argyris1974.

elastoplastic_critical_stress_ratio_use_initial_stress_state (false)

Whether to use the initial stress state to calculate critical stress ratio.

elastoplastic_critical_stress_ratio_use_anisotropic_stress (true)

Whether to use the anisotropic stress tensor to calculate critical stress ratio.

elastoplastic_update_critical_void_ratio_when_required (false)

Whether to update the critical void ratio when required.

elastoplastic_tolerance (1e-7)

Tolerance of yield function for plastic correction.

elastoplastic_max_iterations (100)

Maximum number of iterations for plastic correction.

elastoplastic_check_convergence (true)

Whether to check the convergence for plastic correction.

elastoplastic_ensure_stress_on_yield_surface (false)

Whether to ensure the stress state is on the yield surface.

elastoplastic_min_principal_stress (-1.0)

Minimum principal stress for elastoplastic models, negative value means no limit.

elastoplastic_yield_function_anisotropic_cohesion (false)

Whether the cohesion is anisotropic.

elastoplastic_yield_function_correction_direction (plastic_flow)

Direction for yield function correction, "plastic_flow" for the plastic flow direction or "yield_normal" for the normal direction of the yield surface.

elastoplastic_yield_function_correction_adaptive_ratio (-1.0)

Ratio for adaptive plastic correction, negative values are ignored.

elastoplastic_yield_function_correction_max_const_steps (-1)

Maximum number of constant step size substeps for the plastic correction, non-positive value means no limit.

elastoplastic_yield_function_correction_diverged_steps_raise (true)

Whether to raise an error when the plastic correction is detected as diverged.

elastoplastic_default_yield_function_derivative (false)

Whether to use the default yield function derivative for elastoplastic models.

elastoplastic_yield_function_derivative_strain (true)

Whether to consider the strain contribution to the yield function derivative for elastoplastic models.

elastoplastic_associated_flow_rule (false)

Whether to use associated flow rule for plastic correction.

elastoplastic_default_potential_function_derivative (false)

Whether to use the default potential function derivative for elastoplastic models.

elastoplastic_potential_function_half_shear_derivatives (false)

Whether to use half derivatives of shear components for plastic potential function.

elastoplastic_flow_rule_tolerance (1e-7)

Tolerance of flow_rule for plastic correction, only valid for CPPM method.

elastoplastic_combined_stress_tensor_type (anisotropic)

Type of the combined stress tensor for elastoplastic models, "anisotropic", "isotropic", "linear", "quadratic", "exponential", or "potential".

elastoplastic_combined_stress_tensor_dilatancy_type (anisotropic)

Type of the combined stress tensor in dilatancy for elastoplastic models, "anisotropic", "isotropic", "linear", "quadratic", "exponential", or "potential".

elastoplastic_combined_stress_tensor_fav_ratio (1.0)

Ratio for the fabric anisotropy variable in the combined stress tensor for elastoplastic models.

elastoplastic_combined_stress_tensor_evolution_ratio (1.0)

Ratio for the evolution of the combined stress tensor in elastoplastic models.

elastoplastic_combined_stress_tensor_scale (1.0)

Scale for effect of fabric anisotropy in the combined stress tensor for elastoplastic models.

elastoplastic_fabric_anisotropy_variable_nonproportionality_orthogonal (0.0)

Weight of the orthogonal component of the non-proportionality in the fabric anisotropy variable.

elastoplastic_fabric_anisotropy_variable_nonproportionality_noncoaxial (0.0)

Weight of the non-coaxial component of the non-proportionality in the fabric anisotropy variable.

elastoplastic_substepping_max_plastic_strain (-1.0)

Maximum plastic strain for substepping in plastic correction, negative value means no substepping.

elastoplastic_substepping_max_iterations (100000)

Maximum number of iterations for substepping in plastic correction.

elastoplastic_substepping_initial_step_size (1.0)

Initial step size for substepping in plastic correction.

elastoplastic_substepping_min_step_size (1e-5)

Minimum step size for substepping in plastic correction.

elastoplastic_substepping_max_step_size (1.0)

Maximum step size for substepping in plastic correction.

elastoplastic_substepping_check_min_step_size (true)

Whether to check the minimum step size for substepping in plastic correction.

elastoplastic_substepping_step_size_increase_ratio (2.0)

Step size increase ratio for substepping in plastic correction when the plastic multiplier is less than half of the maximum allowed value.

elastoplastic_substepping_step_size_decrease_ratio (0.5)

Step size decrease ratio for substepping in plastic correction when the step fails.

elastoplastic_runge_kutta_integrate_stress_on_yield_surface_method (bisection)

Method to integrate stress from elastic to the yield surface for Runge-Kutta method, "bisection", "newton" or "none".

elastoplastic_runge_kutta_integrate_stress_on_yield_surface_max_iterations (100)

Maximum number of iterations to integrate stress from elastic to the yield surface for Runge-Kutta method.

elastoplastic_runge_kutta_integrate_stress_on_yield_surface_tolerance (1e-10)

Tolerance to integrate stress from elastic to the yield surface for Runge-Kutta method.

elastoplastic_runge_kutta_order (2)

Order of the Runge-Kutta method for elastoplastic integration, 1, 2, 3, or 4.

elastoplastic_runge_kutta_second_order_alpha (2/3)

Parameter alpha for the second-order Runge-Kutta method in elastoplastic integration. alpha=1/2 corresponds to the midpoint method; alpha=2/3 corresponds to the Ralston method; alpha=1 corresponds to the Heun's method.

elastoplastic_runge_kutta_third_order_alpha (0.5)

Parameter alpha for the third-order Runge-Kutta method in elastoplastic integration.

elastoplastic_runge_kutta_third_order_beta (0.75)

Parameter beta for the third-order Runge-Kutta method in elastoplastic integration.

elastoplastic_runge_kutta_fourth_order_type (classic)

Type of the fourth-order Runge-Kutta method for elastoplastic integration, "classic", "3/8-rule", or "ralston".

elastoplastic_runge_kutta_stiffness_type (weighted)

Type of the elastoplastic stiffness matrix for Runge-Kutta method, "elastic", "elastoplastic", "elastoplastic_end", or "weighted".

elastoplastic_runge_kutta_correction_substep (false)

Whether to perform yield function corrections at each substep of the Runge-Kutta method.

elastoplastic_runge_kutta_max_const_steps (-1)

Maximum number of constant step size substeps for the Runge-Kutta method, non-positive value means no limit.

elastoplastic_runge_kutta_diverged_steps_raise (true)

Whether to raise an error when a Runge-Kutta step is detected as diverged.

elastoplastic_runge_kutta_substepping_tolerance (-1.0)

Tolerance for substepping in Runge-Kutta elastoplastic integration, negative value means no substepping.

elastoplastic_runge_kutta_substepping_max_iterations (100000)

Maximum number of iterations for substepping in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_initial_step_size (1.0)

Initial step size for substepping in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_min_step_size (1e-5)

Minimum step size for substepping in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_max_step_size (1.0)

Maximum step size for substepping in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_check_min_step_size (true)

Whether to check the minimum step size for substepping in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_adaptive_ratio (0.9)

Ratio for adaptive step size control in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_adaptive_max_ratio (1.5)

Maximum step size ratio of adaptive step size control in Runge-Kutta elastoplastic integration.

elastoplastic_runge_kutta_substepping_adaptive_min_ratio (0.25)

Minimum step size ratio of adaptive step size control in Runge-Kutta elastoplastic integration.

Update parameters before the calculation

update_void_ratio_from_after_isotropic_loading_to_before (false)

Update the void ratio from the end of the isotropic loading step to the beginning of the isotropic loading step. This is useful when the void ratio is given at the beginning of the deviatoric loading step, the void ratio should be updated to the beginning of the isotropic loading step.

update_npv (false)

Update the number of particles per volume before the calculation based on the following equation:

\[ \frac{N}{V} = \frac{3(13.28-8e)}{4 \pi r^3 (1+e)} \]

update_fabric_coefs (false)

Update the fabric coefficients \(M_e\) and \(M_c\) for the zhao2020 fabric evolution rule before the calculation based on the following equations:

\[ M_e = \frac{6\sin\phi}{3+\sin\phi}, \quad M_c = \frac{6\sin\phi}{3-\sin\phi} \]

Options to control the framework of the model

kinematic_hypothesis (false)

Whether to use the kinematic hypothesis in the calculation. Compared to the static hypothesis, the kinematic hypothesis localize the macroscopic strain to microscopic displacements.

Warning

The kinematic hypothesis is not tested yet.

best_fit_strain_averaging (false)

Whether to use the best-fit strain averaging to average the contact displacements to the macroscopic strain.

increment_plastic_displacement (false)

Whether to increment the plastic displacement in the contact law.

use_isotropic_fabric_tensor_in_strain_averaging (false)

Whether to use the isotropic fabric tensor in strain averaging.

use_isotropic_fabric_tensor_in_stress_localization (false)

Whether to use the isotropic fabric tensor in stress localization.

use_plastic_strain_in_fabric_evolution (false)

Whether to use the plastic strain in the fabric evolution rule. The plastic strain is calculated as the difference between the total strain and the elastic strain and may be unstable which may lead to the divergence of the calculation.

loading_direction_type (depsd)

Type of loading direction, isotropic, depsd, depspd, s, sa or custom.

loading_direction_scale (1.0)

Scale for loading direction.

ignore_fabric_anisotropy_for_isotropic_loading (false)

Whether to ignore the fabric anisotropy for the isotropic loading.

ignore_fabric_evolution_for_isotropic_loading (false)

Whether to ignore the fabric evolution for the isotropic loading.

ignore_distractions (true)

Whether to ignore the distractions in the calculation.

check_stiffness_matrix_symmetry (false)

Whether to check the symmetry of the stiffness matrix.

save_elastic_stiffness_matrix (false)

Whether to save the elastic stiffness matrix.

multi_scale_return_mapping (false)

Solve the plastic problem with the multi-scale return mapping.

Warning

The multi-scale return mapping option has not been extensively tested.

Mixed load control

mixed_load_check_convergence (true)

Whether to check the convergence of the mixed load control after reaching maximum iterations.

mixed_load_check_strain_convergence (false)

Whether to check the convergence of the strain in the mixed load control.

mixed_load_check_stress_convergence (true)

Whether to check the convergence of the stress in the mixed load control.

mixed_load_check_absolute_convergence (true)

Whether to check the absolute mixed load tolerance.

mixed_load_absolute_tolerance (1e-5)

Absolute tolerance for the mixed load convergence criterion.

mixed_load_relative_tolerance (1e-3, 1e-4 for SANISAND contact law)

Relative tolerance for the mixed load convergence criterion.

mixed_load_max_iterations (100)

Number of maximum iterations for the mixed load convergence criterion.

mixed_load_max_larger_steps (-1)

When the mixed load error becomes larger for this number of steps, the iteration is considered diverged.

mixed_load_constant_elastic_stiffness (true)

Whether to use constant elastic stiffness within a mixed load iteration to improve convergence of state-dependent elastoplastic models.

Note

This option is recommended for state-dependent elastoplastic models to improve the convergence of mixed load control. Setting this option to false preserves the legacy behavior of updating the elastic stiffness within each mixed load iteration.

mixed_load_update_void_ratio_in (after_convergence)

When to update the void ratio in the mixed load control algorithm. Possible values are after_convergence, after_iteration, before_iteration and elastoplastic.

Note

This option is recommended for state-dependent elastoplastic models to improve the convergence of mixed load control. Setting this option to after_iteration preserves the legacy behavior of updating the void ratio after each mixed load iteration.

mixed_load_stress_as_anisotropic_stress (false)

Whether the stress-controlled load is given as anisotropic stress.

Lode angle dependent friction angle

friction_angle_weight_mises (0.0)

Weight of Mises component in lode angle dependent friction angle.

friction_angle_weight_tresca (0.0)

Weight of Tresca component in lode angle dependent friction angle.

friction_angle_weight_mohr_coulomb (1.0)

Weight of Mohr-Coulomb component in lode angle dependent friction angle.

friction_angle_weight_smp (0.0)

Weight of SMP component in lode angle dependent friction angle.

Macro-micro integration

integration_loading_ratio (1.0)

Macro-micro integration loading ratio for the contact force and displacement.

integration_substepping_relative_to_increment (false)

Whether to use the macro-micro integration substepping relative to the increment of last step.

integration_substepping_max_ratio (-1.0, 0.01 for SANISAND contact law)

Maximum macro-micro integration substepping ratio, only valid when it is positive.

integration_substepping_min_ratio (-1.0)

Minimum macro-micro integration substepping ratio, only valid when it is positive.

integration_at_least_once (False)

Whether the macro-micro integration must be ran at least once.

integration_check_convergence (true)

Whether to check the convergence of the macro-micro integration after reaching maximum iterations.

integration_check_absolute_convergence (true)

Check the absolute contact integration error or the relative contact integration error.

integration_tolerance_relative_stress (false)

Whether to use relative tolerance to the stress norm.

integration_absolute_tolerance (1e-10)

Absolute tolerance for the contact integration criterion.

integration_relative_tolerance (1e-3)

Relative tolerance for the contact integration criterion.

integration_max_iterations (100)

Maximum number of iterations for the macro-micro integration iterations.

Contact law

contact_check_convergence (true)

Whether to check the convergence of the contact law after reaching maximum iterations.

contact_tolerance (1e-10, 1e-4 for SANISAND contact law)

Tolerance for the contact law of the yield function.

contact_max_iterations (100)

Maximum number of iterations for the contact law.

contact_substepping (true for nonlinear contact laws, false for elastoplastic contact laws)

Whether to use substepping strategy for the contact law.

contact_substepping_separate_normal_shear_displacements (true)

Whether to separate normal and shear displacement in contact substepping.

contact_substepping_max_increment (0.1 for nonlinear contact laws, -1 for elastoplastic contact laws)

Maximum increment of shear force ratio for the contact law.

contact_min_normal_force (1e-10)

Minimum normal force that is considered as zero.

contact_associated_flow_rule (false)

Whether to use associated flow rule for contact law.

contact_check_plastic_multiplier (true)

Whether to check the sign of plastic multiplier.

contact_plastic_method_multiplier (1)

Multiplier for the contact plastic method.

contact_ensure_force_state_on_yield_surface (false)

Whether to ensure the contact state is on the yield surface.

contact_sanisand_constant_hardening_parameter (true)

Whether to use constant hardening parameter h for the SANISAND contact law.

contact_sanisand_maintain_yield_surface (false)

Whether to maintain the yield surface for the SANISAND contact law.

contact_simsand_use_plastic_displacement (true)

Whether to use plastic displacement in OSIMSAND/SIMSAND contact laws.

contact_simsand_hardening_use_plastic_displacement (true)

Whether to use plastic displacement in OSIMSAND/SIMSAND contact laws in the hardening law.

contact_save_stiffness (false)

Whether to save contact stiffness in the state variables.

contact_tensile_stiffness_ratio (1.0)

Ratio of tensile stiffness to compressive stiffness.

contact_default_yield_function_derivative (false)

Whether to use the default yield function derivative for contact laws.

contact_default_potential_function_derivative (false)

Whether to use the default potential function derivative for contact laws.

cache (true)

Whether to cache the state variables.

cache_precision (15)

Precision of the cache.

elastoplastic_cache_state_variables (true)

Whether to cache state variables for elastoplastic models.

Show verbose information

disp_steps (-1)

Print debug information every disp_steps steps. If disp_steps is set to 0 or negative, no debug information is printed.

verbose (false)

Print verbose information.

Debugging

debug (false)

Whether to record the debug variables. Specific debug variables should be defined in Model.setupDebugVariable method.

run_steps (-1)

Only run the first run_steps steps. If run_steps is set to 0 or negative, run all steps.

run_mixed_load_steps (-1)

Only run the first run_mixed_load_steps steps in the mixed load control. If run_mixed_load_steps is set to 0 or negative, run all steps.

run_contact_integration_steps (-1)

Only run the first run_contact_integration_steps steps in the contact integration. If run_contact_integration_steps is set to 0 or negative, run all steps.

Elastoplastic model options

elastic_stiffness_void_ratio_dependence (true)

Whether to use the void ratio dependent elastic stiffness.

elastic_stiffness_void_ratio_dependence_initial (false)

Whether to use the initial void ratio for void ratio dependent elastic stiffness.

elastic_stiffness_stress_dependence (true)

Whether to use the stress dependent elastic stiffness.

elastic_stiffness_stress_dependence_min_mean_stress_ratio (0.0)

Minimum mean stress ratio for stress dependent elastic stiffness, below which the elastic stiffness does not depend on the stress.

elastic_stiffness_stress_dependence_use_anisotropic_mean_stress (false)

Whether to use anisotropic mean stress in stress dependent elastic stiffness.

elastic_fabric_anisotropy_scale (1.0)

Scale factor for fabric anisotropy in elastic stiffness.

elastoplastic_density_effect_on_strength_dilatancy_type (powerlaw)

The type of density effect on strength and dilatancy, either 'exponential' or 'powerlaw'.

elastoplastic_yield_function_stress_dependent_kp_scale (-1.0)

Scale factor for the stress-dependent kp in the yield function. If negative, kp is a constant.

elastoplastic_yield_function_min_critical_stress_ratio (-1.0)

Minimum critical stress ratio for elastoplastic models. Negative values are ignored.

elastoplastic_yield_function_fabric_anisotropy (true)

Whether to consider fabric anisotropy in the yield function.

simsand_yield_function_use_plastic_strain (true)

Whether to use plastic strain (or total strain) in the yield function for SIMSAND model.

simsand_yield_function_additional_shear_strain (0.0)

Additional shear strain to be added to the yield function for SIMSAND model to improve numerical stability when shear strain is close to zero.

simsand_yield_function_shear_strain_scale (1.0)

Scale factor for the shear strain in the yield function for SIMSAND model.

j2yang_yield_function_epsr_relative_to_kp (false)

Whether to use the epsr relative to kp in the yield function for J2Yang model.

j2yang_yield_function_softening_type (exponential)

Type of softening behavior in the yield function for J2Yang model, either 'exponential', 'hyperbolic' or 'hyperbolic-modified'.

j2yang_yield_function_softening_alpha (1.0)

Parameter alpha to control the softening behavior in the yield function for J2Yang model.

j2yang_yield_function_softening_beta (1.0)

Parameter beta to control the softening behavior in the yield function for J2Yang model.

j2yang_yield_function_softening_relative_to_CSR (false)

Whether softening behavior depends on critical stress ratio in the yield function for J2Yang model.

elastoplastic_dilatancy_separate_friction_angle (false)

Whether to use a separate friction angle for the stress-dilatancy relationship.

elastoplastic_dilatancy_exponent (1.0)

Exponent for the stress-dilatancy relationship when using a power-law type relationship.

elastoplastic_dilatancy_scale_at_low_mean_stress (0.0)

Low mean stress threshold to scale the dilatancy function.

elastoplastic_use_anisotropic_state_parameter (false)

Whether to use the anisotropic state parameter in the stress-dilatancy relationship.