From c2f0faae15f80ea5e79e7d781c773c1b5a50b387 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sat, 2 Dec 2023 14:48:51 +0000 Subject: [PATCH] build based on 1e22571 --- previews/PR10/.documenter-siteinfo.json | 2 +- previews/PR10/differentiation/index.html | 4 ++-- previews/PR10/index.html | 6 +++--- previews/PR10/stressiterations/index.html | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/previews/PR10/.documenter-siteinfo.json b/previews/PR10/.documenter-siteinfo.json index 4032538..96c1706 100644 --- a/previews/PR10/.documenter-siteinfo.json +++ b/previews/PR10/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-02T14:14:41","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-02T14:48:48","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/previews/PR10/differentiation/index.html b/previews/PR10/differentiation/index.html index 00223c8..183f7ac 100644 --- a/previews/PR10/differentiation/index.html +++ b/previews/PR10/differentiation/index.html @@ -1,5 +1,5 @@ -Differentiation · MaterialModelsBase.jl

Differentation of a material

MaterialModelsBase.get_num_tensorcomponents — Function
get_num_tensorcomponents(::AbstractMaterial)

Returns the number of independent components for the given material.

  • If the material works with the small strain tensor and Cauchy stress, return 6 (default)
  • If the material works with the deformation gradient and the 1st Piola-Kirchhoff stress, return 9
  • If the material is a cohesive material working with vectors, return the number of vector components (e.g. 3)

Defaults to 6 if not overloaded

source
MaterialModelsBase.get_num_statevars — Function
get_num_statevars(m::AbstractMaterial)

Return the number of state variables. A tensorial state variable should be counted by how many components it has. E.g. if a state consists of one scalar and one symmetric 2nd order tensor, get_num_statevars should return 7 (if the space dimension is 3).

Defaults to 0 if not overloaded

source
MaterialModelsBase.material2vector! — Function
material2vector!(v::AbstractVector, m::AbstractMaterial)

Put the material parameters of m into the vector m. This is typically used when the parameters should be fitted.

source
MaterialModelsBase.material2vector — Function
material2vector(m::AbstractMaterial)

Out-of place version of material2vector!. Given get_num_params, this function does not need to be overloaded unless another datatype than Float64 should be used.

source
MaterialModelsBase.MaterialDerivatives — Type
MaterialDerivatives(m::AbstractMaterial)

A struct that saves all derivative information using a Matrix{T} for each derivative, where T=get_parameter_type(m). The dimensions are obtained from get_num_tensorcomponents, get_num_statevars, and get_num_params. The values should be updated in differentiate_material! by direct access of the fields, where σ is the stress, ϵ the strain, s and ⁿs are the current and old state variables, and p the material parameter vector.

  • dσdϵ
  • dσdⁿs
  • dσdp
  • dsdϵ
  • dsdⁿs
  • dsdp
source
MaterialModelsBase.allocate_differentiation_output — Function
allocate_differentiation_output(::AbstractMaterial)

When calculating the derivatives of a material, it can often be advantageous to have additional information from the solution procedure inside material_response. This can be obtained via an AbstractExtraOutput, and allocate_differentiation_output provides a standard function name for what extra_output::AbstractExtraOutput that should be allocated in such cases.

Defaults to an NoExtraOutput if not overloaded.

