Architecture

Sources. Thesis App. B.2 (the Kratos framework) and §4.3.3.5 (solution work-flow); code: CMakeLists.txt, pyproject.toml, ContactStructuralMechanicsApplication.json, contact_structural_mechanics_application.{h,cpp}, custom_python/*.cpp, python_scripts/search_base_process.py, python_scripts/auxiliary_methods_solvers.py, python_scripts/contact_structural_mechanics_static_solver.py, custom_processes/base_contact_search_process.{h,cpp}, custom_strategies/custom_strategies/residualbased_newton_raphson_contact_strategy.h, custom_strategies/custom_convergencecriterias/base_mortar_criteria.h, custom_utilities/active_set_utilities.cpp; git log of the application folder.

The ContactStructuralMechanicsApplication (CSMA) is a plug-in of the StructuralMechanicsApplication: it does not define elements, constitutive laws or an analysis stage of its own. It adds the pieces that turn a structural problem into a contact problem, namely the interface conditions, the search that pairs them, the strategies and convergence criteria that drive the active set, and the Python glue that wires everything from a standard ProjectParameters.json. This page explains how these pieces are organised, how they are built, which data they share and in which order they are executed. The classes themselves are documented in the sibling pages: Conditions, Strategies and convergence criteria, Builder and solvers and linear solvers, Processes, Utilities, Frictional laws and MPC constraint and the Variables and flags reference.

Three layers

Figure: the Python layer, the application C++ layer (two CMake targets) and the Kratos core / StructuralMechanicsApplication dependencies.

A design decision worth knowing when reading the code: the mortar machinery itself is not in this application. The mortar operators \(\mathbf{D}\) and \(\mathbf{M}\), the dual shape-function coefficient matrix \(\mathbf{A}_e\), the exact segmentation of a slave/master pair and the mortar mapper are Kratos-core classes (kratos/includes/mortar_classes.h, kratos/utilities/exact_mortar_segmentation_utility.h, kratos/utilities/mortar_utilities.h, kratos/processes/simple_mortar_mapper_process.h), so that the mapping and FSI applications can reuse them. What this application adds on top is the contact-specific use of those operators: the weak contact constraints, their consistent linearisation (custom_utilities/derivatives_utilities.h), the active-set logic and the search. See Mortar integration and dual Lagrange multipliers for the mathematics.

Folder-by-folder map

The application root applications/ContactStructuralMechanicsApplication/ contains the following (all paths relative to it; links point to the page that documents the folder in depth):

Build layout

The CMakeLists.txt defines two targets:

1. KratosContactStructuralMechanicsCore — a SHARED library built from a GLOB_RECURSE of contact_structural_mechanics_application.cpp, contact_structural_mechanics_application_variables.cpp, custom_utilities/*.cpp, custom_frictional_laws/*.cpp, custom_processes/*.cpp, custom_conditions/*.cpp and custom_master_slave_constraints/*.cpp. It links PUBLIC KratosCore KratosStructuralMechanicsCore and is compiled with CONTACT_STRUCTURAL_MECHANICS_APPLICATION=EXPORT,API (the KRATOS_API(CONTACT_STRUCTURAL_MECHANICS_APPLICATION) macro on every exported class).
2. KratosContactStructuralMechanicsApplication — the pybind11 module (pybind11_add_module(... MODULE THIN_LTO ...)) built from custom_python/*.cpp, linked PRIVATE against the core library, with an empty prefix and the .pyd / .so suffix fix-ups for Windows and macOS.

Consequences of this split:

• Strategies, convergence criteria, builder-and-solvers and the linear solver are header-only templates (custom_strategies/**, custom_linear_solvers/). There is no .cpp for them and they are not in the core library glob; their only instantiations are the ones requested by add_custom_strategies_to_python.cpp and add_custom_linear_solvers_to_python.cpp for the UblasSpace sparse/local space pair. A C++ user of these classes includes the header directly.
• Conditions, processes, utilities, frictional laws and the constraint are compiled into the core library, with explicit template class instantiations at the bottom of each .cpp for the geometry pairs <2,2>, <3,3>, <3,4>, <3,3,4> and <3,4,3> (times the FrictionalCase and normal-variation combinations for the conditions).
• Unity build exclusion. When CMAKE_UNITY_BUILD is on, custom_utilities/interface_preprocess.cpp and every custom_conditions/*.cpp are given SKIP_UNITY_BUILD_INCLUSION TRUE (the batch size is KRATOS_UNITY_BUILD_BATCH_SIZE). The generated frictional condition alone is about 170 000 lines, so concatenating it with other translation units would explode compile memory; interface_preprocess.cpp is excluded because of a conflict of explicit instantiations.
• Tests. With KRATOS_BUILD_TESTING=ON, tests/cpp_tests/*.cpp are added through kratos_add_gtests(TARGET KratosContactStructuralMechanicsCore ...). With INSTALL_TESTING_FILES=ON the whole tests/ folder is installed under applications/ContactStructuralMechanicsApplication/ excluding *.c, *.h, *.cpp, *.hpp and *.git so that the Python tests find their reference and parameter files. KRATOS_BUILD_BENCHMARK would build benchmarks/*.cpp against Google Benchmark, but the folder does not currently exist.
• Python install. kratos_python_install copies ContactStructuralMechanicsApplication.py to KratosMultiphysics/ContactStructuralMechanicsApplication/__init__.py and kratos_python_install_directory installs python_scripts/ as the package body (both honour INSTALL_PYTHON_USING_LINKS). The targets are appended to KRATOS_KERNEL and KRATOS_PYTHON_INTERFACE in the parent scope.

Wheel packaging

pyproject.toml (hatchling backend) declares the wheel KratosContactStructuralMechanicsApplication, requires-python = ">=3.8", the dependencies KratosMultiphysics=={env:KRATOS_VERSION} and KratosStructuralMechanicsApplication=={env:KRATOS_VERSION}, and the binaries to ship in [kratos] libs (KratosContactStructuralMechanicsApplication.*, KratosContactStructuralMechanicsCore.*, libKratosContactStructuralMechanicsCore.*). The legacy ContactStructuralMechanicsApplication.json carries the same information for the older wheel scripts (excluded_binaries explicitly leaves libKratosStructuralMechanicsCore.* to the structural wheel). Neither the ConstitutiveLawsApplication (needed by some tests) nor the MeshingApplication (needed for adaptive remeshing, guarded at run time with kratos_utilities.CheckIfApplicationsAvailable("MeshingApplication")) is a build or wheel dependency.

Data model: model parts, properties and flags

A contact simulation manipulates the same ModelPart as the structural problem; the application adds sub-model-parts, non-historical values and flags to it. Everything is created by SearchBaseProcess (Python) and BaseContactSearchProcess (C++).

Sub-model-parts

The pair conditions are created by name: the Python process gives the family stem (for example ALMFrictionlessMortarContact) as condition_name and the master node count as final_string ("4N" for a triangle/quadrilateral pair, "" otherwise), and the C++ search composes condition_name + "Condition" + TDim + "D" + TNumNodes + "N" + final_string (base_contact_search_process.cpp:94-101) and fetches the prototype from KratosComponents<Condition>. The ContactSearchWrapperProcess chooses the template instance (<2,2>, <3,3>, <3,4>, <3,3,4>, <3,4,3>) from DOMAIN_SIZE and the node counts of the first MASTER and SLAVE conditions it finds.

Properties and ProcessInfo

The processes push their settings into three places, which the conditions and utilities then read:

• Properties of each ContactSub<key>: INTEGRATION_ORDER_CONTACT, CONSIDER_TESSELLATION, ACTIVE_CHECK_FACTOR (search_base_process.py:177-179, 407-408), FRICTION_COEFFICIENT per pair (alm_contact_process.py:474), TYING_VARIABLE for mesh tying (mesh_tying_process.py:216), and THICKNESS for axisymmetric conditions (from the material).
• ProcessInfo: ZERO_TOLERANCE_FACTOR, ACTIVE_CHECK_FACTOR, DISTANCE_THRESHOLD (search), CONSIDER_NORMAL_VARIATION, ADAPT_PENALTY, MAX_GAP_FACTOR, OPERATOR_THRESHOLD, TANGENT_FACTOR, SLIP_AUGMENTATION_COEFFICIENT, SLIP_THRESHOLD, INITIAL_PENALTY, SCALE_FACTOR, ACTIVE_SET_CONVERGED (ALM process, alm_contact_process.py:373-447), REACTION_CHECK_STIFFNESS_FACTOR (MPC), MAX_GAP_THRESHOLD (explicit), and the counters NL_ITERATION_NUMBER, INNER_LOOP_ITERATION maintained by the strategy.
• Nodal non-historical values (SetValue): INITIAL_PENALTY, DYNAMIC_FACTOR, AUGMENTED_NORMAL_CONTACT_PRESSURE, AUGMENTED_TANGENT_CONTACT_PRESSURE, NODAL_AREA, NORMAL_GAP, FRICTION_COEFFICIENT; the historical variables and DoFs are added by the solver (AuxiliaryAddVariables / AuxiliaryAddDofs, see the Variables and flags reference).

Flags

Kratos flags are the main state mechanism of the application. Their meaning depends on the entity they are set on:

BaseContactSearchProcess also defines local flags of its own (base_contact_search_process.h:102-106): INVERTED_SEARCH (search from master to slave), CREATE_AUXILIAR_CONDITIONS (a condition_name was given, so pair conditions are created), MULTIPLE_SEARCHS (an id_name was given), PREDEFINE_MASTER_SLAVE and PURE_SLIP. They are set from the JSON of the search in its constructor. Other classes with local flags are BaseMortarConvergenceCriteria (COMPUTE_DYNAMIC_FACTOR, IO_DEBUG, PURE_SLIP), the displacement/residual criteria (ENSURE_CONTACT, PRINTING_OUTPUT, TABLE_IS_INITIALIZED, ROTATION_DOF_IS_CONSIDERED, INITIAL_RESIDUAL_IS_SET, …) and MixedULMLinearSolver (BLOCKS_ARE_ALLOCATED, IS_INITIALIZED). The full list is in the Variables and flags reference.

Life cycle of a time step

Figure: the contact solution loop of one time step (search, prediction, Newton iterations with active-set update, finalisation).

The plain workflow is a StructuralMechanicsAnalysis whose solver is one of the contact solvers and whose processes list contains a contact process. Within one time step the calls are:

1. SearchBaseProcess.ExecuteInitializeSolutionStep (search_base_process.py:211-241). If the current time is inside interval and the step counter reached database_step_update (or STEP == 1), the process resets the MARKER flags and calls ExecuteInitializeSolutionStep of every ContactSearchProcess (one per pair). In C++ this is ClearMortarConditions() followed by UpdateMortarConditions() (base_contact_search_process.cpp:181-189): the pair conditions of the previous step that are no longer close are removed from ComputingContact, the KD-tree / octree is rebuilt from the master conditions, every slave condition is queried, candidate pairs are filtered (normal orientation, gap check through NormalGapProcess when check_gap is MappingCheck) and new MortarContactCondition instances are created and appended to ComputingContact; slave nodes are pre-activated according to ACTIVE_CHECK_FACTOR. When no search is due, the nodes and conditions of the Contact sub-model-part are simply flagged not ACTIVE. Details in Search pipeline and bounding volumes.
2. Strategy InitializeSolutionStep (base Newton–Raphson): the builder-and-solver sets up the DoF set (reform_dofs_at_each_step is forced to true by the solvers because the set of active pairs changes every step) and calls InitializeSolutionStep on every condition; PairedCondition::InitializeSolutionStep recomputes the cached master normal mPairedNormal, and the frictional conditions store the previous mortar operators for the slip increment.
3. ResidualBasedNewtonRaphsonContactStrategy::Predict (residualbased_newton_raphson_contact_strategy.h:313-348): zeroes WEIGHTED_GAP (and WEIGHTED_SLIP when the model part Is(SLIP)) on the Contact nodes, calls ContactUtilities::ComputeExplicitContributionConditions("ComputingContact") so that every pair integrates its current weighted gap \(\tilde{g}_n\), and advances the nodal coordinates by the displacement increment (DISPLACEMENT in step 1, DISPLACEMENT - DISPLACEMENT(1) afterwards). No prediction of the multipliers is made here (that block is commented out); predict_correct_lagrange_multiplier in the search does it instead.
4. SolveSolutionStep (residualbased_newton_raphson_contact_strategy.h:465-515). Two modes, chosen by the INTERACTION flag of the computing model part (see next section). In both, each Newton iteration runs: InitializeNonLinearIteration (conditions recompute normals when CONSIDER_NORMAL_VARIATION requests it) → MortarAndConvergenceCriteria::PreCriteria → build and solve → update → PostCriteria. Inside BaseMortarConvergenceCriteria:
   • PreCriteria (base_mortar_criteria.h:168-232) updates the nodal normals when normal variation is on, the nodal tangents for frictional problems, recomputes the weighted gap when ADAPT_PENALTY or a dynamic problem requires it, runs ComputeDynamicFactorProcess (dynamic case with compute_dynamic_factor) and AALMAdaptPenaltyValueProcess (adapt_penalty).
   • PostCriteria (base_mortar_criteria.h:235-...) copies WEIGHTED_GAP to the buffer, zeroes it, recomputes it with ComputeExplicitContributionConditions, optionally dumps a GiD debug frame, and then calls the family-specific active-set update (ActiveSetUtilities::ComputeALMFrictionlessActiveSet, ComputeALMFrictionalActiveSet, ComputePenaltyFrictionlessActiveSet, …), which evaluates the augmented pressure \(\bar{\lambda}_n = k\lambda_n + \varepsilon\tilde{g}_n\) node by node, toggles ACTIVE (and SLIP) and returns the number of changes. The step converges only when the user criterion (displacement, residual, …) and the active set (no node changed status) are both satisfied.
5. FinalizeSolutionStep: the strategy finalises (the mFinalizeWasPerformed guard avoids doing it twice after an adaptive split), conditions run FinalizeSolutionStep (frictional ones reset mPreviousMortarOperatorsInitialized), and the solver optionally runs ContactUtilities::CheckActivity when ensure_contact is set. Then SearchBaseProcess.ExecuteFinalizeSolutionStep (search_base_process.py:243-257) calls the C++ ExecuteFinalizeSolutionStep, which clears the mortar conditions again when a search is due next step. The ALM process afterwards clears the augmented pressures of inactive nodes for post-processing (clear_inactive_for_post) and resets the SLIP flags every slip_step_reset_frequency steps.
6. Adaptive splitting (adaptative_strategy): if the step did not converge, AdaptativeStep() divides DELTA_TIME by split_factor up to max_number_splits times and re-runs the sequence InitializeSolutionStep → Predict → SolveSolutionStep → FinalizeSolutionStep for every sub-step, driving the user processes and output through the ProcessFactoryUtility lists (AddProcessesList / AddPostProcess of the solver).

The Algorithm-level description of the same loop (thesis Algorithm 2 for frictionless, Algorithm 3 for frictional) is in Frictionless contact and Frictional contact; the criteria are catalogued in Strategies and convergence criteria.

INTERACTION and simplified_semi_smooth_newton

Two ways of combining the Newton iterations with the active-set update exist, and the names are easy to confuse:

The MPC route uses the same flag on the process info (ResidualBasedNewtonRaphsonMPCContactStrategy, residualbased_newton_raphson_mpc_contact_strategy.h:425) and additionally sets INTERACTION on the ComputingContact conditions when update_each_nl_iteration is true, which makes MPCMortarContactCondition::InitializeNonLinearIteration rebuild the constraint relation matrix at every iteration.

Python bindings map

custom_python/contact_structural_mechanics_python_application.cpp defines the module KratosContactStructuralMechanicsApplication, calls the five AddCustom*ToPython functions, exposes the enum NormalDerivativesComputation and registers the variables (see the Variables and flags reference).

Everything else the user touches (contact_settings, contact_process_list) is pure Python in python_scripts/; the solvers are selected by StructuralMechanicsApplication/python_scripts/python_solvers_wrapper_structural.py, which maps the presence of contact_settings to contact_structural_mechanics_{static,implicit_dynamic,explicit_dynamic}_solver and of mpc_contact_settings to mpc_contact_structural_mechanics_{static,implicit_dynamic}_solver. See Getting started.

From ProjectParameters.json to objects

The two JSON blocks a user writes are consumed by different layers, and it helps to know who owns which key. solver_settings is read by the solver (Python), processes.contact_process_list by the contact process (Python), and both hand their values down to C++ objects through constructors, Parameters and the ProcessInfo:

ProjectParameters.json
├── solver_settings
│   ├── solver_type = "Static" | "Dynamic" (+ time_integration_method)   → python_solvers_wrapper_structural.py
│   ├── contact_settings { mortar_type, simplified_semi_smooth_newton,     → Contact*MechanicalSolver
│   │                      inner_loop_iterations, use_mixed_ulm_solver, …}   ├─ AuxiliaryAddVariables / AuxiliaryAddDofs (nodal DB)
│   │                                                                        ├─ ContactConvergenceCriteriaFactory → MortarAndConvergenceCriteria(...)
│   │                                                                        ├─ Contact*BuilderAndSolver, MixedULMLinearSolver
│   │                                                                        └─ ResidualBasedNewtonRaphsonContactStrategy(...)
│   └── mpc_contact_settings { contact_type, update_each_nl_iteration, … }  → MPCContact*Solver → ResidualBasedNewtonRaphsonMPCContactStrategy
└── processes.contact_process_list
    └── alm_contact_process | penalty_contact_process | explicit_penalty_contact_process
        | mpc_contact_process | mesh_tying_process                          → SearchBaseProcess subclasses
            ├─ model parts (Contact, ContactSub<k>), flags, Properties, ProcessInfo values
            ├─ InterfacePreprocessCondition, NormalCheckProcess, MasterSlaveProcess, ALMVariablesCalculationProcess, ALMFastInit
            └─ ContactSearchProcess / MPCContactSearchProcess (one per pair) → ComputingContact conditions / constraints

Two facts follow from this split:

• contact_settings.mortar_type is a user-provided key (the test cases set "ALMContactFrictionless", "ALMContactFrictional", "ALMContactFrictionalPureSlip", "PenaltyContactFrictionless", "PenaltyContactFrictional", "ComponentsMeshTying", …) and must be consistent with contact_type / the process chosen in contact_process_list; nothing cross-checks them. It drives the nodal variables, the DoFs, the mortar convergence criterion and the use of the MixedULMLinearSolver.
• The solver never sees the pair conditions: it only knows the computing model part. The process creates the ComputingContact sub-model-part inside it, so the standard builder-and-solver loop over Conditions() picks the mortar conditions up automatically.

What the contact solvers change with respect to the structural ones

The implicit dynamic solver adds the same overrides on top of ImplicitMechanicalSolver; the explicit solver (ContactExplicitMechanicalSolver) uses the reduced AuxiliaryExplicitContactSettings block and multiplies its stable time step by delta_time_factor_for_contact while the computing model part Is(CONTACT).

Alternative routes

The default route described above (implicit, ALM or penalty, MortarContactCondition families) has three siblings that reuse most of the architecture:

The time step as pseudo-code

The following condenses the previous sections into one block (implicit, ALM/penalty route; the names are the actual methods):

# --- StructuralMechanicsAnalysis.RunSolutionLoop, one step ---
time += ContactSolver.ComputeDeltaTime()              # inner_loop_adaptive may shrink it
SearchBaseProcess.ExecuteInitializeSolutionStep()     # if interval and database_step_update reached:
    ContactSearchProcess.ExecuteInitializeSolutionStep()   #   ClearMortarConditions(); UpdateMortarConditions()
                                                           #   -> pair conditions in "ComputingContact", nodes pre-ACTIVE
Strategy.InitializeSolutionStep()                     # SetUpDofSet (reform_dofs_at_each_step), conditions.InitializeSolutionStep
Strategy.Predict()                                    # WEIGHTED_GAP = 0; ComputeExplicitContributionConditions; x += Δu
Strategy.SolveSolutionStep():
    if model_part.IsNot(INTERACTION):                 # simplified_semi_smooth_newton = true
        for inner in 1..inner_loop_iterations:
            NL_ITERATION_NUMBER = 1; INNER_LOOP_ITERATION = inner
            converged = BaseSolveSolutionStep()       # Newton loop with frozen active set
            converged = criteria.PostCriteria(...)    # active-set update; stop when unchanged
    else:                                             # full semi-smooth Newton (default)
        converged = BaseSolveSolutionStep():
            repeat until converged or max_iteration:
                conditions.InitializeNonLinearIteration()      # normals if CONSIDER_NORMAL_VARIATION
                criteria.PreCriteria()                         # normals/tangents, dynamic factor, AALM penalty
                BuildAndSolve(); Update()                      # MortarContactCondition::CalculateLocalSystem
                converged = criteria.PostCriteria()            # user criterion AND active set unchanged
    if not converged and adaptative_strategy: converged = AdaptativeStep()
Strategy.FinalizeSolutionStep()                       # conditions.FinalizeSolutionStep; ensure_contact check
SearchBaseProcess.ExecuteFinalizeSolutionStep()       # ClearMortarConditions when a search is due next step
ALMContactProcess.ExecuteFinalizeSolutionStep()       # clear_inactive_for_post, slip_step_reset_frequency
OutputProcess.PrintOutput()

Registration and start-up

At import time ContactStructuralMechanicsApplication.py imports KratosMultiphysics.StructuralMechanicsApplication first (so that the structural variables and elements exist), then calls _ImportApplication on a KratosContactStructuralMechanicsApplication() instance. Its Register() (contact_structural_mechanics_application.cpp) performs, in order:

1. KRATOS_REGISTER_VARIABLE / KRATOS_REGISTER_3D_VARIABLE_WITH_COMPONENTS for the 34 application variables (35 registration lines including the constraint).
2. KRATOS_REGISTER_CONDITION for the 68 condition names built from the member prototypes (mMeshTyingMortarCondition2D2N, mALMFrictionlessMortarContactCondition2D2N, …). The prototypes are constructed in the application constructor with a CouplingGeometry-compatible signature (Id, pSlaveGeometry, pProperties, pMasterGeometry); see the Conditions page for the decoder.
3. KRATOS_REGISTER_CONSTRAINT("ContactMasterSlaveConstraint", ...).

Strategies, criteria, builder-and-solvers and the linear solver are not registered in Register() (they are templates); they exist only as Python classes created by the solver scripts, and the strategies additionally carry a Name() ("newton_raphson_contact_strategy", "line_search_contact_strategy", "newton_raphson_mpc_contact_strategy") for the Kratos strategy factory.

Where is …? A quick index

Development timeline

Figure: commits per year touching the application and the main milestones.

The application was created on 2016-08-05 (“Adding the new ContactStructuralMechanicsApplication until is stable enough to move to the StructuralMechanicsApplication or the ContactMechanicsApplication”) together with the first general mortar contact condition. Its git log counts 3 154 commits (as of this writing), distributed as follows:

Milestones (from the commit messages):

• 2016-08 — application created; general mortar contact condition.
• 2017–2018 — dual-mortar ALM frictionless formulation, automatic-differentiation code generation (automatic_differentiation/), exact segmentation, search with KD-trees and bounding boxes, mesh tying, first benchmarks.
• 2019-01 — penalty active-set criteria; explicit contact process, explicit solver and explicit test.
• 2019-04 — penalty frictional condition, frictional explicit contribution, new ALM frictional version (WIP).
• 2019-06 — first frictional laws (Coulomb/Tresca, WIP), derivatives for frictional laws, Hertz frictional tests.
• 2019-08 — specialised MMG remeshing script for contact (contact_remesh_mmg_process.py).
• 2019-09 — self-contact utilities, later improved with the ACTIVE flag.
• 2020-03 — MPCContactSearchWrapperProcess and the MPC (constraint-based) contact route; the thesis is defended the same year.
• 2021-05 — refactor of all convergence criteria (Create + Parameters constructors).
• 2022 onwards — maintenance mode (API updates, bug fixes): 2025-10 DoF initialisation fix in ResidualBasedNewtonRaphsonMPCContactStrategy; 2025-11 consistent naming in automatic_differentiation/ and pyproject.toml for all applications; 2026-08 latest fixes (size-comparison cast in MixedULMLinearSolver, unused coordinate variables in MPCMortarContactCondition).

The status badge of the application is therefore “Maintained” rather than “Actively developed”; see Tips, troubleshooting and limitations for the known limitations that follow from this.