# amzmike/vcl_version2 architecture

> Architecture diagram of the GitHub repository amzmike/vcl_version2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amzmike/vcl_version2
- Repository: https://github.com/amzmike/vcl_version2

## Overview

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`](https://github.com/amzmike/vcl_version2/blob/master/vectorclass.h) (vectorclass.h), [`vectormath_common.h`](https://github.com/amzmike/vcl_version2/blob/master/vectormath_common.h) (vectormath_common.h), [`instrset_detect.cpp`](https://github.com/amzmike/vcl_version2/blob/master/instrset_detect.cpp) (instrset_detect.cpp), [`dispatch_example1.cpp`](https://github.com/amzmike/vcl_version2/blob/master/dispatch_example1.cpp) (dispatch_example1.cpp)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_public["Public API"]
  node_n_vectorclass["vectorclass.h<br/>umbrella header<br/>[vectorclass.h]"]
end

subgraph group_g_core["Core SIMD"]
  node_n_instrset["instrset.h<br/>ISA defs<br/>[instrset.h]"]
  node_n_vector_convert["vector_convert.h<br/>conversion helpers<br/>[vector_convert.h]"]
  node_n_vecf128["vectorf128.h<br/>fp vectors<br/>[vectorf128.h]"]
  node_n_vecf256["vectorf256.h<br/>fp vectors<br/>[vectorf256.h]"]
  node_n_vecf512["vectorf512.h<br/>fp vectors<br/>[vectorf512.h]"]
  node_n_veci128["vectori128.h<br/>int vectors<br/>[vectori128.h]"]
  node_n_veci256["vectori256.h<br/>int vectors<br/>[vectori256.h]"]
  node_n_veci512["vectori512.h<br/>int vectors<br/>[vectori512.h]"]
end

subgraph group_g_math["Math Layer"]
  node_n_vmath_common["vectormath_common.h<br/>math support"]
  node_n_vmath_trig["vectormath_trig.h<br/>math algorithms<br/>[vectormath_trig.h]"]
  node_n_vmath_exp["vectormath_exp.h<br/>math algorithms<br/>[vectormath_exp.h]"]
  node_n_vmath_hyp["vectormath_hyp.h<br/>math algorithms<br/>[vectormath_hyp.h]"]
  node_n_vmath_lib["vectormath_lib.h<br/>math facade<br/>[vectormath_lib.h]"]
end

subgraph group_g_runtime["Runtime Dispatch"]
  node_n_instrset_detect["instrset_detect.cpp<br/>cpu detection"]
end

subgraph group_g_examples["Examples"]
  node_n_dispatch1["dispatch_example1.cpp<br/>dispatch example"]
  node_n_dispatch2["dispatch_example2.cpp<br/>dispatch example"]
end

node_n_consumer(("Consumer code<br/>downstream app"))

node_n_consumer -->|"includes"| node_n_vectorclass
node_n_vectorclass -->|"depends on"| node_n_instrset
node_n_vectorclass -->|"bundles"| node_n_vector_convert
node_n_vectorclass -->|"exports"| node_n_vecf128
node_n_vectorclass -->|"exports"| node_n_vecf256
node_n_vectorclass -->|"exports"| node_n_vecf512
node_n_vectorclass -->|"exports"| node_n_veci128
node_n_vectorclass -->|"exports"| node_n_veci256
node_n_vectorclass -->|"exports"| node_n_veci512
node_n_vectorclass -->|"bundles"| node_n_vmath_lib
node_n_vmath_lib -->|"builds on"| node_n_vmath_common
node_n_vmath_common -->|"uses"| node_n_vecf256
node_n_vmath_common -->|"uses"| node_n_vecf512
node_n_vmath_trig -->|"uses"| node_n_vmath_common
node_n_vmath_exp -->|"uses"| node_n_vmath_common
node_n_vmath_hyp -->|"uses"| node_n_vmath_common
node_n_instrset_detect -->|"reports"| node_n_instrset
node_n_dispatch1 -->|"queries"| node_n_instrset_detect
node_n_dispatch2 -->|"queries"| node_n_instrset_detect
node_n_dispatch1 -->|"uses"| node_n_vectorclass
node_n_dispatch2 -->|"uses"| node_n_vectorclass

click node_n_vectorclass "https://github.com/amzmike/vcl_version2/blob/master/vectorclass.h"
click node_n_instrset "https://github.com/amzmike/vcl_version2/blob/master/instrset.h"
click node_n_vector_convert "https://github.com/amzmike/vcl_version2/blob/master/vector_convert.h"
click node_n_vecf128 "https://github.com/amzmike/vcl_version2/blob/master/vectorf128.h"
click node_n_vecf256 "https://github.com/amzmike/vcl_version2/blob/master/vectorf256.h"
click node_n_vecf512 "https://github.com/amzmike/vcl_version2/blob/master/vectorf512.h"
click node_n_veci128 "https://github.com/amzmike/vcl_version2/blob/master/vectori128.h"
click node_n_veci256 "https://github.com/amzmike/vcl_version2/blob/master/vectori256.h"
click node_n_veci512 "https://github.com/amzmike/vcl_version2/blob/master/vectori512.h"
click node_n_vmath_common "https://github.com/amzmike/vcl_version2/blob/master/vectormath_common.h"
click node_n_vmath_trig "https://github.com/amzmike/vcl_version2/blob/master/vectormath_trig.h"
click node_n_vmath_exp "https://github.com/amzmike/vcl_version2/blob/master/vectormath_exp.h"
click node_n_vmath_hyp "https://github.com/amzmike/vcl_version2/blob/master/vectormath_hyp.h"
click node_n_vmath_lib "https://github.com/amzmike/vcl_version2/blob/master/vectormath_lib.h"
click node_n_instrset_detect "https://github.com/amzmike/vcl_version2/blob/master/instrset_detect.cpp"
click node_n_dispatch1 "https://github.com/amzmike/vcl_version2/blob/master/dispatch_example1.cpp"
click node_n_dispatch2 "https://github.com/amzmike/vcl_version2/blob/master/dispatch_example2.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_vectorclass toneBlue
class node_n_instrset,node_n_vector_convert,node_n_vecf128,node_n_vecf256,node_n_vecf512,node_n_veci128,node_n_veci256,node_n_veci512 toneAmber
class node_n_vmath_common,node_n_vmath_trig,node_n_vmath_exp,node_n_vmath_hyp,node_n_vmath_lib toneMint
class node_n_instrset_detect toneRose
class node_n_dispatch1,node_n_dispatch2 toneIndigo
class node_n_consumer toneNeutral
```

