|
| 1 | +# Overview |
| 2 | +The `experimental_ops` module provides a space for new operators that are not yet ready for production release. Operators in this module are accessible via `flag_gems.experimental_ops.*` and follow the same development patterns as core operators. |
| 3 | + |
| 4 | +# Usage Example |
| 5 | +Users can access operators as: |
| 6 | +``` |
| 7 | +import flag_gems |
| 8 | +
|
| 9 | +# Global enablement |
| 10 | +flag_gems.enable() |
| 11 | +result = flag_gems.experimental_ops.your_operator(*args) |
| 12 | +
|
| 13 | +# Or scoped usage |
| 14 | +with flag_gems.use_gems(): |
| 15 | + result = flag_gems.experimental_ops.your_operator(*args) |
| 16 | +``` |
| 17 | + |
| 18 | + |
| 19 | +# File Structure |
| 20 | +``` |
| 21 | +src/flag_gems/experimental_ops/ |
| 22 | +├── __init__.py # Module initialization |
| 23 | +├── rmsnorm.py # Example operator implementation |
| 24 | +├── [other_operators].py # Additional operators |
| 25 | +├── exp_tests/ # Accuracy test and performance test |
| 26 | + ├── __init__.py |
| 27 | + ├── rmsnorm_test.py |
| 28 | + ├── [other_operators]_test.py |
| 29 | +``` |
| 30 | + |
| 31 | +# Adding New Operators |
| 32 | +## 1. Create Operator Implementation |
| 33 | +Create your operator file in `src/flag_gems/experimental_ops/`: |
| 34 | +``` |
| 35 | +# src/flag_gems/experimental_ops/your_operator.py |
| 36 | +from flag_gems.utils import libentry |
| 37 | +
|
| 38 | +@libentry() |
| 39 | +@triton.autotune( |
| 40 | + configs=[...], |
| 41 | + key=[...] |
| 42 | +) |
| 43 | +def your_operator_kernel(...): |
| 44 | + # Triton kernel implementation |
| 45 | + pass |
| 46 | +
|
| 47 | +def your_operator(*args, **kwargs): |
| 48 | + # Python wrapper |
| 49 | + return your_operator_kernel(*args, **kwargs) |
| 50 | +``` |
| 51 | + |
| 52 | +## 2. Update Module Exports |
| 53 | +Add your operator to `src/flag_gems/experimental_ops/__init__.py` : |
| 54 | +``` |
| 55 | +from .your_operator import your_operator |
| 56 | +__all__ = ["rmsnorm", "your_operator"] |
| 57 | +``` |
| 58 | + |
| 59 | +## 3. Update Main Module |
| 60 | +The experimental_ops module is already integrated in the main `__init__.py` . No changes needed there. |
| 61 | + |
| 62 | + |
| 63 | +# Testing |
| 64 | +## Accuracy Tests |
| 65 | +Add accuracy test in `exp_tests/your_ops_test.py`: |
| 66 | +``` |
| 67 | +import pytest |
| 68 | +import torch |
| 69 | +import flag_gems |
| 70 | +from tests.accuracy_utils import ( |
| 71 | + FLOAT_DTYPES, |
| 72 | + gems_assert_close, |
| 73 | + to_reference, |
| 74 | +) |
| 75 | +
|
| 76 | +@pytest.mark.your_operator |
| 77 | +@pytest.mark.parametrize("shape", [...]) |
| 78 | +@pytest.mark.parametrize("dtype", FLOAT_DTYPES) |
| 79 | +def test_accuracy_your_operator(shape, dtype): |
| 80 | + # Test implementation |
| 81 | + inp = torch.randn(shape, dtype=dtype, device=flag_gems.device) |
| 82 | + ref_inp = to_reference(inp, True) |
| 83 | +
|
| 84 | + # Reference implementation |
| 85 | + ref_out = torch.your_operator(ref_inp, ...) |
| 86 | +
|
| 87 | + # FlagGems implementation |
| 88 | + with flag_gems.use_gems(): |
| 89 | + res_out = flag_gems.experimental_ops.your_operator(inp, ...) |
| 90 | +
|
| 91 | + gems_assert_close(res_out, ref_out, dtype) |
| 92 | +``` |
| 93 | + |
| 94 | +## Performance Tests |
| 95 | +Add performance test in `exp_tests/your_ops_test.py`: |
| 96 | +``` |
| 97 | +import pytest |
| 98 | +import torch |
| 99 | +import time |
| 100 | +import flag_gems |
| 101 | +
|
| 102 | +class TestYourOperatorPerf: |
| 103 | + def setup_method(self): |
| 104 | + flag_gems.enable() |
| 105 | +
|
| 106 | + def teardown_method(self): |
| 107 | + flag_gems.disable() |
| 108 | +
|
| 109 | + @pytest.mark.your_operator |
| 110 | + @pytest.mark.parametrize("shape", [...]) |
| 111 | + def test_perf_your_operator(self, shape): |
| 112 | + inp = torch.randn(shape, device=flag_gems.device) |
| 113 | +
|
| 114 | + # Warmup |
| 115 | + for _ in range(10): |
| 116 | + _ = flag_gems.experimental_ops.your_operator(inp) |
| 117 | +
|
| 118 | + torch.cuda.synchronize() |
| 119 | +
|
| 120 | + # Benchmark FlagGems |
| 121 | + start_time = time.time() |
| 122 | + for _ in range(100): |
| 123 | + out = flag_gems.experimental_ops.your_operator(inp) |
| 124 | + torch.cuda.synchronize() |
| 125 | + gems_time = (time.time() - start_time) / 100 |
| 126 | +
|
| 127 | + # Benchmark PyTorch |
| 128 | + start_time = time.time() |
| 129 | + for _ in range(100): |
| 130 | + ref_out = torch.your_operator(inp) |
| 131 | + torch.cuda.synchronize() |
| 132 | + torch_time = (time.time() - start_time) / 100 |
| 133 | +
|
| 134 | + speedup = torch_time / gems_time |
| 135 | + print(f"YourOperator {shape}: Speedup {speedup:.2f}x") |
| 136 | +
|
| 137 | + assert speedup > 1.0, "Should be faster than PyTorch" |
| 138 | +``` |
| 139 | + |
| 140 | +# CI Integration |
| 141 | +Add tests ad performace tests to the CI workflow `.github/workflows/gems-experimental-test.yaml` . |
0 commit comments