Highway

https://google.github.io/highway/en/master/
Admin
Highway is a C++ library that provides efficient and performance-portable SIMD/vector intrinsics for...
Tokens:42,471
Snippets:240
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Highway with vcpkg Package Manager

Source: https://google.github.io/highway/en/master/README

Installs the Highway library using the vcpkg cross-platform package manager. This command fetches and builds the Highway project, making it available for use in other C++ projects.

```bash
vcpkg install highway
```

--------------------------------

### Highway Dynamic Dispatch Header Guard

Source: https://google.github.io/highway/en/master/README

Provides an example of the special include guard pattern used in `-inl.h` headers when dealing with dynamic dispatch across multiple translation units in Highway.

```cpp
#if defined(HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_) == defined(HWY_TARGET_TOGGLE)
#ifdef HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
#undef HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
#else
#define HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
#endif

#include "hwy/highway.h"
// Your vector code
// For example:
// template <typename T> void MyVectorOp(const T* in, T* out) {
//   const hwy::ScalableTag<T> df;
//   auto v_in = hwy::Load(df, in);
//   auto v_out = v_in;
//   hwy::Store(v_out, df, out);
// }

#endif // HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
```

--------------------------------

### Highway Dynamic Dispatch

Source: https://google.github.io/highway/en/master/README

Demonstrates the implementation and usage of dynamic dispatch in Highway. This includes using `HWY_EXPORT` to generate function pointers and `HWY_DYNAMIC_DISPATCH` or `HWY_DYNAMIC_POINTER` for runtime selection of the best target.

```cpp
#include "hwy/highway.h"
#include "hwy/targets.h"

namespace hwy {
namespace HWY_NAMESPACE {

// Function to be dynamically dispatched
HWY_EXPORT void MyDynamicFunc(float* data, size_t size) {
  // ... SIMD operations ...
}

} // namespace HWY_NAMESPACE

void UseDynamicDispatch() {
  // Update CPU detection information (optional, for first call overhead)
  hwy::GetChosenTarget().Update(hwy::SupportedTargets());

  float data[10];
  size_t size = 10;

  // Option 1: Direct dynamic dispatch
  HWY_DYNAMIC_DISPATCH(MyDynamicFunc)(data, size);

  // Option 2: Get function pointer and call
  auto func_ptr = HWY_DYNAMIC_POINTER(MyDynamicFunc);
  func_ptr(data, size);
}

} // namespace hwy
```

--------------------------------

### Build Highway Project with CMake

Source: https://google.github.io/highway/en/master/README

A standard CMake workflow to configure, build, and test the Highway project. It creates a build directory, navigates into it, configures the build with CMake, and then compiles the project and runs its tests in parallel.

```bash
mkdir -p build && cd build
cmake ..
make -j && make test
```

--------------------------------

### Highway Code Structuring and Aliasing

Source: https://google.github.io/highway/en/master/README

Explains the necessary code structure and aliasing techniques required when calling Highway operations from user code. This includes namespace usage, aliasing, and using-declaration.

```cpp
#include "hwy/highway.h"

namespace hwy {
namespace HWY_NAMESPACE {

// Option 1: Reside inside namespace hwy::HWY_NAMESPACE
HWY_API float AddScalable(float a, float b) {
  return Add(a, b);
}

} // namespace HWY_NAMESPACE
}

// Option 2: Prefix with an alias
namespace hn = hwy::HWY_NAMESPACE;

HWY_API float AddAliased(float a, float b) {
  return hn::Add(a, b);
}

// Option 3: Add using-declarations
using hwy::HWY_NAMESPACE::Add;

HWY_API float AddUsingDecl(float a, float b) {
  return Add(a, b);
}
```

--------------------------------

### Install CMake on Debian-based Systems

Source: https://google.github.io/highway/en/master/README

Installs the CMake build system generator on Debian-based Linux distributions using the apt package manager. This is a prerequisite for building the Highway project.

```bash
sudo apt install cmake
```

--------------------------------

### Highway Static Dispatch

Source: https://google.github.io/highway/en/master/README

Illustrates how to implement and call functions using static dispatch in Highway. This involves defining functions within `HWY_NAMESPACE` and using `HWY_STATIC_DISPATCH` for intra-module calls or wrapping for inter-module calls.

```cpp
#include "hwy/highway.h"

namespace hwy {
namespace HWY_NAMESPACE {

HWY_API void MyStaticFunc(float* data, size_t size) {
  // ... SIMD operations ...
}

} // namespace HWY_NAMESPACE

// Calling from the same module
void CallStaticFunc() {
  float data[10];
  size_t size = 10;
  HWY_STATIC_DISPATCH(MyStaticFunc)(data, size);
}

// Calling from another module (requires a regular function wrapper in a header)
// In header:
// void CallMyStaticFuncExternally(float* data, size_t size);
// In .cc file:
// void CallMyStaticFuncExternally(float* data, size_t size) {
//   hwy::HWY_NAMESPACE::CallStaticFunc(); // Assuming CallStaticFunc is defined here
// }

} // namespace hwy
```

--------------------------------

### Highway SAXPY Example using Transform1

Source: https://google.github.io/highway/en/master/README

