API overview

API overview#

This section documents the installable FlyDSL Python API and the source-tree kernel library. Inclusion in the documentation does not by itself make an API stable: API Stability is the authoritative compatibility policy.

Primary namespaces#

Namespace	Use it for	Reference
`flydsl.expr` (normally `fx`)	DSL scalar and aggregate values, layouts, tensors, memory operations, tiled copy/MMA, control flow helpers, GPU intrinsics, and target-specific operations.	FlyDSL Python DSL
`flydsl.compiler` (normally `flyc`)	Kernel and launcher decorators, specialization, argument conversion, C object export, and backend registration.	Compiler and pipeline
`flydsl.extension`	Libraries implemented on top of the expression language, currently cooperative algorithms and random-number generation. They are also lazily available as `fx.coop` and `fx.random`.	Extension libraries
`flydsl.runtime.device`	Query the target ROCm architecture and distinguish RDNA from CDNA.	Stable runtime helpers
Repository `kernels` tree	Pre-built and reference kernels used from a source checkout. These interfaces are not installed by the wheel and are not stable APIs.	Pre-built kernels

Recommended imports#

import flydsl.compiler as flyc
import flydsl.expr as fx
from flydsl.runtime.device import get_rocm_arch, is_rdna_arch

# Extension aliases are loaded only when first accessed.
reduce_fn = fx.coop.warp_reduce
random_fn = fx.random.rand4x

Most kernel code needs only flyc and fx. Import the runtime helpers only when host code must select an architecture-specific path.

Where DSL operations may run#

Expression operations create MLIR and therefore run while a @flyc.jit or @flyc.kernel function is being traced. They are not eager numerical operations on ordinary Python values. Compile-time values such as fx.Constexpr and static layouts may be folded during tracing; dynamic DSL values emit IR.

Host-side helpers are different. Argument adapters such as flyc.from_dlpack and the architecture helpers in flydsl.runtime.device execute as ordinary Python code.

Package boundary and stability#

The wheel contains the flydsl package and its embedded MLIR runtime. It does not install the repository’s kernels or tests packages. Those source-tree modules are covered by the Guides section, not this API reference.

API Stability defines the compatibility contract for exported expression modules, compiler entry points, extension libraries, and the two runtime helpers listed above.

Print the exact stable catalog for the current checkout without importing the GPU runtime:

python3 scripts/list_stable_apis.py
python3 scripts/list_stable_apis.py --format json

Use the catalog when checking a release boundary. The reference pages provide usage context, but only paths that satisfy API Stability carry a compatibility commitment. The source-tree kernel page is explicitly outside that commitment.