Merge pull request #553 from thelfer/552-mfront-document-the-integrat…

…or-code-block

552 mfront document the integrator code block

docs/mfront/CMakeLists.txt

@@ -171,6 +171,16 @@ install_mfront_desc2(Model GlobalParameter)
 install_mfront_desc2(Model LocalParameter)
 install_mfront_desc2(Model Model)
 install_mfront_desc2(Model Output)
+install_mfront_desc2(Default Integrator)
+install_mfront_desc2(ImplicitGenericBehaviour Integrator)
+install_mfront_desc2(DefaultCZM Integrator)
+install_mfront_desc2(DefaultGenericBehaviour Integrator)
+install_mfront_desc2(Implicit Integrator)
+install_mfront_desc2(ImplicitFiniteStrain Integrator)
+install_mfront_desc2(ImplicitII Integrator)
+install_mfront_desc2(Model Integrator)
+install_mfront_desc2(ImplicitCZM Integrator)
+install_mfront_desc2(DefaultFiniteStrain Integrator)
 
 install_mfront_desc2(bricks StandardElasticity)
 install_mfront_desc2(bricks DDIF2)

docs/mfront/Default/Integrator.md

@@ -0,0 +1,48 @@
+The `@Integrator` keyword allows the user to compute:
+
+- the evolution of the state variables and auxiliary state variables,
+- the value of the stress at the end of the time step,
+- the consistent tangent operator, if any of the
+  @ProvidesSymmetricTangentOperator or @ProvidesTangentOperator was
+  used.
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- sig is initialized by value of the stress at the beginning of the time
+  step. This value must be updated.
+- eto represents the total strain at the beginning of the time step and deto
+  represents its increment (constant over the time step).
+- for any internal variable Y (declared by the @StateVariable keyword),
+  Y represents its value at the beginning of the time step. The
+  increment of Y, represented by the variable dY, must be computed.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step. This value must be updated.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+If the consistent tangent operator is to be computed, the variable Dt is
+available. The computeTangentOperator_ boolean value states if the the
+computation of the tangent operator has been requested by the calling
+solver. The smt variable (stiffness matrix type) contains the kind of
+tangent operator requested.
+
+
+## Notes
+
+The difference between a state variable and an auxiliary state variable
+lies in the fact that the increment is defined for the state variable.
+This increment is used to update the state variable **after** the
+execution of the @Integrator code block.
+
+By default, the temperature T is automatically declared as the first
+external state variable.
+
+The consistent tangent operator can also be computed in the
+@TangentOperator code block. However, computing the consistent tangent
+operator in the @Integrator code block is often more convenient.

docs/mfront/DefaultCZM/Integrator.md

@@ -0,0 +1,51 @@
+The `@Integrator` keyword allows the user to compute:
+
+- the evolution of the state variables and auxiliary state variables,
+- the value of the stress at the end of the time step,
+- the consistent tangent operator, if any of the
+  @ProvidesSymmetricTangentOperator or @ProvidesTangentOperator was
+  used.
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- t is initialized by value of the cohesive force at the beginning of
+  the time step. This value must be updated. t is automatically
+  decomposed in its normal part t_n (scalar) and its tangential part t_t
+  (vectorial).
+- u represents the opening displacement the beginning of the time step and
+  du represents its increment (constant over the time step). u is
+  automatically decomposed in its normal part u_n (scalar) and its
+  tangential part u_t (vectorial).
+- for any internal variable Y (declared by the @StateVariable keyword),
+  Y represents its value at the beginning of the time step. The
+  increment of Y, represented by the variable dY, must be computed.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step. This value must be updated.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+If the consistent tangent operator is to be computed, the variable Dt is
+available. The computeTangentOperator_ boolean value states if the the
+computation of the tangent operator has been requested by the calling
+solver. The smt variable (stiffness matrix type) contains the kind of
+tangent operator requested.
+
+## Notes
+
+The difference between a state variable and an auxiliary state variable
+lies in the fact that the increment is defined for the state variable.
+This increment is used to update the state variable **after** the
+execution of the @Integrator code block.
+
+By default, the temperature T is automatically declared as the first
+external state variable.
+
+The consistent tangent operator can also be computed in the
+@TangentOperator code block. However, computing the consistent tangent
+operator in the @Integrator code block is often more convenient.

docs/mfront/DefaultFiniteStrain/Integrator.md