An example demonstrating the use of the Highway `Transform1` function for vectorizing the SAXPY operation (alpha * x + y). It uses a generic lambda function to define the operation applied to each vector, simplifying loop and remainder handling.

```c++
Transform1(d, x, n, y, [](auto d, const auto v, const auto v1) HWY_ATTR {
  return MulAdd(Set(d, alpha), v, v1);
});
```

--------------------------------

### Using SIMD Vectors with Highway

Source: https://google.github.io/highway/en/master/README

Demonstrates how to utilize Highway's SIMD vector types for performance-critical operations. It covers `ScalableTag` for full SIMD width and `CappedTag` or `FixedTag` for specific lane counts, explaining their use cases and limitations.

```cpp
#include "hwy/highway.h"

namespace hwy {
namespace HWY_NAMESPACE {

// Example using ScalableTag for full SIMD width
template <typename T> 
void ProcessFull(T* data, size_t size) {
  const ScalableTag<T> df;
  // Use Zero/Set/Load with df for maximum performance
  auto vec = Zero(df);
  Load(df, data);
}

// Example using CappedTag for up to N lanes
template <typename T, size_t N>
void ProcessCapped(T* data, size_t size) {
  const CappedTag<T, N> df;
  // Use HWY_CAPPED(T, N) for N rounded down to power of two
  auto vec = Zero(df);
  Load(df, data);
}

// Example using FixedTag for exactly N lanes (power of two)
template <typename T, size_t N>
void ProcessFixed(T* data, size_t size) {
  const FixedTag<T, N> df;
  // Use HWY_CAPPED(T, N) for exactly power of two
  auto vec = Zero(df);
  Load(df, data);
}

} // namespace HWY_NAMESPACE
} // namespace hwy
```

--------------------------------

### Install googletest Development Files on Debian-based Systems

Source: https://google.github.io/highway/en/master/README

Installs the googletest framework development files on Debian-based Linux distributions. This is an optional step if you prefer to manage gtest as a system dependency rather than letting CMake download it automatically.

```bash
sudo apt install libgtest-dev
```

--------------------------------

### Integrate Highway with CMake

Source: https://google.github.io/highway/en/master/faq

Demonstrates how to integrate the Highway library into a CMake-based build system. This involves finding the installed package and linking it to your target project.

```cmake
find_package(HWY 1.3.0)
target_link_libraries(your_project PRIVATE hwy)

```

--------------------------------

### Highway Function Attributes and Dispatch

Source: https://google.github.io/highway/en/master/README

Details the use of `HWY_ATTR` and the `HWY_BEFORE_NAMESPACE`/`HWY_AFTER_NAMESPACE` macros for functions calling Highway operations. It also touches on avoiding namespace-scope initializers for SIMD vectors.

```cpp
#include "hwy/highway.h"

// Using HWY_ATTR before a lambda
auto lambda_func = HWY_ATTR ([]() {
  // Your SIMD operations here
  return 0;
});

// Using HWY_BEFORE_NAMESPACE and HWY_AFTER_NAMESPACE
HWY_BEFORE_NAMESPACE();
void MyHighwayFunction() {
  // SIMD operations directly
}
HWY_AFTER_NAMESPACE();

// Avoid namespace-scope nor static initializers for SIMD vectors
// Instead, constants initialized via Set should generally be local (const) variables.
void LocalConstantExample() {
  const hwy::ScalableTag<float> df;
  const auto val = hwy::Set(df, 1.0f);
  // Use val locally
}
```

--------------------------------

### Type List Macro for Defining Overloads (ARM SVE Example)

Source: https://google.github.io/highway/en/master/impl_details

This example illustrates the use of type list macros, such as HWY_SVE_FOREACH*, in arm_sve-inl.h. This approach defines all overloads for most operations in a single line, simplifying the management of code for different types when operations are orthogonal across types and consistent.

```c++
// Example conceptual usage (actual macro definition not shown):
// HWY_SVE_FOREACH_OP(Add, HWY_SVE_TYPE_LIST)
// This would expand to definitions for Add for all types in HWY_SVE_TYPE_LIST

```

--------------------------------

### C++: Mixed-Precision Type Rebinding

Source: https://google.github.io/highway/en/master/quick_reference

Demonstrates how to obtain tags for smaller types from larger ones in mixed-precision scenarios, using `Rebind<uint8_t, ScalableTag<float>>` as an example for promoting `uint8_t` lanes to `float`.

```cpp
Rebind<uint8_t, ScalableTag<float>>;
```

--------------------------------

### Enabling Specific x86 Features in Baseline

Source: https://google.github.io/highway/en/master/quick_reference

This example shows how to force the inclusion of specific x86 instruction set extensions, SSSE3 and SSE4, into the baseline target set. This is particularly useful on MSVC compilers where these extensions are typically enabled only when AVX is also enabled. These macros ensure the features are available even if the compiler doesn't automatically detect them.

```cpp
#define HWY_WANT_SSSE3
#define HWY_WANT_SSE4
```

--------------------------------

### Target Support Detection Macros (HWY_HAVE_*)

Source: https://google.github.io/highway/en/master/quick_reference

These macros indicate full support for specific lane types on the current target being compiled. They expand to 1 if the feature is supported, and 0 otherwise. Examples include support for 64-bit integers, 16-bit floats, and 64-bit floats.

