mirror of
https://github.com/ROCm/composable_kernel.git
synced 2026-05-15 10:37:44 +00:00
57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
# Client Example: General Tensor Contraction
|
|
|
|
## Theory
|
|
|
|
This client example demonstrates **general tensor contraction** operations, including bilinear and scaled contractions. Tensor contraction generalizes matrix multiplication to higher dimensions and is used in scientific computing, quantum chemistry, and advanced neural network layers.
|
|
|
|
**Mathematical Formulation:**
|
|
- General contraction: $C_{i,j} = \sum_k A_{i,k} \cdot B_{k,j}$
|
|
- Bilinear contraction: $C = \alpha (A \cdot B) + \beta D$
|
|
- Scale contraction: $C = \text{scale}(A, B)$ (elementwise or broadcasted scaling)
|
|
|
|
**Algorithmic Background:**
|
|
- Contraction can be performed over arbitrary axes and supports broadcasting.
|
|
- Bilinear and scale contractions are used for feature fusion, gating, and scientific workloads.
|
|
|
|
## How to Run
|
|
|
|
### Prerequisites
|
|
|
|
Please follow the instructions in the main [Build Guide](../../README.md#building-ck) section as a prerequisite to building and running this example.
|
|
|
|
### Build and run
|
|
```bash
|
|
cd composable_kernel/client_example/04_contraction
|
|
mkdir build && cd build
|
|
cmake -DCMAKE_CXX_COMPILER=/opt/rocm/bin/hipcc ..
|
|
make -j
|
|
|
|
# Example run (bilinear FP32)
|
|
./contraction_bilinear_fp32
|
|
|
|
# Example run (scale FP64)
|
|
./contraction_scale_fp64
|
|
```
|
|
|
|
## Source Code Structure
|
|
|
|
### Directory Layout
|
|
```
|
|
client_example/04_contraction/
|
|
├── contraction_bilinear_fp32.cpp # Bilinear contraction (FP32)
|
|
├── contraction_bilinear_fp64.cpp # Bilinear contraction (FP64)
|
|
├── contraction_g1m2n3k1_add_xdl_fp16.cpp # Grouped contraction with addition (FP16)
|
|
├── contraction_scale_fp32.cpp # Scale contraction (FP32)
|
|
├── contraction_scale_fp64.cpp # Scale contraction (FP64)
|
|
├── CMakeLists.txt # Build configuration for the example
|
|
```
|
|
|
|
### Key Functions
|
|
|
|
- **main()** (in each `.cpp`):
|
|
Sets up input tensors, configures contraction parameters, launches the contraction kernel, and verifies the result.
|
|
- **Contraction kernel invocation**:
|
|
Uses the Composable Kernel device API to launch the contraction operation.
|
|
|
|
This client example provides several variants to demonstrate different contraction types and data types for scientific and ML workloads.
|