source
MaterialModelsBase.differentiate_material! — Function
differentiate_material!(
+Differentiation · MaterialModelsBase.jl
Differentation of a material
MaterialModelsBase.get_num_tensorcomponents — Function
get_num_tensorcomponents(::AbstractMaterial)
Returns the number of independent components for the given material. 
  • If the material works with the small strain tensor and Cauchy stress, return 6 (default)
  • If the material works with the deformation gradient and the 1st Piola-Kirchhoff stress, return 9
  • If the material is a cohesive material working with vectors, return the number of vector components (e.g. 3)
Defaults to 6 if not overloaded
source
MaterialModelsBase.get_num_statevars — Function
get_num_statevars(m::AbstractMaterial)
Return the number of state variables. A tensorial state variable should be counted by how many components it has.  E.g. if a state consists of one scalar and one symmetric 2nd order tensor, get_num_statevars should return 7 (if the space dimension is 3).
Defaults to 0 if not overloaded
source
MaterialModelsBase.material2vector! — Function
material2vector!(v::AbstractVector, m::AbstractMaterial)
Put the material parameters of m into the vector m.  This is typically used when the parameters should be fitted.
source
MaterialModelsBase.material2vector — Function
material2vector(m::AbstractMaterial)
Out-of place version of material2vector!. Given get_num_params, this function does not need to be overloaded unless another datatype than Float64 should be used.
source
MaterialModelsBase.MaterialDerivatives — Type
MaterialDerivatives(m::AbstractMaterial)
A struct that saves all derivative information using a Matrix{T} for each derivative, where T=get_parameter_type(m). The dimensions are obtained from get_num_tensorcomponents,  get_num_statevars, and get_num_params. The values should be updated in differentiate_material! by direct access of the fields, where σ is the stress, ϵ the strain, s and ⁿs are the current  and old state variables, and p the material parameter vector.
  • dσdϵ
  • dσdⁿs
  • dσdp
  • dsdϵ
  • dsdⁿs
  • dsdp
source
MaterialModelsBase.allocate_differentiation_output — Function
allocate_differentiation_output(::AbstractMaterial)
When calculating the derivatives of a material, it can often be advantageous to have additional  information from the solution procedure inside material_response. This can be obtained via an  AbstractExtraOutput, and allocate_differentiation_output provides a standard function name  for what extra_output::AbstractExtraOutput that should be allocated in such cases.
Defaults to an NoExtraOutput if not overloaded. 
source
MaterialModelsBase.differentiate_material! — Function
differentiate_material!(
     diff::MaterialDerivatives, 
     m::AbstractMaterial, 
     ϵ::Union{SecondOrderTensor, Vec}, 
@@ -8,4 +8,4 @@
     cache::AbstractMaterialCache
     dσdϵ::AbstractTensor, 
     extra::AbstractExtraOutput
-    )
Calculate the derivatives and save them in diff, see MaterialDerivatives for a description of the fields in diff.
source

+    )

Calculate the derivatives and save them in diff, see MaterialDerivatives for a description of the fields in diff.

source
diff --git a/previews/PR10/index.html b/previews/PR10/index.html index 859010f..7b7d70b 100644 --- a/previews/PR10/index.html +++ b/previews/PR10/index.html @@ -24,6 +24,6 @@ Δt::Union{Number,Nothing}=nothing, cache::AbstractMaterialCache=allocate_material_cache(m), extras::AbstractExtraOutput=NoExtraOutput() - )

Calculate the stress/traction, stiffness and updated state variables for the material m, given the strain input strain.

Mandatory arguments

Optional positional arguments

When calling the function, the following arguments are optional. When implementing a material, it is not necessary to implement these defaults, but the method signature should allow all arguments to be compatible with libraries relying on the interface. Typically, this can done by using args..., e.g., material_response(m::MyMat, ϵ, state, args...)

Outputs

  1. stress, is the stress measure that is energy conjugated to the strain (2nd) input.
  2. stiffness, is the derivative of the stress output wrt. the strain input.
  3. new_state, are the updated state variables
Note

The state given as input should not be mutated. That is, someone calling material_response multiple times with the same input variables should get the same output each time.

Common strain and stress pairs are

source
MaterialModelsBase.material_response — Method
material_response(stress_state::AbstractStressState, m::AbstractMaterial, args...)

To be able to use material models implemented for 3d stress and strain states in lower-dimensional simulations, such as 2d plane stress, MaterialModelsBase.jl provides a set of stress states. For some states, such as plane stress, iterations will be performed to find the correct state. For other states, such as plane strain, the input is only padded with zeros and the out-of-plane components are removed from the output.

For someone implementing a material model, it is also possible to use dispatch on both the stress state and the material to provide an efficient implementation of a reduced stress state. Note that the interface expects the full strain tensor to be given as a fourth output in this case, but it is optional to implement this but such a deviation should be documented as it could cause problems for users of the material implementation.

The arguments are the same as for material_response(::AbstractMaterial). However, both a full and reduced strain input is accepted. For a full strain input, the out-of-plane components are used as an initial guess. For all cases, the full strain tensor giving the desired reduced response is given as a 4th output.

See also ReducedStressState.

source

State variables

To support state variables define

MaterialModelsBase.initial_material_state — Function
initial_material_state(m::AbstractMaterial)

Return the (default) initial state::AbstractMaterialState of the material m.

Defaults to the empty NoMaterialState()

source

Cache

It is possible to pre-allocate a cache to avoid allocations during the material model calculation, to do this define

MaterialModelsBase.allocate_material_cache — Function
allocate_material_cache(m::AbstractMaterial)

Return a cache::AbstractMaterialCache that can be used when calling the material to reduce allocations

Defaults to the empty NoMaterialCache()

source

Extra outputs

