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 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.
• 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]

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.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[michelebucelli]

Thank @zasexton! I have a few leftover minor comments.

I still think it would be useful if you could provide a prototypical quadrature rule implementation, to give an idea about how you envision this in the longer run.

[michelebucelli]

1. It'd be better to pass these by const reference, I think.
2. Since points and weights are required to have the same size, wouldn't it be better to store them (or at least require the caller to provide them) as std::vector<std::pair<QuadPoint, double>> points_and_weights? This way, the same-size constraint would be impossible to violate. Should this be used for the data members as well, I think the overhead for access through the weight() and point() getters is essentially zero, while there'd be a bit more overhead for the vector accesses points and weights.

[zasexton]

Thank @zasexton! I have a few leftover minor comments.

I still think it would be useful if you could provide a prototypical quadrature rule implementation, to give an idea about how you envision this in the longer run.

I've made a very simple example in the test_QuadratureRule.cpp file for a two-point Gauss rule just to illustrate how this might be used; however the more concrete examples will be the Gauss and Position-based rules.