NetFabric/NetFabric.Numerics / .agents/skills/dotnet-simd
dotnet-simd
VerifiedVectorize hot loops in C#/.NET the right way — reach for System.Numerics.Tensors (TensorPrimitives) first, then System.Runtime.Intrinsics (Vector128/256/512) for hand-written algorithms, hardware intrinsics only as a last resort. USE FOR: choosing between TensorPrimitives, Vector<T>, Vector128/256/512, and X86/Arm/Wasm intrinsics; MemoryMarshal/LoadUnsafe/StoreUnsafe span-to-vector patterns; hardware-acceleration checks (IsHardwareAccelerated, IsSupported); widest-vector-first code paths with scalar/small-input fallbacks; masked remainder handling for non-idempotent vs idempotent ops; lane-crossing pitfalls with Vector256/512 horizontal reductions; eliminating bounds checks/branches in scalar/remainder code; multi-core parallelization via Parallel.Invoke chunking over TensorPrimitives calls; testing SIMD paths via DOTNET_Enable* env vars and .runsettings; benchmarking with BenchmarkDotNet job configs. DO NOT USE FOR: GPU compute (CUDA/TorchSharp); SIMD in non-.NET languages.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/hardware-intrinsics.md | markdown | 1.9 KB |
| references/performance-optimization-ladder.md | markdown | 5.0 KB |
| references/tensor-primitives.md | markdown | 2.7 KB |
| references/testing-and-benchmarking.md | markdown | 4.2 KB |
| references/vector-t-and-fixed-shape.md | markdown | 2.7 KB |
| references/vector128-vectorization.md | markdown | 8.1 KB |
references/testing-and-benchmarking.md
View on GitHub# Testing & Benchmarking SIMD
SIMD behavior varies by hardware. Cover Scalar / Vector128 / Vector256 / Vector512 in both unit tests and benchmarks — even if you don't call SIMD APIs directly, a dependency might.
## Environment Variables
| Variable | Default | Effect |
|----------|:---:|--------|
| `DOTNET_EnableHWIntrinsic` | `1` | Master switch; `0` disables all SIMD/intrinsics, forcing the full software path |
| `DOTNET_EnableAVX2` | `1` | `0` caps SIMD at 128-bit (also gates BMI1/BMI2/F16C/FMA/LZCNT/MOVBE) |
| `DOTNET_EnableAVX512` | `1` | `0` caps SIMD at 256-bit (AVX-512 F+BW+CD+DQ+VL) |
| `DOTNET_MaxVectorTBitWidth` | system default | Caps `Vector<T>`'s max width in bits |
| `DOTNET_PreferredVectorBitWidth` | system default | Caps the widest fixed-width vector (`Vector128`/`256`/`512`) that reports `IsHardwareAccelerated` |
These only ever *narrow* what's used — you can't force a wider width than the hardware supports; setting a knob the CPU doesn't support is ignored. Knob names changed across .NET versions (e.g. the AVX-512 knob was `EnableAVX512F` pre-.NET 9) — confirm against the runtime version you target.
| Scenario | `EnableHWIntrinsic` | `EnableAVX2` | `EnableAVX512` |
|----------|:---:|:---:|:---:|
| No SIMD | `0` | – | – |
| Up to 128-bit | `1` | `0` | `0` |
| Up to 256-bit | `1` | `1` | `0` |
| Up to 512-bit | `1` | `1` | `1` |
**`Vector<T>` does not automatically grow to the widest width the hardware supports.** Its default max width (`MaxVectorTBitWidth`) can be narrower than the hardware's — e.g. `Vector512<T>.IsHardwareAccelerated` can be `true` while `Vector<T>` stays 256-bit unless you set `DOTNET_MaxVectorTBitWidth=512`. `Vector128<T>`/`Vector256<T>`/`Vector512<T>` availability depends independently on the knobs above.
These are diagnostic/testing knobs only — not a production tuning mechanism, and they don't affect ahead-of-time compiled code (ReadyToRun/Native AOT) or the runtime's own internal routines.
## Unit Testing via `.runsettings`
Create one file per scenario (e.g. `_Scalar.runsettings`, `_Vector128.runsettings`, `_Vector256.runsettings`, `_Vector512.runsettings`):
```xml
<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
<RunConfiguration>
<EnvironmentVariables>
<DOTNET_EnableHWIntrinsic>1</DOTNET_EnableHWIntrinsic>
<DOTNET_EnableAVX2>0</DOTNET_EnableAVX2>
<DOTNET_EnableAVX512>0</DOTNET_EnableAVX512>
</EnvironmentVariables>
</RunConfiguration>
</RunSettings>
```
- **Visual Studio**: `Test > Configure Run Settings > Select Solution Wide runsettings File`.
- **CLI**: `dotnet test -s:_Vector128.runsettings` (or inline: `dotnet test -e:DOTNET_EnableAVX2=0 -e:DOTNET_EnableAVX512=0`).
## Benchmarking with BenchmarkDotNet
Define a reusable job config so a single benchmark class runs under every SIMD scenario:
```csharp
class VectorizationConfig : ManualConfig
{
public VectorizationConfig()
{
_ = WithSummaryStyle(SummaryStyle.Default.WithRatioStyle(RatioStyle.Trend));
_ = HideColumns(Column.EnvironmentVariables, Column.RatioSD, Column.Error);
_ = AddJob(Job.Default.WithId("Scalar")
.WithEnvironmentVariable("DOTNET_EnableHWIntrinsic", "0")
.AsBaseline());
if (Vector128.IsHardwareAccelerated)
_ = AddJob(Job.Default.WithId("Vector128")
.WithEnvironmentVariable("DOTNET_EnableAVX2", "0")
.WithEnvironmentVariable("DOTNET_EnableAVX512", "0"));
if (Vector256.IsHardwareAccelerated)
_ = AddJob(Job.Default.WithId("Vector256")
.WithEnvironmentVariable("DOTNET_EnableAVX512", "0"));
if (Vector512.IsHardwareAccelerated)
_ = AddJob(Job.Default.WithId("Vector512"));
}
}
```
Apply with `[Config(typeof(VectorizationConfig))]` only on the benchmark classes that need multi-width comparison. Use `[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]` + `[CategoriesColumn]` + `[BenchmarkCategory("Int")]`/`[BenchmarkCategory("Float")]` to group results by type alongside SIMD width.
Guard each conditional `AddJob` with the corresponding `VectorXXX.IsHardwareAccelerated` check — running a job for a width the host CPU doesn't support produces meaningless results.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |