How amzmike/vcl_version2 works
1. Repository purpose
- This is the Vector Class Library (VCL), a C++ SIMD abstraction layer for x86/x86-64 CPUs on Windows, Linux, and macOS.
- It is primarily a header-based performance library, not an application: consumers include the headers and compile their own code against the chosen SIMD features.
2. Top-level architecture
- The repo is organized around a core umbrella header plus a set of width/type-specific headers.
- The main boundary is between:
- portable user code that includes vectorclass.h, and
- hardware-specific SIMD implementations hidden behind the class templates and instruction-set dispatch.
3. Core entry point
- vectorclass.h is the main integration header.
- It acts as the public façade that aggregates the lower-level vector types and utilities so downstream code can include one file instead of many.
4. SIMD type families by data kind
- The library is split into separate headers for floating-point and integer vectors:
- vectorf128.h, vectorf256.h, vectorf512.h, and extended variants like vectorf256e.h, vectorf512e.h, vectorfp16.h, vectorfp16e.h
- vectori128.h, vectori256.h, vectori512.h, and extended variants like vectori256e.h, vectori512e.h, vectori512s.h, vectori512se.h
- This shows a design where the API is organized by element type and vector width, matching the underlying SIMD instruction sets.
5. Shared utility layer
- vectormath_common.h provides shared math/support code used by the higher-level math headers.
- vector_convert.h suggests a dedicated conversion layer for moving between vector types and scalar representations.
- instrset.h is the instruction-set capability definition layer used throughout the library to decide which CPU features are available.
6. Math subsystem
- The vectormath_* headers are a separate functional layer built on top of the vector primitives:
- vectormath_trig.h
- vectormath_exp.h
- vectormath_hyp.h
- vectormath_lib.h
- Architecturally, this is the algorithm layer: it implements higher-level SIMD math functions using the core vector types.
7. Runtime CPU feature detection
- instrset_detect.cpp is the main non-header implementation file and likely provides runtime detection of the host CPU’s SIMD capabilities.
- This creates a boundary between:
- compile-time selection of vector APIs, and
- runtime dispatch to the best supported implementation on the current machine.
8. Dispatch examples
- dispatch_example1.cpp and dispatch_example2.cpp demonstrate multi-versioning / dispatch patterns.
- They are important architectural reference points because they show how client code can choose an implementation path based on detected instruction set support.
9. Dependency direction
- The dependency graph is layered:
- low-level instruction-set definitions and detection
- vector type headers
- conversion and common helpers
- math libraries built on top
- user-facing code and examples
- The library is intentionally bottom-up, with higher layers depending on lower ones but not vice versa.
10. Platform and technology boundary
- The README makes the platform boundary explicit: x86 and x86-64 only, with no ARM support planned.
- That matters architecturally because the library’s abstractions are designed around Intel/AMD SIMD instruction families rather than a portable cross-ISA backend.
11. Packaging model
- There is no obvious build system or service backend here; the repo is effectively a source-distribution library.
- Consumers integrate it directly into their own build, choosing whether to use a fixed SIMD target or runtime-dispatched variants.
12. What to draw in an architecture diagram
- Show one central library box with:
- public include façade (vectorclass.h)
- core SIMD types (128/256/512-bit float and integer families)
- math extensions (vectormath_*)
- instruction-set detection/dispatch (instrset.h, instrset_detect.cpp, dispatch examples)
- Then place the consumer application on the outside, depending on the library, with runtime branching only where dispatch is used.
Main entry points: vectorclass.h vectorclass.h · vectormath_common.h vectormath_common.h · instrset_detect.cpp instrset_detect.cpp · dispatch_example1.cpp dispatch_example1.cpp
Components 18
Public API
Entry headers that downstream code includes directly.
- vectorclass.h · Main public façade that aggregates the library into one include.
vectorclass.h
Core SIMD
Width- and type-specific vector primitives plus shared support code.
- instrset.h · Instruction-set capability definitions shared across the library.
instrset.h - vector_convert.h · Conversions between vector types and scalar or related representations.
vector_convert.h - vectorf128.h · 128-bit floating-point SIMD types and operations.
vectorf128.h - vectorf256.h · 256-bit floating-point SIMD types and operations.
vectorf256.h - vectorf512.h · 512-bit floating-point SIMD types and operations.
vectorf512.h - vectori128.h · 128-bit integer SIMD types and operations.
vectori128.h - vectori256.h · 256-bit integer SIMD types and operations.
vectori256.h - vectori512.h · 512-bit integer SIMD types and operations.
vectori512.h
Math Layer
Higher-level SIMD math algorithms built on the core vector types.
- vectormath_common.h · Shared support code used by higher-level vector math headers.
vectormath_common.h - vectormath_trig.h · SIMD trigonometric functions built on vector primitives.
vectormath_trig.h - vectormath_exp.h · SIMD exponential and related functions.
vectormath_exp.h - vectormath_hyp.h · SIMD hyperbolic functions built on the math layer.
vectormath_hyp.h - vectormath_lib.h · Convenience entry point for the vectormath subsystem.
vectormath_lib.h
Runtime Dispatch
CPU feature detection and multi-version selection paths.
- instrset_detect.cpp · Runtime probing of host SIMD capability.
instrset_detect.cpp
Examples
Client-side usage patterns for selecting implementations.
- dispatch_example1.cpp · Example of choosing implementations by detected instruction set.
dispatch_example1.cpp - dispatch_example2.cpp · Second dispatch example showing multi-versioning patterns.
dispatch_example2.cpp
Other components
- Consumer code · External code that includes the headers and compiles against chosen SIMD targets.
Connections 21
- Consumer code → vectorclass.h: includes · Typical downstream entry point for the library.
- vectorclass.h → instrset.h: depends on · Umbrella API relies on instruction-set capability definitions.
- vectorclass.h → vector_convert.h: bundles · Public façade exposes conversion utilities alongside vector types.
- vectorclass.h → vectorf128.h: exports · Aggregates 128-bit floating-point vector types.
- vectorclass.h → vectorf256.h: exports · Aggregates 256-bit floating-point vector types.
- vectorclass.h → vectorf512.h: exports · Aggregates 512-bit floating-point vector types.
- vectorclass.h → vectori128.h: exports · Aggregates 128-bit integer vector types.
- vectorclass.h → vectori256.h: exports · Aggregates 256-bit integer vector types.
- vectorclass.h → vectori512.h: exports · Aggregates 512-bit integer vector types.
- vectorclass.h → vectormath_lib.h: bundles · Public façade can include the higher-level math subsystem.
- vectormath_lib.h → vectormath_common.h: builds on · Math facade depends on shared math support.
- vectormath_common.h → vectorf256.h: uses · Math algorithms are implemented on top of core vector types.
- vectormath_common.h → vectorf512.h: uses · Math algorithms are implemented on top of core vector types.
- vectormath_trig.h → vectormath_common.h: uses · Trig routines reuse common math helpers.
- vectormath_exp.h → vectormath_common.h: uses · Exponential routines reuse common math helpers.
- vectormath_hyp.h → vectormath_common.h: uses · Hyperbolic routines reuse common math helpers.
- instrset_detect.cpp → instrset.h: reports · Runtime detection feeds the instruction-set layer.
- dispatch_example1.cpp → instrset_detect.cpp: queries · Example selects code paths based on detected CPU support.
- dispatch_example2.cpp → instrset_detect.cpp: queries · Example selects code paths based on detected CPU support.
- dispatch_example1.cpp → vectorclass.h: uses · Dispatch example still consumes the public vector API.
- dispatch_example2.cpp → vectorclass.h: uses · Dispatch example still consumes the public vector API.