```c++
#if HWY_HAVE_INTEGER64
// Support for 64-bit integer lanes
#endif

#if HWY_HAVE_FLOAT16
// Support for 16-bit floating-point lanes
#endif

#if HWY_HAVE_FLOAT64
// Support for double-precision floating-point lanes
#endif
```

--------------------------------

### Function Builder Macro for Custom Templates (ARM NEON Example)

Source: https://google.github.io/highway/en/master/impl_details

This snippet conceptually represents the 'function builder' macro strategy used in arm_neon-inl.h. It helps define custom function templates required for less common operations, offering more flexibility than simple type list macros for handling 'unusual' ops.

```c++
// Example conceptual usage (actual macro definition not shown):
// HWY_NEON_FUNC_BUILDER(ShiftLeft, HWY_NEON_TYPE_LIST, /* custom logic */)
// This allows defining ShiftLeft with specific behaviors for various NEON types.

```

--------------------------------

### Tuple Operations Support (HWY_HAVE_TUPLE)

Source: https://google.github.io/highway/en/master/quick_reference

The HWY_HAVE_TUPLE macro indicates whether tuple-related operations such as Vec{2-4}, Create{2-4}, and Get{2-4} are available. This is generally true for non-scalable targets and certain SVE/RVV configurations.

```c++
#if HWY_HAVE_TUPLE
// Tuple operations are supported
#else
// Tuple operations are not supported
#endif
```

--------------------------------

### Highway Vector Printing Utility

Source: https://google.github.io/highway/en/master/quick_reference

A utility function for printing vector contents to the console, useful for debugging. It allows specifying a caption, the vector to print, an optional starting lane index, and the maximum number of lanes to display.

```c++
namespace hn = hwy::HWY_NAMESPACE;

// Assuming 'd' is a deactivated ForAll and 'vec' is a vector of type V.
// The Print function is defined in hwy/print-inl.h or hwy/tests/test_util-inl.h.

// Example: Print all lanes with a caption
// hn::Print(d, "MyVector:", vec);

// Example: Print starting from lane 4, up to 8 lanes
// hn::Print(d, "PartialVector:", vec, 4, 8);
```

--------------------------------

### Run Tests on Windows Host

Source: https://google.github.io/highway/en/master/release_testing_process

Executes the test suite on a Windows x86 host environment. This is a batch script designed for Windows command-line execution.

```batch
run_tests.bat
```

--------------------------------

### Manual Compilation with Highway Source Files

Source: https://google.github.io/highway/en/master/faq

Provides instructions for manually compiling with Highway if you are not using CMake or Bazel. This involves adding specific Highway source files to your compilation list.

```makefile
hwy/per_target.cc
hwy/targets.cc

```

--------------------------------

### Highway C++: Vector Initialization and Basic Operations

Source: https://context7.com/context7/google_github_io_highway_en_master/llms.txt

Demonstrates how to create and initialize SIMD vectors using type tags and perform fundamental arithmetic operations like addition, multiplication, and fused multiply-add. It also shows how to determine the number of lanes and extract individual lane values. Requires the 'hwy/highway.h' header.

```cpp
#include "hwy/highway.h"

namespace project {
namespace HWY_NAMESPACE {
namespace hn = hwy::HWY_NAMESPACE;

void BasicVectorOperations() {
  // Create tag for float vectors using all available lanes
  const hn::ScalableTag<float> d;

  // Initialize vectors
  auto zeros = hn::Zero(d);                    // All lanes = 0.0
  auto ones = hn::Set(d, 1.0f);                // All lanes = 1.0
  auto sequence = hn::Iota(d, 0.0f);           // [0.0, 1.0, 2.0, 3.0, ...]

  // Arithmetic operations
  auto sum = hn::Add(ones, sequence);          // [1.0, 2.0, 3.0, 4.0, ...]
  auto product = hn::Mul(sum, hn::Set(d, 2.0f)); // [2.0, 4.0, 6.0, 8.0, ...]
  auto result = hn::MulAdd(sequence, ones, hn::Set(d, 10.0f)); // a*b+c

  // Get number of lanes (platform-dependent)
  size_t num_lanes = hn::Lanes(d);

  // Extract single lane value
  float first_value = hn::GetLane(result);
}

}  // namespace HWY_NAMESPACE
}  // namespace project
```

--------------------------------

### Highway Loop Vectorization: Simple Outer Loop

Source: https://google.github.io/highway/en/master/README

This is a common strategy for loop vectorization where all inputs/outputs are padded. The outer loop iterates in steps of the vector width (N), processing entire vectors. This approach avoids the cost of predication or partial loads/stores, making it efficient for most modern hardware.

```c++
for (size_t i = 0; i < count; i += N) LoopBody<false>(d, i, 0);
```

--------------------------------

### Highway Dynamic Dispatch (C++)

Source: https://google.github.io/highway/en/master/quick_reference

Demonstrates how to implement dynamic dispatch for Highway operations. This involves including specific headers and using macros to enable runtime selection of the best instruction set. It's suitable for scenarios where different CPU architectures might be encountered.

```c++
#define HWY_TARGET_INCLUDE \
    "third_party/highway/hwy/foreach_target.h"
#include HWY_TARGET_INCLUDE
#include "hwy/highway.h"

// ... your code using HWY_DYNAMIC_DISPATCH or HWY_STATIC_DISPATCH
```

