neuronsimulator · nrnhines · Jun 8, 2026 · Jun 4, 2026 · Jun 8, 2026 · Jun 19, 2026
diff --git a/.github/workflows/nvhpc.yml b/.github/workflows/nvhpc.yml
@@ -79,7 +79,7 @@ jobs:
         run: |
           rm -fr ${NRN_INSTALL_DIR}
           source "${VENV_DIR}/bin/activate"
-          export NRN_CONFIG=(-DNRN_ENABLE_CORENEURON=ON -DNRN_ENABLE_MPI=ON -DCORENRN_ENABLE_GPU=ON -DCMAKE_CXX_COMPILER=nvc++ -DNRN_ENABLE_INTERVIEWS=OFF -DNRN_ENABLE_RX3D=OFF -DNRN_ENABLE_DOCS=OFF -DNRN_ENABLE_TESTS=ON -DCMAKE_C_COMPILER=nvc -DCMAKE_CUDA_COMPILER=nvcc -DCMAKE_INSTALL_PREFIX="${NRN_INSTALL_DIR}" -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DNMODL_ENABLE_FLEX_BISON_LINES=OFF -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache -G Ninja -DCMAKE_BUILD_TYPE=Debug)
+          export NRN_CONFIG=(-DNRN_ENABLE_CORENEURON=ON -DNRN_ENABLE_MPI=ON -DCORENRN_ENABLE_GPU=ON -DNRN_ENABLE_GPU=ON -DNRN_GPU_BACKEND=OpenACC -DCMAKE_CUDA_ARCHITECTURES=75 -DCMAKE_CXX_COMPILER=nvc++ -DNRN_ENABLE_INTERVIEWS=OFF -DNRN_ENABLE_RX3D=OFF -DNRN_ENABLE_DOCS=OFF -DNRN_ENABLE_TESTS=ON -DCMAKE_C_COMPILER=nvc -DCMAKE_CUDA_COMPILER=nvcc -DCMAKE_INSTALL_PREFIX="${NRN_INSTALL_DIR}" -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DNMODL_ENABLE_FLEX_BISON_LINES=OFF -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache -G Ninja -DCMAKE_BUILD_TYPE=Debug)
           cmake -B ${NRN_BUILD_DIR} "${NRN_CONFIG[@]}"
 
       - name: "Build NEURON"
@@ -102,7 +102,10 @@ jobs:
           CTEST_PARALLEL_LEVEL: 20
         run: |
           source "${VENV_DIR}/bin/activate"
-          ctest --output-on-failure --test-dir ${NRN_BUILD_DIR}
+          # Phase B native GPU pre-merge proof (docs/dev/gpu-testing.rst).
+          # Full ctest -R gpu (~96 tests) is follow-up for this PR.
+          ctest --output-on-failure --test-dir ${NRN_BUILD_DIR} \
+            -R 'testneuron_gpu|_py_gpu_native|external_ringtest::neuron_gpu'
 
       - name: "Install NEURON"
         run: |

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -109,6 +109,11 @@ option(NRN_ENABLE_MUSIC "Enable MUSIC support" ${NRN_ENABLE_MUSIC_DEFAULT})
 option(NRN_ENABLE_RX3D "Enable rx3d support" ${NRN_ENABLE_RX3D_DEFAULT})
 option(NRN_ENABLE_NMODL "Enable NMODL code-generator support" ${NRN_ENABLE_NMODL_DEFAULT})
 option(NRN_ENABLE_CORENEURON "Enable CoreNEURON support" ${NRN_ENABLE_CORENEURON_DEFAULT})
