rayx-python

Python bindings for RAYX, the ray tracing engine for synchrotron optics.

Installation

pip install rayx

Note: The package includes a compiled C++ extension and is distributed as a pre-built wheel. Source builds are not supported via pip.

Development

The project has two separate concerns that use different tools:

• uv manages the Python virtual environment and dependencies (numpy, pytest, etc.)
• setup_dev.sh builds the C++ extension and wires everything up for a fast dev loop
• cibuildwheel builds the final distributable wheel for release

Setup

./setup_dev.sh
source .venv/bin/activate

setup_dev.sh will:

1. Create a virtual environment with uv if one doesn't exist
2. Build the C++ extension via CMake
3. Symlink the compiled _core.so into python/rayx/ so it can be imported directly
4. Symlink rayxdata from the build directory
5. Generate python/rayx/_core.pyi type stubs so your LSP can resolve symbols from the C++ module

Project structure

python/rayx/
├── __init__.py # Python wrapper and public API
├── _core.so # Symlink to compiled C++ extension (generated by setup_dev.sh)
├── _core.pyi # Type stubs for LSP (generated by setup_dev.sh, do not edit)
└── [...].py # Additional files/directories for organization (need to be added to __init__.py)

LSP / editor support

Type stubs are generated automatically by setup_dev.sh. Point your LSP at the venv Python interpreter (.venv/bin/python3) and symbol resolution for _core will work out of the box.

If you need to regenerate stubs without a full rebuild:

source .venv/bin/activate
python3 -c "import syssys.path.insert(0, 'python')import rayx._core as mwith open('python/rayx/_core.pyi', 'w') as f: f.write('# Auto-generated stub - do not edit, regenerated by setup_dev.sh\n') for name in dir(m): if name.startswith('_'): continue obj = getattr(m, name) if callable(obj): f.write(f'def {name}(*args, **kwargs): ...\n') else: f.write(f'{name}: object\n')"

Running tests

uv run pytest tests

Release

Wheels are built using cibuildwheel inside a custom manylinux container with CUDA support:

pipx run cibuildwheel

Built wheels are placed in wheelhouse/. See pyproject.toml for the build configuration.