Merge pull request #1051 from Antoinemarteau/small_doc_improvement

small TensorValues docu improvements

NEWS.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added Xiao-Gimbutas quadratures for simplices. Since PR[#1058](https://github.com/gridap/Gridap.jl/pull/1058).
+- Small improvements of the documentation of `Gridap.TensorValues`. Since PR[#1051](https://github.com/gridap/Gridap.jl/pull/1051).
 
 ### Fixed
 

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
+```
+

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).
 """

src/TensorValues/SymTracelessTensorValueTypes.jl

@@ -34,9 +34,6 @@ end
   Meta.parse("($str)")
 end
 
-"""
-Alias for [`SymTracelessTensorValue`](@ref).
-"""
 const QTensorValue = SymTracelessTensorValue
 
 ###############################################################

src/TensorValues/TensorValues.jl

@@ -1,75 +1,38 @@
 """
-This module provides the abstract interface `MultiValue` representing tensors
-that are also `Number`s, along with concrete implementations for the following
-tensors:
+Immutable tensor types for Gridap. The currently implemented tensor types are
 - 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)).
+- 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:
+Example usage:
 ```julia
+# create a 2D vector from components
+v = VectorValue(12,31)
+
 # 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
+# create 2x2 tensor from component tuple
 t = TensorValue( (1, 2, 3, 4) )
+# conversion to StaticArrays type
 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)
+# conversion from Array or StaticArray types, symmetric tensor types only store required components
+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)
+See the official documentation for more details.
 """
 module TensorValues