NeurodataWithoutBorders · oruebel · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/.github/workflows/build-demo.yml b/.github/workflows/build-demo.yml
@@ -21,23 +21,29 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-latest]
+        os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
 
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
 
-    - name: Install dependencies - macos
-      if: matrix.os == 'macos-latest'
-      run: brew install hdf5 catch2
+    - name: Install dependencies - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libhdf5-dev libcurl4-openssl-dev
+        git clone https://github.com/catchorg/Catch2.git
+        cd Catch2
+        git checkout "v3.5.3"
+        cmake -Bbuild -H. -DBUILD_TESTING=OFF
+        sudo cmake --build build/ --target install
 
     - name: Configure and build the main project
       shell: pwsh
       run: |
-        cmake "--preset=ci-$("${{ matrix.os }}".split("-")[0])"
-        cmake -B build -S .
+        cmake "--preset=ci-$("${{ matrix.os }}".split("-")[0])" -DAQNWB_USE_REMFILE=ON
         cmake --build build --config Release -j 2
 
     - name: Install aqnwb
@@ -55,28 +61,87 @@ jobs:
       working-directory: build
       run: ctest --output-on-failure --no-tests=error -C Release -j 2
 
-    - name: Build the inspect_electrical_series demo - macos
-      if: matrix.os == 'macos-latest'
+    - name: Set up Conda
+      uses: conda-incubator/setup-miniconda@v3
+      with:
+        activate-environment: aqnwb-demo
+        environment-file: demo/remote_read_benchmark/conda-env.yml 
+      if: matrix.os == 'ubuntu-latest'
+
+    - name: Build the inspect_electrical_series demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
       run: |
         cd demo/inspect_electrical_series
         cmake -B build -S . -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install"
         cmake --build build --config Release -j 2
 
-    - name: Run the inspect_electrical_series demo - macos
-      if: matrix.os == 'macos-latest'
+    - name: Run the inspect_electrical_series demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
       run: |
         cd demo/inspect_electrical_series/build/bin
         ./nwb_analysis_demo ../../../../build/tests/data/createElectricalSeries.nwb
 
-    - name: Build the labmetadata_extension_demo demo - macos
-      if: matrix.os == 'macos-latest'
+    - name: Build the labmetadata_extension_demo demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
       run: |
         cd demo/labmetadata_extension_demo
         cmake -B build -S . -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install"
         cmake --build build --config Release -j 2
 
-    - name: Run the labmetadata_extension_demo demo - macos
-      if: matrix.os == 'macos-latest'
+    - name: Run the labmetadata_extension_demo demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
       run: |
         cd demo/labmetadata_extension_demo/build/bin
         ./labmetadata_extension_demo
+
+    - name: Build the remote_read_benchmark demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        cd demo/remote_read_benchmark
+        cmake -B build -S . -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install"
+        cmake --build build --config Release -j 2
+
+    - name: Run the remote_read_benchmark demo - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        cd demo/remote_read_benchmark/build/bin
+        ./remote_read_benchmark \
+            "https://dandiarchive.s3.amazonaws.com/blobs/fec/8a6/fec8a690-2ece-4437-8877-8a002ff8bd8a" \
+            "us-east-2" \
+            "ElectricalSeriesAp" \
+            "0,0" \
+            "10,1"
+
+    - name: Run the remote_read_benchmark demo with the remfile driver - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        cd demo/remote_read_benchmark/build/bin
+        ./remote_read_benchmark \
+            "https://dandiarchive.s3.amazonaws.com/blobs/fec/8a6/fec8a690-2ece-4437-8877-8a002ff8bd8a" \
+            "us-east-2" \
+            "ElectricalSeriesAp" \
+            "0,0" \
+            "10,1" \
+            remfile
+
+    - name: Run the remote_read_benchmark Python benchmark (ROS3) - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        conda run -n aqnwb-demo python demo/remote_read_benchmark/benchmark.py \
+            "https://dandiarchive.s3.amazonaws.com/blobs/fec/8a6/fec8a690-2ece-4437-8877-8a002ff8bd8a" \
+            "us-east-2" \
+            "ElectricalSeriesAp" \
+            "0,0" \
+            "10,1"
+
+    - name: Run the remote_read_benchmark Python benchmark (remfile) - ubuntu
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        conda run -n aqnwb-demo python demo/remote_read_benchmark/benchmark.py \
+            "https://dandiarchive.s3.amazonaws.com/blobs/fec/8a6/fec8a690-2ece-4437-8877-8a002ff8bd8a" \
+            "us-east-2" \
+            "ElectricalSeriesAp" \
+            "0,0" \
+            "10,1" \
+            --force-remfile
+
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -36,7 +36,7 @@ jobs:
       if: matrix.os == 'ubuntu-latest'
       run: |
         sudo apt-get update
