|
| 1 | +--- |
| 2 | +title: Analysing failure of behaviour integration |
| 3 | +author: Thomas Helfer |
| 4 | +date: 2025 |
| 5 | +lang: en-EN |
| 6 | +numbersections: true |
| 7 | +documentclass: article |
| 8 | +from: markdown+tex_math_single_backslash |
| 9 | +geometry: |
| 10 | + - margin=2cm |
| 11 | +papersize: a4 |
| 12 | +link-citations: true |
| 13 | +colorlinks: true |
| 14 | +figPrefixTemplate: "$$i$$" |
| 15 | +tabPrefixTemplate: "$$i$$" |
| 16 | +secPrefixTemplate: "$$i$$" |
| 17 | +eqnPrefixTemplate: "($$i$$)" |
| 18 | +bibliography: bibliography.bib |
| 19 | +--- |
| 20 | + |
| 21 | +This section describes the features available to analyse the failure of |
| 22 | +the integration of a behaviour at one integration point. |
| 23 | + |
| 24 | +# The `integrate_debug` functions |
| 25 | + |
| 26 | +The `integrate_debug` function are small wrappers around the `integrate` |
| 27 | +functions which, in case of integration failure, calls a user defined |
| 28 | +analyser or the default one. |
| 29 | + |
| 30 | +## Examples of usage |
| 31 | + |
| 32 | +The `integrate_debug` functions are direct substitutes for the |
| 33 | +`integrate` functions and have the same prototypes, when the default |
| 34 | +analyser is used. The following snippet shows how to call it using a |
| 35 | +behaviour data view `v` and a behaviour `b`: |
| 36 | + |
| 37 | +~~~~{.cxx} |
| 38 | +const auto r = integrate_debug(v, b); |
| 39 | +~~~~ |
| 40 | + |
| 41 | +See Section @sec:mgis:integration_failure:default_analyser for a |
| 42 | +description of the default analyser. |
| 43 | + |
| 44 | +The user may pass his own analyser, the type of which must inherit from |
| 45 | +the `BehaviourIntegrationFailureAnalyser` interface, describe below, as |
| 46 | +an extra argument, as follows: |
| 47 | + |
| 48 | +~~~~{.cxx} |
| 49 | +const auto a = CustomAnalyser{}; |
| 50 | +const auto r = integrate_debug(v, b, a); |
| 51 | +~~~~ |
| 52 | + |
| 53 | +See Section @sec:mgis:integration_failure:custom_analyser for details. |
| 54 | + |
| 55 | +## Description of the default analyser {#sec:mgis:integration_failure:default_analyser} |
| 56 | + |
| 57 | +The default analyser generates one file per integration failure |
| 58 | +containing the information required to re-run the simulation, using |
| 59 | +[`MTest`](https://thelfer.github.io/tfel/web/mtest.html) for instance. |
| 60 | + |
| 61 | +By default, a markdown file is generated. Other formats may be supported |
| 62 | +in the future. |
| 63 | + |
| 64 | +By default, the file name is composed by the name of the function |
| 65 | +implementing the behaviour (for the considered modelling hypothesis), a |
| 66 | +unique identifier (a number starting from zero and incremented for each |
| 67 | +integration failure report) and an extension. See Section |
| 68 | +@sec:mgis:integration_failure:default_output_file_name for details. |
| 69 | + |
| 70 | +### Example of generated file |
| 71 | + |
| 72 | +~~~~{.md} |
| 73 | +# Behaviour description |
| 74 | +
|
| 75 | +- library:/home/th202608/codes/mgis/master/src/build/tests/libBehaviourTest.so |
| 76 | +- behaviour: NortonFailure |
| 77 | +- function: NortonFailure_Tridimensional |
| 78 | +
|
| 79 | +# State at the beginning of the time step |
| 80 | +
|
| 81 | +## Gradients |
| 82 | +
|
| 83 | +- Strain (Stensor): {0, 0, 0, 0, 0, 0} |
| 84 | +
|
| 85 | +## Thermodynamic forces |
| 86 | +
|
| 87 | +- Stress (Stensor): {0, 0, 0, 0, 0, 0} |
| 88 | +
|
| 89 | +## Internal state variables |
| 90 | +
|
| 91 | +- ElasticStrain (Stensor): {0, 0, 0, 0, 0, 0} |
| 92 | +- EquivalentViscoplasticStrain (Scalar): 0 |
| 93 | +
|
| 94 | +## External state variables |
| 95 | +
|
| 96 | +- Temperature (Scalar): 293.15 |
| 97 | +
|
| 98 | +# State at the end of the time step |
| 99 | +
|
| 100 | +## Gradients |
| 101 | +
|
| 102 | +- Strain (Stensor): {5e-05, 0, 0, 0, 0, 0} |
| 103 | +
|
| 104 | +## Thermodynamic forces |
| 105 | +
|
| 106 | +- Stress (Stensor): {0, 0, 0, 0, 0, 0} |
| 107 | +
|
| 108 | +## Internal state variables |
| 109 | +
|
| 110 | +- ElasticStrain (Stensor): {0, 0, 0, 0, 0, 0} |
| 111 | +- EquivalentViscoplasticStrain (Scalar): 0 |
| 112 | +
|
| 113 | +## External state variables |
| 114 | +
|
| 115 | +- Temperature (Scalar): 293.15 |
| 116 | +~~~~ |
| 117 | + |
| 118 | +### Changing the generator of the output file name {#sec:mgis:integration_failure:default_output_file_name} |
| 119 | + |
| 120 | +The output file name is generated by the |
| 121 | +`getBehaviourIntegrationFailureAnalysisFileName` function which takes the |
| 122 | +behaviour's function as first argument and the file extension as second |
| 123 | +argument. |
| 124 | + |
| 125 | +The behaviour of the `getBehaviourIntegrationFailureAnalysisFileName` |
| 126 | +function can be altered using the |
| 127 | +`setBehaviourIntegrationFailureAnalysisFileNameGenerator` which takes a |
| 128 | +`std::function` as first argument. This function can be useful in MPI |
| 129 | +computations to distinguish the various processes. |
| 130 | + |
| 131 | +#### Example of usage |
| 132 | + |
| 133 | +~~~~{.cxx} |
| 134 | +auto g = [](std::string_view b, std::string_view n, std::string_view e){ |
| 135 | + int r; |
| 136 | + MPI_Comm_rank(MPI_COMM_WORLD, &r); |
| 137 | + return std::string{b} + '-' + std::to_string(r) + '-' + |
| 138 | + std::string(id) + "." + std::string{ext}; |
| 139 | +}; |
| 140 | +setBehaviourIntegrationFailureAnalysisFileNameGenerator(g); |
| 141 | +~~~~ |
| 142 | + |
| 143 | +## The `BehaviourIntegrationFailureAnalyser` interface {#sec:mgis:integration_failure:custom_analyser} |
| 144 | + |
| 145 | +The `BehaviourIntegrationFailureAnalyser` interface is defined as follows: |
| 146 | + |
| 147 | +~~~~{.cxx} |
| 148 | + struct MGIS_EXPORT BehaviourIntegrationFailureAnalyser { |
| 149 | + virtual void analyse(const Behaviour&, |
| 150 | + const BehaviourData&) const noexcept = 0; |
| 151 | + virtual void analyse(const Behaviour&, |
| 152 | + const BehaviourDataView&) const noexcept = 0; |
| 153 | + virtual bool shallCopyBehaviourDataBeforeIntegration() const noexcept = 0; |
| 154 | + virtual ~BehaviourIntegrationFailureAnalyser() noexcept; |
| 155 | + }; |
| 156 | +~~~~ |
| 157 | + |
| 158 | +The two `analyse` functions do the actual work. The one effectively |
| 159 | +called depends on the value returned by the |
| 160 | +`shallCopyBehaviourDataBeforeIntegration` method. |
| 161 | + |
| 162 | +If the `shallCopyBehaviourDataBeforeIntegration` return `true`, the |
| 163 | +behaviour data view passed to the `integrate_debug` function is copied |
| 164 | +before integrating the behaviour using `integrate`: |
| 165 | + |
| 166 | +- Copying has a significant overhead and is normally not required for |
| 167 | + correctly written behaviours but data corruption may occur, so copying |
| 168 | + is safer. |
| 169 | +- Without copying, calling `integrate_debug` shall be almost as |
| 170 | + efficient than calling `integrate`. |
| 171 | + |
| 172 | +> **Note** |
| 173 | +> |
| 174 | +> The default analyser does a copy of the data, which indeed incurs an |
| 175 | +> overhead. |
0 commit comments