Adopt proper names for entities with different dimensions and codimensions

[KnutAM]

Many issues seem to stem from not having a clear distinction between dimension and codimension.

Adopting the correct names (ref defelement) in Ferrite would be a major change, especially since users would have to change from FaceValues / faceset / FaceIndex to FacetValues / facetset / FacetIndex.

However, it seems to have the benefit of making the code more understandable and extensible as we add more advanced features. It is notable that at least fenics adopts this defintion.

Ref discussions in #899, #767, #789 (and probably more).

Most user calls would occur during construction, so that a regular warning / upgrade error would be feasible for standard users. IMO this should happen before releasing 1.0 or not at all.

Edit: I earlier mistakenly assumed these names were part of the Ciarlet (1978) definitions, but couldn't find any references to this, and AFAIU now that only refers to the triplet $(\mathcal{R},\ \mathcal{V}, \mathcal{L})$ for the reference shape, interpolation space, and unknowns/nodal values which we implicitly already have. Changed the name to reflect this.

[fredrikekre]

Note that as a user you already have to update Face(Scalar|Vector)Values to FaceValues so changing to FacetValues wouldn't be more difficult.

[fredrikekre]

It would be visually a bit confusing to have both face and facet in exported names, but perhaps the face versions can be public but not exported?

[KnutAM]

True. I'm more concerned about facetset regarding readability and the change for users.
I'm not sure how often (I think not often) a user would need to interact with the face/edge items unless extending Ferrite functionality, so public but not exported sounds good to me.

[fredrikekre]

Perhaps we can just keep const faceset = facetset around and come up with another name to obtain specifically ND entities then?

[lijas]

One option would be to introduce the user function getboundaryset which is a bit more readable than getfacetset.
I also think it is possible to keep the name FaceValues, since a face is something that would have normal, which is what we want in both 2d and 3d problems (but we can also define const FacetValues = FaceValues for consistency.

[termi-official]

Thanks for putting together the issue Knut!

Most user calls would occur during construction, so that a regular warning / upgrade error would be feasible for standard users.

Can you elaborate what kind of warning/error path you have in mind?

One option would be to introduce the user function getboundaryset which is a bit more readable than getfacetset. I also think it is possible to keep the name FaceValues, since a face is something that would have normal, which is what we want in both 2d and 3d problems (but we can also define const FacetValues = FaceValues for consistency.

Let us think further about this naming. Regarding getboundaryset, would what would you expect to be returned by the function if we have the following scenario from #899, when we have mixed-dimensional elements attached to each other:

# 3 ____ 4  4
# |      |  |   
# |      |  | (Beam attached to face)    
# 1 ____ 2  2

Regarding FacetValues = FaceValues I think this would cause more harm than good, because it introduces an inconsistency in the naming.

[KnutAM]

Can you elaborate what kind of warning/error path you have in mind?

FaceValues(fqr, ip)
Error: FaceValues are deprecated, use FacetValues instead

addfaceset(grid, args...)
Error: addfaceset is deprecated, use addfacetset instead

getfaceset(grid, ...)
...

where we could also @warn instead of throwing an error, but not use @deprecated since that will not be visible for users running julia without explicit --depwarn=true. (But probably then not for getfaceset since that could happen in a loop and would flod the output with warnings). Similar for edgeset.

For FaceIndex and EdgeIndex I guess the const FaceIndex = FacetIndex approach could be used in a transition, but IMO better to break when releasing 1.0. Otherwise, when removed it would break for users with legacy code after a minor release.

[termi-official]

Can you elaborate what kind of warning/error path you have in mind?

FaceValues(fqr, ip)
Error: FaceValues are deprecated, use FacetValues instead

addfaceset(grid, args...)
Error: addfaceset is deprecated, use addfacetset instead

getfaceset(grid, ...)
...

where we could also @warn instead of throwing an error, but not use @deprecated since that will not be visible for users running julia without explicit --depwarn=true. (But probably then not for getfaceset since that could happen in a loop and would flod the output with warnings). Similar for edgeset.

for i in 1:10
   @warn "Beep boop, you will only see 🦦 once"  maxlog=1
end