--------------------------------

### Integrate Highway with Bazel

Source: https://google.github.io/highway/en/master/faq

Shows how to reference the Highway library within a Bazel build system. This involves adding the Highway dependency to your build file.

```bazel
deps = ["//path/highway:hwy"]

```

--------------------------------

### Highway Loop Vectorization: Scalar Loop Fallback

Source: https://google.github.io/highway/en/master/README

This strategy vectorizes the main part of the loop using full vectors and then switches to a scalar loop for any remaining iterations. It's effective for large counts as it avoids code duplication, but the scalar loop might be slower than other methods for small counts.

```c++
size_t i = 0;
for (; i + N <= count; i += N) LoopBody<false>(d, i, 0);
for (; i < count; ++i) LoopBody<false>(CappedTag<T, 1>(), i, 0);
```

--------------------------------

### Highway Loop Vectorization: Masked Operation Fallback

Source: https://google.github.io/highway/en/master/README

This method processes full vectors and then uses a modified `LoopBody` with masking for the remaining iterations. It's a safe default when padding is infeasible, as it avoids non-atomic 'blending' and partial loads/stores, though it requires careful handling of memory operations that might fault.

```c++
size_t i = 0;
for (; i + N <= count; i += N) {
  LoopBody<false>(d, i, 0);
}
if (i < count) {
  LoopBody<true>(d, i, count - i);
}
```

--------------------------------

### Create and Sign Release Archive

Source: https://google.github.io/highway/en/master/release_testing_process

Commands to create a compressed tarball of the release and then cryptographically sign it using GPG. This process ensures the integrity and authenticity of the release artifact.

```shell
git archive --prefix=highway-X.Y.Z/ -o highway-X.Y.Z.tar.gz X.Y.Z
```

```shell
gpg --armor --detach-sign highway-X.Y.Z.tar.gz
```

--------------------------------

### Highway Loop Vectorization: Idempotent Processing

Source: https://google.github.io/highway/en/master/README

A preferred option for loop vectorization when the loop body is idempotent and the total count is at least the vector width (N). This method processes whole vectors, potentially re-processing elements in the last vector. It offers a single code path and full vectorization, usually outweighing the cost of double processing.

```c++
for (size_t i = 0; i < count; i += N) LoopBody<false>(d, HWY_MIN(i, count - N), 0);
```

--------------------------------

### Highway Static Dispatch (C++)

Source: https://google.github.io/highway/en/master/quick_reference

Illustrates static dispatch in Highway, where code is compiled for a single, typically best-available, instruction set. This method offers no runtime overhead but may not leverage newer instruction sets and can crash if run on unsupported CPUs.

```c++
#include "hwy/highway.h"

// ... your code using HWY_STATIC_DISPATCH
```

--------------------------------

### Run Tests on Linux Host

Source: https://google.github.io/highway/en/master/release_testing_process

Executes the test suite on a Linux x86 host, supporting Clang and GCC compilers with Arm and PPC cross-compilation. This script is intended for Linux environments.

```shell
./run_tests.sh
```

--------------------------------

### Get Lane Type from Dimension

Source: https://google.github.io/highway/en/master/quick_reference

Retrieves the underlying lane type `T` from a dimension `D`. This is useful for generic programming where the specific data type of the vector lanes needs to be known.

```cpp
#include "highway/highway.h"

HWY_NAMESPACE_BEGIN
// ...
  using T = TFromD<D>;
// ...
HWY_NAMESPACE_END
```

--------------------------------

### Dynamic Dispatch with Highway (C++)

Source: https://context7.com/context7/google_github_io_highway_en_master/llms.txt

Sets up dynamic dispatch for compiling Highway code against multiple targets, selecting the best implementation at runtime based on CPU features. This approach ensures maximum portability and performance across diverse hardware. It requires including 'hwy/foreach_target.h' and using HWY_DYNAMIC_DISPATCH.

```cpp
// example.cc - Main implementation file
#undef HWY_TARGET_INCLUDE
#define HWY_TARGET_INCLUDE "example.cc"
#include "hwy/foreach_target.h"
#include "hwy/highway.h"

HWY_BEFORE_NAMESPACE();
namespace project {
namespace HWY_NAMESPACE {

// This function is compiled once per target
float ProcessArray(const float* input, float* output, size_t count) {
  const ScalableTag<float> d;
  const size_t N = Lanes(d);

  float sum = 0.0f;
  for (size_t i = 0; i + N <= count; i += N) {
    auto v = LoadU(d, input + i);
    auto result = Mul(v, Set(d, 2.0f));
    StoreU(result, d, output + i);
    sum += ReduceSum(d, result);
  }
  return sum;
}

}  // namespace HWY_NAMESPACE
}  // namespace project
HWY_AFTER_NAMESPACE();

#if HWY_ONCE
namespace project {
HWY_EXPORT(ProcessArray);

// Public wrapper that dispatches to best implementation
float ProcessArrayWrapper(const float* input, float* output, size_t count) {
  // First call detects CPU features
  return HWY_DYNAMIC_DISPATCH(ProcessArray)(input, output, count);
}

}  // namespace project
#endif  // HWY_ONCE

```

--------------------------------

