13. Vectors

13. Cortex.Vectors

Cortex.Vectors is part of the Cortex Data Framework, providing high-performance mathematical vector types for .NET — optimized for AI, analytics, and numerical computation workloads.

📘 Overview

Cortex.Vectors implements a set of generic math–based vector representations:

Type	Description	Best For
🟢 DenseVector<T>	Contiguous in-memory array of values	Small-to-medium dense data (<10⁶ elements)
🔵 SparseVector<T>	Dictionary-based representation of non-zero entries	Huge vectors with mostly-zero values
🟡 BitVector<T>	Compact bit-packed boolean representation	Binary data, masks, feature flags

All vector types implement the shared IVector interface — supporting Dot, Norm, and Normalize operations — and leverage the modern generic math API (IFloatingPointIeee754) introduced in .NET 7.

🧩 Core Interface — IVector

public interface IVector<T> : IReadOnlyList<T> where T : IFloatingPointIeee754<T>
{
    int Dimension { get; }
    T Dot(IVector<T> other);
    T Norm();
    IVector<T> Normalize();
}

The interface defines a consistent linear-algebra contract:

• Dot — inner product
• Norm — L2 (Euclidean) norm
• Normalize — returns a unit-length version of the vector
• Indexer access via this[int i]

🟢 DenseVector

Description

DenseVector<T> represents a standard contiguous array of floating-point numbers — ideal for dense, SIMD-friendly computations.

Key Features

• Direct array-backed storage (T[])
• Operator overloads for +, -, and scalar *
• Fast normalization and dot product
• Convenient static constructors:
  • DenseVector<T>.Zeros(dimension)
  • DenseVector<T>.Filled(dimension, value)

Example

var a = new DenseVector<float>(1f, 2f, 3f);
var b = DenseVector<float>.Filled(3, 0.5f);

float dot = a.Dot(b);        // 3.0
float norm = a.Norm();       // ≈ 3.7417
var unit = a.Normalize();    // Unit-length vector

🔵 SparseVector

Description

SparseVector<T> stores only non-zero elements using a dictionary, significantly reducing memory footprint for high-dimensional vectors.

Key Features

• Backed by Dictionary<int, T>
• Efficient arithmetic (+, -, scalar *)
• Supports construction from key/value pairs or indices
• Automatically prunes zero results from arithmetic

Example

var sv = new SparseVector<double>(
    1_000_000,
    new[]
    {
        new KeyValuePair<int,double>(42, 1.0),
        new KeyValuePair<int,double>(123456, 2.5)
    });

double norm = sv.Norm();    // √(1² + 2.5²)
var unit = sv.Normalize();  // Unit vector

🟡 BitVector

Description

BitVector<T> is a fixed-length, bit-packed vector representing binary states (0 → T.Zero, 1 → T.One). Useful for feature flags, binary masks, and compact ML representations.

Key Features

• Backed by ulong[] bit blocks
• Constant-time popcount via BitOperations.PopCount
• Efficient bitwise dot product
• Converts automatically to normalized dense form

Example

var bv = new BitVector<float>(128, new[] { 0, 3, 5 });

int ones = bv.PopCount();     // 3
float dot = bv.Dot(bv);       // 3.0
var norm = bv.Norm();         // √3

🧮 Vector Extensions

VectorExtensions provides helper operations built on top of the base interface.

Cosine Similarity

float cosine = a.CosineSimilarity(b);

Dense → Sparse Conversion

var sparse = a.ToSparse();

🧱 Design Principles

• Generic-Math First — All vectors use IFloatingPointIeee754<T> ensuring precision and flexibility (float, double, decimal, Half).
• Memory Efficiency — Choose representation that matches your data density.
• Composable — All types implement a shared contract (IVector<T>), allowing easy interop.
• Performance-Driven — Uses AggressiveInlining, span-based constructors, and popcount intrinsics.

🧠 Typical Use-Cases

• Machine Learning feature vectors
• Similarity search (cosine, dot)
• Sparse embedding manipulation
• Binary data compression and filters
• Numeric computing pipelines in Cortex Streams

🚀 Installation

dotnet add package Cortex.Vectors

🧰 Example End-to-End Usage

using Cortex.Vectors;

var a = new DenseVector<double>(1.0, 0.0, 2.0);
var b = new SparseVector<double>(3, new[] { new KeyValuePair<int,double>(2, 2.0) });
var cosine = a.CosineSimilarity(b);

Console.WriteLine($"Cosine similarity: {cosine}");