advantage.h
advantage/advantage.h · 57 line(s) · c
/*
* advantage.h - Public interface for the advantage module.
*
* Provides a small C-callable API for computing a weighted "advantage"
* score and a reduction over a series of samples. Safe to include from
* both C and C++ translation units.
*/
#ifndef ADVANTAGE_H
#define ADVANTAGE_H
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
* Compute a single advantage value: the reward discounted toward a
* baseline. advantage = reward - baseline, scaled by weight.
*/
double advantage_value(double reward, double baseline, double weight);
/*
* Compute the mean advantage over `count` samples. `rewards` and
* `baselines` must each point to `count` doubles. Returns 0.0 when
* count is 0 or either pointer is NULL.
*/
double advantage_mean(const double *rewards,
const double *baselines,
size_t count,
double weight);
/*
* Sample standard deviation of the per-sample advantage (weight applied).
* Measures how consistent the advantage is. Returns 0.0 when count < 2 or
* either pointer is NULL (spread is unknowable from fewer than two samples).
*/
double advantage_stddev(const double *rewards,
const double *baselines,
size_t count,
double weight);
/*
* Confidence in [0, 1) that a mean over `count` samples deserves trust:
* count / (count + prior). A few observations earn little confidence; many
* earn nearly full confidence. `prior` is the number of observations at
* which confidence is exactly one half. Returns 0.0 when count is 0, and 1.0
* for any count > 0 if prior <= 0 (no skepticism requested).
*/
double advantage_confidence(size_t count, double prior);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* ADVANTAGE_H */