Some theoretical background for the L2 projector by termi-official · Pull Request #1272 · Ferrite-FEM/Ferrite.jl

termi-official · 2026-01-27T13:49:20Z

No description provided.

…teresting for new users.

codecov · 2026-01-27T13:52:58Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.36%. Comparing base (726b223) to head (b6c660a).
⚠️ Report is 6 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1272      +/-   ##
==========================================
- Coverage   94.20%   91.36%   -2.84%     
==========================================
  Files          40       40              
  Lines        6676     6963     +287     
==========================================
+ Hits         6289     6362      +73     
- Misses        387      601     +214

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

KnutAM · 2026-01-27T14:13:59Z

+The operation done by the L2-projector can be interpreted as the Galerkin-projection of ``f`` onto ``u``:
+```math
+    \\int v (u - f) \\ \\mathrm{d}\\Omega = 0 \\quad \\forall v \\in U_h(\\Omega),
+```
+An alternative interpretation here is that we minimize the difference between ``f`` and ``u`` with the functional (induced by the ``L_2`` norm):
+```math
+    \\min_u \\int \\frac{1}{2} (u - f)^2 \\ \\mathrm{d}\\Omega \\, .
+```


Should we reverse the order and stating that the 1st equation is a result of setting the directional derivative of the 2nd equal to zero?

Would it also make sense to introduce the FE-approximation explicitly above then to show the discrete equation system?

Should we reverse the order and stating that the 1st equation is a result of setting the directional derivative of the 2nd equal to zero?

Not necessarily. The first equation is the orthogonality and it just happens here that it is also the variation of the latter and thereby connected.

Would it also make sense to introduce the FE-approximation explicitly above then to show the discrete equation system?

What do you mean?

What do you mean?

$$\underbrace{\int N_i N_j \ \mathrm{d}\Omega}_{M_{ij}}\ a_j = \underbrace{\int N_i f \ \mathrm{d}\Omega}_{f_i} \quad \forall v \in U_h(\Omega)$$
And then say that M is Cholesky factorizated upon close?

Something like this maybe?

fredrikekre · 2026-01-29T12:20:24Z

