Metadata-Version: 2.4
Name: slimcuda
Version: 0.9.4.1
Summary: CUDA, MLX, and NumPy backends for large-scale hologram generation and SLM wavefront synthesis.
Author-email: jwangXTS <junlei.wang@me.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.2
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x<14.0,>=13.0; extra == "cuda"
Requires-Dist: cuda-python<13.0,>=12.4; extra == "cuda"
Requires-Dist: PyOpenGL; extra == "cuda"
Requires-Dist: opencv-python; extra == "cuda"
Requires-Dist: glfw; extra == "cuda"
Requires-Dist: matplotlib; extra == "cuda"
Provides-Extra: mlx
Requires-Dist: mlx>=0.26; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
Requires-Dist: PyOpenGL; extra == "mlx"
Requires-Dist: opencv-python; extra == "mlx"
Requires-Dist: glfw; extra == "mlx"
Requires-Dist: matplotlib; extra == "mlx"
Provides-Extra: cpu
Requires-Dist: matplotlib; extra == "cpu"
Provides-Extra: cpu-gl
Requires-Dist: PyOpenGL; extra == "cpu-gl"
Requires-Dist: opencv-python; extra == "cpu-gl"
Requires-Dist: glfw; extra == "cpu-gl"
Requires-Dist: matplotlib; extra == "cpu-gl"
Provides-Extra: auto
Requires-Dist: cupy-cuda12x<14.0,>=13.0; platform_system != "Darwin" and extra == "auto"
Requires-Dist: cuda-python<13.0,>=12.4; platform_system != "Darwin" and extra == "auto"
Requires-Dist: mlx>=0.26; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "auto"
Requires-Dist: PyOpenGL; extra == "auto"
Requires-Dist: opencv-python; extra == "auto"
Requires-Dist: glfw; extra == "auto"
Requires-Dist: matplotlib; extra == "auto"

# SLiM-CUDA
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/slimcuda?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=RED&left_text=downloads)](https://pepy.tech/projects/slimcuda)
---
**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

```bash
pip install slimcuda
```

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

```bash
# 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:

```python
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:

```python
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:

```bash
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:
```bash
# 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

```bibtex
@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.