### Get Maximum Possible Lane Count

Source: https://google.github.io/highway/en/master/quick_reference

Retrieves a potentially loose upper bound on the number of lanes for a given tag `d`. This function is always `constexpr` and can be used for compile-time calculations or estimations.

```cpp
#include "highway/highway.h"

HWY_NAMESPACE_BEGIN
// ...
  using T = int16_t;
  HWY_FULL(T) d;
  constexpr size_t kMaxLanes = MaxLanes(d);
// ...
HWY_NAMESPACE_END
```

--------------------------------

### Get Lane Count from Tag (runtime)

Source: https://google.github.io/highway/en/master/quick_reference

Retrieves the number of lanes in a vector tag `d` when compile-time determination is not possible. This value might change at runtime, so it should not be cached or used in `constexpr` contexts.

```cpp
#include "highway/highway.h"

HWY_NAMESPACE_BEGIN
// ...
  using T = uint32_t;
  ScalableTag<T> d;
  size_t num_lanes = Lanes(d);
// ...
HWY_NAMESPACE_END
```

--------------------------------

### Highway Vector Code Integration Macro Usage

Source: https://google.github.io/highway/en/master/quick_reference

This snippet demonstrates the recommended way to include and structure code that utilizes Highway's vector operations. It ensures proper namespace isolation for different targets and enables dynamic dispatch. The `HWY_BEFORE_NAMESPACE` and `HWY_AFTER_NAMESPACE` macros must be placed at file scope. The optional `project` namespace can be used for further organization.

```c++
#include "hwy/highway.h"
HWY_BEFORE_NAMESPACE();  // at file scope
namespace project {  // optional
namespace HWY_NAMESPACE {

// implementation

// NOLINTNEXTLINE(google-readability-namespace-comments)
}  // namespace HWY_NAMESPACE
}  // namespace project - optional
HWY_AFTER_NAMESPACE();
```

--------------------------------

### Get Lane Count from Tag (constexpr)

Source: https://google.github.io/highway/en/master/quick_reference

Retrieves the number of lanes in a vector tag `d` when `HWY_HAVE_CONSTEXPR_LANES` is enabled. This allows the lane count to be determined at compile time, improving code generation.

```cpp
#include "highway/highway.h"

HWY_NAMESPACE_BEGIN
// ...
  using T = uint32_t;
  HWY_FULL(T) d;
  constexpr size_t kLanes = Lanes(d);
// ...
HWY_NAMESPACE_END
```

--------------------------------

### Highway Vector Initialization Operations

Source: https://google.github.io/highway/en/master/quick_reference

Provides functions to initialize vectors with specific values. This includes creating zero-initialized vectors, vectors with all lanes set to a given value, undefined vectors, vectors with incrementing lane values (Iota), vectors with only the sign bit set, and vectors created from a set of values broadcasted to 128-bit blocks. Masked operations for setting lanes based on a mask are also included.

```c++
namespace hn = hwy::HWY_NAMESPACE;

V zero_vec = hn::Zero(d);
V set_vec = hn::Set(d, T{10});
V undefined_vec = hn::Undefined<V>(d);
V iota_vec = hn::Iota(d, T2{0});
V sign_bit_vec = hn::SignBit<V>(d);

// Example for Dup128VecFromValues (assuming T is int32_t and d supports at least 16 lanes)
V dup_vec = hn::Dup128VecFromValues<V>(d, T{1}, T{2}, T{3}, T{4}); 

// Example for MaskedSetOr
// Assume 'no' is an existing vector and 'm' is a mask
V masked_or_vec = hn::MaskedSetOr(no, m, T{5});

// Example for MaskedSet
V masked_set_vec = hn::MaskedSet(d, m, T{6});
```

--------------------------------

### Interleave Lower Halves of Vectors (C++)

Source: https://google.github.io/highway/en/master/quick_reference

Returns alternating lanes from the lower halves of vectors `a` and `b`, starting with `a[0]` in the least significant lane. An optional `D` parameter can be provided. The result `D` is the same lane type as the input vectors.

```c++
Vec<DFromV<V>> InterleaveWholeLower(V a, V b)
{
  // Implementation for interleaving lower halves
  return HWY_DYNAMIC_DISPATCH(InterleaveWholeLower)(a, b);
}

// With optional D
Vec<D> InterleaveWholeLower(D d, V a, V b)
{
  // Implementation for interleaving lower halves
  return HWY_DYNAMIC_DISPATCH(InterleaveWholeLower)(a, b);
}
```

--------------------------------

### CMake Integration for Highway Project

Source: https://context7.com/context7/google_github_io_highway_en_master/llms.txt

Provides a CMake configuration file for building a project that utilizes the Highway library. It includes finding the Highway package, adding an executable, linking the Highway library, and setting crucial compiler optimizations for SIMD performance. It also demonstrates integration with Google Test for testing.

```cmake
cmake_minimum_required(VERSION 3.10)
project(highway_example)

set(CMAKE_CXX_STANDARD 11)

# Find Highway package
find_package(HWY 1.0 REQUIRED)

# Add executable
add_executable(example
  main.cc
  vectorized_code.cc
)

# Link Highway library
target_link_libraries(example PRIVATE hwy)

# Enable optimizations (critical for SIMD performance)
if(MSVC)
  target_compile_options(example PRIVATE /O2 /Gv /arch:AVX2)
else()
  target_compile_options(example PRIVATE -O2 -march=native)
endif()

# For testing
enable_testing()
find_package(GTest REQUIRED)
add_executable(test_example test_example.cc)
target_link_libraries(test_example PRIVATE hwy GTest::gtest_main)
add_test(NAME ExampleTest COMMAND test_example)

```

