Skip to main content

Module wgsl_forge

Module wgsl_forge 

Source
Expand description

Deterministic WGSL generation, validation, certification, and tuning.

WGSL Forge treats shader semantics and hardware scheduling as separate typed inputs. Tuning is therefore allowed to change work distribution without changing the mathematical operation being certified.

Re-exports§

pub use runtime::ForgeRuntime;
pub use dispatch::caps;
pub use dispatch::coopmat_usable;
pub use dispatch::fft_f32;
pub use dispatch::gemm_cpu_f64;
pub use dispatch::gemm_f32;
pub use dispatch::gemm_f32_tc;
pub use dispatch::gemm_f32_tc_coopmat;
pub use dispatch::gemm_f32_tc_reduced;
pub use dispatch::gemm_f64;
pub use dispatch::gemm_f64_df64;
pub use dispatch::gemv_cpu_f64;
pub use dispatch::gemv_f32;
pub use dispatch::gemv_f64;
pub use dispatch::pairwise_sq_dist_cpu_f64;
pub use dispatch::pairwise_sq_dist_f64;
pub use observer_kernels::*;

Modules§

attention
audio
Forge-native audio kernels (GPU compute with a CPU oracle + parity certify).
backend
cache
calibration
W10 — Forge calibration pipeline (the training-related upgrade).
compute_passes
Portable compute execution over caller-supplied data.
device_options
dispatch
emit
etalon_bridge
execute
graph_ops
ir
manifest
observer_kernels
Five Normative Observer Projection Kernels for Holographic & Continuum Rendering.
oracle
physics
Certified physics forge kernels — complete, deterministic compute shaders with exact CPU oracles, naga validation, and GPU certification.
profiling
Caller-owned two-slot pass timer. Serialize use and request TIMESTAMP_QUERY first.
roofline
runtime
schedule
substrate_gemm
The portable wgpu f32 GEMM — the execute half of the bridge. Until now compute_bridge only probed and planned; this actually runs a kernel on the GPU and reads the result back, reusing the exact wgpu idioms the capability benchmark (crate::numerical::substrate_gemm) already uses on this hardware.
tune
validate

Structs§

AdapterConstraints
AdapterIdentity
AffineParams
AttentionSchedule
A hardware-safe attention schedule. The generated kernel uses one workgroup per attention head and an online tiled reduction over context.
AttentionShader
Generated attention kernel plus its Naga validation report.
AttentionShaderParams
Uniform parameter block matching AttentionParams in the generated attention shader.
AttentionShape
The attention workload bound into one Forge kernel.
BufferSpec
CandidateEvaluation
CandidateFailure
CandidateResult
CertificationManifest
ComparisonReport
ComputeCaps
Probed compute capabilities of this machine. Every flag reflects what was actually constructible at probe time, not what the build was compiled with — a cuda-feature build on a machine with no NVIDIA device still reports cuda == false.
EtalonGeneratedShader
EtalonKernelSpec
EtalonSchedule
EtalonValidationReport
FfnParams
16-byte uniform block for the fused-FFN kernel.
FftParams
16-byte uniform block for the radix-2 FFT kernel: n complex elements, log2n = log2(n). The kernel runs one workgroup of n threads.
GeneratedShader
GpuEvaluation
HardwareProfile
Rich, queryable description of the local compute hardware (plan §9 profile-hardware). Acts as the topology fingerprint that keys the manifest cache (plan §8): tuning records are only reused when the topology hash matches.
KernelSpec
ManifestCache
Atomic, adapter-keyed storage for certification and tuning evidence.
OracleCase
OracleTolerance
P64GpuWords64
64-byte aligned GPU descriptor container for P64 weight records.
RooflineEstimate
Schedule
ScheduleSpace
SharedMemorySpec
TimingSummary
TopKParams
16-byte uniform block for the top-k kernel (block_size == workgroup size).
TuningConfig
TuningManifest
TuningResult
ValidationReport

Enums§

BufferAccess
BufferElement
BuiltinKernel
EtalonBuiltinKernel
EtalonTargetBackend
ForgeError
Op
RooflineBound
Whether a kernel is dominated by memory traffic or by arithmetic.
ScalarType
SharedLen
TargetBackend
TimingSource
ValidationLevel

Constants§

CUDARC_API_VERSION
cudarc crate API version the cross-backend (CUDA) oracle is built against. Folded into the tuning/certification cache key (plan §8) so reuse is invalidated when the CUDA toolchain surface changes.
ETALON_FORGE_CACHE_MAGIC
ETALON_FORGE_SCHEMA_VERSION
FORGE_SCHEMA_VERSION
GEMM_GPU_THRESHOLD
Problem-size threshold (in m * n * k multiply-adds) below which GEMM stays on the CPU regardless of available accelerators. Small GEMMs are dominated by dispatch/transfer overhead, so the GPU path only earns its keep above this size. 1 << 15 (32768 FMAs, e.g. a 32×32×32 GEMM) is a conservative crossover that keeps the hand-checked unit tests (well below it) firmly on the CPU floor.
NAGA_API_VERSION
WGPU_API_VERSION

