jacobmerson · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -5,3 +5,5 @@ c726b259409b93e0a6df12d199f87eab8caa10db
 88dc8509543b34140a6015e361888644c5f5e0fe
 # reformat simplified-fields
 d521b8ce2e0d510d7472d2ac011cfc84b670f918
+# reformat after the 0.4 reorganization
+9675a362ba1a39515bda5cee679ad5036de46c18
diff --git a/.github/workflows/clang-tidy.yml b/.github/workflows/clang-tidy.yml
@@ -191,7 +191,7 @@ jobs:
                   -DCMAKE_CXX_COMPILER=mpicxx \
                   -DCMAKE_Fortran_COMPILER=mpifort \
                   -DPCMS_ENABLE_PETSC=ON \
-                  -DPETSC_LINK_STATIC=ON \
+                  -DPCMS_PETSC_LINK_STATIC=ON \
                   -DPETSC_DIR=${{ runner.temp }}/petsc-openmpi \
                   -DPETSC_ARCH=ubuntu-kokkos \
                   -DPCMS_TIMEOUT=10 \

diff --git a/.github/workflows/cmake-test.yml b/.github/workflows/cmake-test.yml
@@ -242,7 +242,7 @@ jobs:
       run: |
         echo "PCMS_ENABLE_PETSC=-DPCMS_ENABLE_PETSC=${{ matrix.petsc }}" >> $GITHUB_ENV
         if [ "${{ matrix.petsc }}" = "ON" ]; then
-          echo "PCMS_PETSC_OPTIONS=-DPETSC_LINK_STATIC=ON -DPETSC_DIR=${{ runner.temp }}/petsc -DPETSC_ARCH=ubuntu-kokkos" >> $GITHUB_ENV
+          echo "PCMS_PETSC_OPTIONS=-DPCMS_PETSC_LINK_STATIC=ON -DPETSC_DIR=${{ runner.temp }}/petsc -DPETSC_ARCH=ubuntu-kokkos" >> $GITHUB_ENV
         else
           echo "PCMS_PETSC_OPTIONS=" >> $GITHUB_ENV
         fi
@@ -281,7 +281,7 @@ jobs:
                   ${{ env.PCMS_ENABLE_PETSC }}
                   ${{ env.PCMS_PETSC_OPTIONS }}
                   -DPCMS_TIMEOUT=10
-                  -DPCMS_ENABLE_Python=${{ matrix.python_api }}
+                  -DPCMS_ENABLE_PYTHON=${{ matrix.python_api }}
                   -DCatch2_DIR=${{ runner.temp }}/build-Catch2/install/lib/cmake/Catch2
                   -DOmega_h_DIR=${{ runner.temp }}/build-omega_h/install/lib/cmake/Omega_h
                   ${{ env.PCMS_MESHFIELDS_DIR }}
@@ -332,8 +332,9 @@ jobs:
       if: matrix.python_api == 'OFF'
       shell: bash
       run: |
-        # Configure and build the test
-        # it should only ask for pcms_DIR/ROOT to find all dependencies
+        # Build examples/external-usage-example against the install tree only
+        # (installed headers, exported targets). The package config no longer
+        # bakes in dependency paths, so they come from CMAKE_PREFIX_PATH.
         ls ${{ runner.temp }}/build-pcms/install/lib/cmake/pcms
         echo "-------- PCMS CONFIG -------------"
         cat ${{ runner.temp }}/build-pcms/install/lib/cmake/pcms/pcms-config.cmake
@@ -346,9 +347,15 @@ jobs:
           -B ${{github.workspace}}/examples/external-usage-example/build \
           -S ${{github.workspace}}/examples/external-usage-example/ \
           -Dpcms_DIR=${{ runner.temp }}/build-pcms/install/lib/cmake/pcms \
