{-# OPTIONS_HADDOCK prune #-}
{-# LANGUAGE BangPatterns #-}

-- |
-- Module: Numeric.Eproc.Common
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- Shared vocabulary for the eproc tests: the predictable bettor
-- strategies, the test verdict type, and the configuration-error
-- type. Re-exported from each test module
-- ("Numeric.Eproc.Bounded", "Numeric.Eproc.Paired",
-- "Numeric.Eproc.Bernoulli"); import this module directly only if
-- you need the types without picking a particular test.
--
-- The 'BetState' type and its helpers are internal to the library:
-- they are exposed here so that 'Numeric.Eproc.Bounded' and
-- 'Numeric.Eproc.Bernoulli' can share one implementation, not for
-- direct use.

module Numeric.Eproc.Common (
    Bettor(..)
  , Verdict(..)
  , ConfigError(..)

  -- * Internal: shared bettor state
  , BetState(..)
  , init_bet
  , bet_lambda
  , step_bet

  -- * Internal: helpers
  , finite
  , log_sum_exp
  , log_sum_exps
  , log2_dbl
  ) where

import qualified Data.List as L
import GHC.Float (log1p)

-- | A predictable bettor.
--
--   A bettor describes how, given the history of centred
--   observations @z_t@ (each test module specifies its own centring;
--   see the per-module documentation), the next predictable bet
--   @lambda_t@ is chosen. Predictability -- that is, @lambda_t@
--   depends only on data observed strictly before step @t@ -- is
--   what makes the resulting wealth process a nonnegative
--   supermartingale under @H_0@.
--
--   All three bettors enforce a safe-bet ceiling @lambda_max@
--   derived from the test's admissible-observation range by clipping
--   @lambda@ to @[0, lambda_max]@; this keeps the per-step wealth
--   factor nonnegative.
--
--   * 'Fixed' bets the supplied constant @lambda@ (clipped to
--     @[0, lambda_max]@). The wager does not respond to observed
--     data; this strategy is useful only as a baseline.
--
--   * 'Adaptive' is the aGRAPA (approximate growth-rate adaptive
--     predictable plug-in) bettor of Waudby-Smith & Ramdas (2024).
--     It tracks the empirical mean @mu@ and variance @sigma^2@ of
--     centred observations and bets the Kelly-optimal plug-in
--     @lambda* = mu \/ (sigma^2 + mu^2)@ clipped to
--     @[0, lambda_max]@. Fast to compute and competitive in
--     practice.
--
--   * 'Newton' is the online Newton step (ONS) bettor of
--     Waudby-Smith & Ramdas (2024, Algorithm 2). The per-step
--     log-wealth loss @-log(1 + lambda * z)@ is convex in @lambda@;
--     ONS performs one Newton step per observation, accumulating
--     squared gradients to scale the update by a fixed learning
--     rate @2 \/ (2 - log 3)@. Achieves logarithmic regret against
--     the best constant bet in hindsight and is in practice the
--     strongest of the three bettors under most signal regimes.
--
--     One deliberate deviation from WSR: Algorithm 2 seeds the
--     squared-gradient accumulator at @1@, which presumes
--     observations scaled to @[0, 1]@. On raw-scale data that
--     constant is dimensionally wrong -- negligible when
--     @z^2 >> 1@, paralysing when @z^2 << 1@ -- so the accumulator
--     here is instead seeded near zero, making the update
--     scale-adaptive. The trade is bold early play: the first
--     nonzero observation typically drives the bet straight to
--     the @lambda_max@ ceiling, annealing back toward the Kelly
--     point as gradients accumulate. Validity is unaffected --
--     predictability and clipping are all it needs -- and regret
--     stays logarithmic with a somewhat larger constant. The
--     visible effect is higher-variance early wealth: a supremum
--     modestly above its floor is expected even under @H_0@.
data Bettor =
    Fixed {-# UNPACK #-} !Double
  | Adaptive
  | Newton
  deriving (Bettor -> Bettor -> Bool
(Bettor -> Bettor -> Bool)
-> (Bettor -> Bettor -> Bool) -> Eq Bettor
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Bettor -> Bettor -> Bool
== :: Bettor -> Bettor -> Bool
$c/= :: Bettor -> Bettor -> Bool
/= :: Bettor -> Bettor -> Bool
Eq, Int -> Bettor -> ShowS
[Bettor] -> ShowS
Bettor -> String
(Int -> Bettor -> ShowS)
-> (Bettor -> String) -> ([Bettor] -> ShowS) -> Show Bettor
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Bettor -> ShowS
showsPrec :: Int -> Bettor -> ShowS
$cshow :: Bettor -> String
show :: Bettor -> String
$cshowList :: [Bettor] -> ShowS
showList :: [Bettor] -> ShowS
Show)

-- | Test outcome at the current sample count.
--
--   'Reject' means the wealth process has /ever/ crossed the
--   rejection threshold, so @H_0@ is rejected at level @alpha@.
--   Once a state has rejected it stays rejected, even if subsequent
--   observations drive the current wealth back below threshold;
--   this is the supremum-style guarantee that Ville's inequality
--   actually delivers. 'Continue' means there is not yet enough
--   evidence; collect more samples (or stop and report no
--   rejection -- the type-I error guarantee holds for /any/
--   stopping rule).
data Verdict =
    Reject
  | Continue
  deriving (Verdict -> Verdict -> Bool
(Verdict -> Verdict -> Bool)
-> (Verdict -> Verdict -> Bool) -> Eq Verdict
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Verdict -> Verdict -> Bool
== :: Verdict -> Verdict -> Bool
$c/= :: Verdict -> Verdict -> Bool
/= :: Verdict -> Verdict -> Bool
Eq, Int -> Verdict -> ShowS
[Verdict] -> ShowS
Verdict -> String
(Int -> Verdict -> ShowS)
-> (Verdict -> String) -> ([Verdict] -> ShowS) -> Show Verdict
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Verdict -> ShowS
showsPrec :: Int -> Verdict -> ShowS
$cshow :: Verdict -> String
show :: Verdict -> String
$cshowList :: [Verdict] -> ShowS
showList :: [Verdict] -> ShowS
Show)

-- | Reasons that a test-configuration smart constructor can reject
--   its inputs. Returned by 'Numeric.Eproc.Bounded.config',
--   'Numeric.Eproc.Bounded.configInterval',
--   'Numeric.Eproc.Bernoulli.config',
--   'Numeric.Eproc.Paired.config',
--   'Numeric.Eproc.Mixture.config', and
--   'Numeric.Eproc.ConfSeq.config'.
data ConfigError =
    -- | significance level outside @(0, 1)@
    InvalidAlpha {-# UNPACK #-} !Double
    -- | sample bounds violate @lo < hi@
  | InvalidBounds {-# UNPACK #-} !Double {-# UNPACK #-} !Double
    -- | null mean outside @(lo, hi)@ (strict, to avoid div-by-zero
    --   in the safe-bet ceilings)
  | InvalidNullMean
      {-# UNPACK #-} !Double  -- m
      {-# UNPACK #-} !Double  -- lo
      {-# UNPACK #-} !Double  -- hi
    -- | null-interval endpoints violate @lo < m_lo <= m_hi < hi@
    --   (strict at the sample bounds, to avoid div-by-zero in the
    --   safe-bet ceilings)
  | InvalidNullInterval
      {-# UNPACK #-} !Double  -- m_lo
      {-# UNPACK #-} !Double  -- m_hi
      {-# UNPACK #-} !Double  -- lo
      {-# UNPACK #-} !Double  -- hi
    -- | baseline rate outside @(0, 1)@
  | InvalidBaselineRate {-# UNPACK #-} !Double
    -- | component count not positive
  | InvalidComponentCount {-# UNPACK #-} !Int
    -- | grid size below @1@
  | InvalidGridSize {-# UNPACK #-} !Int
  deriving (ConfigError -> ConfigError -> Bool
(ConfigError -> ConfigError -> Bool)
-> (ConfigError -> ConfigError -> Bool) -> Eq ConfigError
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: ConfigError -> ConfigError -> Bool
== :: ConfigError -> ConfigError -> Bool
$c/= :: ConfigError -> ConfigError -> Bool
/= :: ConfigError -> ConfigError -> Bool
Eq, Int -> ConfigError -> ShowS
[ConfigError] -> ShowS
ConfigError -> String
(Int -> ConfigError -> ShowS)
-> (ConfigError -> String)
-> ([ConfigError] -> ShowS)
-> Show ConfigError
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> ConfigError -> ShowS
showsPrec :: Int -> ConfigError -> ShowS
$cshow :: ConfigError -> String
show :: ConfigError -> String
$cshowList :: [ConfigError] -> ShowS
showList :: [ConfigError] -> ShowS
Show)

-- | True iff the argument is a finite IEEE-754 double (not NaN, not
--   @+\/-Infinity@). Used by the @config@ smart constructors to keep
--   the bounded-random-variable promise honest.
finite :: Double -> Bool
finite :: Double -> Bool
finite Double
x = Bool -> Bool
not (Double -> Bool
forall a. RealFloat a => a -> Bool
isNaN Double
x) Bool -> Bool -> Bool
&& Bool -> Bool
not (Double -> Bool
forall a. RealFloat a => a -> Bool
isInfinite Double
x)
{-# INLINE finite #-}

-- | @log(exp a + exp b)@, computed without intermediate overflow.
--   Used by the convex-hedge two-sided combinations to update the
--   running @log(K^+ + K^-)@ statistic from the two per-direction
--   log-wealths.
log_sum_exp :: Double -> Double -> Double
log_sum_exp :: Double -> Double -> Double
log_sum_exp !Double
a !Double
b
  | Double
a Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
>= Double
b    = Double
a Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
log1p (Double -> Double
forall a. Floating a => a -> a
exp (Double
b Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
a))
  | Bool
otherwise = Double
b Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
log1p (Double -> Double
forall a. Floating a => a -> a
exp (Double
a Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
b))
{-# INLINE log_sum_exp #-}

-- | The log of a sum of exponentials, of values given as logs:
--   stable against overflow, @+Infinity@ where a term is, and
--   @-Infinity@ of no terms or of terms all @-Infinity@. The sum
--   'Numeric.Eproc.Mixture' latches and 'Numeric.Eproc.Merge'
--   averages.
log_sum_exps :: [Double] -> Double
log_sum_exps :: [Double] -> Double
log_sum_exps [Double]
les = case [Double]
les of
  [] -> Double -> Double
forall a. Num a => a -> a
negate (Double
1 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
0)
  (Double
l : [Double]
ls) ->
    let !m :: Double
m = (Double -> Double -> Double) -> Double -> [Double] -> Double
forall b a. (b -> a -> b) -> b -> [a] -> b
forall (t :: * -> *) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
L.foldl' Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
l [Double]
ls
    in  if Double -> Bool
forall a. RealFloat a => a -> Bool
isInfinite Double
m
          then Double
m
          else Double
m Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
log ((Double -> Double -> Double) -> Double -> [Double] -> Double
forall b a. (b -> a -> b) -> b -> [a] -> b
forall (t :: * -> *) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
L.foldl' (\ !Double
acc Double
v -> Double
acc Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
exp (Double
v Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
m)) Double
0 [Double]
les)
{-# INLINE log_sum_exps #-}

-- | @log 2@ as a shared constant. Used both as the initial value of
--   the two-sided running sup-log-sum (since @K^+_0 + K^-_0 = 2@) and
--   as the tight upper-bound slack in the fast-path skip inside
--   'Numeric.Eproc.Bounded.update' /
--   'Numeric.Eproc.Bernoulli.TwoSided.update'.
log2_dbl :: Double
log2_dbl :: Double
log2_dbl = Double -> Double
forall a. Floating a => a -> a
log Double
2
{-# INLINE log2_dbl #-}

-- | Per-bettor state. One constructor per 'Bettor' alternative; the
--   constructor used in any given state matches the 'Bettor' chosen
--   in the enclosing 'Config'.
--
--   Internal: exposed only so that the per-test 'State' types in
--   "Numeric.Eproc.Bounded" and "Numeric.Eproc.Bernoulli" can share
--   one implementation.
data BetState =
    SFixed
  | SAdaptive
      {-# UNPACK #-} !Double  -- sum of z (centred observation)
      {-# UNPACK #-} !Double  -- sum of z^2 (for online variance)
      {-# UNPACK #-} !Int     -- count
  | SNewton
      {-# UNPACK #-} !Double  -- current bet lambda
      {-# UNPACK #-} !Double  -- running sum of per-step squared gradients

-- | Per-bettor initial state.
init_bet :: Bettor -> BetState
init_bet :: Bettor -> BetState
init_bet Bettor
b = case Bettor
b of
  Fixed Double
_  -> BetState
SFixed
  Bettor
Adaptive -> Double -> Double -> Int -> BetState
SAdaptive Double
0 Double
0 Int
0
  Bettor
Newton   -> Double -> Double -> BetState
SNewton Double
0 Double
1.0e-6  -- small acc seed avoids div-by-zero
{-# INLINE init_bet #-}

-- | WSR (2024) Algorithm 2 ONS learning rate, @2 \/ (2 - log 3)@.
ons_lr :: Double
ons_lr :: Double
ons_lr = Double
2 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ (Double
2 Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double -> Double
forall a. Floating a => a -> a
log Double
3)
{-# INLINE ons_lr #-}

-- | Compute the next bet 'lambda' from the bettor and its current
--   state; 'lam_max' is the direction-specific safety bound. All
--   strategies clip the result to @[0, lam_max]@ so the wealth
--   factor stays nonnegative.
bet_lambda :: Bettor -> Double -> BetState -> Double
bet_lambda :: Bettor -> Double -> BetState -> Double
bet_lambda Bettor
b !Double
lam_max !BetState
s = case Bettor
b of
  Fixed Double
lam -> Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
0 (Double -> Double -> Double
forall a. Ord a => a -> a -> a
min Double
lam_max Double
lam)
  Bettor
Adaptive -> case BetState
s of
    SAdaptive !Double
sm !Double
sm2 !Int
n
      | Int
n Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Int
0    -> Double
0
      | Bool
otherwise ->
          let !nd :: Double
nd  = Int -> Double
forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
n
              !mu :: Double
mu  = Double
sm Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
nd
              !mu2 :: Double
mu2 = Double
mu Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
mu
              !var :: Double
var = Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
0 (Double
sm2 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
nd Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
mu2)
              !den :: Double
den = Double
var Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
mu2
              !raw :: Double
raw = if Double
den Double -> Double -> Bool
forall a. Eq a => a -> a -> Bool
== Double
0 then Double
0 else Double
mu Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
den
          in  Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
0 (Double -> Double -> Double
forall a. Ord a => a -> a -> a
min Double
lam_max Double
raw)
    BetState
_ -> Double
0
  Bettor
Newton -> case BetState
s of
    SNewton !Double
lam Double
_ -> Double
lam
    BetState
_              -> Double
0
{-# INLINE bet_lambda #-}

-- | Update bettor state with newly observed centred value 'z'. For
--   'Adaptive' this is just accumulating sums; for 'Newton' we take
--   one online Newton step (with the WSR learning rate) on the
--   per-step log-wealth loss @-log(1 + lambda * z)@, accumulating
--   squared gradients for adaptive scaling.
step_bet :: Bettor -> Double -> BetState -> Double -> BetState
step_bet :: Bettor -> Double -> BetState -> Double -> BetState
step_bet Bettor
b !Double
lam_max !BetState
s !Double
z = case Bettor
b of
  Fixed Double
_ -> BetState
SFixed
  Bettor
Adaptive -> case BetState
s of
    SAdaptive !Double
sm !Double
sm2 !Int
n -> Double -> Double -> Int -> BetState
SAdaptive (Double
sm Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
z) (Double
sm2 Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
z Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
z) (Int
n Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1)
    BetState
_                     -> Double -> Double -> Int -> BetState
SAdaptive Double
z (Double
z Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
z) Int
1
  Bettor
Newton -> case BetState
s of
    SNewton !Double
lam !Double
acc ->
      let !denom :: Double
denom = Double
1 Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
lam Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
z
          !g :: Double
g     = if Double
denom Double -> Double -> Bool
forall a. Eq a => a -> a -> Bool
== Double
0 then Double
0 else Double -> Double
forall a. Num a => a -> a
negate Double
z Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
denom
          !acc' :: Double
acc'  = Double
acc Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
g Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
g
          !lam' :: Double
lam'  = Double
lam Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
ons_lr Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
g Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
acc'
          !clp :: Double
clp   = Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
0 (Double -> Double -> Double
forall a. Ord a => a -> a -> a
min Double
lam_max Double
lam')
      in  Double -> Double -> BetState
SNewton Double
clp Double
acc'
    BetState
_ -> Double -> Double -> BetState
SNewton Double
0 Double
1.0e-6
{-# INLINE step_bet #-}