This version is compatible with behaviours generated by Version 3.4.1 of the TFEL/MFront project using the generic interface. More precisely, one expects that the behaviour must conform to the generic behaviour API Version 1 (See Section 2.5).

1 Known incompatibilites

Reflecting the changes made to the data structures used by the generic behaviour in Version 3.4.1 of the TFEL/MFront project, the API and ABI of MGIS is changed in this version.

Most changes are hidden to the user in the MaterialDataManager and BehaviourData classes. However, at low level, two main changes are worth noting:

• the rdt member of the BehaviourDataView is now a pointer.
• the BehaviourDataView now has a speed_of_sound member (See Section 2.1). This member can be set to nullptr if the computation of the speed of sound is not requested.
• The BehaviourDataView now has an error_message member.
• The meaning of the first entry of the K data member of the BehaviourDataView slightly changed. If K[0] is greater than 50, the speed of sound is computed. In this case, the type of behaviour integration to be performed is given by K[0]-50. If K[0] is lower than 50, it is interpreted as in previous versions. See Section 2.4.1 for details.

2 New features

2.1 Computation of the speed of sound

The speed of sound can now be computed by the behaviour. The computation of this value can be requested using the BehaviourIntegrationOptions class (See Section 2.4.2).

If requested during the behaviour integration, the speed of sound can be retrieved using:

• The speed_of_sound data member of the BehaviourData class.
• The speed_of_sound data member of the MaterialDataManager class.

2.2 New member in the MaterialDataManagerInitializer class

The speed_of_sound data member can point ot to an externally allocated memory which will be used to store the speed of sound. If empty, the material data manager will initialize the required memory internally if required.

2.3 New methods of the MaterialDataManager class

The following methods has been added to the MaterialDataManager class:

• setThreadSafe: set if the MaterialDataManager must take care of thread-safety. This mostly affects member functions allocating memory. Note that thread-safety mostly refers to the standard way of handling threads, so no thread-safety guarantees are provided if other threading libraries/frameworks (such as OpenMP) are used.
• allocateArrayOfTangentOperatorBlocks: allocate the memory associated with the tangent operator blocks.
• useExternalArrayOfTangentOperatorBlocks: use an externally allocated memory to store the tangent operator blocks.
• releaseArrayOfTangentOperatorBlocks: release the memory associated with the tangent operator blocks.
• allocateArrayOfSpeedOfSounds: allocate the memory associated with thespeed of sounds.
• useExternalArrayOfSpeedOfSounds: use an externally allocated memory to store thespeed of sounds.
• releaseArrayOfSpeedOfSounds: release the memory associated with thespeed of sounds.
• getBehaviourIntegrationWorkSpace: return a workspace associated with the behaviour. This method returns a object per thread if thread-safety is ensured by the MaterialDataManager class. This workspace is hold internally. Memory associated with this workspace can be released by the releaseBehaviourIntegrationWorkspaces method.
• releaseBehaviourIntegrationWorkspaces: clear behaviour integration workspaces.

2.4 Enhancements to the behaviour integration

2.4.1 Type of behaviour integration to be performed when using the BehaviourDataView directly

If K[0] is greater than 50, the speed of sound must be computed.

Let Ke be equal to:

• K[0] - 100 if K[0] is greater than 50
• K[0] otherwise.

If Ke is negative, only the prediction operator is computed and no behaviour integration is performed.

Ke has the following meaning:

• if Ke is lower than -2.5, the tangent operator must be computed.
• if Ke is in [-2.5:-1.5]: the secant operator must be computed.
• if Ke is in [-1.5:-0.5]: the elastic operator must be computed.
• if Ke is in [-0.5:0.5]: the behaviour integration is performed, but no stiffness matrix is computed.
• if Ke is in [0.5:1.5]: the behaviour integration is performed and the elastic operator must be computed.
• if Ke is in [1.5:2.5]: the behaviour integration is performed and the secant operator must be computed.
• if Ke is in [2.5:3.5]: the behaviour integration is performed and the secant operator must be computed.
• if Ke is greater than 3.5, the behaviour integration is performed and the consistent tangent operator must be computed.

2.4.2 The BehaviourIntegrationOptions class

New overloads of the integrate functions (See Section 2.4.4) use a new data structure called BehaviourIntegrationOptions to specify the kind of integration to be used, rather than specifying an enumeration of the IntegrationType type.

The BehaviourIntegrationOptions currently has two data members:

• integration_type which is an enumeration of the IntegrationType type.
• compute_speed_of_sound (boolean). This boolean is false by default.

2.4.3 The BehaviourIntegrationResult and MultiThreadedBehaviourIntegrationResult classes

The new overloads of the integrate functions (See Section 2.4.4) may return an object of the type BehaviourIntegrationResult or and of the type MultiThreadedBehaviourIntegrationResult.

The BehaviourIntegrationResult contains the result of the integration on a single thread and contains the following data members:

• exit_status. This data member may have the following:
  • 1: the integration is successful
  • 0: the integration is successful, but a least one Gauss point reported that its result is not reliable. The meaning of unreliable results depends on the behaviour used.
  • -1: the behaviour integration has failed.
• time_step_increase_factor. This data member gives a factor that can be used to increase or decrease the time step. This is mostly useful in case of behaviour integration failure.
• n, which gives the number of the integration point that failed or number of the last integration point that reported unreliable results. This information can be useful what element leads to difficulties regarding the behaviour integration.
• error_message. This data member contains an error message returned by the behaviour in case of failure of the behaviour integration, if any.

