Issue 1982 - First stiffness matrix computation

[lsawade]

Description

This implements the computation of the stiffness kernel in linear systems

• Currently the elastic tag is somewhat hardcoded, which will be removed in subsequent PRs where we call the stiffness computation separately.

Issue Number

Closes #1982

Checklist

Please make sure to check developer documentation on specfem docs.

• I ran the code through pre-commit to check style
• THE DOCUMENTATION BUILDS WITHOUT WARNINGS/ERRORS
• I have added labels to the PR (see right hand side of the PR page)
• My code passes all the integration tests
• I have added sufficient unittests to test my changes
• I have added/updated documentation for the changes I am proposing
• I have updated CMakeLists to ensure my code builds
• My code builds across all platforms

[Copilot]

Pull request overview

Implements first pass of explicit stiffness-kernel extraction for SPECFEM++ linear systems (specfem::linear_system) by probing the existing matrix-free element operator to build dense per-element stiffness blocks, with scope validation and accompanying unit tests/docs.

Changes:

• Add compute_element_stiffness (NGLL-dispatched) and validate_stiffness_scope for 3D elastic isotropic, attenuation-none, natural-boundary meshes.
• Introduce a Kokkos probe kernel that applies gradient → stress → divergence to unit local DOFs to populate dense element blocks.
• Add a unit test that checks symmetry/nullspace properties and matches against the production matrix-free stiffness operator; expose the new API in Sphinx/Doxygen docs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit-tests/serial.cmake	Adds the new element_stiffness_tests target to the serial unit-test suite.
tests/unit-tests/linear_system/element_stiffness_tests.cpp	New tests validating stiffness-block properties and agreement with matrix-free operator.
docs/sections/api/specfem/linear_system/index.rst	New API doc entry for specfem::linear_system.
docs/sections/api/specfem/index.rst	Adds linear_system to the top-level API index.
core/specfem/linear_system/impl/stiffness_probe_kernel.hpp	New Kokkos kernel to probe the element stiffness operator into dense blocks.
core/specfem/linear_system/element_stiffness.hpp	Declares local DOF ordering helper, scope validator, and stiffness-block computation APIs.
core/specfem/linear_system/element_stiffness.tpp	Implements the NGLL-specific stiffness probe execution and buffer validation.
core/specfem/linear_system/element_stiffness.cpp	Implements runtime NGLL dispatcher + scope validation and provides explicit instantiations.
cmake/trilinos.cmake	Adjusts macOS rpath handling for Trilinos shared libraries.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.