In some cases, it is necessary to define additional outputs to provide slight variations in the material calculation. In this case, a mutable input can be given as

MaterialModelsBase.AbstractExtraOutput — Type
AbstractExtraOutput()

By allocating an AbstractExtraOutput type, this type can be mutated to extract additional information from the internal calculations in material_response only in cases when this is desired. E.g., when calculating derivatives or for multiphysics simulations. The concrete NoExtraOutput<:AbstractExtraOutput exists for the case when no additional output should be calculated.

source

Exceptions

Finally, the following exceptions are included

MaterialModelsBase.MaterialConvergenceError — Type
MaterialConvergenceError

Abstract type that can be used to catch errors related to the material not converging.

source
MaterialModelsBase.NoLocalConvergence — Type
NoLocalConvergence(msg::String)
-NoLocalConvergence(args...)

Throw if the material_response routine doesn't converge internally. Other arguments than a single ::String, are converted to String with string

source
MaterialModelsBase.NoStressConvergence — Type
NoStressConvergence(msg::String)
-NoStressConvergence(args...)

This is thrown if the stress iterations don't converge, see Stress states Other arguments than a single ::String, are converted to String with string

source
+ )

Calculate the stress/traction, stiffness and updated state variables for the material m, given the strain input strain.

Mandatory arguments

Optional positional arguments

When calling the function, the following arguments are optional. When implementing a material, it is not necessary to implement these defaults, but the method signature should allow all arguments to be compatible with libraries relying on the interface. Typically, this can done by using args..., e.g., material_response(m::MyMat, ϵ, state, args...)

Outputs

  1. stress, is the stress measure that is energy conjugated to the strain (2nd) input.
  2. stiffness, is the derivative of the stress output wrt. the strain input.
  3. new_state, are the updated state variables
Note

The state given as input should not be mutated. That is, someone calling material_response multiple times with the same input variables should get the same output each time.

Common strain and stress pairs are

source
MaterialModelsBase.material_response — Method
material_response(stress_state::AbstractStressState, m::AbstractMaterial, args...)

To be able to use material models implemented for 3d stress and strain states in lower-dimensional simulations, such as 2d plane stress, MaterialModelsBase.jl provides a set of stress states. For some states, such as plane stress, iterations will be performed to find the correct state. For other states, such as plane strain, the input is only padded with zeros and the out-of-plane components are removed from the output.

For someone implementing a material model, it is also possible to use dispatch on both the stress state and the material to provide an efficient implementation of a reduced stress state. Note that the interface expects the full strain tensor to be given as a fourth output in this case, but it is optional to implement this but such a deviation should be documented as it could cause problems for users of the material implementation.

The arguments are the same as for material_response(::AbstractMaterial). However, both a full and reduced strain input is accepted. For a full strain input, the out-of-plane components are used as an initial guess. For all cases, the full strain tensor giving the desired reduced response is given as a 4th output.

See also ReducedStressState.

source

State variables

To support state variables define

MaterialModelsBase.initial_material_state — Function
initial_material_state(m::AbstractMaterial)

Return the (default) initial state::AbstractMaterialState of the material m.

Defaults to the empty NoMaterialState()

source

Cache

It is possible to pre-allocate a cache to avoid allocations during the material model calculation, to do this define

MaterialModelsBase.allocate_material_cache — Function
allocate_material_cache(m::AbstractMaterial)

Return a cache::AbstractMaterialCache that can be used when calling the material to reduce allocations

Defaults to the empty NoMaterialCache()

source

Extra outputs

In some cases, it is necessary to define additional outputs to provide slight variations in the material calculation. In this case, a mutable input can be given as

MaterialModelsBase.AbstractExtraOutput — Type
AbstractExtraOutput()

By allocating an AbstractExtraOutput type, this type can be mutated to extract additional information from the internal calculations in material_response only in cases when this is desired. E.g., when calculating derivatives or for multiphysics simulations. The concrete NoExtraOutput<:AbstractExtraOutput exists for the case when no additional output should be calculated.

source

Exceptions

Finally, the following exceptions are included

MaterialModelsBase.MaterialConvergenceError — Type
MaterialConvergenceError

Abstract type that can be used to catch errors related to the material not converging.

source
MaterialModelsBase.NoLocalConvergence — Type
NoLocalConvergence(msg::String)
+NoLocalConvergence(args...)

Throw if the material_response routine doesn't converge internally. Other arguments than a single ::String, are converted to String with string

source
MaterialModelsBase.NoStressConvergence — Type
NoStressConvergence(msg::String)
+NoStressConvergence(args...)

