JoelPhys · Oct 19, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -12,10 +12,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-14, macos-26]
+        os: [ubuntu-latest, windows-latest, macos-15, macos-26]
         env-type: [pip]
         include:
-          - os: macos-14
+          - os: macos-15
             llvm: llvm@15
           - os: macos-26
             llvm: llvm@20

diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
@@ -15,11 +15,11 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-14, macos-26]
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-15, macos-26]
         include:
-          - os: macos-14
+          - os: macos-15
             llvm: llvm@15
-            macos_deployment_target: "14.0"
+            macos_deployment_target: "15.0"
           - os: macos-26
             llvm: llvm@20
             macos_deployment_target: "26.0"

diff --git a/.github/workflows/wheels_testpypi.yml b/.github/workflows/wheels_testpypi.yml
@@ -9,9 +9,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-14, macos-26]
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-15, macos-26]
         include:
-        - os: macos-14
+        - os: macos-15
           llvm: llvm@15
         - os: macos-26
           llvm: llvm@20

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,24 @@
+# Agent Instructions — PyVale
+
+PyVale is a Python-first scientific engineering library for sensor simulation, digital image correlation, camera rendering, experimental design, and validation/UQ. Keep changes correct, fast, and simple for users.
+
+## Read first
+
+- [Developer guide](dev/README.md), then relevant project documentation under `dev/` and `docs/`.
+- [CAVL Python style guide](https://github.com/Computer-Aided-Validation-Laboratory/styleguides/blob/main/guides/python_style_guide.md) — including its Cython section.
+- [CAVL Performance Oriented Software guide](https://github.com/Computer-Aided-Validation-Laboratory/styleguides/blob/main/guides/performance_oriented_software_guide.md) — especially for numerical and compiled code.
+- [CAVL C++ style guide](https://github.com/Computer-Aided-Validation-Laboratory/styleguides/blob/main/guides/cpp_style_guide.md) — for C/C++ code.
+- [CAVL Zig style guide](https://github.com/Computer-Aided-Validation-Laboratory/styleguides/blob/main/guides/zig_style_guide.md) — when touching Zig code.
+
+## PyVale-specific rules
+
+1. **Python-first API.** Keep user-facing configuration and workflows in clear, typed Python; use compiled code for measured or clearly identified performance-critical work.
+2. **Scientific meaning matters.** Preserve physical units, coordinate conventions, array shapes and axes, and numerical assumptions. Never silently change their interpretation.
+3. **Explicit native boundaries.** Keep Python/native interfaces narrow, with explicit ownership, lifetime, layout and dtype requirements. Follow `dev/README.md` on C ABI and build tooling.
+4. **Avoid unnecessary data movement.** Design NumPy arrays and native buffers to minimise allocations, conversions, copies and Python calls inside intensive loops.
+5. **Performance is designed in.** Consider computational complexity, data locality, vectorisation and parallelism early; benchmark representative workloads before claiming speedups.
+6. **Validate at boundaries.** Reject invalid or ambiguous inputs clearly, and avoid redundant checks inside validated numerical kernels.
+7. **Prefer straightforward implementations.** Avoid speculative abstractions, inheritance, extra dependencies and tiny single-use helpers that obscure the algorithm.
+8. **API evolution**: Pyvale is a young, evolving project. Do not preserve public APIs at the expense of a cleaner, more consistent design. Breaking changes are acceptable and encouraged when justified. Avoid backwards-compatibility shims, deprecated aliases, and legacy code paths. Update all affected call sites, tests, examples, and documentation.
+9. **Verify numerics.** Add focused tests for changes, including analytic/reference comparisons, regression cases and appropriate tolerances; run the relevant existing tests.
+10. **Keep documentation aligned.** Update applicable `dev/`, user documentation and examples when changing interfaces, conventions or numerical behaviour; report tests and benchmarks actually run.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://pypi.org/project/pyvale/"><img src="https://img.shields.io/pypi/v/pyvale?label=PyPI" alt="PyPI version"></a>
-  <a href="https://pypi.org/project/pyvale/"><img src="https://img.shields.io/pypi/pyversions/pyvale" alt="Supported Python versions"></a>
+  <a href="https://pypi.org/project/pyvale/"><img src="https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white" alt="Supported Python versions"></a>
   <a href="https://github.com/Computer-Aided-Validation-Laboratory/pyvale/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/Computer-Aided-Validation-Laboratory/pyvale/tests.yml?branch=main&label=tests" alt="Tests"></a>
   <a href="https://github.com/Computer-Aided-Validation-Laboratory/pyvale/actions/workflows/wheels.yml"><img src="https://img.shields.io/github/actions/workflow/status/Computer-Aided-Validation-Laboratory/pyvale/wheels.yml?branch=main&label=wheels" alt="Wheels"></a>
   <a href="https://computer-aided-validation-laboratory.github.io/pyvale/"><img src="https://img.shields.io/github/actions/workflow/status/Computer-Aided-Validation-Laboratory/pyvale/docs.yml?branch=main&label=docs" alt="Documentation"></a>

diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "pyvale"
-version = "2026.9.5"
+version = "2026.10.0"
 description = "Your virtual engineering lab: An all-in-one package for simulation-driven experimental design."
 authors = [
   { name = "scepticalrabbit et al.", email = "[email protected]" },
@@ -20,7 +20,7 @@ dependencies = [
   "matplotlib>=3.8",
   "pyvista>=0.43.3",
   "vtk>=9.5.2",
-  "netCDF4>=1.6.5",  
+  "netCDF4==1.7.5",
   "sympy>=1.13.0",
   "PyQT6>=6.7.1",
   "imageio>=2.36.1",
@@ -29,7 +29,7 @@ dependencies = [
   "pyqtgraph>=0.13.7",
   "opencv-python>=4.13.0.92",
   "pandas>=2.3.1",
-  "riley-raster>=2026.9.2",
+  "riley-raster==2026.10.1",
 ]
 
 [project.optional-dependencies]

diff --git a/src/pyvale/dic/_dicchecks.py b/src/pyvale/dic/_dicchecks.py
@@ -87,9 +87,17 @@ def _multiwindow_init(subset_size: int,
                              f"{multiwindow_search_area[i]} at index {i}")
 
     overlap = [x * (1.0-multiwindow_overlap) for x in multiwindow_subset_size]
+    configured_overlap = list(map(int, overlap))
     overlap.append(subset_step)
     overlap  = list(map(int,overlap))
 
+    # Avoid running the same final FFT level twice when size and overlap are identical
+    if (multiwindow_subset_size and
+            multiwindow_subset_size[-1] == subset_size and
+            multiwindow_search_area[-1] == subset_size and
+            configured_overlap[-1] == subset_step):
+        return configured_overlap, multiwindow_subset_size, multiwindow_search_area
+
     multiwindow_subset_size.append(subset_size)
     multiwindow_search_area.append(subset_size)
 
@@ -245,7 +253,9 @@ def _check_thresholds(threshold: float,
         raise ValueError("Optimizer precision must be a float strictly "
                          "between 0 and 1.")
 
-def _check_subsets(subset_size: int, subset_step: int) -> None:
+def _check_subsets(subset_size: int,
+                   subset_step: int,
+                   method: str | None = None) -> None:
     """
 
     Parameters
@@ -254,6 +264,9 @@ def _check_subsets(subset_size: int, subset_step: int) -> None:
         Threshold for the Levenberg optimization method.
     subset_step : int
         Threshold for the brute-force optimization method.
+    method : str, optional
+        Scan method. Even subset sizes are supported by the FFT-only
+        ``MULTIWINDOW`` method, but remain disallowed for the other methods.
 
     Raises
     ------
@@ -262,8 +275,8 @@ def _check_subsets(subset_size: int, subset_step: int) -> None:
     """
 
 
-    # Enforce scalar types for non-FFT methods
-    if subset_size % 2 == 0:
+    # The FFT-only multiwindow path handles even-sized subsets explicitly.
+    if subset_size % 2 == 0 and method != "MULTIWINDOW":
         raise ValueError("subset_size must be an odd number.")
 
     # check if subset_step is larger than the subset_size

diff --git a/src/pyvale/dic/dic2d.py b/src/pyvale/dic/dic2d.py
@@ -232,7 +232,7 @@ def calculate_2d(reference: np.ndarray | str | Path,
 
     dicchecks._check_thresholds(threshold, precision)
     common_util.check_output_directory(str(output_basepath), output_prefix, print_level)
-    dicchecks._check_subsets(subset_size, subset_step)
+    dicchecks._check_subsets(subset_size, subset_step, method_enum.value)
     updated_seeds = dicchecks._check_and_update_rg_seed(seed, roi_mask, method_enum.value, w, h, subset_size, subset_step)
     num_params = dicchecks._check_shape_function(shape_function_enum)
 

diff --git a/src/pyvale/dic/dic3d.py b/src/pyvale/dic/dic3d.py
@@ -130,7 +130,9 @@ def calculate_3d(reference: list[np.ndarray] | list[str] | list[Path],
         the existing flat format ``[x0, y0, x1, y1, ...]`` or tuple format
         ``[(x0, y0), (x1, y1), ...]``. If the method is not RG, this will be ignored.
     subset_size : int, optional
-        Size of the square subset window in pixels (default: 21).
+        Size of the square subset window in pixels (default: 21). Must be odd
+        except for the FFT-only ``"MULTIWINDOW"`` method, which also supports
+        even sizes.
     subset_step : int, optional
         Step size between subset centers in pixels (default: 10).
     correlation_criteria : str, optional
@@ -323,7 +325,7 @@ def calculate_3d(reference: list[np.ndarray] | list[str] | list[Path],
     # checks on the config
     dicchecks._check_thresholds(threshold, precision)
     common_util.check_output_directory(str(output_basepath), output_prefix, print_level)
-    dicchecks._check_subsets(subset_size, subset_step)
+    dicchecks._check_subsets(subset_size, subset_step, method_enum.value)
     updated_seeds = dicchecks._check_and_update_rg_seed(seed, roi_mask, method_enum.value, w0, h0, subset_size, subset_step)
     num_params = dicchecks._check_shape_function(shape_function_enum)
 

diff --git a/src/pyvale/examples/render3d/ex1a_riley_quickstart.py b/src/pyvale/examples/render3d/ex1a_riley_quickstart.py
@@ -61,6 +61,7 @@
     rot_world=Rotation.identity(),
     roi_cent_world=np.zeros(3),
     focal_length=1.0,
+    subsample=4,
 )
 
 camera = render.cam_frame_mesh(camera, mesh, fov_scale=1.0)
@@ -69,9 +70,12 @@
 # 3. Build renderer backend
 # -------------------------------
 
-config = riley.create_raster_config(1, save_strategy=riley.SaveStrategy.both)
+config = riley.RasterConfig(
+    parallel=1,
+    save_strategy=riley.SaveStrategy.both,
+    image_save_mode=riley.ImageSaveMode.grey,
+)
 config.report = riley.ReportMode.bench
-config.image_save_mode = riley.ImageSaveMode.grey
 config.save_scaling = riley.ScaleStrategy.none
 
 output_dir = Path.cwd() / "pyvale-output" / "render3d_ex1a_riley_quickstart"

diff --git a/src/pyvale/examples/render3d/ex1b_riley_sphere200.py b/src/pyvale/examples/render3d/ex1b_riley_sphere200.py
@@ -77,7 +77,7 @@
     rot_world=rotation,
     roi_cent_world=np.zeros(3),
     focal_length=focal_length,
-    subsample=2,
+    subsample=4,
 )
 
 camera = render.cam_frame_mesh(camera, mesh, fov_scale=1.0)
@@ -86,10 +86,11 @@
 # 3. Configure and build the renderer
 # ------------------------------------------------------------
 
-config = riley.create_raster_config(
-    num_frames=1,
-    total_threads=4,
+config = riley.RasterConfig(
+    parallel=4,
     save_strategy=riley.SaveStrategy.disk,
+    image_save_mode=riley.ImageSaveMode.grey,
+    save_scaling=riley.ScaleStrategy.auto,
 )
 output_dir = Path.cwd() / "pyvale-output" / "render3d_ex1b_riley_sphere200"
 

diff --git a/src/pyvale/examples/render3d/ex1c_riley_rabbits.py b/src/pyvale/examples/render3d/ex1c_riley_rabbits.py
@@ -137,7 +137,7 @@ def load_rabbit(
     rot_world=Rotation.identity(),
     roi_cent_world=np.zeros(3),
     focal_length=focal_length,
-    subsample=2,
+    subsample=4,
 )
 
 camera = render.cam_frame_scene(camera, meshes, fov_scale=1.01)
@@ -146,9 +146,8 @@ def load_rabbit(
 # 3. Configure and build the renderer
 # ------------------------------------------------------------
 
-config = riley.create_raster_config(
-    num_frames=1,
-    total_threads=4,
+config = riley.RasterConfig(
+    parallel=4,
     save_strategy=riley.SaveStrategy.disk,
 )
 config.background_value = 127.5

diff --git a/src/pyvale/examples/render3d/ex1d_riley_dicuq.py b/src/pyvale/examples/render3d/ex1d_riley_dicuq.py
@@ -103,12 +103,12 @@
     rot_world=rot_world_0,
     roi_cent_world=roi_centre,
     focal_length=focal_length,
-    sub_sample=2,
-    distortion_model=distortion_model,
-    distortion_k1=-0.2,
-    distortion_k2=0.1,
-    distortion_p1=0.0001,
-    distortion_p2=-0.0001,
+    sub_sample=4,
+    distort_model=distortion_model,
+    distort_k1=-0.2,
+    distort_k2=0.1,
+    distort_p1=0.0001,
+    distort_p2=-0.0001,
 )
 
 camera_1 = copy.deepcopy(camera_0)
@@ -119,9 +119,8 @@
 # 3. Configure and build the renderer
 # ------------------------------------------------------------
 
-config = riley.create_raster_config(
-    num_frames=mesh.displacements.shape[0],
-    total_threads=8,
+config = riley.RasterConfig(
+    parallel=4,
     save_strategy=riley.SaveStrategy.disk,
 )
 config.background_value = 128.0

diff --git a/src/pyvale/examples/render3d/ex1e_riley_dic_from_exodus.py b/src/pyvale/examples/render3d/ex1e_riley_dic_from_exodus.py
@@ -111,12 +111,12 @@
     rot_world=rot_world_0,
     roi_cent_world=roi_centre,
     focal_length=focal_length,
-    sub_sample=2,
-    distortion_model=distortion_model,
-    distortion_k1=-0.2,
-    distortion_k2=0.1,
-    distortion_p1=0.0001,
-    distortion_p2=-0.0001,
+    sub_sample=4,
+    distort_model=distortion_model,
+    distort_k1=-0.2,
+    distort_k2=0.1,
+    distort_p1=0.0001,
+    distort_p2=-0.0001,
 )
 
 camera_1 = copy.deepcopy(camera_0)
@@ -129,9 +129,8 @@
 # 3. Configure and build the renderer
 # ------------------------------------------------------------
 
-config = riley.create_raster_config(
-    num_frames=surface_mesh.displacements.shape[0],
-    total_threads=8,
+config = riley.RasterConfig(
+    parallel=4,
     save_strategy=riley.SaveStrategy.disk,
 )
 

diff --git a/src/pyvale/examples/render3d/ex1f_riley_stereocal.py b/src/pyvale/examples/render3d/ex1f_riley_stereocal.py
@@ -98,13 +98,13 @@
     rot_world=rot_world_0,
     roi_cent_world=roi_cent,
     focal_length=focal_length,
-    sub_sample=2,
-    distortion_model=distortion_model,
-    distortion_k1=-0.2,
-    distortion_k2=0.1,
-    distortion_k3=0.0,
-    distortion_p1=0.0001,
-    distortion_p2=-0.0001,
+    sub_sample=4,
+    distort_model=distortion_model,
+    distort_k1=-0.2,
+    distort_k2=0.1,
+    distort_k3=0.0,
+    distort_p1=0.0001,
+    distort_p2=-0.0001,
 )
 
 camera_1 = copy.deepcopy(camera_0)
@@ -126,10 +126,10 @@
 # 5. Configure and build the renderer
 # ------------------------------------------------------------
 
-config = riley.create_raster_config(
-    num_frames=mesh.displacements.shape[0],
-    total_threads=4,
+config = riley.RasterConfig(
+    parallel=4,
     save_strategy=riley.SaveStrategy.disk,
+    save_scaling=riley.ScaleStrategy.auto,
 )
 config.background_value = 128.0
 

diff --git a/src/pyvale/examples/render3d/ex1g_riley_psf.py b/src/pyvale/examples/render3d/ex1g_riley_psf.py
@@ -79,12 +79,11 @@
 scene = render.Scene3D(meshes=[mesh], cameras=[camera])
 
 for buffer_mode in buffer_modes:
-    config = riley.create_raster_config(
-        num_frames=1,
-        total_threads=4,
+    config = riley.RasterConfig(
+        parallel=4,
         save_strategy=riley.SaveStrategy.disk,
     )
-    
+
     config.buffer_mode = buffer_mode
     output_dir = output_root / buffer_mode.name
     renderer = render.Riley(config, output_dir)

diff --git a/src/pyvale/examples/render3d/ex1h_riley_feature_zoo.py b/src/pyvale/examples/render3d/ex1h_riley_feature_zoo.py
@@ -202,11 +202,11 @@ def build_cameras(meshes: list[riley.Mesh]) -> list[riley.Camera]:
         cam.sub_sample = sub_sample
 
         if optics in ("distortion", "both", "ring"):
-            cam.distortion_model = 1
-            cam.distortion_k1 = -0.12
-            cam.distortion_k2 = 0.035
-            cam.distortion_p1 = 0.0002
-            cam.distortion_p2 = -0.0001
+            cam.distort_model = 1
+            cam.distort_k1 = -0.12
+            cam.distort_k2 = 0.035
+            cam.distort_p1 = 0.0002
+            cam.distort_p2 = -0.0001
 
         if optics in ("psf", "both"):
             cam.psf_type = riley.PsfType.gaussian
@@ -300,9 +300,8 @@ def render_case(channels: int, bits: int) -> None:
     native_meshes = [render.to_riley_mesh(mesh) for mesh in meshes]
     cameras = build_cameras(native_meshes)
     case_name = f"{'mono' if channels == 1 else 'rgb'}-u{bits}"
-    config = riley.create_raster_config(
-        num_frames=len(FRAME_INDICES),
-        total_threads=4,
+    config = riley.RasterConfig(
+        parallel=4,
         save_strategy=riley.SaveStrategy.disk,
     )
     config.image_save_mode = (