Enhance documentation for sum_into_values

[jh66637]

By now, FEPointEvaluation::integrate(buffer, flags) zeroed out the whole buffer and possibly wrote to a subset of DoFs. Therefore, the code becomes tedious and error-prone if multiple FEPointEvaluation objects work on the same buffer. This PR aims to zero out only the values the objects actually work on.

fe_eval_first_selected_component_0.integrate(dst,flags); 
fe_eval_first_selected_component_1.integrate(dst,flags); 

While above code works as expected, if we use FEEvaluation objects with FEPointEvaluation currently one would have to write

// Zeroes out everything and writes some values to buffer
fe_point_eval_first_selected_component_0.integrate(buffer,flags); 

// We have to use sum_into_values=true so that the line does not zero out anything.
// Instead we relie on a different object to zero out the values before this line. 
// With sum_into_values=false the values that are written to the buffer in the first line are zeroed out.
fe_point_eval_first_selected_component_1.integrate(buffer,flags,true); 

Additionally, from the documentation of sum_into_values: "Flag specifying if the integrated values should be summed into the solution values. Defaults to false." I would expect that only those DoFs are changed that the object works on.

Maybe there are reasons why everything is currently zeroed out that I couldn't think of. Can you comment on this after the holidays @bergbauer?

---

EDIT: As described in #16382 (comment) using separate buffers results in similar code as for FEFaceEvaluation. Therefore, I simply enhanced the documentation.

[bergbauer]

This behavior existed before I started working on FEPointEvaluation, I have added the option sum_into_values because of efficiency reasons. The zeroing-out is tested by quite some tests, see e.g. https://github.com/dealii/dealii/blob/35f9cb91f997df8e9d9d3405592b49d5fecf0c83/tests/matrix_free/point_evaluation_04.cc

In my opinion, we should make the behavior as similar as possible to FEEvaluation, so I would be in favor of changing it to your suggestion. If we decide to keep the current behavior, we should try to improve the documentation to make this obvious. What do you think @peterrum @kronbichler

With your suggestion, do I still need to zero out before the quadrature loop? The components worked on are written anyway if sum_into_values==false.

[peterrum]

In my opinion, we should make the behavior as similar as possible to FEEvaluation, so I would be in favor of changing it to your suggestion.

Yes, I think this is the right step. When reviewing step-89 (from where the above example comes), it was quite non-intuitive that you need to add the second time.

[jh66637]

With your suggestion, do I still need to zero out before the quadrature loop? The components worked on are written anyway if sum_into_values==false.

We only have to zero out in one corner case (where nothing has to be done). The rest should be fine by simply skipping the lines.

[bergbauer]

We only have to zero out in one corner case (where nothing has to be done). The rest should be fine by simply skipping the lines.

Nice, then we can get rid of the complicated check!

[jh66637]

@peterrum I can take a shot once this is marked ready to test, so I know which tests are failing.

[peterrum]

/rebuild

[jh66637]

Maybe the behavior was motivated because the buffer is typically used for evaluate() and integrate(). If not all DoFs are zeroed out, there might be DoF values left in the buffer after integrate() which is not intuitive. Using different buffers for each FEPointEvaluation object, it is possible to write the code the same way as with FEEvaluation which also holds different buffers internally. This requires to call distribute_local_to_global() twice, which is also done for FEEvaluation objects. Using one buffer and calling distribute_local_to_global always directly after integrate() works as well.

I gave this some more thoughts and am now in favor of keeping everything as it is. Does this also make sense to you @bergbauer @peterrum? If so, I will simply enhance the documentation.

[bergbauer]

Maybe the behavior was motivated because the buffer is typically used for evaluate() and integrate(). If not all DoFs are zeroed out, there might be DoF values left in the buffer after integrate() which is not intuitive. Using different buffers for each FEPointEvaluation object, it is possible to write the code the same way as with FEEvaluation which also holds different buffers internally. This requires to call distribute_local_to_global() twice, which is also done for FEEvaluation objects. Using one buffer and calling distribute_local_to_global always directly after integrate() works as well.

In my opinion, FEPointEvalaution should work on the buffers of FEEvaluation and we should write the code such that this works intuitively.

[jh66637]

@bergbauer using the buffers from corresponding FEFaceEvaluation objects works already intuitively by zeroing out the whole buffer.

[jh66637]

@bergbauer @peterrum I clarified the documentation. Using separate buffers (e.g. from corresponding FEEvaluation objects) leads to intuitive code.

[peterrum]

Maybe the behavior was motivated because the buffer is typically used for evaluate() and integrate(). If not all DoFs are zeroed out, there might be DoF values left in the buffer after integrate() which is not intuitive. Using different buffers for each FEPointEvaluation object, it is possible to write the code the same way as with FEEvaluation which also holds different buffers internally. This requires to call distribute_local_to_global() twice, which is also done for FEEvaluation objects. Using one buffer and calling distribute_local_to_global always directly after integrate() works as well.

Can you give an example code?

[jh66637]

Sure. Below you see a pseudocode using different buffers (here using the buffers from FEEvaluation objects:

fe_point_eval_first_selected_component_0.integrate(fe_eval_first_selected_component_0.get_buffer(),flags); 
fe_point_eval_first_selected_component_1.integrate(fe_eval_first_selected_component_1.get_buffer(),flags); 

fe_eval_first_selected_component_0.distribute_local_to_global();
fe_eval_first_selected_component_1.distribute_local_to_global();