@@ -0,0 +1,36 @@
+The `@Integrator` keyword allows the user to compute:
+
+- the evolution of the state variables and auxiliary state variables,
+- the value of the stress at the end of the time step.
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- sig is initialized by value of the Cauchy stress at the beginning of
+  the time step. This value must be updated.
+- F0 represents the deformation gradient at the beginning of the time
+  step and F1 represents the deformation gradient at the end of the time
+  step.
+- for any internal variable Y (declared by the @StateVariable
+  keyword), Y represents its value at the beginning of
+  the time step. The increment of Y, represented by the variable dY,
+  must be computed.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step. This value must be updated.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+## Notes
+
+The difference between a state variable and an auxiliary state variable
+lies in the fact that the increment is defined for the state variable.
+This increment is used to update the state variable **after** the
+execution of the @Integrator code block.
+
+By default, the temperature T is automatically declared as the first
+external state variable.

docs/mfront/DefaultGenericBehaviour/Integrator.md

@@ -0,0 +1,51 @@
+The `@Integrator` keyword allows the user to compute:
+
+- the evolution of the state variables and auxiliary state variables,
+- the value of the stress at the end of the time step,
+- the consistent tangent operator, if any of the
+  @ProvidesSymmetricTangentOperator or @ProvidesTangentOperator was
+  used.
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- for any thermodynamic force thf (declared using the
+  @ThermodynamicForce keyword), thf represents the value of the
+  thermodynamic force at the beginning of the time step. This value must
+  be updated.
+- for any gradient g (declared using the @Gradient keyword), g
+  represents the value of the gradient the beginning of the time step
+  and dg represents its increment (constant over the time step).
+- for any internal variable Y (declared using the @StateVariable
+  keyword), Y represents its value at the beginning of the time step.
+  The increment of Y, represented by the variable dY, must be computed.
+- for any auxiliary internal variable Y (declared using the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step. This value must be updated.
+- for any external variable V (declared using the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+If the consistent tangent operator is to be computed, the variable Dt is
+available. The computeTangentOperator_ boolean value states if the the
+computation of the tangent operator has been requested by the calling
+solver. The smt variable (stiffness matrix type) contains the kind of
+tangent operator requested.
+
+
+## Notes
+
+The difference between a state variable and an auxiliary state variable
+lies in the fact that the increment is defined for the state variable.
+This increment is used to update the state variable **after** the
+execution of the @Integrator code block.
+
+By default, the temperature T is automatically declared as the first
+external state variable.
+
+The consistent tangent operator can also be computed in the
+@TangentOperator code block. However, computing the consistent tangent
+operator in the @Integrator code block is often more convenient.

docs/mfront/Implicit/Integrator.md

@@ -0,0 +1,45 @@
+The `@Integrator` code block allows the user to construct a residual,
+and, depending on the algorihm used (selected by the @Algorithm
+keyword), its derivative, called the jacobian in the following which
+aims at determining the increments of the integration variables
+(integration variables are introduced either by the @IntegrationVariable
+or the @StateVariable keyword).
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- sig represents the updated stress at the middle of the time step (i.e.
+  at t + theta * dt) using the current estimate of the elastic strain
+  (calculated by the code provided after the @ComputeStress keyword);
+- eto represents the total strain at the beginning of the time step and deto
+  represents its increment (constant over the time step).
+- for any internal variable Y (introduced by the @StateVariable), Y
+  represents its value at the start of the time step;
+- for any integration variable (introduced either by the
+  @IntegrationVariable keyword or by the @StateVariable keyword) Y, dY
+  represents the current estimate of the increment of this variable over
+  the time step.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+fY is the part of the residual associated  to the integration variable Y.
+
+In the jacobian matrix is needed, dfY1_ddY2 is the block of the jacobian
+matrix corresponding to the derivative of fY1 (part of the residual
+associated with Y1) with respect to dY2 (increment of the Y2 integration
+variable).
+
+## Notes
+
+- For an integration variable Y declared by the @IntegrationVariable
+  keyword (and not introduced by the @StateVariable keyword), the
+  variable Y is defined by not initialized.
+- The residual can be accessed through the fzeros variable.
+- The jacobian matrix can be accessed through the jacobian variable.

docs/mfront/ImplicitCZM/Integrator.md

@@ -0,0 +1,46 @@
+The `@Integrator` code block allows the user to construct a residual,
+and, depending on the algorihm used (selected by the @Algorithm
+keyword), its derivative, called the jacobian in the following which
+aims at determining the increments of the integration variables
+(integration variables are introduced either by the @IntegrationVariable
+or the @StateVariable keyword).
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- t is the current estimate of the cohesive force at the middle of the
+  time step (at t + theta * dt), as computed by the
+  @ComputeCohesiveForce code block. t is automatically decomposed in its
+  normal part t_n (scalar) and its tangential part t_t (vectorial).
+- u represents the opening displacement the beginning of the time step and
+  du represents its increment (constant over the time step). u is
+  automatically decomposed in its normal part u_n (scalar) and its
+  tangential part u_t (vectorial).
+- for any integration variable (introduced either by the
+  @IntegrationVariable keyword or by the @StateVariable keyword) Y, dY
+  represents the current estimate of the increment of this variable over
+  the time step.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+fY is the part of the residual associated  to the integration variable Y.
+
+In the jacobian matrix is needed, dfY1_ddY2 is the block of the jacobian
+matrix corresponding to the derivative of fY1 (part of the residual
+associated with Y1) with respect to dY2 (increment of the Y2 integration
+variable).
+
+## Notes
+
+- For an integration variable Y declared by the @IntegrationVariable
+  keyword (and not introduced by the @StateVariable keyword), the
+  variable Y is defined by not initialized.
+- The residual can be accessed through the fzeros variable.
+- The jacobian matrix can be accessed through the jacobian variable.

docs/mfront/ImplicitFiniteStrain/Integrator.md

@@ -0,0 +1,41 @@
+The `@Integrator` code block allows the user to construct a residual,
+and, depending on the algorihm used (selected by the @Algorithm
+keyword), its derivative, called the jacobian in the following which
+aims at determining the increments of the integration variables
+(integration variables are introduced either by the @IntegrationVariable
+or the @StateVariable keyword).
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- F0 represents the deformation gradient at the beginning of the time
+  step and F1 represents the deformation gradient at the end of the time
+  step.
+- for any integration variable (introduced either by the
+  @IntegrationVariable keyword or by the @StateVariable keyword) Y, dY
+  represents the current estimate of the increment of this variable over
+  the time step.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+fY is the part of the residual associated  to the integration variable Y.
+
+In the jacobian matrix is needed, dfY1_ddY2 is the block of the jacobian
+matrix corresponding to the derivative of fY1 (part of the residual
+associated with Y1) with respect to dY2 (increment of the Y2 integration
+variable).
+
+## Notes
+
+- For an integration variable Y declared by the @IntegrationVariable
+  keyword (and not introduced by the @StateVariable keyword), the
+  variable Y is defined by not initialized.
+- The residual can be accessed through the fzeros variable.
+- The jacobian matrix can be accessed through the jacobian variable.

docs/mfront/ImplicitGenericBehaviour/Integrator.md

@@ -0,0 +1,48 @@
+The `@Integrator` code block allows the user to construct a residual,
+and, depending on the algorihm used (selected by the @Algorithm
+keyword), its derivative, called the jacobian in the following which
+aims at determining the increments of the integration variables
+(integration variables are introduced either by the @IntegrationVariable
+or the @StateVariable keyword).
+
+## Specific conventions 
+
+
+The following conventions apply: 
+
+- for any thermodynamic force thf (declared using the
+  @ThermodynamicForce keyword), thf represents the value of the
+  thermodynamic force at the the middle of the time step (i.e.
+  at t + theta * dt) calculated using the @ComputeThermodynamicForce
+  code block.
+- for any gradient g (declared using the @Gradient keyword), g
+  represents the value of the gradient the beginning of the time step
+  and dg represents its increment (constant over the time step).
+- for any internal variable Y (introduced by the @StateVariable), Y
+  represents its value at the start of the time step;
+- for any integration variable (introduced either by the
+  @IntegrationVariable keyword or by the @StateVariable keyword) Y, dY
+  represents the current estimate of the increment of this variable over
+  the time step.
+- for any auxiliary internal variable Y (declared by the
+  @AuxiliaryStateVariable keyword), Y represents its value at the
+  beginning of the time step.
+- for any external variable V (declared by the @ExternalStateVariable
+  keyword), V represents its value at the beginning of the time step and
+  dV represents its increment over the time step (constant over the time
+  step).
+
+fY is the part of the residual associated  to the integration variable Y.
+
+In the jacobian matrix is needed, dfY1_ddY2 is the block of the jacobian
+matrix corresponding to the derivative of fY1 (part of the residual
+associated with Y1) with respect to dY2 (increment of the Y2 integration
+variable).
+
+## Notes
+
+- For an integration variable Y declared by the @IntegrationVariable
+  keyword (and not introduced by the @StateVariable keyword), the
+  variable Y is defined by not initialized.
+- The residual can be accessed through the fzeros variable.
+- The jacobian matrix can be accessed through the jacobian variable.