Add polyorder kwarg, and test that quadrature rules fulfils this

[KnutAM]

#1200 revealed that we are not really clear on what order in QuadratureRule implies. Based on my investigations here, it implies the highest order of a complete polynomial that is exactly integrated for RefSimplex, RefPrism, and RefPyramid, but the number of quadrature points in each direction for RefHypercube.

To allow requesting a certain accuracy (measured in what polynomial order that is exactly integrated), this PR adds an option to construct a quadrature rule as
QuadratureRule{RefShape}([T::Type{<:Number}], [quad_type::Symbol]; polyorder::Int), where the polyorder kwarg always is the highest order of a complete polynomial that is exactly integrated.

This can then be used internally in #1200.

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.99%. Comparing base (5e1f1de) to head (fc7a949).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Quadrature/quadrature.jl	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1220      +/-   ##
==========================================
- Coverage   94.14%   91.99%   -2.15%     
==========================================
  Files          40       40              
  Lines        6641     6811     +170     
==========================================
+ Hits         6252     6266      +14     
- Misses        389      545     +156     

☔ 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.

[termi-official]

While I like the idea, I am not sure if adding kwargs is a good design for this (as this also seems to be some way forward to resolve the existing ambiguity in order). I guess that even with a good explanation, the difference between order and polyorder might be quite hard to understand for new users, especially with the existing ambiguitiy. Polyorder might also be a bit tricky as a name, if users come from some background where they also might use quadrature rules which also included non-polynomial functions.

May I suggest to rather introduce new create_... functions which return QuadratureRules instead of adding more constructors?

[KnutAM]

Polyorder might also be a bit tricky as a name, if users come from some background where they also might use quadrature rules which also included non-polynomial functions.

For those cases (I.e. passing a ruletype that isn't based on polynomial order) I just imagine it should error

[KnutAM]

While I like the idea, I am not sure if adding kwargs is a good design for this (as this also seems to be some way forward to resolve the existing ambiguity in order).

Why is adding more (exported) names a better interface?

With kwargs, we could introduce the alternative variant being number of quadrature points, allowing e.g.

qr = QuadratureRule{RefQuadrilateral}(; polyorder = 2) # 2x2 rule
qr = QuadratureRule{RefQuadrilateral}(; npoints = 4) # 2x2 rule

Would be a quite alright interface, and then we could keep the legacy and ambiguous order interface

qr = QuadratureRule{RefQuadrilateral}(2) # 2x2 (legacy)

but removing it from docs/tutorials.

[termi-official]

Why is adding more (exported) names a better interface?

My argument here is merely that I think it is easier to comprehend (and discover) different functions than a single function with many different combinations of potentially incompatible kwargs.

[KnutAM]

My argument here is merely that I think it is easier to comprehend (and discover)

For discovery I would say it is easy with kwargs, as it would be stated in the docstring. I also don't think we would add a lot of different cases here: since the polynomial case is rather common and we need it internally for #1200 (would work there apart for pyramids), I argue this makes sense. The other case IMO that makes sense is the number of quadrature points (not so user-friendly as dimension dependent, but very clean and could also be added).

[lijas]

How would polyorder work with other types of quad_rule_,types that can be added?

[KnutAM]

How would polyorder work with other types of quad_rule_,types that can be added?

For different quad_rule_type::Symbol, this should already work?

For cases that we cannot guarantee exact integration of a certain polynomial order, e.g. non-polynomial quadrature rules, I think we should error.