-          ${{ matrix.petsc == 'ON' && format('-DPETSC_LINK_STATIC=ON -DPETSC_DIR={0}/petsc -DPETSC_ARCH=ubuntu-kokkos', runner.temp) || '' }} \
+          -DCMAKE_PREFIX_PATH="${{ runner.temp }}/build-kokkos/install;${{ runner.temp }}/build-kokkos-kernels/install;${{ runner.temp }}/build-omega_h/install;${{ runner.temp }}/build-redev/install;${{ runner.temp }}/build-ADIOS2/install;${{ runner.temp }}/build-perfstubs/install;${{ runner.temp }}/build-meshFields/install" \
+          -DCMAKE_CXX_COMPILER=`which mpicxx` \
+          ${{ matrix.petsc == 'ON' && format('-DPCMS_PETSC_LINK_STATIC=ON -DPETSC_DIR={0}/petsc -DPETSC_ARCH=ubuntu-kokkos', runner.temp) || '' }} \
           --debug-output
         cmake --build ${{github.workspace}}/examples/external-usage-example/build
+        mpirun --oversubscribe -np 1 ${{github.workspace}}/examples/external-usage-example/build/pcms_test
+
+    - name: Check public header includes
+      run: python3 tools/check-public-includes.py
 
   deploy-docs:
     needs: test-build

diff --git a/.github/workflows/self-hosted.yml b/.github/workflows/self-hosted.yml
@@ -117,7 +117,7 @@ jobs:
             -DKokkos_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/kokkos/install/lib64/cmake/Kokkos/ \
             -DKokkosKernels_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/kokkos-kernels/install/lib64/cmake/KokkosKernels/ \
             -DBUILD_TESTING=ON \
-            -DPCMS_ENABLE_Python=ON \
+            -DPCMS_ENABLE_PYTHON=ON \
             -DPCMS_ENABLE_PETSC=ON \
             -DPETSC_ARCH="" \
             -DPETSC_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/petsc/install \
@@ -168,7 +168,7 @@ jobs:
             -DKokkos_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/kokkos/install/lib64/cmake/Kokkos/ \
             -DKokkosKernels_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/kokkos-kernels/install/lib64/cmake/KokkosKernels/ \
             -DBUILD_TESTING=ON \
-            -DPCMS_ENABLE_Python=ON \
+            -DPCMS_ENABLE_PYTHON=ON \
             -DPCMS_ENABLE_PETSC=ON \
             -DPETSC_ARCH="" \
             -DPETSC_DIR=$DEPENDENCY_DIR/${DEVICE_ARCH}/petsc/install \

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.4.0
+
+A one-time breaking reorganization so that downstream codes migrate once.
+Numerical behavior is unchanged. See [MIGRATION.md](MIGRATION.md) and
+`tools/migrate-pcms.sh`; the decisions behind the changes are in
+`tools/reorg/decisions.md`.
+
+### Changed (breaking)
+
+- Public API: only interfaces and factory functions are public
+  (`CreateLagrangeSpace`, `CreateSplineSpace`,
+  `CreatePolynomialReconstructionSpace`, `CreateUniformGridDiscretization`,
+  `CreateEmptyDiscretization`, `CreateEmptyLayout`,
+  `CreateConservativeProjection`, `CreateControlVariateProjection`, and the
+  backend entry points in `pcms/backends/<name>/<name>.hpp`). The concrete
+  spaces, layouts, discretizations and projections are internal.
+- Headers: all C++ headers are `.hpp`; only public headers are installed, in
+  `include/pcms/<library>/`; `pcms.h` is replaced by the umbrella
+  `pcms/pcms.hpp`; core public headers no longer include Omega_h, MFEM,
+  MeshFields, PETSc or ADIOS2.
+- Namespaces: backend code is in `pcms::backend::<name>`, internal code in
+  `pcms::<library>`; the public API stays in `pcms::`.
+- Omega_h types left the core public signatures (`MakeConstRank2View`,
+  `CreateUniformGridFromMesh` and the Omega_h `OverlapMask` constructors moved
+  to the Omega_h backend; `UniformGrid` point queries take any indexable
+  point).
+- `pcms::Mode` is a PCMS enum instead of an alias of `redev::Mode`.
+- Python API mirrors the C++ factories; the class-based constructors are
+  removed.
+- Macros `MAX_DIM` and `ACTIVE_GPU_EXECUTION` are `PCMS_`-prefixed.
+- Build: CMake 3.23 required; options renamed to `PCMS_ENABLE_<UPPERCASE>` /
+  `PCMS_` form (old names still accepted in 0.4, deprecated); `pcms::core` is
+  a deprecated alias of `pcms::pcms`; `pcms::transfer` no longer depends on
+  the coupler, redev or ADIOS2; package files installed to
+  `lib/cmake/pcms`; no baked dependency paths; `SameMinorVersion`
+  compatibility; libraries have `VERSION`/`SOVERSION`; the SWIG interface
+  files are no longer installed.
+
+### Added
+
+- `PCMS_ENABLE_COUPLER` to build without redev and ADIOS2.
+- Factory functions and backend headers listed above; `FunctionSpace`
+  discretizations in Python (`pcms.backend.omega_h`).
+- Tests that every public header compiles on its own and that core public
+  headers include no backend library; CI builds and runs
+  `examples/external-usage-example` against the install tree.
+- `tools/migrate-pcms.sh` with `tools/reorg/header-map.txt` and
+  `tools/reorg/symbol-map.txt`.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,16 +1,21 @@
-cmake_minimum_required(VERSION 3.19)
+cmake_minimum_required(VERSION 3.23)
 project(
   pcms
-  VERSION 0.3.0
+  VERSION 0.4.0
   LANGUAGES CXX)
 
 include(GNUInstallDirs)
