slimcuda 0.9.4.1

CUDA, MLX, and NumPy backends for large-scale hologram generation and SLM wavefront synthesis.

SLiM-CUDA

SLiM-CUDA is a backend collection for large-scale hologram generation and wavefront synthesis, designed for high-performance spatial light modulator (SLM) workflows.

The package contains CUDA, Apple MLX/Metal, and NumPy CPU fallback backends under one slimcuda namespace. The CUDA and MLX backends are intentionally independent because they target machines that normally cannot share the same accelerator stack.

---

Features

• CUDA-accelerated weighted Gerchberg–Saxton (WGS)–style solvers
• MLX/Metal backend for Apple Silicon using the original _og math path
• NumPy CPU backend for RS-only fallback and oracle testing
• Designed for large multi-focus hologram synthesis
• Backend-specific optional dependencies
• Drop-in CUDA upgrade path for optimized kernels (no API changes)

---

Installation

pip install slimcuda

The base install is CPU-safe and only installs shared Python code plus NumPy. Select the accelerator backend explicitly:

# CUDA machines
pip install "slimcuda[cuda]"

# Apple Silicon / Metal machines
pip install "slimcuda[mlx]"

# Let packaging markers choose CUDA on non-macOS and MLX on Apple Silicon
pip install "slimcuda[auto]"

# CPU oracle plus optional simulation plotting
pip install "slimcuda[cpu]"

Canonical dispatching import:

from slimcuda import SlimCuda

slm = SlimCuda()                            # CUDA + OpenGL render, legacy default
slm = SlimCuda(backend="cuda", render=False)
slm = SlimCuda(backend="mlx", render=False)
slm = SlimCuda(backend="cpu", render=False)

Direct backend imports remain available:

from slimcuda import SlimCudaGl, SlimCuda_base        # CUDA backend
from slimcuda import SlimCudaMlx, SlimCudaMlx_base    # MLX backend
from slimcuda import SlimCudaCpu, SlimCudaCpu_base    # NumPy fallback

Backend and render-environment diagnosis is available through the tester:

python slimcuda_tester.py --backend auto --diagnose-only
python slimcuda_tester.py --backend auto --render --diagnose-only

SlimCudaCpu_base implements RS methods only. WGS is intentionally not implemented on CPU because it is not practically useful at full SLM scale.

Kernel Architecture & Performance Model

Public CUDA kernel set

The PyPI wheel ships with CUDA source and public PTX assets, but CUDA runtime dependencies are installed only through the cuda or auto extras.

The public CUDA kernel set includes:

• slimcuda_og.ptx
• Corresponding CUDA source (.cu, .cuh) files

This build prioritizes:

• Broad GPU compatibility
• Reproducibility
• Ease of installation

⚠️ Performance note

The PTX kernels are not performance-optimized for modern GPUs. They exist to ensure correctness and portability.

Optimized builds (collaborators)

Highly optimized, GPU-specific kernels are distributed as fatbin / cubin binaries and are not included in the public wheel.

If an optimized kernel is present locally, SLiM-CUDA will automatically detect and load it.

Benefits:

• Substantially higher throughput
• Reduced launch overhead
• Architecture-specific tuning

If you are a collaborator or have a supported GPU and need optimized kernels, please contact the author.

Runtime Banner

SLiM-CUDA runtime banners have two layers:

• a loaded-backend indicator, for example [SLiM-CUDA] Loaded legacy PTX kernels ...
• an optional explanatory note for non-fatbin backends such as public PTX, MLX/Metal, or NumPy CPU

The optimized fatbin path only prints the loaded-backend indicator. Non-fatbin backends also print a short performance note by default; hide that note with:

# Linux / macOS
export SLIMCUDA_BANNER=0

# Windows (PowerShell)
setx SLIMCUDA_BANNER 0

To silence both layers programmatically, pass show_banner=False to the backend constructor/factory.

GPU Compatibility

• Public PTX kernels: should run on most CUDA-capable GPUs
• Optimized kernels: GPU- and build-specific

If you have an optimized kernel but encounter issues on your GPU, please contact the author for a tailored build.

License

• Python code: MIT License
• Public CUDA source (PTX / .cu): MIT License
• Optimized CUDA binaries: distributed separately under collaborator-specific terms

Citation

If you use SLiM-CUDA in academic work, please cite the following:

Primary citation (recommended)

SLiM-CUDA was originally developed to support the methodology described in:

Z. Qu et al., Deep-learning-aided multi-focal hologram generation, Optics & Laser Technology, 2025. DOI: 10.1016/j.optlastec.2024.112056

@article{jwangSlimCuda,
  title   = {Deep-learning-aided multi-focal hologram generation},
  author  = {Qu, Z. and others},
  journal = {Optics & Laser Technology},
  year    = {2025},
  doi     = {10.1016/j.optlastec.2024.112056}
}

If your work builds upon or uses the algorithms and concepts enabled by SLiM-CUDA,
please cite this publication.

Software citation

If you prefer to cite the software directly (e.g. for tooling or infrastructure use), you may cite:

SLiM-CUDA: GPU-accelerated hologram generation backend.
https://pypi.org/project/slimcuda/

A formal software citation entry (BibTeX) will be provided in a future release.

Disclaimer

This software is intended for research and advanced technical use.

API stability is maintained, but internal kernel implementations may evolve.