PR feedback: cuDSS cleanup, guard, schema version, docs, tests, GPU CI

Maintainer feedback on the cuDSS support:

- Rebase cleanup: in cudss.cpp swap the transitive utils/iodata.hpp include for
  utils/labels.hpp, the header that actually defines the MatrixSymmetry /
  SymbolicFactorization types the file uses (include-what-you-use); drop the
  dead IoData forward-decl in cudss.hpp and the unused cudss.hpp include in
  waveportoperator.cpp; and document the intentionally-unused reorder argument
  in the CuDSSSolver constructor.

- Consolidate the "not built with cuDSS" guard to a single config-time check in
  iodata.cpp (mirroring the SuperLU/STRUMPACK/MUMPS guards), and drop the
  redundant #else MFEM_ABORT from the ksp.cpp cuDSS case so it matches the
  empty-guarded MUMPS pattern.

- Bump the configuration schema $id to 1-1-0 for the new "cuDSS"
  Solver.Linear.Type enum value: a new allowed enum value is a backward-
  compatible SchemaVer REVISION (required by scripts/check-schema-version). Tag
  the CHANGELOG entry with "SchemaVer 1-1-0" per the bump policy; the notes.md
  release table is intentionally left untouched (updated only at release time).

- Document cuDSS in the install guide (build flag + spack example) and add unit
  tests: every Solver.Linear.Type value (incl. "cuDSS") validates against the
  schema, and Type="cuDSS" parses to LinearSolver::CUDSS when built with cuDSS.

- Enable cuDSS in the GPU CI: build with +cuda+cudss and add a cuDSS entry to
  the GPU regression-test solver matrix.

Author: hughcars

.github/workflows/spack.yml

@@ -63,7 +63,7 @@ jobs:
       - uses: ./.github/actions/palace-ci
         with:
           toolchain: gcc
-          variant: +cuda
+          variant: +cuda+cudss
           run-regression-tests: 'false'
 
   build-x64-gcc-openmp:
@@ -177,13 +177,14 @@ jobs:
           - solver: SuperLU
           - solver: STRUMPACK
           - solver: Default
+          - solver: cuDSS
     runs-on: [self-hosted, gpu-4xlarge]
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/run-regression-tests
         with:
           toolchain: gcc
-          variant: +cuda
+          variant: +cuda+cudss
           linear-solver: ${{ matrix.solver }}
 
   test-x64-gcc-openmp:

CHANGELOG.md