-        sudo apt-get install -y libhdf5-dev
+        sudo apt-get install -y libhdf5-dev libcurl4-openssl-dev
         git clone https://github.com/catchorg/Catch2.git
         cd Catch2
         git checkout "v3.5.3"
@@ -45,18 +45,18 @@ jobs:
 
     - name: Install dependencies - macos
       if: matrix.os == 'macos-latest'
-      run: brew install hdf5 catch2
+      run: brew install hdf5 catch2 curl
 
     - name: Install dependencies - windows
       if: matrix.os == 'windows-latest'
       run: |
         cd "${VCPKG_INSTALLATION_ROOT}"
-        vcpkg install hdf5[cpp]:x64-windows catch2:x64-windows
+        vcpkg install hdf5[cpp]:x64-windows catch2:x64-windows curl:x64-windows
         vcpkg integrate install
 
     - name: Configure
       shell: pwsh
-      run: cmake "--preset=ci-$("${{ matrix.os }}".split("-")[0])"
+      run: cmake "--preset=ci-$("${{ matrix.os }}".split("-")[0])" -DAQNWB_USE_REMFILE=ON
 
     - name: Build
       run: cmake --build build --config Release -j 2
@@ -87,15 +87,15 @@ jobs:
     - name: Install dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y libhdf5-dev
+        sudo apt-get install -y libhdf5-dev libcurl4-openssl-dev
         git clone https://github.com/catchorg/Catch2.git
         cd Catch2
         git checkout "v3.5.3"
         cmake -Bbuild -H. -DBUILD_TESTING=OFF
         sudo cmake --build build/ --target install
 
     - name: Configure
-      run: cmake --preset=ci-sanitize
+      run: cmake --preset=ci-sanitize -DAQNWB_USE_REMFILE=ON
 
     - name: Build
       run: cmake --build build/sanitize -j 2
@@ -157,11 +157,11 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install dependencies - macos
-        run: brew install hdf5 catch2
+        run: brew install hdf5 catch2 curl
 
       - name: Configure (C++23)
         shell: pwsh
-        run: cmake "--preset=ci-macos" -DAQNWB_CXX_STANDARD=23
+        run: cmake "--preset=ci-macos" -DAQNWB_CXX_STANDARD=23 -DAQNWB_USE_REMFILE=ON
 
       - name: Build
         run: cmake --build build --config Release -j 2

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,12 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-
 ## Upcoming  (~June 2026)
 
 ### Added
