FE Quadrature Phase 01 abstract contract

[zasexton]

Summary

This pull request establishes Phase 01 of the finite-element Quadrature module.
It defines the immutable reference-rule contract that concrete rule generation,
selection, and consumer migration can build on in later phases.

Related to #580.

The change:

• Adds an abstract, immutable QuadratureRule interface for canonical
  reference cells.
• Defines ordered point/weight storage using the FE fixed-size vector type.
• Exposes cell family, reference dimension, polynomial exactness,
  reference-cell measure, and const sample access.
• Establishes one construction-time validation boundary for provider data.
• Adds exact, order-independent binary64 validation of the weight sum.
• Adds focused unit coverage for the new representation, validation boundary,
  and immutable query interface.
• Registers the Quadrature sources with the solver build and the module with
  the FE documentation hierarchy.

Design

Immutable rule contract

QuadratureRule owns one complete set of ordered reference points and weights.
Successful construction establishes the invariant, after which consumers use
only const queries. Rule objects are non-copyable and non-movable and are
intended to be created once and shared through const ownership.

Concrete providers construct a protected RuleData payload containing:

• Declared total-degree polynomial exactness.
• Ordered canonical reference points.
• Corresponding ordered weights.

The base class derives dimension and reference-cell measure from CellFamily,
preventing providers from supplying redundant topology metadata.

Supported reference cells

The Phase 01 contract covers:

• Point
• Line
• Triangle
• Quadrilateral
• Tetrahedron
• Hexahedron
• Wedge

Pyramid, polygon, polyhedron, and unknown families remain explicitly
unsupported.

Construction validation

Construction rejects:

• Unsupported cell families.
• Negative polynomial exactness.
• Empty or mismatched point/weight storage.
• Non-finite coordinates or weights.
• Nonzero inactive coordinates.
• Points outside the declared canonical reference cell.
• Weights that do not reproduce the reference-cell measure within the scaled
  validation tolerance.

Duplicate points and zero or negative individual weights remain admissible when
all other invariants hold.

The weight sum is evaluated exactly from the stored binary64 values using a
fixed-storage accumulator. Validation is therefore independent of point/weight
ordering, cancellation, intermediate floating-point overflow, and the host
long double representation. Compile-time checks document and enforce the
binary64 value model and object layout required by that accumulator; this
will be important for cross-platform compile time validation.

Phase 01 regression tests

The Phase 01 tests are intentionally limited to the new Quadrature
infrastructure. They verify:

• The fixed-size QuadPoint representation.
• The immutable QuadratureRule query interface.
• Supported and unsupported reference-cell families.
• Metadata and point/weight storage invariants.
• Finite values, inactive coordinates, and canonical reference-cell
  containment.
• Reference-cell measure validation, including admissible negative weights.
• Exact binary64 weight summation under cancellation, subnormal values,
  reordered inputs, and large rules.
• Construction tolerances for reference coordinates and weight normalization.

These tests do not exercise existing quadrature tables, solver-specific selection
paths, or integration consumers.

Supporting changes

• Removes the unused speculative QuadratureType enumeration from the shared
  FE vocabulary.
• Adds FE/Quadrature sources to the solver target.
• Adds the Quadrature module to the top-level FE documentation hierarchy.
• Runs Doxygen from the repository root and removes stale generated output
  before documentation generation, ensuring relative paths resolve
  consistently.

Scope and non-goals

This pull request intentionally does not:

• Add production concrete quadrature providers.
• Add a quadrature factory, cache, or rule-selection policy.
• Migrate solver containers or integration consumers.
• Change basis selection, reduced-integration policy, or physical-space
  mapping.

Validation performed

• GCC build of run_all_unit_tests and svmultiphysics.
• GCC unit suite: 245 of 245 tests passed.
• Doxygen validation with no Quadrature-specific warnings.

[zasexton]

@ktbolt @michelebucelli let me know what you think of the abstract class contract for quadrature. I believe the public API for this contract is minimal and clean while ensuring that explicit Quadrature rules that are created can be validated. As always, happy to have more design input here and will incorporate changes pretty quickly so we can begin making a concrete QuadratureRule class.

[codecov]

Codecov Report

❌ Patch coverage is 92.67782% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.79%. Comparing base (18edacd) to head (1c28f9e).

Files with missing lines	Patch %	Lines
...s/unitTests/FE/Quadrature/test_QuadratureRules.cpp	88.69%	32 Missing ⚠️
...ode/Source/solver/FE/Quadrature/QuadratureRule.cpp	98.37%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #593      +/-   ##
==========================================
+ Coverage   72.54%   72.79%   +0.24%     
==========================================
  Files         252      255       +3     
  Lines       39033    39511     +478     
  Branches     6684     6711      +27     
==========================================
+ Hits        28318    28763     +445     
- Misses      10480    10513      +33     
  Partials      235      235              

☔ View full report in Codecov by Harness.
📢 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.

[michelebucelli]

Thank you @zasexton! I have left some comments. Some of them relate to the documentation, others to the interface itself.

In general, I am not sure I have understood correctly how the concrete rules are meant to be implemented (as you might see from some of my comments). In this respect, I think it would be useful to include in this PR at least one concrete rule (I assume you have implemented some, at least for the sake of testing the infrastructure), which would serve as a demonstration of how to use the abstract framework. I think this would make review a bit easier.

[zasexton]

Thanks for these comments @michelebucelli I'll review these today and make appropriate changes. Overall there is a good bit of important design feedback here that will help me to improve this base abstraction (which is the main purpose of me posting this draft PR). Thank you!

[ktbolt]

@zasexton Why all of this complexity to implement just the few quadrature rules needed for the elements we support ?

[zasexton]

Thanks for the patience! I have made my relevant edits to the PR branch and will be going through and addressing comments directly now!

[zasexton]

@ktbolt and @michelebucelli let me know what you think of the changes and simplifications that have been made over the last 11 commits. I believe that I have addressed many of the original comments. Overall, I think that we are getting close to a clean abstract class here to complete phase 1 of the quadrature refactor.