C · Probability Metrics

Probability Metrics

#include <numkong/probability.h> 8.0.0-rc.1 · b1f866ab

Probability kernels target divergences directly instead of making you rebuild them from scalar loops.

nk_f32_t p[] = {0.2f, 0.3f, 0.5f}, q[] = {0.1f, 0.3f, 0.6f};
nk_f64_t kl_forward = 0, kl_reverse = 0, js_forward = 0, js_reverse = 0;

nk_kld_f32_best(p, q, 3, &kl_forward, capabilities, NULL);
nk_kld_f32_best(q, p, 3, &kl_reverse, capabilities, NULL);
assert(kl_forward != kl_reverse && "KLD is asymmetric");

nk_jsd_f32_best(p, q, 3, &js_forward, capabilities, NULL);
nk_jsd_f32_best(q, p, 3, &js_reverse, capabilities, NULL);
assert(js_forward == js_reverse && "JSD is symmetric");

These paths are useful once you move below f64. Naive implementations are usually dominated by repeated scalar transcendental calls and weak accumulation policy.

API

Functions

nk_kld_*_best× 4Kullback-Leibler divergence between two discrete probability distributions.
probability.h:100 ↗
nk_status_t nk_kld_f16_best(
    nk_f16_t const *a,
    nk_f16_t const *b,
    nk_size_t n,
    nk_f32_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);
Symbola, bresultBackends
nk_kld_f16_bestnk_f16_tnk_f32_t5
nk_kld_bf16_bestnk_bf16_tnk_f32_t2
nk_kld_f32_bestnk_f32_tnk_f64_t5
nk_kld_f64_bestnk_f64_tnk_f64_t5

Backends

  • nk_kld_f16serialneonhaswellskylakervv
  • nk_kld_bf16serialrvv
  • nk_kld_f32serialneonhaswellskylakervv
  • nk_kld_f64serialneonhaswellskylakervv

Parameters

ainThe first discrete probability distribution.
binThe second discrete probability distribution.
ninThe number of elements in the distributions.
resultoutThe output divergence value.
capabilitiesinOne device's capabilities, like nk_cpu_capabilities_enabled reports.
streaminNull on the CPU, or the GPU stream of that device to queue on.

Notes

  • The distributions are assumed to be normalized.
  • The output divergence value is non-negative.
  • The output divergence value is zero if and only if the two distributions are identical.

Statuses

nk_jsd_*_best× 4Jensen-Shannon distance between two discrete probability distributions.
probability.h:184 ↗
nk_status_t nk_jsd_f16_best(
    nk_f16_t const *a,
    nk_f16_t const *b,
    nk_size_t n,
    nk_f32_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);
Symbola, bresultBackends
nk_jsd_f16_bestnk_f16_tnk_f32_t5
nk_jsd_bf16_bestnk_bf16_tnk_f32_t2
nk_jsd_f32_bestnk_f32_tnk_f64_t5
nk_jsd_f64_bestnk_f64_tnk_f64_t5

Backends

  • nk_jsd_f16serialneonhaswellskylakervv
  • nk_jsd_bf16serialrvv
  • nk_jsd_f32serialneonhaswellskylakervv
  • nk_jsd_f64serialneonhaswellskylakervv

Parameters

ainThe first discrete probability distribution.
binThe second discrete probability distribution.
ninThe number of elements in the distributions.
resultoutThe output distance value.
capabilitiesinOne device's capabilities, like nk_cpu_capabilities_enabled reports.
streaminNull on the CPU, or the GPU stream of that device to queue on.

Notes

  • The distributions are assumed to be normalized.
  • The output distance value is non-negative.
  • The output distance value is zero if and only if the two distributions are identical.

Statuses

nk_probability_output_dtypeReturns the output dtype for probability measures (KLD, JSD).
probability.h:366 ↗
nk_dtype_t nk_probability_output_dtype(nk_dtype_t dtype);
nk_probability_term_dtypeReturns the type the ratio and logarithm of every term are computed in.
probability.h:377 ↗
nk_dtype_t nk_probability_term_dtype(nk_dtype_t dtype);
nk_probability_error_boundReturns the error bound of divergences, per nk_accumulation_error_bound of their terms.
probability.h:388 ↗
nk_f64_t nk_probability_error_bound(nk_dtype_t dtype);
nk_probability_find_kernelFinds the probability kernel of kind for dtype, from the best of capabilities.
probability.h:404 ↗
nk_status_t nk_probability_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

kindinThe verb whose kernel to find.
dtypeinThe input type the kernel reads.
capabilitiesinThe mask to pick the best capability from.
kerneloutThe kernel, or null when no capability in capabilities has it.
capabilityoutThe capability the kernel belongs to, or zero.

Statuses