+* **Added support for streaming data read of remote NWB files:**
+    * Added `HDF5IO::openS3(...)` method to support opening an existing remote file in S3 in read-only mode using the HDF5 ROS3 driver. (@oruebel, [#307](https://github.com/NeurodataWithoutBorders/aqnwb/pull/307))
+    * Added `HDF5IO::openRemote()` method to read remote NWB files over HTTP(S) using the [remfile-cpp](https://github.com/catalystneuro/remfile-cpp) virtual file driver (a C++ port of the Python [remfile](https://github.com/magland/remfile) package), imported as an optional CMake dependency (`AQNWB_USE_REMFILE`, requires `libcurl`). Unlike ROS3, remfile does not require HDF5 to be built with ROS3 support and works with any HTTP(S) server that supports byte-range requests. (@bendichter, [#309](https://github.com/NeurodataWithoutBorders/aqnwb/pull/309))
+    * Added demo for benchmarking ROS3 and remfile performance and comparing with PyNWB S3 reads (`demo/ros3_benchmark`). (@oruebel, [#308](https://github.com/NeurodataWithoutBorders/aqnwb/pull/308); @bendichter, [#309](https://github.com/NeurodataWithoutBorders/aqnwb/pull/309))
+    * Added tutorial on using the ROS3 and remfile drivers to read NWB files in S3 (`docs/pages/userdocs/reads3.dox`) 
 * Added `ElectricalSeries::writeAllChannels` method and `IO::writeElectricalSeriesData` overload to simplify zero-copy interleaved multichannel writes. (@copilot, @oruebel, [#293](https://github.com/NeurodataWithoutBorders/aqnwb/pull/293))
 * Added `ElectricalSeries::channelsAtSameSampleOffset` method to check if all channels are at the same sample offset, which is a requirement for using `writeAllChannels`. (@copilot, @oruebel, [#293](https://github.com/NeurodataWithoutBorders/aqnwb/pull/293))
+* Added new `BaseIO::findObject` and `RegisteredType::findOwnedObject` methods to simplify searching for objects by name. Added `HDF5IO::findObject` override method to optimize the search for HDF5 objects. (@oruebel, [#308](https://github.com/NeurodataWithoutBorders/aqnwb/pull/308))   
 
 ### Changed
 * **[BREAKING]** Moved `disableSWMRMode` option from `HDF5IO` constructor to a new `HDF5IO::startRecording(bool disableSWMRMode)` overload. The `BaseIO`-compliant `startRecording()` override is preserved and defaults to SWMR enabled. 
@@ -20,6 +25,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 * Updated nwbinspector validation tests in the CI to: 1) `--ignore=check_subject_exists` and 2) remove dependency on `sanitizer` tests to speed up CI (@oruebel, [#289](https://github.com/NeurodataWithoutBorders/aqnwb/pull/289))
 * Fixed `get_utc_offset_seconds` to correctly account for daylight saving time using platform-specific APIs (`tm_gmtoff` on Unix/macOS; `_get_timezone` + `_get_dstbias` on Windows), preventing `session_start_time` from being written ~1 hour ahead of UTC during DST (@cboulay, [#295](https://github.com/NeurodataWithoutBorders/aqnwb/pull/295))
+* Fixed bug in `HDF5IO::canModifyObjects` returning true when a file is opened in read-only. (@oruebel, [#307](https://github.com/NeurodataWithoutBorders/aqnwb/pull/307))
+* Fixed `install-config.cmake` to propagate HDF5 include directories to downstream consumers of the `aqnwb::aqnwb` target, allowing them to locate HDF5 headers regardless of where HDF5 is installed on the system. (@oruebel, [#308](https://github.com/NeurodataWithoutBorders/aqnwb/pull/308))
+* Updated `build-demo.yml` and `tests.yml` CI to support testing of the new ROS3 and remfile features and scripts  (@oruebel, [#308](https://github.com/NeurodataWithoutBorders/aqnwb/pull/308))
 
 
 ## [0.3.0] - 2026-02-23

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -106,6 +106,43 @@ set_target_properties(aqnwb_aqnwb PROPERTIES
 
 target_compile_definitions(aqnwb_aqnwb PUBLIC AQNWB_CXX_STANDARD=${AQNWB_CXX_STANDARD})
 
+# ---- Optional remfile VFD for reading remote files over HTTP(S) ----
+# remfile provides an HDF5 virtual file driver that reads remote files with
+# HTTP range requests and adaptive read-ahead caching. Unlike the ROS3 VFD,
+# it does not require HDF5 to be built with ROS3 support.
+set(aqnwb_use_remfile_default OFF)
+option(AQNWB_USE_REMFILE "Enable reading remote files over HTTP(S) via the remfile VFD (requires libcurl)" ${aqnwb_use_remfile_default})
+
+if(AQNWB_USE_REMFILE)
+  find_package(CURL QUIET)
+  if(NOT CURL_FOUND)
+    message(STATUS "remfile VFD disabled: libcurl not found")
+    set(AQNWB_USE_REMFILE OFF)
+  endif()
+endif()
+
+if(AQNWB_USE_REMFILE)
+  # Prefer an installed remfile package; otherwise fetch it from GitHub.
+  # When fetched, remfile's own install rules run as part of this project's
+  # install, so downstream consumers of the installed aqnwb package can
+  # resolve the remfile::remfile target via find_dependency(remfile).
+  find_package(remfile CONFIG QUIET)
+  if(remfile_FOUND)
+    message(STATUS "remfile VFD enabled (found installed remfile ${remfile_VERSION})")
+  else()
+    include(FetchContent)
+    FetchContent_Declare(
+        remfile
+        GIT_REPOSITORY https://github.com/catalystneuro/remfile-cpp.git
+        GIT_TAG main
+    )
+    FetchContent_MakeAvailable(remfile)
+    message(STATUS "remfile VFD enabled (fetched from GitHub)")
+  endif()
+  target_compile_definitions(aqnwb_aqnwb PUBLIC AQNWB_HAVE_REMFILE_VFD)
+  target_link_libraries(aqnwb_aqnwb PUBLIC remfile::remfile)
+endif()
+
 # ---- Additional libraries needed ----
 find_package(HDF5 REQUIRED COMPONENTS CXX)
 

diff --git a/CMakePresets.json b/CMakePresets.json
@@ -100,7 +100,7 @@
     {
       "name": "ci-win64",
       "inherits": ["flags-msvc", "ci-std"],
-      "generator": "Visual Studio 17 2022",
+      "generator": "Visual Studio 18 2026",
       "architecture": "x64",
       "cacheVariables": {
         "CMAKE_TOOLCHAIN_FILE": "C:/vcpkg/scripts/buildsystems/vcpkg.cmake"

diff --git a/cmake/install-config.cmake b/cmake/install-config.cmake
@@ -2,4 +2,19 @@ include(CMakeFindDependencyMacro)
 
 find_dependency(HDF5 COMPONENTS CXX)
 
-include("${CMAKE_CURRENT_LIST_DIR}/aqnwbTargets.cmake")
+# When aqnwb was built with AQNWB_USE_REMFILE=ON, the exported target
+# references remfile::remfile. remfile installs into the same prefix as
+# aqnwb when it was fetched at build time, so this lookup is quiet and
+# harmless when aqnwb was built without remfile support.
+find_package(remfile CONFIG QUIET)
+
+include("${CMAKE_CURRENT_LIST_DIR}/aqnwbTargets.cmake")
+
+# The aqnwb_aqnwb target only propagates HDF5 include directories via
+# $<BUILD_INTERFACE:...> (see the top-level CMakeLists.txt), so they are not
+# part of the installed target's INTERFACE_INCLUDE_DIRECTORIES. Explicitly add
+# the HDF5 include directories found above to the imported aqnwb::aqnwb target
+# so that downstream consumers (e.g. via find_package(aqnwb)) can locate HDF5
+# C/C++ headers regardless of where HDF5 is installed on the system.
+target_include_directories(aqnwb::aqnwb SYSTEM INTERFACE ${HDF5_INCLUDE_DIRS})
+
diff --git a/demo/remote_read_benchmark/CMakeLists.txt b/demo/remote_read_benchmark/CMakeLists.txt
@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.15)
+project(remote_read_benchmark VERSION 0.1.0 LANGUAGES CXX)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Find aqnwb - this automatically brings in HDF5 as a transitive dependency
+find_package(aqnwb REQUIRED)
+
+# Add the executable
+add_executable(remote_read_benchmark main.cpp)
+
+# Link to aqnwb - HDF5 includes/libraries are provided transitively
+target_link_libraries(remote_read_benchmark PRIVATE aqnwb::aqnwb)
+
+# Set the output directory
+set_target_properties(remote_read_benchmark PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/bin
+)
+
+# Install rules
+install(TARGETS remote_read_benchmark
+    RUNTIME DESTINATION bin
+)