## Components

### Public API

Entry headers that downstream code includes directly.

- [vectorclass.h](https://github.com/amzmike/vcl_version2/blob/master/vectorclass.h): umbrella header · 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](https://github.com/amzmike/vcl_version2/blob/master/instrset.h): ISA defs · Instruction-set capability definitions shared across the library. · `instrset.h`
- [vector_convert.h](https://github.com/amzmike/vcl_version2/blob/master/vector_convert.h): conversion helpers · Conversions between vector types and scalar or related representations. · `vector_convert.h`
- [vectorf128.h](https://github.com/amzmike/vcl_version2/blob/master/vectorf128.h): fp vectors · 128-bit floating-point SIMD types and operations. · `vectorf128.h`
- [vectorf256.h](https://github.com/amzmike/vcl_version2/blob/master/vectorf256.h): fp vectors · 256-bit floating-point SIMD types and operations. · `vectorf256.h`
- [vectorf512.h](https://github.com/amzmike/vcl_version2/blob/master/vectorf512.h): fp vectors · 512-bit floating-point SIMD types and operations. · `vectorf512.h`
- [vectori128.h](https://github.com/amzmike/vcl_version2/blob/master/vectori128.h): int vectors · 128-bit integer SIMD types and operations. · `vectori128.h`
- [vectori256.h](https://github.com/amzmike/vcl_version2/blob/master/vectori256.h): int vectors · 256-bit integer SIMD types and operations. · `vectori256.h`
- [vectori512.h](https://github.com/amzmike/vcl_version2/blob/master/vectori512.h): int vectors · 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](https://github.com/amzmike/vcl_version2/blob/master/vectormath_common.h): math support · Shared support code used by higher-level vector math headers. · `vectormath_common.h`
- [vectormath_trig.h](https://github.com/amzmike/vcl_version2/blob/master/vectormath_trig.h): math algorithms · SIMD trigonometric functions built on vector primitives. · `vectormath_trig.h`
- [vectormath_exp.h](https://github.com/amzmike/vcl_version2/blob/master/vectormath_exp.h): math algorithms · SIMD exponential and related functions. · `vectormath_exp.h`
- [vectormath_hyp.h](https://github.com/amzmike/vcl_version2/blob/master/vectormath_hyp.h): math algorithms · SIMD hyperbolic functions built on the math layer. · `vectormath_hyp.h`
- [vectormath_lib.h](https://github.com/amzmike/vcl_version2/blob/master/vectormath_lib.h): math facade · Convenience entry point for the vectormath subsystem. · `vectormath_lib.h`

### Runtime Dispatch

CPU feature detection and multi-version selection paths.

- [instrset_detect.cpp](https://github.com/amzmike/vcl_version2/blob/master/instrset_detect.cpp): cpu detection · Runtime probing of host SIMD capability. · `instrset_detect.cpp`

### Examples

Client-side usage patterns for selecting implementations.

- [dispatch_example1.cpp](https://github.com/amzmike/vcl_version2/blob/master/dispatch_example1.cpp): dispatch example · Example of choosing implementations by detected instruction set. · `dispatch_example1.cpp`
- [dispatch_example2.cpp](https://github.com/amzmike/vcl_version2/blob/master/dispatch_example2.cpp): dispatch example · Second dispatch example showing multi-versioning patterns. · `dispatch_example2.cpp`

### Other components

- **Consumer code**: downstream app · External code that includes the headers and compiles against chosen SIMD targets.

## Connections

- 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.