The MultiThreadedBehaviourIntegrationResult contains the result of the integration on multiple threads and contains the following data members:

• exit_status. This value is the minimum of the exit statuses of all threads.
• results which gives the behaviour integration results returned by the resolution on the various threads.

2.4.4 New overloads of the integrate functions

The following overloads of the integrate functions are now available:

/*!
 * \brief integrate the behaviour for a range of integration points.
 * \return the result of the behaviour integration.
 * \param[in,out] m: material data manager
 * \param[in] c: description of the operation to be performed
 * \param[in] dt: time step
 * \param[in] b: first index of the range
 * \param[in] e: last index of the range
 *
 * \note if required, the memory associated with the tangent operator blocks
 * is automatically allocated.
 */
BehaviourIntegrationResult
integrate(MaterialDataManager&,
          const BehaviourIntegrationOptions&,
          const real,
          const size_type,
          const size_type);
/*!
 * \brief integrate the behaviour over all integration points using a thread
 * pool to parallelize the integration.
 * \return the result of the behaviour integration.
 * \param[in,out] p: thread pool
 * \param[in,out] m: material data manager
 * \param[in] c: description of the operation to be performed
 * \param[in] dt: time step
 *
 * \note if required, the memory associated with the tangent operator blocks
 * is automatically allocated.
 */
MultiThreadedBehaviourIntegrationResult
integrate(mgis::ThreadPool&,
          MaterialDataManager&,
          const BehaviourIntegrationOptions&,
          const real);

2.5 API versioning

Version 3.4.1 of TFEL changed the API and ABI of the generic interface. This change may lead to conflicts with the API used by MGIS, notably errors of segmentation.

The API introduced in Version 3.4.1 of TFEL is said to match Version 1 of the generic behaviour interface. By convention, previous versions are associated with Version 0.

The behaviours generated by the generic interface now exports their API version. This piece of information can be retrieved by the getAPIVersion of the LibrariesManager class.

The load function uses this feature to check if the API of the behaviour conforms with the one expected by MGIS.

2.6 Enhancements to the C bindings

2.6.1 New function related to the mgis_bv_MaterialDataManagerInitializer data structure

The mgis_bv_material_data_manager_initializer_bind_speed_of_sound has been added. It allows to associate a memory area to the computation of the speed of the sound in the mgis_bv_MaterialDataManagerInitializer data structure.

2.6.2 New functions related to the mgis_bv_MaterialDataManager data structure

New functions mirroring the new methods introduced in Section 2.3 has been added:

• mgis_bv_material_data_manager_set_thread_safe
• mgis_bv_material_data_manager_allocate_array_of_tangent_operator_blocks
• mgis_bv_material_data_manager_use_external_array_of_tangent_operator_blocks
• mgis_bv_material_data_manager_release_array_of_tangent_operator_blocks
• mgis_bv_material_data_manager_allocate_array_of_speed_of_sounds
• mgis_bv_material_data_manager_use_external_array_of_speed_of_sounds
• mgis_bv_material_data_manager_release_array_of_speed_of_sounds

2.7 Enhancements to the mgis_behaviour module

2.7.1 New function related to the MaterialDataManagerInitializer data structure

The material_data_manager_initializer_bind_speed_of_sound has been added. It allows to associate a memory area to the computation of the speed of the sound in the mgis_bv_MaterialDataManagerInitializer data structure. ### New functions related to theMaterialDataManager` data structure

New functions mirroring the new methods introduced in Section 2.3 has been added:

• material_data_manager_set_thread_safe
• material_data_manager_allocate_array_of_tangent_operator_blocks
• material_data_manager_use_array_of_tangent_operator_blocks. Note that this function names differs from its C counterpart du to limitation to the length of Fortran functions.
• material_data_manager_release_array_of_tangent_operator_blocks
• material_data_manager_allocate_array_of_speed_of_sounds
• material_data_manager_use_array_of_speed_of_sounds. Note that this function names differs from its C counterpart for consistency with the material_data_manager_use_array_of_tangent_operator_blocks function.
• material_data_manager_release_array_of_speed_of_sounds

2.8 Enhancements to the python bindings

2.8.1 New methods in the MaterialDataManager class

The methods described in Section 2.3 has been wrapped to python.

2.8.2 Enhancements to the behaviour integration

The following classes and functions are now available in python:

• The BehaviourIntegrationOptions class, described in Section 2.4.2.
• The BehaviourIntegrationResult and MultiThreadedBehaviourIntegrationResult classes, described in Section 2.4.3.
• The integrate functions describe in Section 2.4.4.

2.8.3 Enhancements to the mgis.fenics module

• A set_internal_state_variables is now available to update the values of internal state variables at the beginning of the time step.
• linear_solver and preconditioner keywords are now available when performing projection in the ̀get_flux,get_gradientandget_state_variable` methods.

2.9 Enhancements to the Julia bindings

Support for recent version of CxxWrap has been added.

3 Issues solved

3.1 Issue #66: mgis.fenics: Missing update of external state variables when seen as UFL expression

Declaring external state variables as UFL expressions were not properly updated between time steps.

3.2 Issue #31: Sound Velocity management

The speed of sound can now be computed. See section 2.1.