Functions§

candidate_evaluation
Evaluates a candidate WGSL expression.
causal_attention_oracle
Caller-buffered stable scaled-dot-product attention oracle.
certify_builtin
Certifies a builtin oracle against expected outputs.
certify_etalon_kernel
Certifies a WGSL kernel source string via Naga validation.
compare_f32
Compares f32 results against tolerance. Nonfinite values fail. Invalid tolerances report a failure even for empty inputs.
decode_spirv_words
Decode a ;-joined decimal SPIR-V word string back into Vec<u32>.
dft_cpu
Naive O(N²) forward Discrete Fourier Transform, the reference the GPU radix-2 FFT is differentially checked against. Complex data is interleaved f32: element j is (input[2*j], input[2*j+1]) = (real, imag), so both the input slice and the returned vector hold 2*N f32.
emit_etalon_shader
Emits a complete shader module from a KernelSpec and Schedule for target.
emit_shader
Emits shader.
evaluate_builtin
Evaluates a WGSL builtin on host for oracle checking.
evaluate_ffn
Cross-backend differential-oracle evaluation for the fused FFN against ffn_cpu (plan §7). Generic over OracleContext — the same code runs on wgpu and CUDA; only OracleContext::run_kernel differs. One workgroup-thread per output element; the output buffer is output_size. Tensors, bindings, dispatch sizing and tolerance are identical to the prior wgpu/evaluate_ffn_cuda paths.
evaluate_fft
Differential-oracle evaluation of the radix-2 FFT (out = forward DFT(in)) against dft_cpu. One workgroup of n = schedule.workgroup_size threads (one complex element per thread; n must be a power of two), mirroring the single-workgroup dispatch of evaluate_topk(): element_count = n with workgroup_size = n launches exactly one workgroup. The input/output buffers hold 2*n interleaved f32.
evaluate_matmul_tc
Differential-oracle evaluation of the cooperative-matrix (tensor-core) 8x8 GEMM tile C = A * B against matmul_cpu. All-f32 — the only coopmat configuration wgpu/naga 29 implements (see crate::numerical::emit::coopmat). One subgroup (32-lane NVIDIA warp) cooperatively computes the tile; the row-major loads/store reproduce the row-major CPU reference, so agreement is to f32 precision (a tiny tolerance covers tensor-core accumulation order).
evaluate_p64
Differential-oracle evaluation for the P64 projection against p64_project_cpu.
evaluate_topk
Cross-backend differential-oracle evaluation for the top-k kernel against topk_cpu (plan §7). Generic over OracleContext — the same code runs on wgpu and CUDA; only OracleContext::run_kernel differs.
ffn_cpu
CPU reference for the fused FFN, matching the emitted kernel’s op order exactly (hidden outer, input inner) so GPU/CPU agree within tolerance: out[o] = sum_h w2[o,h] * gelu(sum_i w1[h,i] * input[i]).
ffn_tensors
Deterministic FFN test tensors. Weights are scaled by 1/sqrt(fan_in) so the pre-activations stay O(1) and GPU/CPU agree within a modest tolerance.
fft_inputs
Deterministic complex test signal as interleaved f32 (2*n values), drawn from the same xorshift stream as every other oracle vector so it is reproducible. Both the real and imaginary parts land in [-1, 1].
generate_and_certify_via_etalon
Compatibility wrapper that discards the report from generate_with_validation_via_etalon. Successful emission alone does not establish device or numerical correctness.
generate_builtin
Generates a WGSL builtin.
generate_with_validation_via_etalon
Emits a shader and retains Etalon’s WGSL validation report unchanged.
install_device_policy
matmul_cpu
Row-major n×n matrix multiply reference: c[i][j] = sum_k a[i][k] * b[k][j].
matmul_tc_wgsl
Emits the cooperative-matrix 8x8 GEMM tile C = A * B, all-f32.
p64_project_cpu
CPU reference for the P64 projection: out[r] = sum_w weights[w] * f32(word_w), reading the 16 packed u32 words in the same lane order as the kernel.
p64_records
Deterministic P64 descriptors with small (f32-exact) u32 words.
resolve_execution_backend
Resolve which backend the execution/validation pipeline should actually use, given a preferred target and a predicate reporting whether a given backend’s native toolchain is available on this host.
roofline_for
Roofline estimate for kernel over a representative size n (output elements / records / rays, depending on the kernel).
synthesize_causal_attention
Emit and Naga-validate a causal scaled-dot-product attention kernel.
topk_cpu
CPU reference for the per-block top-k: the k largest values of each block_size-element block, in descending order. Blocks shorter than block_size (the tail) are padded with the sentinel, mirroring the GPU kernel’s out-of-range loads.
topk_inputs
Deterministic xorshift test vector in [-1, 1], matching the affine generator.
tune_with
Tunes with the given config.
validate_native
Validate a non-WGSL shader by spawning the target’s offline compiler. When the source was generated from a known KernelSpec, pass it so the report carries that kernel’s real entry point and binding count; for an opaque external source (kernel = None) those fields are left empty/zero rather than guessed.
validate_wgsl
Validates wgsl.