+# The package config files go to <prefix>/lib/cmake/pcms on every platform.
+set(PCMS_INSTALL_CMAKEDIR "lib/cmake/pcms"
+    CACHE STRING "Install directory of the pcms CMake package files")
 include(CMakePackageConfigHelpers)
 
 # use _ROOT variables for configurations
 cmake_policy(SET CMP0074 NEW)
 
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
+# map options renamed in 0.4 (e.g. PCMS_ENABLE_Python) to their new names
+include(PcmsRenamedOptions)
 
 option(PCMS_ENABLE_ASAN "enable address sanitizer" OFF)
 set(PCMS_HAS_ASAN OFF)
@@ -41,13 +46,14 @@ endif()
 
 option(PCMS_ENABLE_SERVER "enable the coupling server implementation" ON)
 option(PCMS_ENABLE_CLIENT "enable the coupling client implementation" ON)
+option(PCMS_ENABLE_COUPLER "Build the coupler (requires redev and ADIOS2)" ON)
 
 option(PCMS_ENABLE_XGC "enable xgc field adapter" ON)
 option(PCMS_ENABLE_OMEGA_H "enable Omega_h field adapter" OFF)
 option(PCMS_ENABLE_MFEM "enable MFEM field adapter" OFF)
 option(PCMS_ENABLE_TRANSIENT "Enable pcms transient module" ON)
 option(PCMS_ENABLE_C "Enable pcms C api" ON)
-option(PCMS_ENABLE_Python "Enable pcms Python api" OFF)
+option(PCMS_ENABLE_PYTHON "Enable pcms Python api" OFF)
 
 option(PCMS_ENABLE_PRINT "PCMS print statements enabled" ON)
 option(PCMS_ENABLE_EXAMPLES "Build the in-tree C++ examples" ON)
