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!

[mipals]

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 guess it is a matter of style for 2nd oder stuff. The main reason that I prefer the linear algebra approach is that you in most cases end up having to solve a linear system of equations, and using indices sort of obfuscates the way there (at least for the simpler problems that I have solved).

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

Yeah, I saw that page. My main problem is that the $\otimes$ symbol is on both sides of the equation, which mean that on its own it does not really define anything. However after reading the section on index notation, which is linked to in the start of the page, things become more clear. Note that off course you should expect the reader to go through the pages "linearly", but I skipped ahead because Fredrik linked to that section. Lastly, I slightly disagree with the statement that the product do not "do" anything", I think I get the sentiment, but $A\otimes B$ is quite a different object than $A$ and $B$ whereas with matrices $AB$ is still just a matrix.

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.

I find that reasonable.

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!

I am still just learning all this tensor stuff, but maybe if I at some point get more comfortable with it I will do that 😄