diff --git a/NEWS.md b/NEWS.md index f2973a265..dec364e56 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +### Added + +- Small improvements of the documentation of `Gridap.TensorValues`. Since PR[#1051](https://github.com/gridap/Gridap.jl/pull/1051). + ## [0.18.7] - 2024-10-8 ### Added diff --git a/docs/src/TensorValues.md b/docs/src/TensorValues.md index 3c0725777..6b04631cf 100644 --- a/docs/src/TensorValues.md +++ b/docs/src/TensorValues.md @@ -1,9 +1,151 @@ +# Gridap.TensorValues + ```@meta CurrentModule = Gridap.TensorValues ``` -# Gridap.TensorValues +This module provides the abstract interface `MultiValue` representing tensors +that are also `Number`s, along with concrete implementations for the following +tensors: +- 1st order [`VectorValue`](@ref), +- 2nd order [`TensorValue`](@ref), +- 2nd order and symmetric [`SymTensorValue`](@ref), +- 2nd order, symmetric and traceless [`SymTracelessTensorValue`](@ref), +- 3rd order [`ThirdOrderTensorValue`](@ref), +- 4th order and symmetric [`SymFourthOrderTensorValue`](@ref). + +## Generalities + +The main feature of this module is that the provided types do not extend from `AbstractArray`, but from `Number`! + +This allows one to work with them as if they were scalar values in broadcasted operations on arrays of `VectorValue` objects (also for `TensorValue` or `MultiValue` objects). For instance, one can perform the following manipulations: +```julia +# Assign a VectorValue to all the entries of an Array of VectorValues +A = zeros(VectorValue{2,Int}, (4,5)) +v = VectorValue(12,31) +A .= v # This is possible since VectorValue <: Number -```@autodocs -Modules = [TensorValues,] +# Broadcasting of tensor operations in arrays of TensorValues +t = TensorValue(13,41,53,17) # creates a 2x2 TensorValue +g = TensorValue(32,41,3,14) # creates another 2x2 TensorValue +B = fill(t,(1,5)) +C = inner.(g,B) # inner product of g against all TensorValues in the array B +@show C +# C = [2494 2494 2494 2494 2494] ``` + +To create a [`::MultiValue`](@ref) tensor from components, these should be given +as separate arguments or all gathered in a `tuple`. The order of the arguments +is the order of the linearized Cartesian indices of the corresponding array +(order of the `Base.LinearIndices` indices): +```julia +using StaticArrays +t = TensorValue( (1, 2, 3, 4) ) +ts= convert(SMatrix{2,2,Int}, t) +@show ts +# 2×2 SMatrix{2, 2, Int64, 4} with indices SOneTo(2)×SOneTo(2): +# 1 3 +# 2 4 +t2[1,2] == t[1,2] == 3 # true +``` +For symmetric tensor types, only the independent components should be given, see +[`SymTensorValue`](@ref), [`SymTracelessTensorValue`](@ref) and [`SymFourthOrderTensorValue`](@ref). + +A `MultiValue` can be created from an `AbstractArray` of the same size. If the +`MultiValue` type has internal constraints (e.g. symmetries), ONLY the required +components are picked from the array WITHOUT CHECKING if the given array +did respect the constraints: +```julia +SymTensorValue( [1 2; 3 4] ) # -> SymTensorValue{2, Int64, 3}(1, 2, 4) +SymTensorValue( SMatrix{2}(1,2,3,4) ) # -> SymTensorValue{2, Int64, 3}(1, 3, 4) +``` + +`MultiValue`s can be converted to static and mutable arrays types from +`StaticArrays.jl` using `convert` and [`mutable`](@ref), respectively. + +## Tensor types + +The following concrete tensor types are currently implemented: + +```@docs +VectorValue +TensorValue +SymTensorValue +SymTracelessTensorValue +ThirdOrderTensorValue +SymFourthOrderTensorValue +``` + +### Abstract tensor types + +```@docs +MultiValue +AbstractSymTensorValue +``` + +## Interface + +The tensor types implement methods for the following `Base` functions: `getindex`, `length`, `size`, `rand`, `zero`, `real`, `imag` and `conj`. + +`one` is also implemented in particular cases: it is defined for second +and fourth order tensors. For second order, it returns the identity tensor `δij`, +except `SymTracelessTensorValue` that does not implement `one`. For fourth order symmetric tensors, see [`one`](@ref). + +Additionally, the tensor types expose the following interface: + +```@docs +num_components +mutable +Mutable +num_indep_components +indep_comp_getindex +indep_components_names +change_eltype + +inner +dot +double_contraction +outer +``` + +### Other type specific interfaces + +#### For square second order tensors + +```@docs +det +inv +symmetric_part +``` + +#### For first order tensors + +```@docs +diagonal_tensor +``` + +#### For second and third order tensors + +```@docs +tr +``` + +#### For first and second order tensors + +```@docs +norm +meas +``` + +#### For `VectorValue` of length 2 and 3 + +```@docs +cross +``` + +#### For second order non-traceless and symmetric fourth order tensors + +```@docs +one +``` + diff --git a/src/TensorValues/MultiValueTypes.jl b/src/TensorValues/MultiValueTypes.jl index d95047aa7..cc73d31aa 100644 --- a/src/TensorValues/MultiValueTypes.jl +++ b/src/TensorValues/MultiValueTypes.jl @@ -11,7 +11,7 @@ Abstract type representing a multi-dimensional number value. The parameters are - `N` is the order of the tensor, the length of `S`, - `L` is the number of components stored internally. -`MultiValue`s are immutable. See [`TensorValues`](@ref) for more details on usage. +`MultiValue`s are immutable. """ abstract type MultiValue{S,T,N,L} <: Number end @@ -48,7 +48,7 @@ change_eltype(::Number,::Type{T2}) where {T2} = change_eltype(Number,T2) Mutable(T::Type{<:MultiValue}) -> ::Type{<:MArray} Mutable(a::MultiValue) -Return the concrete `MArray` type (defined by `StaticArrays.jl`) corresponding +Return the concrete mutable `MArray` type (defined by `StaticArrays.jl`) corresponding to the `MultiValue` type T or array size and type of `a`. See also [`mutable`](@ref). @@ -59,7 +59,7 @@ Mutable(::MultiValue) = Mutable(MultiValue) """ mutable(a::MultiValue) -Converts `a` into an array of type `MArray` defined by `StaticArrays.jl`. +Converts `a` into a mutable array of type `MArray` defined by `StaticArrays.jl`. See also [`Mutable`](@ref). """ diff --git a/src/TensorValues/SymTracelessTensorValueTypes.jl b/src/TensorValues/SymTracelessTensorValueTypes.jl index 9e3ddfa03..c872641cd 100644 --- a/src/TensorValues/SymTracelessTensorValueTypes.jl +++ b/src/TensorValues/SymTracelessTensorValueTypes.jl @@ -34,9 +34,6 @@ end Meta.parse("($str)") end -""" -Alias for [`SymTracelessTensorValue`](@ref). -""" const QTensorValue = SymTracelessTensorValue ############################################################### diff --git a/src/TensorValues/TensorValues.jl b/src/TensorValues/TensorValues.jl index 11972a83d..5985195dc 100644 --- a/src/TensorValues/TensorValues.jl +++ b/src/TensorValues/TensorValues.jl @@ -1,75 +1,5 @@ """ -This module provides the abstract interface `MultiValue` representing tensors -that are also `Number`s, along with concrete implementations for the following -tensors: -- 1st order [`VectorValue`](@ref), -- 2nd order [`TensorValue`](@ref), -- 2nd order and symmetric [`SymTensorValue`](@ref), -- 2nd order, symmetric and traceless [`SymTracelessTensorValue`](@ref), -- 3rd order [`ThirdOrderTensorValue`](@ref), -- 4th order and symmetric [`SymFourthOrderTensorValue`](@ref)). - -## Why - -The main feature of this module is that the provided types do not extend from `AbstractArray`, but from `Number`! - -This allows one to work with them as if they were scalar values in broadcasted operations on arrays of `VectorValue` objects (also for `TensorValue` or `MultiValue` objects). For instance, one can perform the following manipulations: -```julia -# Assign a VectorValue to all the entries of an Array of VectorValues -A = zeros(VectorValue{2,Int}, (4,5)) -v = VectorValue(12,31) -A .= v # This is possible since VectorValue <: Number - -# Broadcasting of tensor operations in arrays of TensorValues -t = TensorValue(13,41,53,17) # creates a 2x2 TensorValue -g = TensorValue(32,41,3,14) # creates another 2x2 TensorValue -B = fill(t,(1,5)) -C = inner.(g,B) # inner product of g against all TensorValues in the array B -@show C -# C = [2494 2494 2494 2494 2494] -``` - -To create a variable of type [`MultiValue`](@ref) from components, these should be given -as separate arguments or all gathered in a `tuple`. The order of the arguments -is the order of the linearized Cartesian indices of the corresponding array -(order of the [`LinearIndices`](@ref) indices): -```julia -using StaticArrays -t = TensorValue( (1, 2, 3, 4) ) -ts= convert(SMatrix{2,2,Int}, t) -@show ts -# 2×2 SMatrix{2, 2, Int64, 4} with indices SOneTo(2)×SOneTo(2): -# 1 3 -# 2 4 -t2[1,2] == t[1,2] == 3 # true -``` -For symetric tensor types, only the independent components should be given, see -[`SymTensorValue`](@ref), [`SymTracelessTensorValue`](@ref) and [`SymFourthOrderTensorValue`](@ref). - -A `MultiValue` can be created from an `AbstractArray` of the same size. If the -`MultiValue` type has internal constraints (e.g. symmetries), ONLY the required -components are picked from the array WITHOUT CHECKING if the given array -did respect the constraints: -```julia -SymTensorValue( [1 2; 3 4] ) # -> SymTensorValue{2, Int64, 3}(1, 2, 4) -SymTensorValue( SMatrix{2}(1,2,3,4) ) # -> SymTensorValue{2, Int64, 3}(1, 3, 4) -``` - -`MultiValue`s can be converted to static and mutable arrays types from -`StaticArrays.jl` using `convert` and [`mutable`](@ref), respectively. - -The concrete `MultiValue` types implement methods for the following -`Base` functions: `length`, `size`, `rand`, `zero`, `real`, `imag` and -`conj`. - -`one` is also implemented in particular cases, it is defined for second -and fourth order tensors. For second order, it returns the identity tensor `δij`, -for fourth order, see [`one`](@ref). `SymTracelessTensorValue` does not implement -`one`. - -The exported names are: - -$(EXPORTS) +Immutable tensor types for Gridap. """ module TensorValues