mirror of
https://github.com/dotnet/skills.git
synced 2026-09-20 09:49:54 +08:00
Add general .NET vectorization skill
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Tanner Gooding
@@ -11,3 +11,4 @@ Advanced .NET and C# skills for niche scenarios and coding agents.
|
||||
- csharp-scripts
|
||||
- dotnet-pinvoke
|
||||
- nuget-trusted-publishing
|
||||
- vectorization
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
name: vectorization
|
||||
description: >
|
||||
Design, implement, optimize, and review SIMD code in .NET.
|
||||
USE FOR: vectorizing scalar loops with TensorPrimitives,
|
||||
Vector64/128/256/512, or platform hardware intrinsics; reviewing existing SIMD
|
||||
code, including Vector<T>, for contract equivalence, tail handling, memory
|
||||
safety, portability, fallbacks, and measured performance. DO NOT USE FOR:
|
||||
performance work unrelated to SIMD or vectorization.
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# .NET SIMD vectorization
|
||||
|
||||
Produce a portable optimization that preserves the scalar contract, remains memory-safe at every
|
||||
length, and earns its complexity with measured results. **Read the official
|
||||
[SIMD and hardware-intrinsics guidance](https://learn.microsoft.com/dotnet/standard/simd) first**
|
||||
and follow its comprehensive implementation templates. In particular, use its self-contained
|
||||
per-width dispatch, dedicated small-input handling, loop, and remainder shapes rather than reducing
|
||||
them to a chain of width checks. This skill supplies the decision rules and validation checks to
|
||||
apply while changing real code.
|
||||
|
||||
## Inputs and prerequisites
|
||||
|
||||
Discover these from the repository before asking the user:
|
||||
|
||||
| Input | Required | What to establish |
|
||||
| --- | --- | --- |
|
||||
| Scalar implementation and tests | Yes | Existing contract, representative call sites, and supported overlap |
|
||||
| Target frameworks and platforms | Yes | Available SIMD APIs and architectures that must behave consistently |
|
||||
| Build and test workflow | Yes | The repository's normal commands and how to launch separate test processes |
|
||||
| Representative workload or benchmark | For optimization | Typical input sizes and the baseline to beat |
|
||||
|
||||
Do not add a package merely because an API exists there. First check the target framework and the
|
||||
project's existing dependency/versioning policy.
|
||||
|
||||
## Core rules
|
||||
|
||||
1. **Use the highest-level API that matches the contract.** `Span<T>` and `string` operations,
|
||||
`TensorPrimitives`, and tensor types already accelerate many operations. LINQ reductions such as
|
||||
`Sum`, `Min`, `Max`, and `Average` can also accelerate when the source exposes its underlying
|
||||
span. Verify empty-input and floating-point behavior rather than assuming similarly named
|
||||
operations are interchangeable. Fixed-shape `System.Numerics` types remain appropriate for
|
||||
graphics and similar domains.
|
||||
2. **Start new explicit SIMD loops with `Vector128<T>`.** It is accelerated across the broadest
|
||||
hardware set. Add wider fixed-width paths only when measurements justify them.
|
||||
3. **Keep platforms consistent.** Prefer cross-platform operations on the fixed-width vector types;
|
||||
they lower to the appropriate target instructions. For example,
|
||||
`(vector & mask) == Vector128<byte>.Zero` becomes `ptest` on x86/x64. Use
|
||||
architecture-specific intrinsics only for a measured gap, guard them with `IsSupported`, and
|
||||
retain equivalent portable or scalar behavior.
|
||||
4. **Read `IsHardwareAccelerated`, `IsSupported`, and `Count` directly.** The JIT treats them as
|
||||
constants, so caching them adds no value and obscures which branches disappear.
|
||||
5. **Prefer operators where they are clear.** Parenthesize expressions that mix bitwise and
|
||||
comparison operators so precedence is explicit.
|
||||
|
||||
If the task is review-only, do not rewrite the code. Report correctness and memory-safety defects
|
||||
before performance opportunities.
|
||||
|
||||
## Authoring checklist
|
||||
|
||||
- **Contract:** identify behavior for empty and short inputs, overlap, overflow, NaN, signed zero,
|
||||
ordering, and exceptions before changing the implementation.
|
||||
- **Structure:** for new explicit SIMD, implement `Vector128<T>` and scalar first. Only after
|
||||
measurements justify wider paths, check `Vector512<T>`, then `Vector256<T>`, optional `Vector<T>`,
|
||||
`Vector128<T>`, and finally scalar. Omit paths the implementation does not need. Each outer
|
||||
fixed-width guard checks only its `IsHardwareAccelerated` property and, for generic element types,
|
||||
`IsSupported`. Inside that block, run the width-specific helper when the input has at least
|
||||
`Count` elements; otherwise run a dedicated small-input helper, then return. Do not put the length
|
||||
check in the outer guard and fall through to repeat dispatch at narrower widths. Keeping each
|
||||
supported-width block self-contained lets the JIT remove unsupported blocks and avoids redundant
|
||||
work on common small inputs.
|
||||
- **Loads and stores:** prefer span-based `Vector128.Create(span)` and `CopyTo`; the JIT keeps them
|
||||
efficient and they require no pinning or reference arithmetic. Unsafe loads and stores are largely
|
||||
unnecessary. When a path genuinely must walk a buffer by managed reference, use the element-offset
|
||||
`LoadUnsafe(ref T, nuint)` and `StoreUnsafe` overloads rather than pointers or manually advanced
|
||||
references.
|
||||
- **Empty inputs:** in a reference-based path, obtain the starting reference with
|
||||
`MemoryMarshal.GetReference(span)` or `MemoryMarshal.GetArrayDataReference(array)`, not by indexing
|
||||
element `0`.
|
||||
- **Unsupported element types:** the fixed-width vectors support primitive numeric element types,
|
||||
not `char` or `bool`. Reinterpret with `MemoryMarshal.Cast` or `As<TFrom, TTo>`; reinterpretation
|
||||
changes only the type, not the bits. Keep Boolean data as `0` or `1` and characters as valid
|
||||
UTF-16, normalizing results before storing when necessary.
|
||||
- **Offsets:** prove the input contains a full vector before subtracting `Count` or converting an
|
||||
index to `nuint`; otherwise a negative value becomes a huge unsigned offset.
|
||||
- **Managed references:** never create a reference before the start or past the end of its object,
|
||||
even temporarily. A collection during that interval can leave an interior reference untracked.
|
||||
- **Remainders:** cover every length, including `0`, `Count - 1`, `Count`, `Count + 1`, and
|
||||
nonmultiples of each width. Once the input contains a full vector, keep the tail vectorized by
|
||||
reprocessing the last full vector. An idempotent operation can fold that overlap in directly. A
|
||||
non-idempotent operation must use `ConditionalSelect` to replace repeated lanes with the
|
||||
operation's identity before folding them in. For in-place transforms, preserve the original tail
|
||||
values before overlapping stores and write only valid results.
|
||||
- **Buffer overlap:** choose a traversal direction or staging strategy that prevents stores from
|
||||
corrupting values not yet loaded.
|
||||
- **Numeric behavior:** account for floating-point reassociation, NaN and signed-zero semantics,
|
||||
checked or unchecked integer overflow, and endianness where the algorithm depends on byte order.
|
||||
`Native` and `Estimate` operations can intentionally relax precision or IEEE edge-case behavior;
|
||||
use them only when the contract permits it and measurements justify them.
|
||||
|
||||
The official guidance contains the complete dispatch, small-input, unrolling, and remainder
|
||||
templates; use those for the full implementation. The following excerpt illustrates only the inner
|
||||
safe `Vector128<T>` loop for an in-place elementwise transform, after its self-contained dispatch
|
||||
block has established at least one full vector. `Transform` represents the operation being
|
||||
implemented:
|
||||
|
||||
```csharp
|
||||
Span<int> tail = data.Slice(data.Length - Vector128<int>.Count);
|
||||
Vector128<int> end = Vector128.Create<int>(tail);
|
||||
Span<int> remaining = data;
|
||||
|
||||
while (remaining.Length >= Vector128<int>.Count)
|
||||
{
|
||||
Vector128<int> values = Vector128.Create<int>(remaining);
|
||||
Transform(values).CopyTo(remaining);
|
||||
remaining = remaining.Slice(Vector128<int>.Count);
|
||||
}
|
||||
|
||||
if (!remaining.IsEmpty)
|
||||
{
|
||||
Transform(end).CopyTo(tail);
|
||||
}
|
||||
```
|
||||
|
||||
The early `end` load preserves original values before overlapping stores. For a read-only reduction,
|
||||
load the same final span after the main loop and use `ConditionalSelect` to replace already-processed
|
||||
lanes with the operation's identity. Do not substitute `LoadUnsafe`/`StoreUnsafe` or a scalar
|
||||
epilogue merely to avoid span bounds checks.
|
||||
|
||||
## Testing checklist
|
||||
|
||||
- Compare the optimized implementation with the scalar contract across boundary lengths,
|
||||
randomized values, empty inputs, supported overlap, and numeric edge cases. Cover every
|
||||
implemented width and the scalar path with inputs both large enough and too small to benefit.
|
||||
- Exercise every implemented width and the scalar fallback in separate processes. On x86/x64
|
||||
CoreCLR, `DOTNET_EnableAVX2=0` disables AVX2 and `DOTNET_EnableHWIntrinsic=0` disables hardware
|
||||
intrinsics. Use the repository's normal test command and do not change these process-wide
|
||||
settings inside a unit test. These settings do not change code already compiled as ReadyToRun or
|
||||
ahead of time, so confirm the target code is JIT-compiled when using them to force a path.
|
||||
- For unsafe loads and stores, use guard-page or equivalent boundary tests when available. Put the
|
||||
inaccessible page after the buffer for forward iteration and before it for backwards iteration,
|
||||
and include nonmultiple lengths. An ordinary array allocation does not reliably expose an
|
||||
out-of-bounds read.
|
||||
|
||||
## Benchmarking
|
||||
|
||||
Use BenchmarkDotNet to measure representative small and large inputs before keeping the added
|
||||
complexity. Compare scalar, `Vector128<T>`, and each wider implemented path in the same run. Small
|
||||
inputs can be slower because setup dominates, and speedups are rarely the theoretical vector-width
|
||||
multiple because memory throughput, alignment, and latency still apply. Report throughput or time
|
||||
with noise context and, when relevant, generated code size or instruction counts. Control allocation
|
||||
alignment for stable measurements or randomize it to observe the distribution. A wider vector is
|
||||
not automatically faster.
|
||||
|
||||
If the project cannot target the required framework, run the relevant architecture, or execute the
|
||||
fallback configuration, state exactly which path remains unverified. Do not claim success from a
|
||||
default-hardware test alone.
|
||||
|
||||
## Completion contract
|
||||
|
||||
- **Authoring:** leave the scalar contract covered by tests; identify the framework or SIMD layer
|
||||
selected; report measurements for the representative workload; name any architecture or fallback
|
||||
path that could not be exercised.
|
||||
- **Review:** report only concrete findings, ordered by correctness, memory safety, portability,
|
||||
tests, then performance evidence. If none remain, say so directly.
|
||||
- Do not call an optimization complete when it only builds, only passes on the current machine, or
|
||||
has no comparison against the scalar baseline.
|
||||
|
||||
## Review checklist
|
||||
|
||||
Review in this order:
|
||||
|
||||
1. Scalar-contract equivalence, including signed zero, NaN, overflow, and relevant endianness
|
||||
2. Reuse of an existing accelerated framework API
|
||||
3. Tail correctness for idempotent versus non-idempotent work
|
||||
4. Memory safety, unsigned offset arithmetic, empty inputs, and overlapping buffers
|
||||
5. Portable dispatch and behaviorally equivalent fallbacks
|
||||
6. Tests that force each width and the scalar path
|
||||
7. Benchmarks that justify explicit SIMD and additional widths
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
name: exp-simd-vectorization
|
||||
description: "Optimizes hot-path scalar loops in .NET 8+ with cross-platform Vector128/Vector256/Vector512 SIMD intrinsics, or replaces manual math loops with single TensorPrimitives API calls. Covers byte-range validation, character counting, bulk bitwise ops, cross-type conversion, fused multi-array computations, and float/double math operations."
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# SIMD Vectorization
|
||||
|
||||
## Decision Gate
|
||||
1. **Check `Span<T>` and `MemoryExtensions` first.** If the operation can be expressed using built-in `Span<T>` methods (e.g., `Contains`, `IndexOf`, `CopyTo`, `SequenceEqual`) or `MemoryExtensions`, use them — no additional dependency is needed and the runtime already vectorizes many of these internally.
|
||||
2. **Check for TensorPrimitives next.** If one or more TensorPrimitives methods cover the operation → use them. If the `.csproj` does NOT already reference `System.Numerics.Tensors`, **add the package**, for example: `<PackageReference Include="System.Numerics.Tensors" />` (or use the versioning approach already used by your solution). Then replace the scalar loop with TP calls and stop. See the full API table below. Compose multiple TP calls when needed (e.g., finding both min and max → `TensorPrimitives.Min(span)` + `TensorPrimitives.Max(span)` as two calls). Do NOT write manual Vector128 code for operations TP already handles.
|
||||
3. **Scalar loop over contiguous array/span** of `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `nint`, `nuint`, `float`, `double` (and `char` via reinterpretation as `ushort`)? → Implement with explicit `Vector128<T>` / `Vector256<T>` / `Vector512<T>` intrinsics using the patterns below.
|
||||
4. **No contiguous numeric arrays to process** (dictionary lookups, tree traversals, linked lists, state machines, string formatting, small collections, enum comparisons, recursive algorithms, decimal arithmetic)? → Report `[NO SIMD OPPORTUNITY]` and write a **full paragraph** explaining WHY, referencing the specific code characteristics that prevent vectorization (e.g., "State machines require sequential branching on enum values — there are no contiguous numeric arrays to process in parallel, and each transition depends on the previous state"). This explanation is graded.
|
||||
|
||||
## TensorPrimitives API Reference
|
||||
TensorPrimitives APIs are generic and work for any primitive type that satisfies the method's generic constraints — not just `float`/`double`. For example, `Sum` requires `IAdditionOperators<T,T,T>` + `IAdditiveIdentity<T,T>` and works for all primitive numeric types, while `CosineSimilarity` requires `IRootFunctions<T>` and only works for `float`/`double`. If the project doesn't already reference `System.Numerics.Tensors`, add it to the `.csproj`. Replace the entire manual loop with **one or more** `TensorPrimitives` calls as needed (prefer a single call when possible):
|
||||
|
||||
### Reductions (span → scalar)
|
||||
| Operation | API |
|
||||
|-----------|-----|
|
||||
| Sum | `TensorPrimitives.Sum(span)` |
|
||||
| Sum of squares | `TensorPrimitives.SumOfSquares(span)` |
|
||||
| Sum of magnitudes (L1 norm) | `TensorPrimitives.SumOfMagnitudes(span)` |
|
||||
| L2 norm | `TensorPrimitives.Norm(span)` |
|
||||
| Product of all elements | `TensorPrimitives.Product(span)` |
|
||||
| Min value | `TensorPrimitives.Min(span)` |
|
||||
| Max value | `TensorPrimitives.Max(span)` |
|
||||
| Index of max | `TensorPrimitives.IndexOfMax(span)` |
|
||||
| Index of min | `TensorPrimitives.IndexOfMin(span)` |
|
||||
| Dot product | `TensorPrimitives.Dot(a, b)` |
|
||||
| Cosine similarity | `TensorPrimitives.CosineSimilarity(a, b)` |
|
||||
| Euclidean distance | `TensorPrimitives.Distance(a, b)` |
|
||||
|
||||
### Element-wise transforms (span → span)
|
||||
| Operation | API |
|
||||
|-----------|-----|
|
||||
| Negate | `TensorPrimitives.Negate(src, dst)` |
|
||||
| Abs | `TensorPrimitives.Abs(src, dst)` |
|
||||
| Sqrt | `TensorPrimitives.Sqrt(src, dst)` |
|
||||
| Exp | `TensorPrimitives.Exp(src, dst)` |
|
||||
| Log | `TensorPrimitives.Log(src, dst)` |
|
||||
| Log2 | `TensorPrimitives.Log2(src, dst)` |
|
||||
| Tanh | `TensorPrimitives.Tanh(src, dst)` |
|
||||
| Sigmoid | `TensorPrimitives.Sigmoid(src, dst)` |
|
||||
| SoftMax | `TensorPrimitives.SoftMax(src, dst)` |
|
||||
| Sinh | `TensorPrimitives.Sinh(src, dst)` |
|
||||
| Cosh | `TensorPrimitives.Cosh(src, dst)` |
|
||||
| Round | `TensorPrimitives.Round(src, dst)` |
|
||||
| Floor | `TensorPrimitives.Floor(src, dst)` |
|
||||
| Ceiling | `TensorPrimitives.Ceiling(src, dst)` |
|
||||
| CopySign | `TensorPrimitives.CopySign(src, sign, dst)` |
|
||||
| Pow | `TensorPrimitives.Pow(bases, exponents, dst)` |
|
||||
|
||||
### Two-span operations (a, b → dst)
|
||||
| Operation | API |
|
||||
|-----------|-----|
|
||||
| Add | `TensorPrimitives.Add(a, b, dst)` |
|
||||
| Subtract | `TensorPrimitives.Subtract(a, b, dst)` |
|
||||
| Multiply | `TensorPrimitives.Multiply(a, b, dst)` |
|
||||
| Divide | `TensorPrimitives.Divide(a, b, dst)` |
|
||||
| Element-wise Min | `TensorPrimitives.Min(a, b, dst)` |
|
||||
| Element-wise Max | `TensorPrimitives.Max(a, b, dst)` |
|
||||
|
||||
### Three-span fused operations
|
||||
| Operation | API |
|
||||
|-----------|-----|
|
||||
| (x+y)*z | `TensorPrimitives.AddMultiply(x, y, z, dst)` |
|
||||
| x*y+z | `TensorPrimitives.MultiplyAdd(x, y, z, dst)` |
|
||||
| fma(x,y,z) | `TensorPrimitives.FusedMultiplyAdd(x, y, z, dst)` |
|
||||
|
||||
> `AddMultiply` and `MultiplyAdd` are distinct — they optimize differently depending on whether the dependency chain flows from the addend or the multiplier. `FusedMultiplyAdd` is the IEEE 754 fused form of (x*y)+z with a single rounding step.
|
||||
|
||||
## Manual SIMD with Vector128/Vector256/Vector512
|
||||
|
||||
Use this when TensorPrimitives doesn't have a single API for the operation. This is required for byte-level operations, character class counting, range validation, bitwise bulk ops, cross-type conversions, and custom patterns.
|
||||
|
||||
### Required imports
|
||||
```csharp
|
||||
using System.Runtime.CompilerServices;
|
||||
using System.Runtime.InteropServices;
|
||||
using System.Runtime.Intrinsics;
|
||||
```
|
||||
Prefer cross-platform APIs (`System.Runtime.Intrinsics`). Only use platform-specific intrinsics (`System.Runtime.Intrinsics.X86`, `.Arm`) when there is a significant performance advantage that justifies the increased code complexity of maintaining separate code paths.
|
||||
|
||||
### Three-tier dispatch pattern
|
||||
Always include all three tiers. Use `if`/`else if` so that small inputs hit only one branch before reaching the scalar fallback — a fallthrough pattern (sequential `if`s) pessimizes the scalar case by requiring up to three not-taken branches that may mispredict. The `IsHardwareAccelerated` checks are JIT-time constants, so dead paths are eliminated at compile time:
|
||||
```csharp
|
||||
ref var src = ref MemoryMarshal.GetReference(span);
|
||||
uint i = 0;
|
||||
uint length = (uint)span.Length;
|
||||
|
||||
if (Vector512.IsHardwareAccelerated && Vector512<T>.IsSupported)
|
||||
{
|
||||
uint vec512Count = (uint)Vector512<T>.Count;
|
||||
while (i + vec512Count <= length)
|
||||
{
|
||||
var vec = Vector512.LoadUnsafe(ref src, i);
|
||||
// ... process vec ...
|
||||
i += vec512Count;
|
||||
}
|
||||
}
|
||||
else if (Vector256.IsHardwareAccelerated && Vector256<T>.IsSupported)
|
||||
{
|
||||
uint vec256Count = (uint)Vector256<T>.Count;
|
||||
while (i + vec256Count <= length)
|
||||
{
|
||||
var vec = Vector256.LoadUnsafe(ref src, i);
|
||||
// ... process vec ...
|
||||
i += vec256Count;
|
||||
}
|
||||
}
|
||||
else if (Vector128.IsHardwareAccelerated && Vector128<T>.IsSupported)
|
||||
{
|
||||
uint vec128Count = (uint)Vector128<T>.Count;
|
||||
while (i + vec128Count <= length)
|
||||
{
|
||||
var vec = Vector128.LoadUnsafe(ref src, i);
|
||||
// ... process vec ...
|
||||
i += vec128Count;
|
||||
}
|
||||
}
|
||||
// Scalar fallback for remaining elements (and the only loop hit for small inputs)
|
||||
for (; i < length; i++)
|
||||
{
|
||||
// ... scalar processing ...
|
||||
}
|
||||
```
|
||||
|
||||
### Core SIMD operations
|
||||
- **Load/Store:** `Vector128.LoadUnsafe(ref src, offset)` / `.StoreUnsafe(ref dst, offset)`
|
||||
- **Arithmetic:** `+`, `-`, `*`, `/` operators on vector types
|
||||
- **Multiply-add (approximate):** `Vector128.MultiplyAddEstimate(a, b, c)` — performs a multiply-add with implementation-defined approximation; not guaranteed to be a strict IEEE fused multiply-add. For precise fused semantics, use `Vector128.FusedMultiplyAdd(a, b, c)`.
|
||||
- **Comparison:** `Vector128.Equals`, `.LessThan`, `.GreaterThan` — returns mask vector
|
||||
- **Mask ops:** `Vector128.All(mask)`, `.Any(mask)`, `.None(mask)`, `.Count(mask)`, `.CountWhereAllBitsSet(mask)`
|
||||
- **Horizontal:** `Vector128.Sum(vec)` for reduction; `.Min(a,b)`, `.Max(a,b)` element-wise
|
||||
- **Broadcast:** `Vector128.Create(scalarValue)` — fill all lanes with one value
|
||||
- **Bitwise:** `&`, `|`, `^`, `~` operators; `Vector128.ShiftLeft`, `.ShiftRightLogical`
|
||||
- **Widening:** `Vector128.WidenLower(v)` / `.WidenUpper(v)` for byte→short, short→int
|
||||
- **Narrowing:** `Vector128.Narrow(lower, upper)` for int→short, short→byte
|
||||
- **Type convert:** `Vector128.ConvertToSingle(intVec)`, `.ConvertToInt32(floatVec)`
|
||||
- **Shuffle:** `Vector128.Shuffle(vec, indices)` — lookup table / permutation
|
||||
- **Conditional:** `Vector128.ConditionalSelect(mask, trueVec, falseVec)`
|
||||
|
||||
### Pattern: Unsigned range check (byte-range validation)
|
||||
For checking if all bytes are in range [lo, hi]:
|
||||
```csharp
|
||||
var vLo = Vector128.Create((byte)lo);
|
||||
var vRange = Vector128.Create((byte)(hi - lo));
|
||||
// (b - lo) > range means out-of-range (unsigned wraparound catches b < lo)
|
||||
var shifted = Vector128.Subtract(vec, vLo);
|
||||
var inRange = Vector128.LessThanOrEqual(shifted, vRange);
|
||||
if (!Vector128.All(inRange.AsByte())) return false; // for validation
|
||||
// or: count += Vector128.CountWhereAllBitsSet(inRange); // for counting
|
||||
```
|
||||
|
||||
### Pattern: Nibble-lookup counting (character classes, popcount, etc.)
|
||||
For counting bytes matching a sparse set of values (vowels, digits, punctuation, bit counts) — build two 16-byte lookup tables indexed by low/high nibble:
|
||||
```csharp
|
||||
var lo_lut = Vector128.Create(/* 16 bytes: bit pattern for low nibble match */);
|
||||
var hi_lut = Vector128.Create(/* 16 bytes: bit pattern for high nibble match */);
|
||||
var nibbleMask = Vector128.Create((byte)0x0F);
|
||||
|
||||
var lo_nibble = vec & nibbleMask;
|
||||
var hi_nibble = Vector128.ShiftRightLogical(vec.AsUInt16(), 4).AsByte() & nibbleMask;
|
||||
var lo_match = Vector128.Shuffle(lo_lut, lo_nibble);
|
||||
var hi_match = Vector128.Shuffle(hi_lut, hi_nibble);
|
||||
var match = lo_match & hi_match;
|
||||
count += Vector128.CountWhereAllBitsSet(~Vector128.Equals(match, Vector128<byte>.Zero));
|
||||
```
|
||||
This same technique works for popcount (LUT = {0,1,1,2,1,2,2,3,1,2,2,3,2,3,3,4}).
|
||||
For simpler cases (single byte value, adjacent range), use `Equals` + `Count` or range check instead.
|
||||
|
||||
### Pattern: Cross-type conversion (widening chains)
|
||||
When the source and destination types differ (e.g., byte→float for dequantization, short→byte for narrowing):
|
||||
```csharp
|
||||
// Widen: byte → short → int → float
|
||||
var bytes = Vector128.LoadUnsafe(ref src, offset);
|
||||
var (lo16, hi16) = Vector128.Widen(bytes);
|
||||
var (lo32a, lo32b) = Vector128.Widen(lo16);
|
||||
var f0 = Vector128.ConvertToSingle(lo32a.AsInt32());
|
||||
|
||||
// Narrow: int → short → byte (with saturation via Min/Max clamping)
|
||||
var clamped = Vector128.Min(Vector128.Max(vec, Vector128<short>.Zero), Vector128.Create((short)255));
|
||||
var narrowed = Vector128.Narrow(clamped.AsUInt16(), nextVec.AsUInt16());
|
||||
```
|
||||
|
||||
### Trailing elements
|
||||
- **Idempotent ops** (validation, search): overlap last vector — re-processing is safe
|
||||
- **Aggregations** (sum, count, min/max): scalar loop for remainder to avoid double-counting
|
||||
- **Store ops** (transform in-place): use `ConditionalSelect` to merge with last stored vector
|
||||
|
||||
## Key Rules
|
||||
- Preserve original method signature — drop-in replacement
|
||||
- Keep scalar code as fallback — never delete it
|
||||
- Use `Vector128<T>` / `Vector256<T>` / `Vector512<T>` explicitly — never `Vector<T>`
|
||||
- Prefer portable `Vector128<T>`/`Vector256<T>`/`Vector512<T>` APIs over platform-specific intrinsics (`Avx2`, `Sse42`, `AdvSimd`, `Fma`) unless there is a significant performance advantage
|
||||
- Testing: use `dotnet run` (NOT `dotnet test`) — xunit.v3 is an in-process runner
|
||||
Reference in New Issue
Block a user