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.