This is thrown if the stress iterations don't converge, see Stress states Other arguments than a single ::String, are converted to String with string

source
diff --git a/previews/PR10/stressiterations/index.html b/previews/PR10/stressiterations/index.html index 6c0eafd..ab1bb87 100644 --- a/previews/PR10/stressiterations/index.html +++ b/previews/PR10/stressiterations/index.html @@ -1,2 +1,2 @@ -Stress states · MaterialModelsBase.jl

Stress states

In many cases, the full 3d stress and strain states are not desired. In some cases, a specialized reduced material model can be written for these cases, but for advanced models this can be tedious. A stress state iteration procedure is therefore included in this package, since this does not interfere with the internal implementation of the material model.

It also allows custom implementations of specific materials for e.g. plane stress if desired.

The specific stress state is invoked by defining a stress state of type AbstractStressState, of which the following specific stress states are implemented:

MaterialModelsBase.FullStressState — Type
FullStressState()

Return the full stress state, without any constraints. Equivalent to not giving any stress state to the material_response function, except that when given, the full strain (given as input) is also an output which can be useful if required for consistency with the other stress states.

source
MaterialModelsBase.PlaneStrain — Type
PlaneStrain()

Plane strain such that if only 2d-components (11, 12, 21, and 22) are given, the remaining strain components are zero. The output is the reduced set, with the mentioned components. It is possible to give non-zero values for the other strain components, and these will be used for the material evaluation.

source
MaterialModelsBase.PlaneStress — Type
PlaneStress(; kwargs...)

Plane stress such that $\sigma_{33}=\sigma_{23}=\sigma_{13}=\sigma_{32}=\sigma_{31}=0$ The strain input should be at least 2d (components 11, 12, 21, and 22). A 3d input is also accepted and used as an initial guess for the unknown out-of-plane strain components.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.UniaxialStrain — Type
UniaxialStrain()

Uniaxial strain such that if only the 11-strain component is given, the remaining strain components are zero. The output is the reduced set, i.e. only the 11-stress-component. It is possible to give non-zero values for the other strain components, and these will be used for the material evaluation.

source
MaterialModelsBase.UniaxialStress — Type
UniaxialStress(; kwargs...)

Uniaxial stress such that $\sigma_{ij}=0 \forall (i,j)\neq (1,1)$ The strain input can be 1d (SecondOrderTensor{1}). A 3d input is also accepted and used as an initial guess for the unknown strain components.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.UniaxialNormalStress — Type
UniaxialNormalStress(; kwargs...)

This is a variation of the uniaxial stress state, such that only $\sigma_{22}=\sigma_{33}=0$ The strain input must be 3d, and the components $\epsilon_{22}$ and $\epsilon_{33}$ are used as initial guesses. This case is useful when simulating strain-controlled axial-shear experiments. Note that the stress and stiffness outputs are the 3d tensors, and that the stiffness is not modified to account for the stress constraints.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.GeneralStressState — Type
GeneralStressState(σ_ctrl::AbstractTensor{2,3,Bool}, σ::AbstractTensor{2,3,Bool}; kwargs...)

Construct a general stress state controlled by σ_ctrl whose component is true if that component is stress-controlled and false if it is strain-controlled. If stress-controlled, σ gives the value to which it is controlled. The current stress, for stress-controlled components can be updated by calling update_stress_state!(s::GeneralStressState, σ). Components in σ that are not stress-controlled are ignored.

Note that the stress and stiffness outputs are the 3d tensors, and that the stiffness is not modified to account for the stress constraints.

The optional keyword arguments are forwarded to IterationSettings.

source

To adjust the iteration parameters (number of iterations and tolerance) for stress states requiring iterations, such stress states contain an IterationSettings object,

MaterialModelsBase.IterationSettings — Type
IterationSettings(;tolerance=1e-8, max_iter=10)

Settings for stress iterations. Constructors for iterative stress states forwards given keyword arguments to this constructor and saves the result.

source

Reduced stress state wrapper

When used in finite element codes, it is often convenient to collect both the stress state and the material type into a single type that is passed to the element routine. The wrapper ReducedStressState is provided for that purpose.

MaterialModelsBase.ReducedStressState — Type
ReducedStressState(s::AbstractStressState, m::AbstractMaterial)

Creates a subtype of AbstractMaterial that wraps a stress state and a material, such that calls to material_response(w::ReducedStressState, args...) gives the same result as material_response(s, m, args...). Calls to initial_material_state, allocate_material_cache, get_num_tensorcomponents, get_num_statevars, get_num_params, get_parameter_type, material2vector!, material2vector, and allocate_differentiation_output are forwarded with m as the argument. vector2material returns ReducedStressState and is supported as well.

