move common functionality to a utility library

[jacobmerson]

This reorganization will help decouple components. For example, the vmec field needs to use interpolation. With the utility libraries moved to a lower level, we can avoid a circular dependency between pcms::core pcms::interpolator. That is, pcms::core can utilize pcms::interpolator. This is really the first step in a broader re-organization of the pcms::sources to be more modular.

[Copilot]

Pull request overview

This PR reorganizes the codebase by moving common utility functionality (types, arrays, memory spaces, assertions, profiling, printing, etc.) into a new pcms::utility library. This refactoring addresses circular dependency issues, particularly enabling pcms::core to utilize pcms::interpolator without creating dependency cycles. The changes lay the groundwork for more modular organization of pcms::sources components.

Key Changes

• Created a new pcms::utility library containing low-level utilities (types, arrays, memory spaces, assertions, profiling, and printing functionality)
• Updated all include paths throughout the codebase from pcms/<utility>.h to pcms/utility/<utility>.h
• Moved ProcessType alias from utility/common.h to coupler.h to keep it in the public API layer
• Updated CMake configuration to build and export the new utility library, with proper dependency ordering

Reviewed changes

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

Show a summary per file

File	Description
src/pcms/utility/types.h	New file defining basic types (Real, LO, GO) and type utilities
src/pcms/utility/profile.h	New file with performance profiling macros
src/pcms/utility/print.h	Moved print utilities with updated includes
src/pcms/utility/print.cpp	Moved print implementation with corrected include path
src/pcms/utility/memory_spaces.h	New file defining Kokkos memory space aliases
src/pcms/utility/inclusive_scan.h	New file with inclusive scan implementation
src/pcms/utility/common.h	Moved common utilities, removed ProcessType alias
src/pcms/utility/assert.h	Moved assertion macros with PCMS_ prefixes
src/pcms/utility/assert.cpp	Moved assertion implementation
src/pcms/utility/arrays.h	Moved array utilities with updated includes
src/pcms/utility/array_mask.h	Moved array mask utilities (has include path issues)
src/pcms/utility/CMakeLists.txt	New CMake configuration for utility library
src/CMakeLists.txt	Updated to build utility library and link pcms_core to it
config.cmake.in	Added pcms_utility-targets import
src/pcms/coupler.h	Added ProcessType alias for public API
src/pcms/*.h	Multiple core files updated with new include paths
src/pcms/adapter/**/*.{h,cpp}	Adapter files updated with new include paths
src/pcms/interpolator/**/*.hpp	Interpolator files updated with new include paths
src/pcms/capi/*.cpp	C API files updated with new include paths
test/*.cpp	Test files updated with new include paths
tools/*.cpp	Tool files updated with new include paths

Comments suppressed due to low confidence (4)

src/pcms/utility/array_mask.h:3

• This include path should be updated to use the new utility directory. It should be #include "pcms/utility/arrays.h" instead of #include "pcms/arrays.h" to match the refactoring where arrays.h was moved to the utility library.
  src/pcms/utility/array_mask.h:4
• This include should use the full path pcms/utility/assert.h instead of just assert.h. The relative include assert.h could potentially resolve to the standard library's assert.h instead of the intended pcms utility assert header, which would cause compilation errors since the file needs the PCMS_ALWAYS_ASSERT macro and other definitions.
  src/pcms/utility/assert.cpp:1
• The assert.cpp implementation file should include its own header pcms/utility/assert.h to ensure the function declaration matches the implementation. This is a best practice that helps catch signature mismatches at compile time and ensures consistency.
  src/pcms/utility/assert.h:48
• These commented-out undef statements should either be removed entirely or uncommented if they're needed. Leaving them commented creates ambiguity about whether macro cleanup is intentionally disabled or simply forgotten. Since these macros are prefixed with PCMS_ to avoid naming conflicts, leaving them defined is likely acceptable, but the code should be consistent with the project's approach.

---

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

[jacobmerson]

I think the clang-tidy failure here is actually an issue with redev. See: SCOREC/redev#56

[jacobmerson]

Note:

1. self hosted runner is currently failing with:
   cudaGetDeviceCount(&count) error( cudaErrorInitializationError): initialization error /space/d_zxg05646/asics-actions-runner-linux-x64-2.323.0/_work/pcms/pcms/pcmsCI_2025-12-21-18-05/kokkos/core/src/impl/Kokkos_Core.cpp:134
   see: https://github.com/SCOREC/pcms/actions/runs/20416693526/job/58661403802?pr=252#step:4:7930
   I think this is the intermittent failure that @Sichao25 @cwsmith have been seeing on the self-hosted runner. We will try re-running later.
2. @jacobmerson (note to self) at this point, don't force push as other branches are based on this.

[Sichao25]

Looks good to me!