Introduce indexed ray transfer APIs and tests

[munechika-koyo]

Summary

This PR introduces a general index-function-based ray transfer API by adding indexed emitter and integrator classes, replacing mesh-specific naming with functionality-based naming.

Key Changes

• Added cherab/tools/raytransfer/emitters.pyx implementations:
  • IndexedRayTransferIntegrator
  • IndexedRayTransferEmitter
• Updated cherab/tools/raytransfer/emitters.pxd public Cython declarations for the new APIs.
• Added and updated unit tests in cherab/tools/tests/test_raytransfer.py:
  • evaluate behavior for indexed emission/integration
  • default integrator wiring
  • Discrete3DMesh-backed index_function behavior
  • equivalent tetrahedral mesh construction checks using numpy.ndindex patterns

Unit Test

Test	Purpose	Setup	Verification	Why it matters
test_evaluate_function	Validate that IndexedRayTransferEmitter works correctly with NumericalIntegrator and maps contributions to the correct bins via index_function.	A 3x3x3 Box domain is used with bins=27. A diagonal ray crosses the volume. The index function maps in-domain points to 0..26 and returns -1 outside.	Only bins 0, 13, and 26 are non-zero, each with path-length contribution sqrt(3). The output spectrum matches the expected vector with atol=0.001.	Confirms correct geometric integration and bin assignment for the index-function-based workflow.
test_default_integrator	Confirm default integrator behavior when no integrator is explicitly passed.	IndexedRayTransferEmitter is created without an integrator argument under the same ray/volume setup as above.	The emitter uses IndexedRayTransferIntegrator by default, and the resulting spectrum matches the same expected vector (atol=0.001).	Guarantees safe default behavior and avoids mandatory integrator wiring for users.
test_discrete3dmesh_as_index_function	Validate that Discrete3DMesh can be used as an equivalent index function source.	A Discrete3DMesh is built from a 4x4x4 vertex grid over 3x3x3 cells; each cube is split into 6 tetrahedra. Cell values follow the same indexing rule as the reference index function.	Representative points across all 27 cells match the reference mapping; outside-domain points return -1; ray-transfer spectra from mesh-based and function-based indexing are equal within atol=0.001.	Demonstrates implementation-agnostic design and compatibility with tetrahedral mesh indexing in practical ray-transfer use.

Executed:

python -m unittest cherab.tools.tests.test_raytransfer.TestIndexedRayTransferEmitter -v

Result:

• test_default_integrator: ok
• test_discrete3dmesh_as_index_function: ok
• test_evaluate_function: ok
• Ran 3 tests, all passed.

Example Usage

from raysect.optical import World
from cherab.tools.raytransfer import IndexedRayTransferEmitter

def index_func(x, y, z):
    if x < 0:
        return 0
    return 1

world = World()
material = IndexedRayTransferEmitter(index_func, bins=2)

Compatibility and Risk

• Scope is limited to ray transfer emitter/integrator API naming and related tests.
• Runtime behavior is validated by focused unit tests for indexed evaluation and Discrete3DMesh integration.

Reviewer Notes

• Main implementation: cherab/tools/raytransfer/emitters.pyx
• Public declarations: cherab/tools/raytransfer/emitters.pxd
• Validation tests: cherab/tools/tests/test_raytransfer.py

Checklist

• API implementation updated
• Cython declaration file updated
• Unit tests added/updated
• Targeted tests executed in pixi test environment

Benchmark

The appendix in this paper (https://doi.org/10.1063/5.0225703) compared the raytransfer of Discrete3D meshes with that of regular grids, showing that the geometry matrix calculation for rectangular grids' raytransfer was much faster than the Discrete3D one.

[jacklovell]

Very cool. If I understand this correctly, it's a generalisation of the existing ray transfer objects where a callable function replaces the voxel map, and this function returns the voxel index at a given point in space. As well as the 3D application in https://doi.org/10.1063/5.0225703 (which you should cite somewhere in the documentation by the way), I can see the possibility of application to axisymmetric voxels of arbitrary poloidal cross section without having to approximate them with a rectangular grid.

I think a demo would be highly beneficial, as it's hard to see a concrete use case from the docstrings alone. Perhaps you could adapt Vlad's Space Invaders demos to showcase the new tools.

[munechika-koyo]

Thank you for your review!
I've been thinking about what makes an effective demo script.
Currently, my ideas are using index functions like:

• analytical geometry with sin, cos, circle, etc.
• using mesh geometry (triangulation for 2D, tetrahedralization for 3D, e.g., Stanford Bunny data used in raysect).

I will try to work out these ideas with AI assistance for now.
Any idea of yours is really helpful.

[jacklovell]

Analytically-defined voxels will make a nice demo, agreed. For example, flux-aligned axisymmetric voxels for the generomak equilibrium defined in ($\Delta \psi$, $\Delta \beta$) space for normalised flux $\Psi$ and poloidal angle $\beta$. The ToroidalVoxelGrid could handle this but I expect the ray transfer framework to be more performant.

And yes, voxels defined by triangular or tetrahedral meshes would also be a good illustration, showing the ability to extend beyond regular rectilinear grids.