Curved Metrics | NumKong for C

Curved-space kernels are separate from the flat Euclidean family because their dataflow is different. They combine vectors with an extra metric tensor or covariance inverse.

// Complex bilinear form: aᴴ M b
nk_f32c_t a[32], b[32], metric[32 * 32];
nk_f64c_t result = {0, 0};
nk_bilinear_f32c_best(a, b, metric, 32, &result, capabilities, NULL);

// Real Mahalanobis distance: √((a−b)ᵀ M⁻¹ (a−b))
nk_f32_t x[64], y[64], inv_cov[64 * 64];
nk_f64_t distance = 0;
nk_mahalanobis_f32_best(x, y, inv_cov, 64, &distance, capabilities, NULL);

API

Functions

nk_bilinear_*_best× 4Bilinear form between vectors a and b under metric tensor C.

curved.h:76 ↗

nk_status_t nk_bilinear_f64_best(
    nk_f64_t const *a,
    nk_f64_t const *b,
    nk_f64_t const *c,
    nk_size_t n,
    nk_f64_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);

Symbol	`a, b, c`	`result`	Backends
`nk_bilinear_f64_best`	`nk_f64_t`	`nk_f64_t`	6
`nk_bilinear_f32_best`	`nk_f32_t`	`nk_f64_t`	6
`nk_bilinear_f16_best`	`nk_f16_t`	`nk_f32_t`	4
`nk_bilinear_bf16_best`	`nk_bf16_t`	`nk_f32_t`	5

Backends

nk_bilinear_f64serialneonsmef64haswellskylakervv
nk_bilinear_f32serialneonsmef64haswellskylakervv
nk_bilinear_f16serialneonhaswellrvv
nk_bilinear_bf16serialneonbfdothaswellgenoarvv

Computes aᵀ × C × b = Σᵢ Σⱼ aᵢ × cᵢⱼ × bⱼ

Parameters

`a`	in	The first vector.
`b`	in	The second vector.
`c`	in	The metric tensor or covariance matrix, stored row-major as an n × n matrix.
`n`	in	The number of dimensions in the vectors.
`result`	out	The output bilinear form value.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Notes

The output value can be negative.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_mahalanobis_*_best× 4Mahalanobis distance between vectors a and b under metric tensor C.

curved.h:110 ↗

nk_status_t nk_mahalanobis_f64_best(
    nk_f64_t const *a,
    nk_f64_t const *b,
    nk_f64_t const *c,
    nk_size_t n,
    nk_f64_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);

Symbol	`a, b, c`	`result`	Backends
`nk_mahalanobis_f64_best`	`nk_f64_t`	`nk_f64_t`	6
`nk_mahalanobis_f32_best`	`nk_f32_t`	`nk_f64_t`	6
`nk_mahalanobis_f16_best`	`nk_f16_t`	`nk_f32_t`	4
`nk_mahalanobis_bf16_best`	`nk_bf16_t`	`nk_f32_t`	5

Backends

nk_mahalanobis_f64serialneonsmef64haswellskylakervv
nk_mahalanobis_f32serialneonsmef64haswellskylakervv
nk_mahalanobis_f16serialneonhaswellrvv
nk_mahalanobis_bf16serialneonbfdothaswellgenoarvv

Computes √((a-b)ᵀ × C × (a-b)) = √(Σᵢ Σⱼ (aᵢ-bᵢ) × cᵢⱼ × (aⱼ-bⱼ))

Parameters

`a`	in	The first vector.
`b`	in	The second vector.
`c`	in	The Positive Semi-Definite (PSD) matrix, stored row-major as an n × n matrix.
`n`	in	The number of dimensions in the vectors.
`result`	out	The output distance value.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Notes

The output value is non-negative when C is PSD.
The output value is zero if and only if the two vectors are identical.
The matrix C must be positive semi-definite. If C is not PSD, the quadratic form (a-b)ᵀ C (a-b) may be negative, and the square root will produce NaN.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_bilinear_*_best× 4Complex bilinear form between vectors a and b under metric tensor C.

curved.h:137 ↗

nk_status_t nk_bilinear_f64c_best(
    nk_f64c_t const *a,
    nk_f64c_t const *b,
    nk_f64c_t const *c,
    nk_size_t n,
    nk_f64c_t *results,
    nk_capability_t capabilities,
    nk_stream_t stream);

Symbol	`a, b, c`	`results`	Backends
`nk_bilinear_f64c_best`	`nk_f64c_t`	`nk_f64c_t`	3
`nk_bilinear_f32c_best`	`nk_f32c_t`	`nk_f64c_t`	4
`nk_bilinear_f16c_best`	`nk_f16c_t`	`nk_f32c_t`	2
`nk_bilinear_bf16c_best`	`nk_bf16c_t`	`nk_f32c_t`	3

Backends

nk_bilinear_f64cserialsmef64skylake
nk_bilinear_f32cserialneonsmef64skylake
nk_bilinear_f16cserialneon
nk_bilinear_bf16cserialneonbfdotgenoa

Parameters

`a`	in	The first complex vector.
`b`	in	The second complex vector.
`c`	in	The complex metric tensor, stored row-major as an n × n matrix.
`n`	in	The number of dimensions in the vectors.
`results`	out	The output complex value with real and imaginary parts.
`capabilities`	in	One device's capabilities, like `nk_cpu_capabilities_enabled` reports.
`stream`	in	Null on the CPU, or the GPU stream of that device to queue on.

Statuses

nk_missing_kernel_k No capability in capabilities has it.

nk_bilinear_output_dtypeReturns the output dtype for bilinear forms.

curved.h:335 ↗

nk_dtype_t nk_bilinear_output_dtype(nk_dtype_t dtype);

nk_mahalanobis_output_dtypeReturns the output dtype for Mahalanobis metrics.

curved.h:350 ↗

nk_dtype_t nk_mahalanobis_output_dtype(nk_dtype_t dtype);

nk_bilinear_error_boundReturns the error bound of bilinear forms, per nk_accumulation_error_bound of their output.

curved.h:362 ↗

nk_f64_t nk_bilinear_error_bound(nk_dtype_t dtype);

nk_mahalanobis_error_boundReturns the error bound of Mahalanobis metrics, per nk_accumulation_error_bound of their output.

curved.h:368 ↗

nk_f64_t nk_mahalanobis_error_bound(nk_dtype_t dtype);

nk_curved_find_kernelFinds the curved kernel of kind for dtype, from the best of capabilities.

curved.h:384 ↗

nk_status_t nk_curved_find_kernel(
    nk_kernel_kind_t kind,
    nk_dtype_t dtype,
    nk_capability_t capabilities,
    nk_kernel_punned_t *kernel,
    nk_capability_t *capability);

Parameters

`kind`	in	The verb whose kernel to find.
`dtype`	in	The input type the kernel reads.
`capabilities`	in	The mask to pick the best capability from.
`kernel`	out	The kernel, or null when no capability in `capabilities` has it.
`capability`	out	The capability the kernel belongs to, or zero.

Statuses

nk_missing_kernel_k
nk_missing_library_k Header-only.