@@ -69,21 +75,25 @@ set(PCMS_PROJECTION_KSP_RTOL 1e-14 CACHE STRING
 set(PCMS_PROJECTION_KSP_ATOL 1e-50 CACHE STRING
     "Default absolute tolerance for the projection mass-matrix solve")
 
-option(PETSC_LINK_STATIC "Use pkg-config --static results for PETSc"
+option(PCMS_PETSC_LINK_STATIC "Use pkg-config --static results for PETSc"
        ${_pcms_link_petsc_static_default})
 
 # find package before fortran enabled, so we don't require the adios2 fortran
 # interfaces this is important because adios2 build with clang/gfortran is
 # broken
-find_package(redev 4.3.0 REQUIRED)
+if(PCMS_ENABLE_COUPLER)
+  find_package(redev 4.3.0 REQUIRED)
+elseif(PCMS_ENABLE_PYTHON)
+  message(FATAL_ERROR "PCMS_ENABLE_PYTHON requires PCMS_ENABLE_COUPLER")
+endif()
 
-if (PCMS_ENABLE_Python)
+if (PCMS_ENABLE_PYTHON)
   set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
 endif ()
 if(PCMS_ENABLE_C)
   enable_language(C)
-  option(PCMS_ENABLE_Fortran "Enable pcms fortran api" ON)
-  if(PCMS_ENABLE_Fortran)
+  option(PCMS_ENABLE_FORTRAN "Enable pcms fortran api" ON)
+  if(PCMS_ENABLE_FORTRAN)
     enable_language(Fortran)
   endif()
 endif()
@@ -130,7 +140,9 @@ if(PROJECT_IS_TOP_LEVEL)
   endif()
 endif()
 
-message(STATUS "Found redev: ${redev_DIR} (found version ${redev_VERSION})")
+if(PCMS_ENABLE_COUPLER)
+  message(STATUS "Found redev: ${redev_DIR} (found version ${redev_VERSION})")
+endif()
 if(PCMS_ENABLE_OMEGA_H)
   find_package(Omega_h REQUIRED VERSION 10)
   message(
@@ -148,7 +160,9 @@ if(PCMS_ENABLE_MFEM)
   endif()
 endif()
 # adios2 adds C and Fortran depending on how it was built
-find_package(ADIOS2 CONFIG 2.10.2 REQUIRED)
+if(PCMS_ENABLE_COUPLER)
+  find_package(ADIOS2 CONFIG 2.10.2 REQUIRED)
+endif()
 find_package(Kokkos CONFIG 4.5 REQUIRED)
 
 option(PCMS_ENABLE_MESHFIELDS "Enable MeshFields support" ON)
@@ -179,33 +193,36 @@ if(NOT BUILD_TESTING)
     COMMENT "Test installed PUMIPic utilities")
 endif()
 
-add_executable(smoke_test test/test_ohClassPtn.cpp)
-target_link_libraries(smoke_test pcms::core test_support)
-# Uses a mesh vendored in test/data so the install check works without
-# PCMS_TEST_DATA_DIR (e.g. with BUILD_TESTING=OFF).
-dual_mpi_test(
-  TESTNAME
-  smoke_test
-  TIMEOUT
-  4
-  NAME1
-  rdv
-  EXE1
-  smoke_test
-  PROCS1
-  2
-  ARGS1
-  1
-  ${CMAKE_CURRENT_SOURCE_DIR}/test/data/cyclone23/mesh.osh/
-  NAME2
-  app
-  EXE2
-  smoke_test
-  PROCS2
-  1
-  ARGS2
-  0
-  ${CMAKE_CURRENT_SOURCE_DIR}/test/data/cyclone23/mesh.osh/)
+# the smoke test exercises the coupler
+if(TARGET pcms::coupler)
+  add_executable(smoke_test test/test_ohClassPtn.cpp)
+  target_link_libraries(smoke_test pcms::pcms test_support)
+  # Uses a mesh vendored in test/data so the install check works without
+  # PCMS_TEST_DATA_DIR (e.g. with BUILD_TESTING=OFF).
+  dual_mpi_test(
+    TESTNAME
+    smoke_test
+    TIMEOUT
+    4
+    NAME1
+    rdv
+    EXE1
+    smoke_test
+    PROCS1
+    2
+    ARGS1
+    1
+    ${CMAKE_CURRENT_SOURCE_DIR}/test/data/cyclone23/mesh.osh/
+    NAME2
+    app
+    EXE2
+    smoke_test
+    PROCS2
+    1
+    ARGS2
+    0
+    ${CMAKE_CURRENT_SOURCE_DIR}/test/data/cyclone23/mesh.osh/)
+endif()
 
 if(BUILD_TESTING)
   add_subdirectory(test)

diff --git a/Doxyfile b/Doxyfile
@@ -2287,7 +2287,7 @@ PREDEFINED             = PCMS_ENABLE_SERVER \
                          PCMS_ENABLE_MFEM \
                          PCMS_ENABLE_C \
                          PCMS_ENABLE_TRANSIENT \
-                         PCMS_ENABLE_Fortran \
+                         PCMS_ENABLE_FORTRAN \
                          PCMS_ENABLE_MESHFIELDS \
                          PCMS_ENABLE_PETSC \
                          KOKKOS_INLINE_FUNCTION= \