--------------------------------

### Interleave Upper Halves of Vectors (C++)

Source: https://google.github.io/highway/en/master/quick_reference

Returns alternating lanes from the upper halves of vectors `a` and `b`, starting with `a[N/2]` in the least significant lane. The type `D` must be `DFromV<V>`. This operation is useful for specific data interleaving tasks.

```c++
Vec<D> InterleaveWholeUpper(D d, V a, V b)
{
  // Implementation for interleaving upper halves
  return HWY_DYNAMIC_DISPATCH(InterleaveWholeUpper)(d, a, b);
}
```

--------------------------------

### Setting Runtime Targets for Testing

Source: https://google.github.io/highway/en/master/quick_reference

This function allows explicitly setting the return value of SupportedTargets() for testing purposes. It overrides the runtime detection and any targets disabled by DisableTargets(). This is invaluable for unit testing specific target codepaths without needing to run on hardware with those features.

```cpp
SetSupportedTargetsForTest(b); // Where 'b' is the desired bitmask of targets
```

--------------------------------

### Getting Target Name String

Source: https://google.github.io/highway/en/master/quick_reference

This function retrieves a string literal that identifies the current Highway target. It's typically used with HWY_TARGET to provide a human-readable name for the specific instruction set being compiled or executed. This is useful for debugging or logging purposes.

```cpp
const char* target_name = TargetName(HWY_TARGET);
```

--------------------------------

### Load and Broadcast 128-bit Block

Source: https://google.github.io/highway/en/master/quick_reference

Loads a single 128-bit block from memory and broadcasts it to all 128-bit blocks within the vector. This can be faster than broadcasting individual values and simplifies the preparation of constants for varying vector lengths. Requires HWY_TARGET != HWY_SCALAR.

```c++
template<typename D, typename T>
Vec<D> LoadDup128(D d, const T* p);
```

--------------------------------

### InterleaveOdd: Interleave odd-indexed lanes of two vectors

Source: https://google.github.io/highway/en/master/quick_reference

Returns alternating lanes from the odd-indexed lanes of two input vectors (`a` and `b`), starting with `a[1]`. Lanes do not move across block boundaries. This operation is typically more efficient than `OddEven(b, DupOdd(a))`. A dimension parameter `D` is required. Available for non-scalar targets.

```c++
V InterleaveOdd(D d, V a, V b)
```

--------------------------------

### InterleaveEven: Interleave even-indexed lanes of two vectors

Source: https://google.github.io/highway/en/master/quick_reference

Returns alternating lanes from the even-indexed lanes of two input vectors (`a` and `b`), starting with `a[0]`. Lanes do not move across block boundaries. This operation is typically more efficient than `OddEven(DupEven(b), a)`. An optional dimension parameter `D` can be provided. Available for non-scalar targets.

```c++
V InterleaveEven(D d, V a, V b)
```

```c++
V InterleaveEven(V a, V b)
```

--------------------------------

### Reorder Widen Multiplication Accumulate (ReorderWidenMulAccumulate)

Source: https://google.github.io/highway/en/master/quick_reference

Widens `a` and `b` to `TFromD<DW>`, computes `a[i] * b[i]`, and adds it to either `sum1[j]` or the return value's lane `j`, based on a permutation `P(i)`. `SumOfLanes(d, Add(return_value, sum1))` equals the sum of all `a[i] * b[i]`. Useful for dot products and L2 norms. Initial `sum1` must be zero.

```c++
VW ReorderWidenMulAccumulate(DW d, V a, V b, VW sum0, VW& sum1)
```

--------------------------------

### Bit Casting and Resizing

Source: https://google.github.io/highway/en/master/quick_reference

Functions for reinterpreting bits of vectors between different types and resizing them.

```APIDOC
## BitCast

### Description
Returns the bits of `V` reinterpreted as type `Vec<D>`.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> BitCast(D, V)
```

### Response
#### Success Response (200)
- **Vec<D>** - The bits of V reinterpreted as type Vec<D>.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## ResizeBitCast

### Description
Resizes `V` to a vector of `Lanes(D()) * sizeof(TFromD<D>)` bytes, and then returns the bits of the resized vector reinterpreted as type `Vec<D>`. If `Vec<D>` is a larger vector than `V`, then the contents of any bytes past the first `Lanes(DFromV<V>()) * sizeof(TFromV<V>)` bytes of the result vector is unspecified.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> ResizeBitCast(D, V)
```

### Response
#### Success Response (200)
- **Vec<D>** - The bits of the resized vector reinterpreted as type Vec<D>.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## ZeroExtendResizeBitCast

### Description
Resizes `V`, which is a vector of type `Vec<DFrom>`, to a vector of `Lanes(D()) * sizeof(TFromD<D>)` bytes, and then returns the bits of the resized vector reinterpreted as type `Vec<DTo>`. If `Lanes(DTo()) * sizeof(TFromD<DTo>)` is greater than `Lanes(DFrom()) * sizeof(TFromD<DFrom>)`, then any bytes past the first `Lanes(DFrom()) * sizeof(TFromD<DFrom>)` bytes of the result vector are zeroed out.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<DTo> ZeroExtendResizeBitCast(DTo, DFrom, V)
```