@@ -12,6 +12,16 @@ The format of this changelog is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+#### New Features
+
+  - Added support for the [NVIDIA cuDSS](https://docs.nvidia.com/cuda/cudss/index.html)
+    high-performance CUDA sparse direct solver, selectable via
+    `config["Solver"]["Linear"]["Type"] = "cuDSS"` for the KSP and wave port solvers.
+    Enable at build time with `PALACE_WITH_CUDSS=ON` (requires `PALACE_WITH_CUDA=ON`).
+    SchemaVer 1-1-0 [PR 717](https://github.com/awslabs/palace/pull/717).
+
 ## [0.17.0] - 2026-06-28
 
 #### New Features

docs/src/install.md

@@ -54,10 +54,10 @@ spack install palace
 
 This will install the default version of *Palace*. Spack supports installing
 _variants_ of *Palace*. For instance, if you want to install *Palace* with CUDA,
-MUMPS and SLEPc, call
+MUMPS, SLEPc and the NVIDIA cuDSS GPU sparse direct solver, call
 
 ```bash
-spack install palace +mumps +slepc +cuda cuda_arch=90
+spack install palace +mumps +slepc +cuda +cudss cuda_arch=90
 ```
 
 where `cuda_arch` is determined by the [generation of your
@@ -192,6 +192,9 @@ Additional build options are (with default values in brackets):
   - `PALACE_WITH_SUPERLU [ON]` :  Build with SuperLU_DIST sparse direct solver
   - `PALACE_WITH_STRUMPACK [OFF]` :  Build with STRUMPACK sparse direct solver
   - `PALACE_WITH_MUMPS [OFF]` :  Build with MUMPS sparse direct solver
+  - `PALACE_WITH_CUDSS [OFF]` :  Build with NVIDIA cuDSS sparse direct solver (requires
+    `PALACE_WITH_CUDA=ON`; the cuDSS installation directory can be specified with
+    `CUDSS_DIR`)
   - `PALACE_WITH_SLEPC [ON]` :  Build with SLEPc eigenvalue solver
   - `PALACE_WITH_ARPACK [OFF]` :  Build with ARPACK eigenvalue solver
   - `PALACE_WITH_LIBXSMM [ON]` :  Build with LIBXSMM backend for libCEED
@@ -281,7 +284,9 @@ source code for these dependencies is downloaded during the build process:
 
 For solving eigenvalue problems, at least one of SLEPc or ARPACK-NG must be specified.
 Typically only one of the SuperLU_DIST, STRUMPACK, and MUMPS dependencies is required but
-all can be built so the user can decide at runtime which solver to use.
+all can be built so the user can decide at runtime which solver to use. On CUDA builds, the
+NVIDIA cuDSS GPU-resident sparse direct solver is additionally available via
+`PALACE_WITH_CUDSS` (selected at runtime with `"Type": "cuDSS"`).
 
 For unit testing, *Palace* relies on the [Catch2
 library](https://github.com/catchorg/Catch2), which is automatically downloaded

palace/linalg/cudss.cpp

@@ -6,7 +6,7 @@
 
 #if defined(MFEM_USE_CUDSS)
 
-#include "utils/iodata.hpp"
+#include "utils/labels.hpp"
 
 namespace palace
 {
@@ -30,8 +30,11 @@ mfem::CuDSSSolver::MatType GetCuDSSMatType(MatrixSymmetry sym)
 
 }  // namespace
 
-CuDSSSolver::CuDSSSolver(MPI_Comm comm, MatrixSymmetry sym, SymbolicFactorization reorder,
-                         bool reorder_reuse, int print)
+// cuDSS does not expose a reordering-strategy selection (it only supports reordering
+// reuse), so the SymbolicFactorization argument is accepted for interface parity with the
+// other direct solvers (see MakeWrapperSolver in ksp.cpp) but is intentionally unused.
+CuDSSSolver::CuDSSSolver(MPI_Comm comm, MatrixSymmetry sym,
+                         SymbolicFactorization /*reorder*/, bool reorder_reuse, int print)
   : mfem::CuDSSSolver(comm)
 {
   SetMatrixSymType(GetCuDSSMatType(sym));

palace/linalg/cudss.hpp

@@ -14,8 +14,6 @@
 namespace palace
 {
 
-class IoData;
-
 //
 // A wrapper for cuDSS.
 //

palace/linalg/ksp.cpp

@@ -196,9 +196,6 @@ ConfigurePreconditionerSolver(const config::LinearSolverData &linear,
       pc = MakeWrapperSolver<OperType, CuDSSSolver>(linear, comm, pc_mat_sym,
                                                     linear.sym_factorization,
                                                     linear.reorder_reuse, print);
-#else
-      MFEM_ABORT(
-          "Solver was not built with cuDSS support, please choose a different solver!");
 #endif
       break;
     case LinearSolver::DEFAULT:

palace/models/waveportoperator.cpp

@@ -8,7 +8,6 @@
 #include "linalg/ams.hpp"
 #include "linalg/arpack.hpp"
 #include "linalg/blockprecond.hpp"
-#include "linalg/cudss.hpp"
 #include "linalg/gmg.hpp"
 #include "linalg/hypre.hpp"
 #include "linalg/iterative.hpp"

palace/utils/iodata.cpp

@@ -593,6 +593,10 @@ void IoData::CheckConfiguration()
   MFEM_VERIFY(solver.linear.type != LinearSolver::MUMPS,
               "Linear solver MUMPS requested but Palace was not built with MUMPS support!");
 #endif
+#if !defined(MFEM_USE_CUDSS)
+  MFEM_VERIFY(solver.linear.type != LinearSolver::CUDSS,
+              "Linear solver cuDSS requested but Palace was not built with cuDSS support!");
+#endif
 
   // Configure settings for quadrature rules and partial assembly.
   BilinearForm::pa_order_threshold = solver.pa_order_threshold;

scripts/schema/config-schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "urn:palace:schema:1-0-0",
+  "$id": "urn:palace:schema:1-1-0",
   "title": "Configuration File Schema",
   "description": "Palace configuration file schema for 3D electromagnetic simulations.",
   "type": "object",

test/unit/test-config.cpp

@@ -1516,3 +1516,18 @@ TEST_CASE("ConcretizeDefaults", "[config][Serial]")
     CHECK(mat_gaps.empty());
   }
 }
+
+#if defined(MFEM_USE_CUDSS)
+TEST_CASE("Linear solver Type cuDSS parses when built with cuDSS", "[config][Serial]")
+{
+  // With cuDSS support built in, Solver.Linear.Type = "cuDSS" must parse to the
+  // CUDSS enum and not trip the "not built with cuDSS" configuration guard.
+  json config = {{"Problem", {{"Type", "Electrostatic"}, {"Output", "test_output"}}},
+                 {"Model", {{"Mesh", "test.msh"}}},
+                 {"Domains", {{"Materials", {{{"Attributes", {1}}}}}}},
+                 {"Boundaries", json::object()},
+                 {"Solver", {{"Linear", {{"Type", "cuDSS"}}}}}};
+  IoData iodata(config, false);
+  CHECK(iodata.solver.linear.type == LinearSolver::CUDSS);
+}
+#endif