Clearing things in the `FEValues` section of the documentation

[mipals]

Hi there,

I am reading through some of the documentation and the section FEValues was not so straightforward to read for somebody coming from a background where tensors are not common. I think most of my issues might be related to that, but I think it does not hurt to make the text more clear as others might have the same issues.

For context I am mostly used to the vector forms (which should be equivalent with your definitions)

$$ \mathbf{x}(\mathbf{\xi}) = \mathbf{X}\mathbf{N}^g(\mathbf{\xi}) $$

$$ \mathbf{J}(\xi) = \nabla^\top \left(\mathbf{X}\mathbf{N}^g(\xi)\right) = \mathbf{X}\left(\nabla^\top\mathbf{N}(\xi)\right) $$

I guess the introduction of the Hessian (or in general higher order things) is why tensors become useful.

My main issues were

1. The operators $\otimes$ and $\cdot$ are not properly introduced. I am still not sure if they're the standard Kronecker and dot products or not. From context I think that they're not - But somehow they're still very similar. Having a small definition or a link to somewhere were one could read more would be very useful.
2. Multivariate calculus can be confusing and its not made easier by different conventions (https://en.wikipedia.org/wiki/Matrix_calculus#Layout_conventions). Maybe give some indication of which conventions is used and stick to it. For what it is worth I do actually think that you are being consistent, but it could be a source of confusion. (For me this was mostly an issue when I thought $\otimes$ and $\cdot$ were the standard Kronecker and dot products since things only sort of made sense if you had used inconsistent derivative notation.)

In addition there are some non obvious things in the otherwise pretty useful walkthrough example:

1. The geometric shape functions were introduced as $N^g(\xi)$ but in the code they are called $M(\xi)$.
2. cv in the Ferrite.reinit! function is actually called simple_cv later while cv is something else.

Cheers, Mikkel

[fredrikekre]

Just for reference, the page you are refering to is https://ferrite-fem.github.io/Ferrite.jl/dev/topics/FEValues/ (?).

The operators ⊗ and ⋅ are not properly introduced. I am still not sure if they're the standard Kronecker and dot products or not.

⊗ is the open product (or outer/dyadic product) and ⋅ the dot product (or single contraction). As you suggest, could probably be useful to link to something like https://knutam.github.io/tensors/ on this page (incidentally, @KnutAM have authored both this page and most of the stuff in the FEValues docs). The documentation for Tensors.jl could perhaps also be useful (https://ferrite-fem.github.io/Tensors.jl/stable/).

[KnutAM]

Thank you for the good suggestions!

• Yes, probably good to link to https://knutam.github.io/tensors/Theory/TensorDifferentiation/ then.
• Renaming $\hat{N}^g$ to $\hat{M}$ makes sense IMO to be consistent with Ferrite src
• Would renaming the created cv::CellValues to builtin_cv::CellValues and keeping simple_cv::SimpleCellValues make it clearer?

[mipals]

Yes, that is the page I am referring to.

The note from Knut clear up some things, and I think that should be referenced 👍 I am still not sure what tensor algebra brings that being consistent with the linear algebra doesn't (This is not meant as a criticism - I am sure that there are good reasons, but I am trying to find them and understand. My hunch is that it has to do with higher order things.)

• I do not think the page knutam.github.io/tensors/Theory/TensorDifferentiation is enough as it does not introduce the notation properly. Thinking e.g. that $\otimes$ is the Kronecker product will be confusing as e.g. in (2) we have that $e_i\otimes e_j=\text{kron}(e_i,e_j^\top)$.
• I think any renaming would suffice as long as the naming inside of the function is consistent with the variable definitions outside of the function.

A side note here: I noticed that the gradient as introduced here (https://knutam.github.io/tensors/Theory/TensorIntro/) is a column vector in (3) but subsequently it is a row vector in (4). I guess these "transposing errors" are what you're trying to get around by introducing the tensor notation.

[KnutAM]

I am still not sure what tensor algebra brings that being consistent with the linear algebra doesn't (This is not meant as a criticism - I am sure that there are good reasons, but I am trying to find them and understand. My hunch is that it has to do with higher order things.)

Yes, for tensors higher than 2nd order, I find it hard to use linear algebra notation. Even for 2nd order objects, I prefer the tensor notation to avoid the transposition issues that you mentioned (which is what I try to motivate on the "TensorIntro" page).

I do not think the page knutam.github.io/tensors/Theory/TensorDifferentiation is enough as it does not introduce the notation properly. Thinking e.g. that $\otimes$ is the Kronecker product will be confusing as e.g. in (2) we have that $e_i\otimes e_j=\text{kron}(e_i,e_j^\top)$.

The dyadic product is defined here: https://knutam.github.io/tensors/Theory/TensorAlgebra/#open_product_otimes. Suggestions for improvements to that description are welcome!

I think any renaming would suffice as long as the naming inside of the function is consistent with the variable definitions outside of the function.

I would disagree here as many students struggle with separating the name outside and inside functions. But I agree that the current use of cv::SimpleCellValues inside the function and then cv::CellValues outside can be confusing, so I'd suggest the change above then, but keeping cv::SimpleCellValues inside.

A side note here: I noticed that the gradient as introduced here (https://knutam.github.io/tensors/Theory/TensorIntro/) is a column vector in (3) but subsequently it is a row vector in (4).

Thanks, I missed that there should be a transpose of the entire expression there!

In general, if you are interested, I'm very happy to take suggestions for improvements to the description on the tensors page! Feel free to open issues and PRs!