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.

[Mateasek]

Hi @munechika-koyo , this is a very nice generalisation of the RT framework! I have one important question to raise.

Changing the indexing function from Function3D to Function6D would allow to pass also direction information which would make the new IRT framwrok applicable to also anisotropic radiation.

[Mateasek]

Making index_function a Function3D makes the IndexedRay framework specific to isotropic radiation. If you made it Function6D which now we have in Cherab, the framework would be generalised to anisotropic applications because you could also pass direction vector components. That is something I'm be very interested in. From the point of view of the code it shouldn't be a large change. What do you think @munechika-koyo?

[munechika-koyo]

That sounds really interesting!
It might also be useful for distributional tomography.
I think we need to add a new API or refactor the existing one to accept Function6D as an index function for the IndexedRayTransferEmitter.emission_function() and IndexedRayTransferIntegrator.integrate() methods.
These changes don't seem straightforward to me, so should we handle them in a separate PR after finalizing this one?

In addition, any good ideas for your demo using Function6D would be really helpful.