docs contribution

[kreutzheidephil]

• docstring for evaluate_at_grid_nodes() and
• suggestion for more detailed explanation on quadrature order

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.72%. Comparing base (f6edc3f) to head (aeb522d).
Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1098   +/-   ##
=======================================
  Coverage   93.72%   93.72%           
=======================================
  Files          39       39           
  Lines        6008     6008           
=======================================
  Hits         5631     5631           
  Misses        377      377           

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

[KnutAM]

Welcome @kreutzheidephil 🚀

Some comments below. It will also be required to merge with the master branch.
After that, need to fix formatting to remove errors reported by the "pre-commit" workflow (and later "runic" after merge with master)

[KnutAM]

This is only true for hypercubes. For simplexes the concept of "each direction" is a bit harder to describe. I don't think we are fully consistent with what is meant with order, see also #1022 for some discussions about the options. For now, would something like this explain good enough?

Suggested change

	`order` is related to the number of quadrature points per direction (i.e. a `QuadratureRule{RefQuadrilateral}(2)`
	uses 2 quadrature points per direction). `quad_rule_type` is an optional argument determining the type of quadrature rule,
	`order` is related to the number of quadrature points, but is dependent on the reference shape.
	`quad_rule_type` is an optional argument determining the type of quadrature rule,

[DRollin]

I discussed that with Phil: We thought the general "is related to" would be enough to make clear that this is not always exactly true
Now, I see that this is still not perfectly clear.
What you suggest could be read as "The order depends on the reference shape." But this is not what you mean, right?

[termi-official]

Ohh, good catch here! Not sure how we missed that inconsistency earlier. We should definitely clarify this.

When writing the docs I found it difficult to make a balance between 1) being precise and 2) being still useful for users which are not fully aware (and interested) of all details. So for everything but hypercubes we refer with order to the actual integration order of the rule w.r.t. to the function system it integrates. Note that the function system varies between rules, see for example the Gauss-Laguerre rule for an example of a fancy system. So, if you have any idea how to communicate what "order" means to users, I am open for any suggestion.

[KnutAM]

Good point!
Something like this, and then we should document the rules somewhere and point to that location in the docstring. Probably nice not having all rules documented in the docstring as this would get too verbose.

Suggested change

	`order` is related to the number of quadrature points per direction (i.e. a `QuadratureRule{RefQuadrilateral}(2)`
	uses 2 quadrature points per direction). `quad_rule_type` is an optional argument determining the type of quadrature rule,
	`order` affects the number of quadrature points, and thus the precision of the integration rule. The exact relationship between `order` and the number of quadrature points depends on the `quad_rule_type` and `shape`.
	`quad_rule_type` is an optional argument determining the type of quadrature rule,

[DRollin]

I think this is nice for the docstring 👍
Maybe we could add a more detailed description (hypercubes vs. other shapes) somewhere in the documentation?
Suggestions where to add it:

1. at the beginning of "Topic guides/Reference shapes"

2. at the end of "Topic guides/Reference shapes"

3. in the tutorial "Heat equation"

[KnutAM]

The length can be different from getnnodes.

Suggested change

	`vals` must have length `getnnodes(grid)`.
	`vals` should be the output from `project` using `proj`.