### Response
#### Success Response (200)
- **Vec<DTo>** - The bits of the resized vector reinterpreted as type Vec<DTo>.

#### Response Example
```
// Example usage depends on the specific types DTo, DFrom, and V
```
```

--------------------------------

### Promote Half Vector to Full Vector (FP32 to FP64)

Source: https://google.github.io/highway/en/master/quick_reference

Promotes a half vector of f32 to f64. The function widens the input single-precision floating-point lanes to double-precision.

```c++
Vec<D> PromoteTo(D d, V part)
// f32 to f64
```

--------------------------------

### Initialize Float16_t or Bfloat16_t via BitCastScalar

Source: https://google.github.io/highway/en/master/quick_reference

Initializes `float16_t` or `bfloat16_t` types using `BitCastScalar`. Due to their nature as wrapper structs, direct initialization is not supported. This method allows for bit-level conversion from compatible types.

```cpp
#include "highway/highway.h"

HWY_NAMESPACE_BEGIN
// ...
  float16_t hf = BitCastScalar<float16_t>(static_cast<uint16_t>(0x3c00)); // Represents 1.0f
  bfloat16_t bf = BitCastScalar<bfloat16_t>(static_cast<uint16_t>(0x3f80)); // Represents 1.0f
// ...
HWY_NAMESPACE_END
```

--------------------------------

### Widen Pairwise Multiplication and Add (WidenMulPairwiseAdd)

Source: https://google.github.io/highway/en/master/quick_reference

Widens vectors `a` and `b` to a wider type `TFromD<D>` and computes the sum of pairwise products: `a[2*i+1]*b[2*i+1] + a[2*i+0]*b[2*i+0]` for each lane `i`. Requires a `D` descriptor for repartitioning to wide vectors.

```c++
Vec<D> WidenMulPairwiseAdd(D d, V a, V b)
```

--------------------------------

### Declaring Target-Specific Functions with HWY_VISIT_TARGETS

Source: https://google.github.io/highway/en/master/quick_reference

This snippet illustrates how to declare functions that are specific to enabled Highway targets. HWY_VISIT_TARGETS iterates over all enabled targets and applies a VISITOR macro, allowing for the declaration of target-specific functions within their respective namespaces. This avoids dynamic dispatch overhead for known targets at compile time.

```cpp
HWY_VISIT_TARGETS(VISITOR)
// Example VISITOR usage:
// VISITOR(HWY_AVX2, N_AVX2) -> declares function in namespace N_AVX2
```

--------------------------------

### Promote Half Vector to Full Vector (General Type Promotion)

Source: https://google.github.io/highway/en/master/quick_reference

Promotes a half vector to a full vector, allowing type conversions such as unsigned to wider signed/unsigned, signed to wider signed, f16 to f32, f16 to f64, bf16 to f32, and f32 to f64. The function zero- or sign-extends integer types or widens floating-point types.

```c++
Vec<D> PromoteTo(D d, V part)
// Unsigned V to wider signed/unsigned D; signed to wider signed,
// f16 to f32, f16 to f64, bf16 to f32, f32 to f64
```

--------------------------------

### Integer and Float Conversions

Source: https://google.github.io/highway/en/master/quick_reference

Functions for converting between integer and floating-point types, including special cases and range-aware conversions.

```APIDOC
## U8FromU32

### Description
Special-case `u32` to `u8` conversion when all lanes of `V` are already clamped to `[0, 256)`.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
V8 U8FromU32(V) // Where V is u32 and V8 is u8
```

### Response
#### Success Response (200)
- **V8** - The converted u8 vector.

#### Response Example
```
// Example usage depends on the specific types V and V8
```

## ConvertTo (Integer to Float)

### Description
Converts a signed/unsigned integer value to same-sized floating point.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> ConvertTo(D, V) // Where D is a float type and V is an integer type
```

### Response
#### Success Response (200)
- **Vec<D>** - The converted floating-point vector.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## ConvertTo (Float to Integer)

### Description
Rounds floating point towards zero and converts the value to same-sized signed/unsigned integer. Returns the closest representable value if the input exceeds the destination range.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> ConvertTo(D, V) // Where D is an integer type and V is a float type
```

### Response
#### Success Response (200)
- **Vec<D>** - The converted integer vector.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## ConvertInRangeTo

### Description
Rounds floating point towards zero and converts the value to same-sized signed/unsigned integer. Returns an implementation-defined value if the input exceeds the destination range.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> ConvertInRangeTo(D, V) // Where D is an integer type and V is a float type
```

### Response
#### Success Response (200)
- **Vec<D>** - The converted integer vector.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## NearestInt

