Mesh Convention Tools for Upstreaming to pyvale

.gitignore

@@ -47,6 +47,8 @@ refs/
 # Keep the min test suite to ship with the repo
 !data/min/
 !data/min/**/*.csv
+!data/cubes/
+!data/cubes/**/*.csv
 !gold/min/
 !gold/min/**/*.fimg
 !gold/min/**/*.bmp
@@ -97,8 +99,8 @@ uv.lock
 
 # Cython
 *.html
-src/riley/cyth/riley.c
-src/riley/cyth/riley.html
+src/riley/cython/riley.c
+src/riley/cython/riley.html
 
 # Windows :(
 *.dll

MANIFEST.in

@@ -8,7 +8,7 @@ include scripts/python_package_data.toml
 recursive-include src/riley *.py *.pxd *.h *.zig
 
 prune src/riley/__pycache__
-prune src/riley/cyth/__pycache__
+prune src/riley/cython/__pycache__
 prune src/riley/zig/__pycache__
 prune src/riley_raster.egg-info
 prune src/riley.egg-info

README.md

@@ -95,11 +95,13 @@ or with the build system:
 zig build demo-<CASE> -Doptimize=ReleaseFast
 ```
 
-where `CASE` is one of `sphere200`, `rabbits`, `dicuq`, or `stereocal`. Zig demo output is written to `./out/demo-CASE/`.
+where `CASE` is one of `sphere200`, `psf`, `rabbits`, `dicuq`, or `stereocal`. Zig demo output is written to `./out/demo-CASE/`.
+The `psf` demo writes separate `global_subpx_full` and `global_subpx_stripe` subdirectories.
 
 Zig demo source on GitHub:
 
 - [`demo_sphere200.zig`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/demo_sphere200.zig)
+- [`demo_psf.zig`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/demo_psf.zig)
 - [`demo_rabbits.zig`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/demo_rabbits.zig)
 - [`demo_dicuq.zig`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/demo_dicuq.zig)
 - [`demo_stereocal.zig`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/demo_stereocal.zig)
@@ -115,6 +117,7 @@ Python demo output is written to `Path.cwd() / "out-riley-py" / "demo-CASE"`.
 Python demo source on GitHub:
 
 - [`demo_sphere200.py`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/riley/pydemos/demo_sphere200.py)
+- [`demo_psf.py`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/riley/pydemos/demo_psf.py)
 - [`demo_rabbits.py`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/riley/pydemos/demo_rabbits.py)
 - [`demo_dicuq.py`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/riley/pydemos/demo_dicuq.py)
 - [`demo_dic_from_exodus.py`](https://github.com/Computer-Aided-Validation-Laboratory/riley-raster/blob/main/src/riley/pydemos/demo_dic_from_exodus.py)

build.zig

@@ -2,8 +2,8 @@ const std = @import("std");
 
 const riley_version = std.SemanticVersion{
     .major = 2026,
-    .minor = 7,
-    .patch = 1,
+    .minor = 9,
+    .patch = 0,
 };
 
 const RunEntry = struct {
@@ -52,7 +52,7 @@ pub fn build(b: *std.Build) void {
         build_options_module,
     );
     shared_lib.installHeader(
-        b.path("src/riley/cyth/riley.h"),
+        b.path("src/riley/cython/riley.h"),
         "riley.h",
     );
     b.installArtifact(shared_lib);
@@ -95,6 +95,11 @@ pub fn build(b: *std.Build) void {
             .description = "Run the sphere200 demo",
             .source_path = "src/demo_sphere200.zig",
         },
+        .{
+            .step_name = "demo-psf",
+            .description = "Run the Gaussian PSF demo",
+            .source_path = "src/demo_psf.zig",
+        },
         .{
             .step_name = "demo-rabbits",
             .description = "Run the rabbits demo",

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .riley,
-    .version = "2026.7.1",
+    .version = "2026.9.0",
     .fingerprint = 0x7380980579fcd8b7, // Changing this has security and trust implications.
     .minimum_zig_version = "0.16.0",
     .dependencies = .{

data/FE/save_sim_to_csv.py

@@ -37,7 +37,7 @@ def main() -> None:
                 mesh_world.coords,
                 (2464, 2056),
                 uv_span_max=0.8,
-                projection_plane=(
+                proj_plane=(
                     np.array((0.0, 0.0, -1.0), dtype=np.float64),
                     np.array((0.0, 0.0, 0.0), dtype=np.float64),
                 ),

data/audit_mesh_convention.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Report whether every CSV mesh below ``data`` follows Riley's convention."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import importlib.util
+
+import numpy as np
+
+
+DATA_DIR = Path(__file__).resolve().parent
+CONNECT_FILENAMES = ("connect.csv", "connectivity.csv")
+
+
+def _load_meshconv():
+    """Load Riley's dependency-free convention module without its Cython API."""
+
+    module_path = DATA_DIR.parent / "src" / "riley" / "python" / "meshconv.py"
+    spec = importlib.util.spec_from_file_location("riley_meshconv", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Could not load mesh-convention module: {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+meshconv = _load_meshconv()
+
+
+def main() -> int:
+    results = [audit_mesh(mesh_dir) for mesh_dir in find_mesh_dirs()]
+    width = max(len(mesh_name) for status, mesh_name, _ in results)
+
+    print("Riley mesh convention audit")
+    print()
+    for status, mesh_name, detail in results:
+        print(f"{status:<11} {mesh_name:<{width}}  {detail}")
+
+    conforms = sum(status == "CONFORMS" for status, _, _ in results)
+    errors = len(results) - conforms
+    print()
+    print(f"Summary: {conforms} conform, {errors} do not ({len(results)} meshes total).")
+    return 1 if errors else 0
+
+
+def find_mesh_dirs() -> list[Path]:
+    return sorted(
+        {
+            path.parent
+            for filename in CONNECT_FILENAMES
+            for path in DATA_DIR.rglob(filename)
+            if path.parent.joinpath("coords.csv").is_file()
+        },
+    )
+
+
+def audit_mesh(mesh_dir: Path) -> tuple[str, str, str]:
+    mesh_name = mesh_dir.relative_to(DATA_DIR).as_posix()
+    try:
+        coords = np.loadtxt(mesh_dir / "coords.csv", delimiter=",", dtype=np.float64)
+        connect_paths = [mesh_dir / name for name in CONNECT_FILENAMES]
+        connect_paths = [path for path in connect_paths if path.is_file()]
+        connect_tables = [np.loadtxt(path, delimiter=",", dtype=np.int64) for path in connect_paths]
+        if len(connect_tables) == 2 and not np.array_equal(*connect_tables):
+            raise ValueError("connect.csv and connectivity.csv differ")
+
+        mesh = meshconv.SimData(
+            coords=np.atleast_2d(coords),
+            connect={"connect1": np.atleast_2d(connect_tables[0])},
+            mesh_type=_mesh_type_hint(mesh_dir),
+        )
+        report = meshconv.check_mesh_convention(mesh)
+    except (OSError, ValueError, NotImplementedError) as err:
+        return "DOES NOT", mesh_name, str(err)
+
+    if report.is_valid:
+        return "CONFORMS", mesh_name, ""
+    return "DOES NOT", mesh_name, ", ".join(report.failed_checks)
+
+
+def _mesh_type_hint(mesh_dir: Path) -> meshconv.EMeshType | None:
+    if (
+        mesh_dir.parent.name in {"FE", "cubes"}
+        or mesh_dir.name.endswith("calplate3d")
+    ):
+        return meshconv.EMeshType.VOL
+    if mesh_dir.name.startswith(("tri", "quad")):
+        return meshconv.EMeshType.SURF
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/bench/gen_bench_data.py

@@ -1,10 +1,23 @@
 import numpy as np
 import os
 
+from riley.python import meshconv
+
 def save_csv(path, data):
     os.makedirs(os.path.dirname(path), exist_ok=True)
     np.savetxt(path, data, delimiter=',', fmt='%.10f' if data.dtype == np.float64 else '%d')
 
+def save_surface_mesh(out_dir, coords, connect):
+    connect = meshconv.enforce_mesh_convention(
+        meshconv.MeshData(
+            coords=np.ascontiguousarray(coords, dtype=np.float64),
+            connect={"connect1": np.ascontiguousarray(connect, dtype=np.int64)},
+            mesh_type="surface",
+        )
+    ).connect["connect1"]
+    save_csv(f"{out_dir}/coords.csv", coords)
+    save_csv(f"{out_dir}/connect.csv", connect)
+
 def get_nodes_for_elem(etype):
     return {
         "tri3": 3,
@@ -68,8 +81,7 @@ def generate_fullscreen(etype, out_dir):
             else: connect = np.array([[0, 1, 2, 3, 4, 5, 6, 7, 8]])
         else:
             connect = np.array([[0, 1, 2, 3]])
-    save_csv(f"{out_dir}/coords.csv", coords)
-    save_csv(f"{out_dir}/connect.csv", connect)
+    save_surface_mesh(out_dir, coords, connect)
     save_csv(f"{out_dir}/field.csv", compute_rgb_fields(coords))
     save_csv(f"{out_dir}/uvs.csv", compute_uvs(coords))
 
@@ -102,8 +114,7 @@ def generate_grid(etype, out_dir, N=320):
                 q8 = [i0, i1, i2, i3, m01, m12, m23, m30]
                 if etype == "quad9": q8.append(i0+(xn+1)+1)
                 conn.append(q8)
-    save_csv(f"{out_dir}/coords.csv", coords)
-    save_csv(f"{out_dir}/connect.csv", np.array(conn))
+    save_surface_mesh(out_dir, coords, np.array(conn))
     save_csv(f"{out_dir}/field.csv", compute_rgb_fields(coords))
     save_csv(f"{out_dir}/uvs.csv", compute_uvs(coords))
 
@@ -199,8 +210,7 @@ def generate_sphere(etype, out_dir, N_target):
                     q.append((r + 1) * cols + (c + 1))
                 conn.append(q)
 
-    save_csv(f"{out_dir}/coords.csv", coords)
-    save_csv(f"{out_dir}/connect.csv", np.array(conn))
+    save_surface_mesh(out_dir, coords, np.array(conn))
     save_csv(f"{out_dir}/uvs.csv", uvs)
     save_csv(f"{out_dir}/field.csv", fields)
 

data/calplate/main_gen_calplate.py

@@ -8,6 +8,8 @@
 from scipy.spatial.transform import Rotation
 from scipy.stats import qmc
 
+from riley.python import meshconv
+
 
 BASE_DIR = Path(__file__).resolve().parent
 
@@ -445,11 +447,20 @@ def write_case(
     connect: np.ndarray,
     uvs: np.ndarray,
     states: list[MotionState],
+    enforce_convention: bool = False,
 ) -> None:
     out_dir = BASE_DIR / case_name
     out_dir.mkdir(parents=True, exist_ok=True)
 
     disp_x, disp_y, disp_z = displacement_fields(coords, states)
+    if enforce_convention:
+        connect = meshconv.enforce_mesh_convention(
+            meshconv.MeshData(
+                coords=np.ascontiguousarray(coords, dtype=np.float64),
+                connect={"connect1": np.ascontiguousarray(connect, dtype=np.int64)},
+                mesh_type="surface",
+            )
+        ).connect["connect1"]
 
     save_csv_matrix(out_dir / "coords.csv", coords, "%.10f")
     save_csv_matrix(out_dir / "connect.csv", connect, "%d")
@@ -478,7 +489,7 @@ def main() -> None:
     cases = mesh_cases()
 
     for case_name, (coords, connect, uvs) in cases.items():
-        write_case(case_name, coords, connect, uvs, states)
+        write_case(case_name, coords, connect, uvs, states, enforce_convention=True)
 
     print(f"Generated {len(cases)} calplate mesh cases in {BASE_DIR}")
     print(f"Mode: {CAL_MODE}")

data/cubes/README.md

@@ -0,0 +1,9 @@
+# Mesh-convention cube fixtures
+
+These files are small CSV exports of PyVale's 10 mm element-test cubes.
+`connectivity.csv` deliberately retains the source Exodus convention: it is
+one-based and node-major. Riley mesh-convention tests use these fixtures to
+verify normalization to zero-based, row-major connectivity.
+
+The supported fixtures are `tet4`, `tet10`, `hex8`, `hex20`, and `hex27`.
+`tet14` is retained as the explicit unsupported-topology fixture.

data/cubes/hex20/connectivity.csv

@@ -0,0 +1,8 @@
+0,1,2,3,4,5,6,7,8,9,10,11,16,17,18,19,12,13,14,15
+1,20,21,2,5,22,23,6,24,25,26,9,29,30,31,17,13,27,28,14
+3,2,32,33,7,6,34,35,10,36,37,38,18,41,42,43,15,14,39,40
+2,21,44,32,6,23,45,34,26,46,47,36,31,49,50,41,14,28,48,39
+4,5,6,7,51,52,53,54,16,17,18,19,59,60,61,62,55,56,57,58
+5,22,23,6,52,63,64,53,29,30,31,17,67,68,69,60,56,65,66,57
+7,6,34,35,54,53,70,71,18,41,42,43,61,74,75,76,58,57,72,73
+6,23,45,34,53,64,77,70,31,49,50,41,69,79,80,74,57,66,78,72

data/cubes/hex20/coords.csv

@@ -0,0 +1,81 @@
+0,0,0
+0.0050000000000000001,0,0
+0.0050000000000000001,0.0050000000000000001,0
+0,0.0050000000000000001,0
+0,0,0.0050000000000000001
+0.0050000000000000001,0,0.0050000000000000001
+0.0050000000000000001,0.0050000000000000001,0.0050000000000000001
+0,0.0050000000000000001,0.0050000000000000001
+0.0025000000000000001,0,0
+0.0050000000000000001,0.0025000000000000001,0
+0.0025000000000000001,0.0050000000000000001,0
+0,0.0025000000000000001,0
+0,0,0.0025000000000000001
+0.0050000000000000001,0,0.0025000000000000001
+0.0050000000000000001,0.0050000000000000001,0.0025000000000000001
+0,0.0050000000000000001,0.0025000000000000001
+0.0025000000000000001,0,0.0050000000000000001
+0.0050000000000000001,0.0025000000000000001,0.0050000000000000001
+0.0025000000000000001,0.0050000000000000001,0.0050000000000000001
+0,0.0025000000000000001,0.0050000000000000001
+0.01,0,0
+0.01,0.0050000000000000001,0
+0.01,0,0.0050000000000000001
+0.01,0.0050000000000000001,0.0050000000000000001
+0.0074999999999999997,0,0
+0.01,0.0025000000000000001,0
+0.0074999999999999997,0.0050000000000000001,0
+0.01,0,0.0025000000000000001
+0.01,0.0050000000000000001,0.0025000000000000001
+0.0074999999999999997,0,0.0050000000000000001
+0.01,0.0025000000000000001,0.0050000000000000001
+0.0074999999999999997,0.0050000000000000001,0.0050000000000000001
+0.0050000000000000001,0.01,0
+0,0.01,0
+0.0050000000000000001,0.01,0.0050000000000000001
+0,0.01,0.0050000000000000001
+0.0050000000000000001,0.0074999999999999997,0
+0.0025000000000000001,0.01,0
+0,0.0074999999999999997,0
+0.0050000000000000001,0.01,0.0025000000000000001
+0,0.01,0.0025000000000000001
+0.0050000000000000001,0.0074999999999999997,0.0050000000000000001
+0.0025000000000000001,0.01,0.0050000000000000001
+0,0.0074999999999999997,0.0050000000000000001
+0.01,0.01,0
+0.01,0.01,0.0050000000000000001
+0.01,0.0074999999999999997,0
+0.0074999999999999997,0.01,0
+0.01,0.01,0.0025000000000000001
+0.01,0.0074999999999999997,0.0050000000000000001
+0.0074999999999999997,0.01,0.0050000000000000001
+0,0,0.01
+0.0050000000000000001,0,0.01
+0.0050000000000000001,0.0050000000000000001,0.01
+0,0.0050000000000000001,0.01
+0,0,0.0074999999999999997
+0.0050000000000000001,0,0.0074999999999999997
+0.0050000000000000001,0.0050000000000000001,0.0074999999999999997
+0,0.0050000000000000001,0.0074999999999999997
+0.0025000000000000001,0,0.01
+0.0050000000000000001,0.0025000000000000001,0.01
+0.0025000000000000001,0.0050000000000000001,0.01
+0,0.0025000000000000001,0.01
+0.01,0,0.01
+0.01,0.0050000000000000001,0.01
+0.01,0,0.0074999999999999997
+0.01,0.0050000000000000001,0.0074999999999999997
+0.0074999999999999997,0,0.01
+0.01,0.0025000000000000001,0.01
+0.0074999999999999997,0.0050000000000000001,0.01
+0.0050000000000000001,0.01,0.01
+0,0.01,0.01
+0.0050000000000000001,0.01,0.0074999999999999997
+0,0.01,0.0074999999999999997
+0.0050000000000000001,0.0074999999999999997,0.01
+0.0025000000000000001,0.01,0.01
+0,0.0074999999999999997,0.01
+0.01,0.01,0.01
+0.01,0.01,0.0074999999999999997
+0.01,0.0074999999999999997,0.01
+0.0074999999999999997,0.01,0.01