Variables and Flags Reference

Sources. Thesis §4.3.3.3 (ALM parameters), §4.3.3.6 and §4.3.4.5 (active and slip sets); code: contact_structural_mechanics_application_variables.{h,cpp}, contact_structural_mechanics_application.cpp (Register()), custom_python/contact_structural_mechanics_python_application.cpp:49-95, python_scripts/auxiliary_methods_solvers.py:122-170, python_scripts/search_base_process.py, python_scripts/alm_contact_process.py, python_scripts/mpc_contact_process.py, custom_processes/base_contact_search_process.h, custom_linear_solvers/mixedulm_linear_solver.h, custom_strategies/custom_convergencecriterias/*.h, custom_utilities/active_set_utilities.cpp, kratos/includes/variables.h, kratos/includes/mapping_variables.h, kratos/includes/mortar_classes.h.

The application communicates between its Python layer, its processes, its strategies and its conditions almost exclusively through variables (stored in the ProcessInfo, in the Properties of a pair, or on the nodes as historical or non-historical values) and through flags (on nodes, conditions and model parts). This page is the reference for all of them. It complements the Architecture page, which explains when they are set during a time step, and the Conditions page, which lists the subset consumed at assembly time. Nothing here is a user setting: the JSON keys that produce these values are documented in the Solver settings reference and the Contact process settings reference.

Figure: what each `mortar_type` adds to the nodes (historical variables and DoFs) and which non-historical values and flags the search and active-set code rely on.

Application variables

The 34 variables below are declared in contact_structural_mechanics_application_variables.h with KRATOS_DEFINE_APPLICATION_VARIABLE(CONTACT_STRUCTURAL_MECHANICS_APPLICATION, <type>, <NAME>) (or the _3D_..._WITH_COMPONENTS form, which also creates the _X, _Y, _Z components), created in contact_structural_mechanics_application_variables.cpp and registered in KratosContactStructuralMechanicsApplication::Register(). The group column follows the comment blocks of the header; storage tells where the value normally lives (PI = ProcessInfo, Prop = pair Properties, N-hist = nodal historical, N-val = nodal non-historical SetValue, C-val = condition SetValue). The “written by / read by” columns were obtained by searching every .h, .cpp and .py of the application (tests excluded).

MPC contact

Mortar general

Weighted (mortar-integrated) quantities

The two residual variables exist only because VariableUtils().AddDof(variable, reaction, model_part) requires a reaction variable; the # TODO Remove WEIGHTED_SCALAR_RESIDUAL in case of check for reaction is defined comments in auxiliary_methods_solvers.py:159, 161 acknowledge that no criterion reads them.

Augmented Lagrangian method

Mesh tying, explicit and frictional laws

Note. Three variables (TANGENT_SLIP, PARENT_ELEMENT, FRICTIONAL_LAW) are registered but have no consumer in the current code base, and FRICTIONAL_LAW is not even written. They are kept for compatibility and for the planned frictional-law refactoring.

Kratos-core variables used by the application

These variables are defined in kratos/includes/variables.h (or mapping_variables.h for TANGENT_FACTOR) and are therefore available as KratosMultiphysics.<NAME> in Python; they play a central role in the formulation.

Nodal variables and DoFs added by the solvers

The contact solvers call AuxiliaryAddVariables(main_model_part, mortar_type) inside AddVariables and AuxiliaryAddDofs(main_model_part, mortar_type) inside AddDofs (python_scripts/auxiliary_methods_solvers.py:122-170), on top of what the structural solver adds (DISPLACEMENT, REACTION, VELOCITY, ACCELERATION, …). NORMAL and NODAL_H are added for every non-empty mortar_type; the MPC solvers use AuxiliaryMPCAddVariables (l. 150-156) instead and add no multiplier DoF.

The multiplier DoFs are added to all nodes of the main model part (VariableUtils().AddDof(..., main_model_part)); the block builder-and-solver fixes the ones that do not belong to an active slave node (Builder and solvers and linear solvers). Because the frictional formulations difference the displacement over two previous steps, the contact solvers raise the minimum buffer size to 3 for ALMContactFrictional* and PenaltyContactFrictional* (Solver settings reference).

Enumerations

Python exposure

custom_python/contact_structural_mechanics_python_application.cpp:49-95 exposes the NormalDerivativesComputation enum and registers the variables with KRATOS_REGISTER_IN_PYTHON_VARIABLE / KRATOS_REGISTER_IN_PYTHON_3D_VARIABLE_WITH_COMPONENTS, so that they are reachable as KratosMultiphysics.ContactStructuralMechanicsApplication.<NAME> (the scripts of the application import the module as CSMA). The following details are worth knowing:

• Not exposed: CONSTRAINT_POINTER, PARENT_ELEMENT and FRICTIONAL_LAW. Their types (MasterSlaveConstraint::Pointer, Element::Pointer, FrictionalLaw::Pointer) have no Variable<> binding in Python, so these three can only be read or written from C++.
• Registered twice: ACTIVE_CHECK_FACTOR appears at lines 70 and 78 of the binding file. The second registration overwrites the first attribute with the same object; it is harmless.
• Core variable re-registered: TANGENT_FACTOR (line 88) is a Kratos-core variable from mapping_variables.h that is registered again in this module, so it exists both as KratosMultiphysics.TANGENT_FACTOR and as KratosMultiphysics.ContactStructuralMechanicsApplication.TANGENT_FACTOR (the application scripts use KM.TANGENT_FACTOR).
• The component variables (WEIGHTED_SLIP_X, AUGMENTED_TANGENT_CONTACT_PRESSURE_Y, …) are created by the _3D_VARIABLE_WITH_COMPONENTS macros and are usable as any other double variable, for instance in WriteNodalResults or AssignScalarVariableProcess.

A minimal example of reading contact results from Python after a solve:

import KratosMultiphysics as KM
import KratosMultiphysics.ContactStructuralMechanicsApplication as CSMA

contact_model_part = model["Structure.Contact"]
for node in contact_model_part.Nodes:
    if node.Is(KM.SLAVE) and node.Is(KM.ACTIVE):
        gap      = node.GetSolutionStepValue(CSMA.WEIGHTED_GAP)               # historical
        pressure = node.GetValue(CSMA.AUGMENTED_NORMAL_CONTACT_PRESSURE)      # non-historical
        lm       = node.GetSolutionStepValue(CSMA.LAGRANGE_MULTIPLIER_CONTACT_PRESSURE)

Flags

Kratos flags are bits stored on any Flags-derived object (nodes, conditions, elements, model parts, and also the ProcessInfo and the processes themselves). The application uses the core flags listed below with an entity-dependent meaning, plus a few local flags defined by its own classes. The Architecture page shows when each flag is set during a time step; this table is the exhaustive reference.

Core flags

Local flags

Local flags are declared with KRATOS_DEFINE_LOCAL_FLAG inside a class and are set on the object itself (a process, a criterion or a linear solver), usually from its JSON settings in the constructor:

The strategies and criteria are documented in Strategies and convergence criteria, the search flags in Search pipeline and bounding volumes and the linear-solver flags in Builder and solvers and linear solvers.

Quick lookup by question

Source files on GitHub: contact_structural_mechanics_application_variables.h, contact_structural_mechanics_application_variables.cpp, contact_structural_mechanics_python_application.cpp, auxiliary_methods_solvers.py, base_contact_search_process.h, mixedulm_linear_solver.h, kratos/includes/variables.h.