This is great, but perhaps it should go into the "Topic guides" section rather than the docstring? (If we consider docstrings to be reference (https://diataxis.fr/start-here/#reference)).

termi-official · 2026-01-29T12:32:05Z

This is great, but perhaps it should go into the "Topic guides" section rather than the docstring? (If we consider docstrings to be reference (https://diataxis.fr/start-here/#reference)).

Going over this again I still think it should be in the docstring. Quoting the material here, putting what I think is relevant into bold :[...] accurate, complete, reliable information, free of distraction and interpretation. They contain propositional or theoretical knowledge, not guides to action.` Or am I missing something? If you prefer that this should go into a new Topic guide I can do it anyway. :) I do not have any opinion here about where it should go. I just found it brief enough that it might go directly into the docstring as it does not seem to causing much noise and contains some relevant information.

fredrikekre · 2026-01-29T13:13:30Z

I still think theoretical background is Explanation (or what we call topic guides). I interpret reference as "what you need while coding", i.e. how to use the thing ("reference documentation serves the user who is at work").

KnutAM · 2026-01-29T13:20:55Z

Is there a neat way to link to the online documentation directly from the docstring?
Should (can?) we add some utility functions and do something like

"""
    foo()
    
Nothing here, but see the [Topic guide]($(docref_topics("postprocessing")))
"""
foo() = nothing

termi-official · 2026-02-06T21:25:23Z

Done and deploys.

KnutAM

To me it would look better to mirror the API-section and have postprocessing at the end. Also to add this in the Topic guide overview.

KnutAM · 2026-02-10T08:12:24Z

@@ -0,0 +1,30 @@
+# [Projections and Transfer](@id man-projection-transfer)


Suggested change

# [Projections and Transfer](@id man-projection-transfer)

# [Projection](@id man-projection-transfer)

Since we only have projection for now?

We also have the PointEvalHandler as a transfer function. I just didn't wanted to include too many changes in one PR.

OK, I read transfer as transferring between grids. But if following the API-section, this should still be two separate sub-headings then?

I read transfer as transferring between grids

Yes. This is one examplaric use-case of the PointEvalHandler. Does that make sense?

should still be two separate sub-headings then?

This is the heading for the full section. We also have this for example in the Grid and AbstractGrid section.

I am still open for improvements on the name. Postprocessing is misleading tho.

Postprocessing is misleading tho.

True, but that also a problem in the API section then, and keeping these in sync I think is better? And if we decide on a good way to split we do it for both?

Yes. This is one examplaric use-case of the PointEvalHandler. Does that make sense?

True, but another is plotting along a line as put in the postprocessing how-to, and I think finding that functionality as a transfer could be hard for users?

This is the heading for the full section.

Yes, wasn't against a general heading (just that moving it to include export, if we do that). I'm also not sure what the best name here would be.

I just didn't wanted to include too many changes in one PR.

Sure, that makes sense (but hard to see here, so IMO better add a general header then :) )

KnutAM · 2026-02-10T08:15:09Z

@@ -0,0 +1,30 @@
+# [Projections and Transfer](@id man-projection-transfer)
+
+This section is concerned with projection and transfer techniques implemented in Ferrite.


Suggested change

This section is concerned with projection and transfer techniques implemented in Ferrite.

Ferrite can [`project`](@ref) values stored in the quadrature points onto a finite element interpolation, making it suitable for e.g. plotting. Currently, [L2 projection](@ref man-l2projection) is implemented.

KnutAM · 2026-02-10T08:23:19Z

+This technique is concerned with finding the best field for some function, or after numerical quadrature for some given data points.
+To be mathematically more precise, the operation done by the L2-projector can be interpreted as the Galerkin-projection of ``f`` onto ``u``:


Suggested change

This technique is concerned with finding the best field for some function, or after numerical quadrature for some given data points.

To be mathematically more precise, the operation done by the L2-projector can be interpreted as the Galerkin-projection of ``f`` onto ``u``:

This method finds the closest (in the L2 norm) projection of some function onto a finite element interpolation. In practice, the function is often described by its values in the quadrature points and numerical integration is used directly.

The L2-projection is the Galerkin-projection of the function ``f`` onto the function space ``U(\Omega)``, i.e. find `u \in U(\Omega)` such that

KnutAM · 2026-02-10T08:26:11Z

+\underbrace{\int N_i N_j \ \mathrm{d}\Omega}_{M_{ij}}\ u^h_j = \underbrace{\int N_i f \ \mathrm{d}\Omega}_{b_i}
+```
+where ``u^h_j`` denotes the unknown dofs of the finite-dimensional discrete space to project onto (e.g. Lagrange polynomials) with ansatz and test functions ``N``.
+``b_i`` denotes the right hand side of the finite-dimensional discrete linear system. For vectorized problems we simply apply the projection component-wise.


Suggested change

``b_i`` denotes the right hand side of the finite-dimensional discrete linear system. For vectorized problems we simply apply the projection component-wise.

``b_i`` denotes the right hand side of the finite-dimensional discrete linear system. The L2 projection of vector- or tensor-valued quantities onto scalar-valued finite element spaces is computed by projecting component-wise.

To prep for adding details from #1161 here.

KnutAM · 2026-02-10T08:40:48Z

 a function space. To define the function space, add interpolations for
 different cell sets with `add!` before `close!`ing the projector,
 see the example below.

 The `L2Projector` acts as the integrated left hand side of the projection equation:
-Find projection ``u \\in U_h(\\Omega) \\subset L_2(\\Omega)`` such that
+Find projection ``u \\in U(\\Omega) \\subset L_2(\\Omega)`` such that
 ```math
-\\int v u \\ \\mathrm{d}\\Omega = \\int v f \\ \\mathrm{d}\\Omega \\quad \\forall v \\in U_h(\\Omega),
+\\int v u \\ \\mathrm{d}\\Omega = \\int v f \\ \\mathrm{d}\\Omega \\quad \\forall v \\in U(\\Omega),
 ```
-where ``f \\in L_2(\\Omega)`` is the data to project. The function space ``U_h(\\Omega)``
+where ``f \\in L_2(\\Omega)`` is the data to project. The function space ``U(\\Omega)``
 is the finite element approximation given by the interpolations `add!`ed to the `L2Projector`.


Perhaps make it cleaner to not have it at all here then?

And if not removing, regarding the change from U_h to U, shouldn't it be U_h here because we say that it is the finite element approximation, whereas in the the initial part of the topic guide it is described as a general function space which later is restricted (discretized) with finite elements?

Suggested change

is the finite element approximation given by the interpolations `add!`ed to the `L2Projector`.

a function space. See the corresponding [topic guide](@ref man-l2projection)

for the mathematical details.

To define the function space, add interpolations for

different cell sets with `add!` before `close!`ing the projector,

see the example below.

termi-official · 2026-02-10T15:44:16Z

To me it would look better to mirror the API-section and have postprocessing at the end.

Really not sure here. I do not like having the API section called postprocessing in first place -- but I think having a how to on postprocessing is a good idea. The sectioning needs a bit of restructuring anyways. For example, we have a "How to postprocessing", a "postprocessing API" and an "Export topic guide" section. Then we also list AffineConstraints in the API reference as boundary conditions, while the topic guide has its the affine constraints in its own section. It is really far from ideal and we need to put more thought into how to group stuff. For this reason I have used "Projection and Transfer" here as a separate section for now, as it is more discoverable. Although we should technically also put the projected Dirichlet here.

Also, L2 projections are indeed sometimes used in postprocessing (which can be quite harmful if one is not careful), it is also also used for example in solvers and error estimators.

Also to add this in the Topic guide overview.

I also saw that I forgot this. Thanks for pointing this out!

KnutAM · 2026-02-10T16:02:14Z

Although we should technically also put the projected Dirichlet here.

I don't think so, that is still about enforcing a constraint/bc, even if the constraint is not point-wise and based on the projection equation.

Really not sure here. I do not like having the API section called postprocessing in first place

I agree that we have a discrepancy and that it is not ideal, I just believe we should keep these more in sync and avoid making them even more different. Perhaps it makes sense to add this PR to add the content following the API structure, and add another issue/PR to make what is different the same and create more logical headers / overall structure? (Probably an issue as it might need some discussion first?) Would be a shame to stall the details added in this while discussing the more overall structure.

termi-official · 2026-02-28T01:47:09Z

I think this is a bigger change than I initially anticipated. I just wanted to upstream here some stuff from the Ferrite paper. Probably easiest if this is picked up after we have fixed the docs.

Add some theoretical background to the L2 projector which might be in…

8443495

…teresting for new users.

KnutAM reviewed Jan 27, 2026

View reviewed changes

Incorporate Knut's suggestion

57d0c13

Move new parts of docstring into topic

b6c660a

termi-official added the awaiting review PR is finished from the authors POV, waiting for feedback label Feb 6, 2026

KnutAM reviewed Feb 10, 2026

View reviewed changes

termi-official removed the awaiting review PR is finished from the authors POV, waiting for feedback label Feb 10, 2026

termi-official closed this Feb 28, 2026

termi-official mentioned this pull request Feb 28, 2026

Documentation grouping inconsistencies #1292

Open

		@@ -0,0 +1,30 @@
		# [Projections and Transfer](@id man-projection-transfer)

	# [Projections and Transfer](@id man-projection-transfer)
	# [Projection](@id man-projection-transfer)

		@@ -0,0 +1,30 @@
		# [Projections and Transfer](@id man-projection-transfer)

		This section is concerned with projection and transfer techniques implemented in Ferrite.

	This section is concerned with projection and transfer techniques implemented in Ferrite.
	Ferrite can [`project`](@ref) values stored in the quadrature points onto a finite element interpolation, making it suitable for e.g. plotting. Currently, [L2 projection](@ref man-l2projection) is implemented.

		This technique is concerned with finding the best field for some function, or after numerical quadrature for some given data points.
		To be mathematically more precise, the operation done by the L2-projector can be interpreted as the Galerkin-projection of ``f`` onto ``u``:

	``b_i`` denotes the right hand side of the finite-dimensional discrete linear system. For vectorized problems we simply apply the projection component-wise.
	``b_i`` denotes the right hand side of the finite-dimensional discrete linear system. The L2 projection of vector- or tensor-valued quantities onto scalar-valued finite element spaces is computed by projecting component-wise.

Conversation

termi-official commented Jan 27, 2026

Uh oh!

codecov Bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KnutAM Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fredrikekre commented Jan 29, 2026

Uh oh!

termi-official commented Jan 29, 2026

Uh oh!

fredrikekre commented Jan 29, 2026

Uh oh!

KnutAM commented Jan 29, 2026

Uh oh!

termi-official commented Feb 6, 2026

Uh oh!

KnutAM left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

termi-official commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KnutAM commented Feb 10, 2026

Uh oh!

termi-official commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Jan 27, 2026 •

edited

Loading

KnutAM Jan 27, 2026 •

edited

Loading

termi-official commented Feb 10, 2026 •

edited

Loading