source
+Stress states · MaterialModelsBase.jl

Stress states

In many cases, the full 3d stress and strain states are not desired. In some cases, a specialized reduced material model can be written for these cases, but for advanced models this can be tedious. A stress state iteration procedure is therefore included in this package, since this does not interfere with the internal implementation of the material model.

It also allows custom implementations of specific materials for e.g. plane stress if desired.

The specific stress state is invoked by defining a stress state of type AbstractStressState, of which the following specific stress states are implemented:

MaterialModelsBase.FullStressState — Type
FullStressState()

Return the full stress state, without any constraints. Equivalent to not giving any stress state to the material_response function, except that when given, the full strain (given as input) is also an output which can be useful if required for consistency with the other stress states.

source
MaterialModelsBase.PlaneStrain — Type
PlaneStrain()

Plane strain such that if only 2d-components (11, 12, 21, and 22) are given, the remaining strain components are zero. The output is the reduced set, with the mentioned components. It is possible to give non-zero values for the other strain components, and these will be used for the material evaluation.

source
MaterialModelsBase.PlaneStress — Type
PlaneStress(; kwargs...)

Plane stress such that $\sigma_{33}=\sigma_{23}=\sigma_{13}=\sigma_{32}=\sigma_{31}=0$ The strain input should be at least 2d (components 11, 12, 21, and 22). A 3d input is also accepted and used as an initial guess for the unknown out-of-plane strain components.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.UniaxialStrain — Type
UniaxialStrain()

Uniaxial strain such that if only the 11-strain component is given, the remaining strain components are zero. The output is the reduced set, i.e. only the 11-stress-component. It is possible to give non-zero values for the other strain components, and these will be used for the material evaluation.

source
MaterialModelsBase.UniaxialStress — Type
UniaxialStress(; kwargs...)

Uniaxial stress such that $\sigma_{ij}=0 \forall (i,j)\neq (1,1)$ The strain input can be 1d (SecondOrderTensor{1}). A 3d input is also accepted and used as an initial guess for the unknown strain components.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.UniaxialNormalStress — Type
UniaxialNormalStress(; kwargs...)

This is a variation of the uniaxial stress state, such that only $\sigma_{22}=\sigma_{33}=0$ The strain input must be 3d, and the components $\epsilon_{22}$ and $\epsilon_{33}$ are used as initial guesses. This case is useful when simulating strain-controlled axial-shear experiments. Note that the stress and stiffness outputs are the 3d tensors, and that the stiffness is not modified to account for the stress constraints.

The optional keyword arguments are forwarded to IterationSettings.

source
MaterialModelsBase.GeneralStressState — Type
GeneralStressState(σ_ctrl::AbstractTensor{2,3,Bool}, σ::AbstractTensor{2,3,Bool}; kwargs...)

Construct a general stress state controlled by σ_ctrl whose component is true if that component is stress-controlled and false if it is strain-controlled. If stress-controlled, σ gives the value to which it is controlled. The current stress, for stress-controlled components can be updated by calling update_stress_state!(s::GeneralStressState, σ). Components in σ that are not stress-controlled are ignored.

Note that the stress and stiffness outputs are the 3d tensors, and that the stiffness is not modified to account for the stress constraints.

The optional keyword arguments are forwarded to IterationSettings.

source

To adjust the iteration parameters (number of iterations and tolerance) for stress states requiring iterations, such stress states contain an IterationSettings object,

MaterialModelsBase.IterationSettings — Type
IterationSettings(;tolerance=1e-8, max_iter=10)

Settings for stress iterations. Constructors for iterative stress states forwards given keyword arguments to this constructor and saves the result.

source

Reduced stress state wrapper

When used in finite element codes, it is often convenient to collect both the stress state and the material type into a single type that is passed to the element routine. The wrapper ReducedStressState is provided for that purpose.

MaterialModelsBase.ReducedStressState — Type
ReducedStressState(s::AbstractStressState, m::AbstractMaterial)

Creates a subtype of AbstractMaterial that wraps a stress state and a material, such that calls to material_response(w::ReducedStressState, args...) gives the same result as material_response(s, m, args...). Calls to initial_material_state, allocate_material_cache, get_num_tensorcomponents, get_num_statevars, get_num_params, get_parameter_type, material2vector!, material2vector, and allocate_differentiation_output are forwarded with m as the argument. vector2material returns ReducedStressState and is supported as well.

source