### Description
Returns the integer nearest to `a[i]`; results are undefined for NaN.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Ret NearestInt(V a) // Where V is a float type and Ret is a signed integer type
```

### Response
#### Success Response (200)
- **Ret** - The nearest integer value.

#### Response Example
```
// Example usage depends on the specific types V and Ret
```

## CeilInt

### Description
Equivalent to `ConvertTo(RebindToSigned<DFromV<V>>(), Ceil(a))`, but `CeilInt(a)` is more efficient on some targets, including SSE2, SSSE3, and AArch64 NEON.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Ret CeilInt(V a) // Where V is a float type and Ret is a signed integer type
```

### Response
#### Success Response (200)
- **Ret** - The ceiling integer value.

#### Response Example
```
// Example usage depends on the specific types V and Ret
```

## FloorInt

### Description
Equivalent to `ConvertTo(RebindToSigned<DFromV<V>>(), Floor(a))`, but `FloorInt(a)` is more efficient on some targets, including SSE2, SSSE3, and AArch64 NEON.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Ret FloorInt(V a) // Where V is a float type and Ret is a signed integer type
```

### Response
#### Success Response (200)
- **Ret** - The floor integer value.

#### Response Example
```
// Example usage depends on the specific types V and Ret
```

## DemoteToNearestInt

### Description
Converts `v[i]` to `TFromD<D>`, rounding to nearest (with ties to even). `DemoteToNearestInt(d, v)` is equivalent to `DemoteTo(d, Round(v))`, but `DemoteToNearestInt(d, v)` is more efficient on some targets, including x86 and RVV.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> DemoteToNearestInt(D d, V v) // Where D is i32 and V is f64
```

### Response
#### Success Response (200)
- **Vec<D>** - The demoted and rounded to nearest integer vector.

#### Response Example
```
// Example usage depends on the specific types D and V
```

## MaskedConvertTo

### Description
Returns `v[i]` converted to `D` where `m` is active and returns zero otherwise.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
Vec<D> MaskedConvertTo(M m, D d, V v)
```

### Response
#### Success Response (200)
- **Vec<D>** - The masked and converted vector.

#### Response Example
```
// Example usage depends on the specific types M, D, and V
```
```

--------------------------------

### Promote Half Vector to Full Vector (Integer to FP64)

Source: https://google.github.io/highway/en/master/quick_reference

Promotes a half vector of {u,i}32 to f64. The function widens the input integer lanes to double-precision floating-point values.

```c++
Vec<D> PromoteTo(D d, V part)
// {u,i}32 to f64
```

--------------------------------

### Ordered Demote Two Vectors (C++)

Source: https://google.github.io/highway/en/master/quick_reference

Converts two input vectors `a` and `b` into a single output vector `D` with twice the number of lanes. The output is formed by demoting `a`'s elements into the lower half and `b`'s elements into the upper half. Integer inputs are saturated. Only available if HWY_TARGET != HWY_SCALAR.

```c++
Vec<D> OrderedDemote2To(D d, V a, V b)
{
  // Implementation for ordered demotion of two vectors
  return HWY_DYNAMIC_DISPATCH(OrderedDemote2To)(d, a, b);
}
```

--------------------------------

### Create Masks

Source: https://google.github.io/highway/en/master/quick_reference

Functions for creating masks based on lane indices, vector values, or bit patterns. Includes creating all-true, all-false, and specific bit-based masks. Some functions have efficiency advantages over generic equivalents.

```c++
M FirstN(D d, size_t N);
M MaskFromVec(V v);
M LoadMaskBits(D d, const uint8_t* p);
M Dup128MaskFromMaskBits(D d, unsigned mask_bits);
M MaskFalse(D d);
M SetMask(D d, bool val);
```

--------------------------------

### Add Highway as a Git Submodule

Source: https://google.github.io/highway/en/master/faq

This snippet shows how to add the Highway library as a Git submodule to your project. This allows for easy recursive cloning of your repository, ensuring that Highway is included.

```gitconfig
[submodule "highway"]
    path = highway
    url = https://github.com/google/highway

```

--------------------------------

### Lint-Friendly Include Guard for Per-Target Compilation

Source: https://google.github.io/highway/en/master/faq

This snippet demonstrates how to prevent linter warnings for the special per-target include guard. It includes a conventional empty include guard at the beginning of the file, followed by the special guard, satisfying both the linter and the per-target compilation requirements.

```c++
// Start of file: empty include guard to avoid lint errors
#ifndef MYPROJECT_FILE_INL_H_
#define MYPROJECT_FILE_INL_H_
#endif
// Followed by the actual per-target guard as above

```

--------------------------------

### Safe Array Remainder Handling with Highway (C++)

Source: https://google.github.io/highway/en/master/faq

Demonstrates how to safely handle array remainders when dealing with vector lengths, preventing page faults or ASan/MSan errors. It utilizes the `hwy/contrib/algo/transform-inl.h` library, which abstracts away the complexities of loop iteration and remainder management. Users define a templated function for a single iteration, and Highway's `Generate` or `Transform*` functions manage the rest.

```c++
#include "hwy/contrib/algo/transform-inl.h"

// Example usage of Generate or Transform*
// Assume MyFunctor is a templated lambda or struct that implements one iteration
// For example:
// auto MyFunctor = [&](auto d) {
//   // vector operations using Auto's lanes
// };
// Highway::Generate(my_output_buffer, num_elements, MyFunctor);
// or
// Highway::Transform(my_input_buffer, my_output_buffer, num_elements, MyFunctor);

```
Tokens:
Raw