+option(NRN_ENABLE_GPU "Enable NEURON native GPU support" ${NRN_ENABLE_GPU_DEFAULT})
+set(NRN_GPU_BACKEND
+    "${NRN_GPU_BACKEND_DEFAULT}"
+    CACHE STRING "GPU backend for NEURON native GPU (OpenACC only in Phase A-B)")
+set_property(CACHE NRN_GPU_BACKEND PROPERTY STRINGS OpenACC)
 option(NRN_ENABLE_BACKTRACE "Enable pretty-printed backtraces" ${NRN_ENABLE_BACKTRACE_DEFAULT})
 option(NRN_ENABLE_TESTS "Enable unit tests" ${NRN_ENABLE_TESTS_DEFAULT})
 option(NRN_ENABLE_MATH_OPT "Enable extra math optimisations (to enable SIMD)"
@@ -673,6 +678,24 @@ else()
   set(NRN_CODEGENERATOR_TARGET nocmodl)
 endif()
 
+# =============================================================================
+# NEURON native GPU (Phase A: option scaffolding; execution still via CoreNEURON)
+# =============================================================================
+if(NRN_ENABLE_GPU)
+  if(NOT NRN_GPU_BACKEND STREQUAL "OpenACC")
+    message(
+      FATAL_ERROR
+        "NRN_GPU_BACKEND=${NRN_GPU_BACKEND} is not supported. Only OpenACC is supported in Phase A-B."
+    )
+  endif()
+  if(NOT NRN_ENABLE_CORENEURON)
+    message(
+      FATAL_ERROR
+        "NRN_ENABLE_GPU=ON requires NRN_ENABLE_CORENEURON=ON during the Phase A transition. "
+        "Native GPU execution without CoreNEURON is not yet implemented.")
+  endif()
+endif()
+
 # =============================================================================
 # Enable CoreNEURON support
 # =============================================================================
@@ -703,6 +726,7 @@ if(NRN_ENABLE_CORENEURON)
   # CoreNEURON exports this list of flags as a property; turn it into a variable in this scope. If
   # CoreNEURON is installed externally then this is exported into coreneuron-config.cmake.
   get_property(CORENRN_LIB_LINK_FLAGS GLOBAL PROPERTY CORENRN_LIB_LINK_FLAGS)
+  get_property(CORENRN_ACC_COMP_FLAGS GLOBAL PROPERTY CORENRN_ACC_COMP_FLAGS)
   get_property(CORENRN_NEURON_LINK_FLAGS GLOBAL PROPERTY CORENRN_NEURON_LINK_FLAGS)
   get_property(CORENRN_ENABLE_SHARED GLOBAL PROPERTY CORENRN_ENABLE_SHARED)
 
@@ -752,6 +776,7 @@ endif()
 # =============================================================================
 add_subdirectory(src/sparse13)
 add_subdirectory(src/gnu)
+add_subdirectory(src/neuron)
 add_subdirectory(src/nrniv)
 
 if(NRN_ENABLE_PYTHON)
@@ -802,6 +827,14 @@ endif()
 if(NRN_ENABLE_CORENEURON)
   list(APPEND NRN_RUN_FROM_BUILD_DIR_ENV "CORENRNHOME=${PROJECT_BINARY_DIR}")
 endif()
+if(NRN_ENABLE_GPU AND CORENRN_ENABLE_GPU)
+  if(NOT CUDAToolkit_FOUND)
+    find_package(CUDAToolkit 9.0 QUIET)
+  endif()
+  if(CUDAToolkit_FOUND)
+    prepend_to_var(LD_LIBRARY_PATH "${CUDAToolkit_LIBRARY_DIR}")
+  endif()
+endif()
 if(NRN_ENABLE_PYTHON)
   prepend_to_var(PYTHONPATH "${PROJECT_BINARY_DIR}/lib/python:${PROJECT_SOURCE_DIR}/test/rxd")
 endif()
@@ -949,21 +982,42 @@ add_custom_target(
   COMMAND ${PROJECT_SOURCE_DIR}/external/coding-conventions/bin/format
   WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
-# Prepare a shell script to format only files modified with respect to master branch
+# Prepare a shell script to format only files modified with respect to master/main branch that still
+# exist on disk (filters out deleted files).
 file(
   WRITE ${CMAKE_CURRENT_BINARY_DIR}/format-pr.sh
-  "\
-#!bash\n\
-set -e\n\
-cmd='cd ${PROJECT_SOURCE_DIR} && external/coding-conventions/bin/format `git diff --name-only master`'\n\
-echo $cmd\n\
-cd ${PROJECT_SOURCE_DIR} && external/coding-conventions/bin/format `git diff --name-only master`\n\
+  "#!/bin/bash
+set -euo pipefail
+
+# Try 'main' first, then fall back to 'master'
+for base in main master; do
+    if git rev-parse --verify \"\$base\" >/dev/null 2>&1; then
+        BASE_BRANCH=\"\$base\"
+        break
+    fi
+done
+
+if [ -z \"\${BASE_BRANCH:-}\" ]; then
+    echo \"Error: Neither 'main' nor 'master' branch found.\" >&2
+    exit 1
+fi
+
+echo \"Formatting changes vs '\$BASE_BRANCH' (existing files only)...\" >&2
+
+# Get changed files, but only pass files that still exist
+git diff --name-only \"\$BASE_BRANCH\" | \\
+while read -r file; do
+    if [ -e \"\$file\" ]; then
+        printf '%s\\n' \"\$file\"
+    fi
+done | \\
+xargs --no-run-if-empty external/coding-conventions/bin/format \"\$@\"
 ")
 
 add_custom_target(
   format-pr
   COMMAND bash ${CMAKE_CURRENT_BINARY_DIR}/format-pr.sh
-  COMMENT "Format only files modified with respect to master branch."
+  COMMENT "Format only files modified with respect to main/master (existing files only)"
   WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 
 # =============================================================================
@@ -1313,6 +1367,10 @@ if(NRN_ENABLE_CORENEURON)
   message(STATUS "  PATH        | ${CORENEURON_DIR}")
   message(STATUS "  LINK FLAGS  | ${CORENRN_LIB_LINK_FLAGS}")
 endif()
+message(STATUS "NEURON GPU    | ${NRN_ENABLE_GPU}")
+if(NRN_ENABLE_GPU)
+  message(STATUS "  Backend     | ${NRN_GPU_BACKEND}")
+endif()
 message(STATUS "NMODL codegen   | ${NRN_ENABLE_NMODL}")
 if(NRN_UNIVERSAL2_BUILD)
   message(STATUS "CMAKE_OSX_ARCH| ${CMAKE_OSX_ARCHITECTURES}")

diff --git a/bin/nrnivmodl.in b/bin/nrnivmodl.in
@@ -49,6 +49,7 @@ UserLDFLAGS=""
 UserCOREFLAGS=()
 UserNMODLBIN=""
 UserNMODLFLAGS=""
+ForceNOCMODL=false
 
 # - options come first but can be in any order.
 while [ "$1" ] ; do
@@ -72,11 +73,14 @@ while [ "$1" ] ; do
         shift
         shift;;
     -nmodl)
-        echo "[NMODL][warning] Code generation with NMODL is pre-alpha, lacks features and is intended only for development use"
+        @NRN_ENABLE_GPU_FALSE@echo "[NMODL][warning] Code generation with NMODL is pre-alpha, lacks features and is intended only for development use"
         UserNMODLBIN="$2"
         UserNMODLFLAGS="--neuron $UserNMODLFLAGS"
         shift
         shift;;
+    -nocmodl)
+        ForceNOCMODL=true
+        shift;;
     -nmodlflags)
         echo "[NMODL][warning] If sympy is enabled, NMODL needs to be found in PYTHONPATH"
         UserNMODLFLAGS="$UserNMODLFLAGS $2"
@@ -88,8 +92,9 @@ while [ "$1" ] ; do
         echo "  -coreneuron                      Compile MOD files for CoreNEURON using nrnivmodl-core."
         echo "  -incflags    \"include flags\"     Extra include flags and paths when MOD (C++) files are compiled."
         echo "  -loadflags   \"link flags\"        Extra link flags, paths, and libraries when MOD (C++) files are linked."
-        echo "  -nmodl /path/to/nmodl            Path to the new NMODL transpiler for MOD files (pre-alpha, development use only)."
-        echo "  -nmodlflags  \"CLI flags\"         Additional CLI flags for new NMODL transpiler"
+        echo "  -nmodl /path/to/nmodl            Path to the NMODL transpiler for MOD files."
+        echo "  -nmodlflags  \"CLI flags\"         Additional CLI flags for NMODL transpiler"
+        echo "  -nocmodl                         Force NOCMODL codegen (not supported with NRN_ENABLE_GPU builds)"
         echo "  -h, --help                       Show this help message and exit."
         echo "If no MOD files or directories provided then MOD files from current directory are used."
         exit 0;;
@@ -101,6 +106,15 @@ while [ "$1" ] ; do
     esac
 done
 
+@NRN_ENABLE_GPU_TRUE@if [ "$ForceNOCMODL" = true ]; then
+@NRN_ENABLE_GPU_TRUE@    echo "ERROR: -nocmodl is not supported with NRN_ENABLE_GPU builds. Use NMODL (default) instead."
+@NRN_ENABLE_GPU_TRUE@    exit 1
+@NRN_ENABLE_GPU_TRUE@fi
+@NRN_ENABLE_GPU_TRUE@if [ -n "$UserNMODLBIN" ] && echo "$UserNMODLBIN" | grep -q nocmodl; then
+@NRN_ENABLE_GPU_TRUE@    echo "ERROR: NOCMODL cannot be used with NRN_ENABLE_GPU builds. Use NMODL (default) instead."
+@NRN_ENABLE_GPU_TRUE@    exit 1
+@NRN_ENABLE_GPU_TRUE@fi
+
 echo "$PWD"
 
 # Mod file paths may contain spaces which make variable lists of those

diff --git a/cmake/BuildOptionDefaults.cmake b/cmake/BuildOptionDefaults.cmake
@@ -16,6 +16,8 @@ set(NRN_ENABLE_MUSIC_DEFAULT OFF)
 set(NRN_ENABLE_RX3D_DEFAULT ON)
 set(NRN_ENABLE_NMODL_DEFAULT OFF)
 set(NRN_ENABLE_CORENEURON_DEFAULT OFF)
+set(NRN_ENABLE_GPU_DEFAULT OFF)
+set(NRN_GPU_BACKEND_DEFAULT "OpenACC")
 set(NRN_ENABLE_BACKTRACE_DEFAULT OFF)
 set(NRN_ENABLE_TESTS_DEFAULT OFF)
 set(NRN_ENABLE_MODEL_TESTS_DEFAULT "")
@@ -61,6 +63,8 @@ set(NRN_OPTION_NAME_LIST
     NRN_ENABLE_MPI
     NRN_ENABLE_RX3D
     NRN_ENABLE_CORENEURON
+    NRN_ENABLE_GPU
+    NRN_GPU_BACKEND
     NRN_ENABLE_TESTS
     NRN_ENABLE_MODEL_TESTS
     NRN_ENABLE_PYTHON_DYNAMIC

diff --git a/cmake/ConfigFileSetting.cmake b/cmake/ConfigFileSetting.cmake
@@ -42,6 +42,14 @@ else()
   set(CORENEURON_ENABLED_FALSE "")
 endif()
 
+if(NRN_ENABLE_GPU)
+  set(NRN_ENABLE_GPU_TRUE "")
+  set(NRN_ENABLE_GPU_FALSE "#")
+else()
+  set(NRN_ENABLE_GPU_TRUE "#")
+  set(NRN_ENABLE_GPU_FALSE "")
+endif()
+
 # ~~~
 # A variable that doesn't start out as #undef but as #define needs an
 # explicit @...@ replacement in the .h.in files.

diff --git a/cmake/NeuronTestHelper.cmake b/cmake/NeuronTestHelper.cmake
@@ -209,6 +209,9 @@ function(nrn_add_test_group)
       endforeach()
       # Construct the names of the important output files
       set(special "${nrnivmodl_directory}/${CMAKE_HOST_SYSTEM_PROCESSOR}/special")
+      set(nrnmech_lib
+          "${nrnivmodl_directory}/${CMAKE_HOST_SYSTEM_PROCESSOR}/${CMAKE_SHARED_LIBRARY_PREFIX}nrnmech${CMAKE_SHARED_LIBRARY_SUFFIX}"
+      )
       # Add the custom command to generate the binaries. Get nrnivmodl from the build directory. At
       # the moment it seems that `nrnivmodl` is generated at configure time, so there is no target
       # to depend on and it should always be available, but it will try and link against libnrniv.so
@@ -217,6 +220,11 @@ function(nrn_add_test_group)
       # be a wrapper that invokes CMake?
       set(output_binaries "${special}")
       list(APPEND nrnivmodl_dependencies nrniv_lib)
+      # Re-run nrnivmodl when libnrniv.so changes so test special does not retain stale NVHPC
+      # pgcudafat object paths from a prior libnrniv link line.
+      list(
+        APPEND nrnivmodl_dependencies
+        "${CMAKE_BINARY_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}nrniv${CMAKE_SHARED_LIBRARY_SUFFIX}")
       if(NRN_ENABLE_CORENEURON AND NRN_ADD_TEST_GROUP_CORENEURON)
         list(APPEND output_binaries "${special}-core")
         if((NOT coreneuron_FOUND) AND (NOT DEFINED CORENEURON_BUILTIN_MODFILES))
@@ -229,6 +237,8 @@ function(nrn_add_test_group)
       add_custom_command(
         OUTPUT ${output_binaries}
         DEPENDS ${nrnivmodl_dependencies} ${modfile_build_paths}
+        # Force libnrnmech relink when libnrniv.so changes (NVHPC embeds transient pgcudafat paths).
+        COMMAND ${CMAKE_COMMAND} -E rm -f ${nrnmech_lib} ${special}
         COMMAND ${nrnivmodl_command}
         COMMENT "Building special[-core] for test group ${NRN_ADD_TEST_GROUP_NAME}"
         WORKING_DIRECTORY "${nrnivmodl_directory}")
@@ -281,7 +291,11 @@ function(nrn_add_test)
   else()
     set(feature_mod_compatibility_enabled OFF)
   endif()
-  set(feature_gpu_enabled ${CORENRN_ENABLE_GPU})
+  if(NRN_ENABLE_GPU OR (NRN_ENABLE_CORENEURON AND CORENRN_ENABLE_GPU))
+    set(feature_gpu_enabled ON)
+  else()
+    set(feature_gpu_enabled OFF)
+  endif()
   # Check REQUIRES
   set(requires_coreneuron OFF)
   foreach(required_feature ${NRN_ADD_TEST_REQUIRES})
@@ -339,6 +353,13 @@ function(nrn_add_test)
   if(DEFINED NRN_ADD_TEST_SIM_DIRECTORY)
     set(sim_directory "${NRN_ADD_TEST_SIM_DIRECTORY}")
   endif()
+  # NVHPC may leave transient fat-object files in $TMPDIR when special runs with -gpu under MPI. Use
+  # a per-test TMPDIR under the build tree (see external_ringtest GPU ctest notes).
+  if("gpu" IN_LIST NRN_ADD_TEST_REQUIRES AND (CORENRN_ENABLE_GPU OR NRN_ENABLE_GPU))
+    set(gpu_tmpdir "${PROJECT_BINARY_DIR}/test/tmp/${NRN_ADD_TEST_GROUP}/${NRN_ADD_TEST_NAME}")
+    file(MAKE_DIRECTORY "${gpu_tmpdir}")
+    list(APPEND extra_environment "TMPDIR=${gpu_tmpdir}")
+  endif()
   # Finally a working directory for this specific test within the group
   set(working_directory "${PROJECT_BINARY_DIR}/test/${NRN_ADD_TEST_GROUP}/${NRN_ADD_TEST_NAME}")
   file(MAKE_DIRECTORY "${working_directory}")
@@ -405,9 +426,15 @@ function(nrn_add_test)
     if(NOT "PATH" IN_LIST test_env_var_names)
       message(FATAL_ERROR "Expected to find PATH in ${test_env_var_names} but didn't")
     endif()
+    set(_nrn_test_mech_dir "${nrnivmodl_directory}/${CMAKE_HOST_SYSTEM_PROCESSOR}")
     # PATH will already be set in test_env
-    list(TRANSFORM test_env REPLACE "^PATH="
-                                    "PATH=${nrnivmodl_directory}/${CMAKE_HOST_SYSTEM_PROCESSOR}:")
+    list(TRANSFORM test_env REPLACE "^PATH=" "PATH=${_nrn_test_mech_dir}:")
+    # pytest/python3 launches do not search PATH for dlopen(libnrnmech.so).
+    if("LD_LIBRARY_PATH" IN_LIST test_env_var_names)
+      list(TRANSFORM test_env REPLACE "^LD_LIBRARY_PATH=" "LD_LIBRARY_PATH=${_nrn_test_mech_dir}:")
+    else()
+      list(APPEND test_env "LD_LIBRARY_PATH=${_nrn_test_mech_dir}")
+    endif()
   endif()
   list(TRANSFORM test_env REPLACE "^PYTHONPATH="
                                   "PYTHONPATH=${CMAKE_SOURCE_DIR}/docs/nmodl/python_scripts:")

diff --git a/cmake/coreneuron/OpenAccHelper.cmake b/cmake/coreneuron/OpenAccHelper.cmake
@@ -96,6 +96,7 @@ if(CORENRN_ENABLE_GPU)
   # something like `-acc -lcorenrnmech ...`. CORENRN_NEURON_LINK_FLAGS only contains flags that need
   # to be used when linking the NEURON Python module to make sure it is able to dynamically load
   # libcorenrnmech.so.
+  set_property(GLOBAL PROPERTY CORENRN_ACC_COMP_FLAGS "${NVHPC_ACC_COMP_FLAGS}")
   set_property(GLOBAL PROPERTY CORENRN_LIB_LINK_FLAGS "${NVHPC_ACC_COMP_FLAGS}")
   if(CORENRN_ENABLE_SHARED)
     # Because of