Add Adaptive Estimate interpolation and wire it to the viscoplastic material InelasticDefgradTransvIsotropElastViscoplast

[dragos-ana]

This PR implements the Adaptive Estimate Interpolation (AEI) algorithm, as presented in Ana, Schmidt, and Wall: Adaptive Estimate Interpolation: Accelerating Local Newton-Raphson Schemes in Computational Plasticity and Viscoplasticity (soon as a preprint).

A summary of the method and its significant advantages for the computational efficiency and numerical robustness of local integration for general plasticity / viscoplasticity models is given below (see description of the last commit / stacked PR).
As an example, AEI achieved a 3.6× speedup compared to the conventional elastic predictor when using the same time-step size. At the same time, the scheme allowed for time-step sizes up to 1000× larger than those possible with the elastic predictor.

Why a single PR?

Integrating the algorithm is difficult to split into independent sequential PRs, as reliably reviewing and merging the implementation requires context across the newly introduced parameters, the associated logic, and their integration into Mat::InelasticDefgradTransvIsotropElastViscoplast.

For this reason, @c-p-schmidt, @rjoussen, and I explicitly decided against a sequential approach. Our original plan was instead to use a stacked PR workflow (see GitHub's documentation), with one commit per component and the individual changes mergeable independently or as a whole.

Unfortunately, stacked PRs are currently not supported for cross-fork branches (see this issue). We therefore decided to consolidate the planned stack into this single PR for now - if review gets too complex, we might use an alternative strategy.

Structure of the PR

Below, I provide detailed descriptions of the individual components/commits that would originally have formed the stacked PR. These descriptions are intentionally fairly extensive to make the implementation easier to review despite the size of the PR.

Although @c-p-schmidt and @rjoussen have agreed to review the PR in its current form, feedback from other developers is very welcome as well.

Commits

Add LocalIntegrationInput

Enhance storage struct for local integration (AEI Stacked PR: 1/5)

Enhance the storage struct for the deformation tensors used by several local integration routines to include additional relevant input data, such as the absolute temperature, previous plastic strain, and timestep/substep size. The struct is renamed to LocalIntegrationInput to reflect its extended purpose.

For now, its usage is restricted to the routines that already use the deformation-tensor struct and additionally require temperature, previous plastic strain, and timestep information. More granular local evaluation routines, such as residual and Jacobian evaluations or state quantities and their derivatives, could also make use of LocalIntegrationInput in the future, potentially in combination with the migration to tensors.

Add AEI parameters

Add relevant parameters for the Adaptive Estimate Interpolation (AEI Stacked PR: 2/5)

Add the parameters required for Adaptive Estimate Interpolation (AEI), as described in Ana, Schmidt, Wall: Adaptive Estimate Interpolation: Accelerating Local Newton-Raphson Schemes in Computational Plasticity and Viscoplasticity (Preprint) (summary of the method provided in LINK).

The added parameters cover interpolation preconditioning, plastic predictor construction, estimate interpolation between predictors, hardening management, and re-estimation.

The framework is designed to be as general and extensible as possible. Some enum classes currently contain only a single value but can be extended with additional options in the future.

A helper header for constructing AEI parameter objects for different unit tests is also added. It is currently used only by 4C_inelastic_defgrad_factors_test.cpp; upcoming PRs will also use it in 4C_inelastic_defgrad_factors_service_test.cpp.

Add utils for AEI

Add various utilities for the Adaptive Estimate Interpolation (AEI Stacked PR: 3/5)

This PR adds the infrastructure required for Adaptive Estimate Interpolation (AEI), as described in Ana, Schmidt, Wall: Adaptive Estimate Interpolation: Accelerating Local Newton-Raphson Schemes in Computational Plasticity and Viscoplasticity (Preprint) (summary of the method provided in LINK).

Main additions

• Add PredictorInterpolator to construct and store the elastic and preliminary plastic predictors at each Gauss point.
• Interpolate the elastic deformation gradient: elastic stretch eigenvalues using logarithmic weighted average, eigenvector rotations using spherical linear quaternion interpolation, elastic rotations using spherical linear quaternion interpolation.
• Add support for the currently implemented preliminary plastic predictor construction: elastic stretch eigenvectors and elastic rotation are directly taken from the elastic predictor, stretch eigenvalues are initialized from the volumetric part of the elastic predictor.
• Add optional preconditioning of the elastic deformation gradient within the elastic predictor before its spectral decomposition.
• Add InterpolationPointContainer for managing AEI interpolation points and their bounds across Gauss points.
• Make the scalar interpolation routines const where appropriate.

Testing

Add unit tests covering: preliminary plastic predictor construction and interpolation, combinations of stretch eigenvector and rotation contributions, preconditioning,
interpolation point initialization and reset.

Limitations

The rotational contributions of the preliminary plastic predictor are currently only supported using the corresponding quantities from the elastic predictor. Other construction options are intentionally left unsupported for now, particularly because eigenvector canonicalization for repeated eigenvalues needs to be addressed before meaningful relative eigenvector rotations can be constructed.

Add AEI manager

Add manager object for the Adaptive Estimate Interpolation (AEI Stacked PR: 4/5)

This PR adds a manager object for Adaptive Estimate Interpolation (AEI), as described in Ana, Schmidt, Wall: Adaptive Estimate Interpolation: Accelerating Local Newton-Raphson Schemes in Computational Plasticity and Viscoplasticity (Preprint) (summary of the method provided in LINK).

Main additions

• New AEINamespace::AEIManager class (4C_mat_inelastic_defgrad_factors_service.hpp/.cpp):
  • Tracks interpolation bounds/points per Gauss point via InterpolationPointContainer and PredictorInterpolator.
  • Interpolates the inverse inelastic deformation gradient and exposes a dedicated accessor for the plastic predictor endpoint.
  • Adapts the interpolation interval based on the type of evaluation error (adapt_interpolation_interval, via new InterpolationShiftAction enum and get_interpolation_shift_action helper).
  • Supports several current interpolation point presets: plastic predictor construction/estimate interpolation updates, interval bounds, elastic/plastic predictor endpoints, starting point, and intermediate point.
  • Supports two starting point strategies (StartingPointType): a user-set fixed value, and a history-based estimate (equiv_stress_history) computed from the equivalent stress of the previous solution relative to both predictors (I_HIST method).
• Wires the manager into Mat::InelasticDefgradTransvIsotropElastViscoplast as an optional member, constructed conditionally in the material constructor.
• Diagnostic info to get_error_warning_info().
• New InputEquivStressStartingPoint struct carrying the equivalent stresses of the solution, elastic predictor, and plastic predictor needed for the history-based starting point.

Testing

Added three unit tests in 4C_inelastic_defgrad_factors_service_test.cpp:

• TestAdaptiveEstimateInterpolationManagerBookkeeping: verifies iteration/re-estimation limit tracking and reset behavior.
• TestAdaptiveEstimateInterpolationManagerInterpolation: verifies predictor construction and interpolated deformation gradients across the CurrentInterpPointPreset options against computed reference values.
• TestAdaptiveEstimateInterpolationManagerStartingPoints: verifies both starting point strategies, including the throw when equivalent stress input is missing.

Wire AEI to vplast. material & Add framework tests

Wire Adaptive Estimate Interpolation to finite strain viscoplastic material model (AEI Stacked PR: 5/5)

This PR integrates the Adaptive Estimate Interpolation (AEI) algorithm into the Local Newton-Raphson scheme of InelasticDefgradTransvIsotropElastViscoplast to improve robustness and efficiency for challenging viscoplastic material states where the standard elastic predictor provides a poor initial estimate.
The algorithm is presented in Ana, Schmidt, and Wall: Adaptive Estimate Interpolation: Accelerating Local Newton-Raphson Schemes in Computational Plasticity and Viscoplasticity (Preprint). It contains the following main components:

• Construction of a plastic predictor: To enable the use of initial estimates with reduced stress states, we construct a plastic predictor as a counterpart to the elastic predictor.

• Estimate interpolation between predictors: The initial estimate is obtained by interpolating between the elastic predictor and the constructed plastic predictor while preserving model-specific constraints, such as plastic incompressibility.
  The resulting estimate must satisfy admissibility requirements, including numerically evaluable residuals and Jacobians within the local Newton--Raphson procedure, as well as the occurence of plastic flow.

• Dynamic recovery via re-estimation: If pathological states (e.g., numerical overflow, inadmissible configurations, singular linear systems, or stagnation due to negligible increments) occur during subsequent local Newton--Raphson iterations ($l > 0$), the local Newton--Raphson procedure is automatically restarted with an updated estimate. This adaptive restart mechanism is referred to as re-estimation.

Utilizing a viscoplastic model from literature, we benchmarked the developed scheme against the elastic predictor initialization under both simple and complex loading protocols.
Our results reveal pronounced computational efficiency gains, with constitutive update procedures up to $3.6 \times$ faster than the reference.
Furthermore, the scheme demonstrates superior numerical robustness, enabling time step sizes of up to three orders of magnitude larger than the standard elastic predictor usage.

Main additions

• Wire manage_evaluation to accept LocalIntegrationInput and drive AEI-based re-estimation (reestimate_to_restart_local_newton) as the default error management strategy when AEI is enabled, falling back to substepping (if configured) or throwing otherwise.
• Implement construct_plastic_predictor: the interpolation interval is iteratively shifted between the elastic and preliminary plastic predictors until the resulting stress state satisfies the relative understress tolerance; add assert_predictor_stress_consistency (debug-only) to sanity-check the elastic/preliminary-plastic-predictor stress bounds against the lowest meaningful stress threshold.
• Implement interpolate_estimate to produce admissible initial/updated Local Newton estimates by interpolating the inverse inelastic deformation gradient and, depending on the configured hardening method, either reusing the previous plastic strain or integrating it via integrate_plastic_strain (Newton loop on the hardening evolution equation).
• Implement reinterpolate_with_updated_bounds and reestimate_to_restart_local_newton to compute a re-estimated candidate at the intermediate interpolation point, verify it via verify_estimate_candidate.
• Add verify_estimate_candidate and exhibits_plastic_flow helpers used to admit/reject interpolated candidates during both initial estimation and re-estimation.
• Rewire determine_local_newton_init_estimate to build the initial estimate via AEI (reset manager, construct plastic predictor, interpolate) when AEI is enabled, instead of always using the elastic predictor.
• Add update_aei_starting_point (called in update() before history variables are overwritten) and get_input_equiv_stress_starting_point to update the AEI starting point for the next time step per Gauss point, per the configured strategy (user_set or equiv_stress_history).
• Add InputHardeningIntegration struct to carry inputs for the plastic strain integration routine.
• Add USE_ADAPTIVE_ESTIMATE_INTERPOLATION: false to all existing material test inputs that don't exercise AEI, plus explanatory TITLE notes.

Testing

Added TestElasticPredictorAgainstAdaptiveEstimateInterpolation, TestHardeningManagementAdaptiveEstimateInterpolation, and TestAdaptiveEstimateInterpolationWithSubstepping unit tests, plus four new regression input files (equiv_stress_history / user_set starting points, each with and without restart) registered in list_of_tests.cmake. Together these verify:

• the elastic predictor fails to converge for a challenging loading state, while AEI (with re-estimation) succeeds, and fails again if re-estimation is disabled;
• AEI with hardening integration and AEI with fixed plastic strain agree for a numerically tractable state, but only hardening integration converges for a more challenging one;
• AEI without substepping fails to converge for a severe deformation state, while combining AEI with substepping as the fallback strategy succeeds;
• Added framework tests for both starting point strategies (user-set and history-inferred based on the equivalent stress), both with and without restarts. The input files for the no-restart tests are used in the paper in the numerical robustness study (monotonic loading) as they are.

Interested parties

@ischeider @c-p-schmidt @rjoussen

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

src/global_legacy_module/4C_global_legacy_module_validmaterials.cpp:3112

• The description string contains f$ which looks like a malformed LaTeX delimiter (elsewhere you use \\f$ ... \\f$). This will show up in generated docs/help; replace f$ with the intended delimiter/escape sequence.

                            parameter<int>("MAX_ITER",
                                {.description = "maximum number of construction iterations f$ "
                                                "i_{\\text{C,max}} $",
                                    .default_value = 50,
                                    .validator = positive<int>(),
                                    .store = in_struct(&AEINamespace::
                                            PlasticPredictorConstructionParams::max_iter)}),

src/mat/4C_mat_inelastic_defgrad_factors_service.cpp:169

• std::clamp requires <algorithm>, but this .cpp file does not visibly include it. Relying on transitive includes is brittle; add the direct standard include to ensure portable compilation.

    return std::clamp((input_equiv_stress_starting_point.equiv_stress_solution -
                          input_equiv_stress_starting_point.equiv_stress_elast_pred) /
                          (input_equiv_stress_starting_point.equiv_stress_plast_pred -
                              input_equiv_stress_starting_point.equiv_stress_elast_pred),
        ELASTIC_PREDICTOR_LOCATION, PLASTIC_PREDICTOR_LOCATION);

[c-p-schmidt]

The first commit is still rather small and easy to review. ;-)

[c-p-schmidt]

Wouldn't it be nicer here to just pass the local_integration_input as a const reference, along with the error status, and deduce the relevant objects from it inside the method?

[c-p-schmidt]

Same here.