Skip to main content

sinistra_core/
lib.rs

1//! # sinistra-core
2//!
3//! Core simulation logic for a **drift-diffusion model** (DDM), the standard
4//! sequential-sampling model of two-alternative forced-choice decisions in
5//! cognitive science.
6//!
7//! A single decision is modelled as a one-dimensional diffusion process
8//! `x(t)` that starts between two absorbing boundaries and drifts until it
9//! hits one of them:
10//!
11//! ```text
12//!   x = boundary_separation   ── "upper" response
13//!   x = start * boundary_sep  ── initial value
14//!   x = 0                     ── "lower" response
15//! ```
16//!
17//! The process is integrated with the **Euler–Maruyama** scheme at a fixed
18//! step `dt` = [`DT`]:
19//!
20//! ```text
21//!   dx = drift_rate * dt + noise_sd * sqrt(dt) * N(0, 1)
22//! ```
23//!
24//! The reported response time is the elapsed *simulated* time plus a fixed
25//! `non_decision_time` offset (encoding + motor latency).
26//!
27//! ## The simulation-time cap
28//!
29//! Pathological parameters (e.g. zero drift with tiny noise, or a boundary
30//! far from the start) can make an individual trial take arbitrarily long to
31//! terminate. To keep every call bounded, a trial is force-terminated once
32//! its *simulated* time reaches [`MAX_SIM_TIME`] (10 s), **before** the
33//! non-decision offset is added. On a forced termination the response is
34//! attributed to whichever boundary the process is nearer to (see
35//! [`simulate_trial`]). With well-behaved parameters this cap is never
36//! reached; if you see response times clustered exactly at
37//! `MAX_SIM_TIME + non_decision_time`, your parameters are degenerate.
38
39use argmin::core::{CostFunction, Error as ArgminError, Executor, State};
40use argmin::solver::neldermead::NelderMead;
41use rand::{Rng, SeedableRng};
42use rand_chacha::ChaCha8Rng;
43use rand_distr::StandardNormal;
44use rayon::prelude::*;
45
46/// Fixed Euler–Maruyama integration step, in seconds.
47pub const DT: f64 = 0.001;
48
49/// Hard cap on *simulated* decision time, in seconds.
50///
51/// A trial that has not hit a boundary after this much simulated time is
52/// force-terminated. The cap guards against non-terminating loops on
53/// degenerate parameters. See the crate-level docs for details.
54pub const MAX_SIM_TIME: f64 = 10.0;
55
56/// Parameters of a drift-diffusion model.
57#[derive(Debug, Clone, PartialEq)]
58pub struct Params {
59    /// Mean rate of evidence accumulation (units of `x` per second).
60    /// Positive values pull the process toward the upper boundary.
61    pub drift_rate: f64,
62    /// Distance between the two absorbing boundaries (`> 0`).
63    pub boundary_separation: f64,
64    /// Starting point as a fraction of `boundary_separation`, in `[0, 1]`.
65    /// `0.5` is unbiased; larger values start nearer the upper boundary.
66    pub starting_point: f64,
67    /// Non-decision time (encoding + motor latency), in seconds, added to
68    /// every response time.
69    pub non_decision_time: f64,
70    /// Standard deviation of the within-trial noise. Conventionally fixed at
71    /// `1.0`, which is the value produced by [`Params::new`] and
72    /// [`Params::default`].
73    pub noise_sd: f64,
74}
75
76impl Default for Params {
77    fn default() -> Self {
78        Self {
79            drift_rate: 0.0,
80            boundary_separation: 1.0,
81            starting_point: 0.5,
82            non_decision_time: 0.0,
83            noise_sd: 1.0,
84        }
85    }
86}
87
88impl Params {
89    /// Construct parameters with the conventional `noise_sd = 1.0`.
90    pub fn new(
91        drift_rate: f64,
92        boundary_separation: f64,
93        starting_point: f64,
94        non_decision_time: f64,
95    ) -> Self {
96        Self {
97            drift_rate,
98            boundary_separation,
99            starting_point,
100            non_decision_time,
101            noise_sd: 1.0,
102        }
103    }
104
105    /// Builder-style override of [`Params::noise_sd`].
106    #[must_use]
107    pub fn with_noise_sd(mut self, noise_sd: f64) -> Self {
108        self.noise_sd = noise_sd;
109        self
110    }
111}
112
113/// The outcome of a single simulated decision.
114#[derive(Debug, Clone, Copy, PartialEq)]
115pub struct Trial {
116    /// `true` if the process terminated at the upper boundary, `false` for
117    /// the lower boundary. On a [`MAX_SIM_TIME`] timeout this holds the
118    /// nearer boundary (see [`simulate_trial`]).
119    pub upper_boundary: bool,
120    /// Response time in seconds: simulated decision time plus
121    /// `non_decision_time`.
122    pub rt: f64,
123    /// `true` if the trial was force-terminated at the [`MAX_SIM_TIME`]
124    /// cutoff rather than by a genuine boundary crossing. Such trials have
125    /// an unreliable `rt` and `upper_boundary` and should be excluded from
126    /// downstream estimation (e.g. [`ez_diffusion`] drops them).
127    pub timed_out: bool,
128}
129
130/// Simulate one trial of the diffusion process with Euler–Maruyama steps.
131///
132/// The process starts at `starting_point * boundary_separation` and is
133/// stepped with `dt = `[`DT`] until it crosses `0` or `boundary_separation`,
134/// or until simulated time reaches [`MAX_SIM_TIME`].
135///
136/// Boundary attribution uses the midpoint test `x >= boundary_separation / 2`:
137///
138/// * On normal termination `x` has already crossed a boundary, so the test
139///   selects the boundary that was actually crossed.
140/// * On a [`MAX_SIM_TIME`] timeout `x` is still strictly inside the interval,
141///   and the test attributes the response to the nearer boundary. Such a
142///   trial is flagged with [`Trial::timed_out`]` == true`.
143///
144/// `non_decision_time` is added to the elapsed simulated time to form
145/// [`Trial::rt`].
146pub fn simulate_trial(params: &Params, rng: &mut impl Rng) -> Trial {
147    let sqrt_dt = DT.sqrt();
148    let boundary = params.boundary_separation;
149    let mut x = params.starting_point * boundary;
150    let mut t = 0.0_f64;
151
152    while x > 0.0 && x < boundary && t < MAX_SIM_TIME {
153        let z: f64 = rng.sample(StandardNormal);
154        x += params.drift_rate * DT + params.noise_sd * sqrt_dt * z;
155        t += DT;
156    }
157
158    // If the process is still strictly inside the interval, the loop can only
159    // have exited on the time cap.
160    let timed_out = x > 0.0 && x < boundary;
161
162    Trial {
163        upper_boundary: x >= 0.5 * boundary,
164        rt: t + params.non_decision_time,
165        timed_out,
166    }
167}
168
169/// Simulate `n` independent trials in parallel with [`rayon`].
170///
171/// # Determinism
172///
173/// The result is a deterministic function of `(params, n, seed)` and does
174/// **not** depend on the number of worker threads or on scheduling order.
175///
176/// Each trial `i` gets its own [`ChaCha8Rng`] seeded from `seed` and then
177/// switched to cipher **stream** `i` via `set_stream`. ChaCha's streams are
178/// disjoint, non-overlapping keystreams of length `2^64` blocks each, so
179/// every trial draws from an independent, reproducible random sequence that
180/// is fixed by `(seed, i)` alone. Results are collected through rayon's
181/// order-preserving indexed collect, so `trials[i]` always corresponds to
182/// trial index `i`.
183pub fn simulate_n(params: &Params, n: usize, seed: u64) -> Vec<Trial> {
184    (0..n as u64)
185        .into_par_iter()
186        .map(|i| {
187            let mut rng = ChaCha8Rng::seed_from_u64(seed);
188            rng.set_stream(i);
189            simulate_trial(params, &mut rng)
190        })
191        .collect()
192}
193
194/// The three summary statistics both estimators ([`ez_diffusion`],
195/// [`fit_simulation`]) reduce a data set to. Computed by [`summary_stats`].
196#[derive(Debug, Clone, Copy, PartialEq)]
197pub struct SummaryStats {
198    /// `Pc`: proportion of usable trials that hit the **upper** boundary
199    /// (treated as the "correct" response).
200    pub accuracy: f64,
201    /// `MRT`: mean RT, in seconds, of the upper-boundary ("correct") trials.
202    pub mean_rt: f64,
203    /// `VRT`: sample variance (`/(m-1)`) of the upper-boundary trials' RT.
204    pub var_rt: f64,
205    /// Number of trials that were not timed out (the denominator of `accuracy`).
206    pub n_usable: usize,
207    /// Number of upper-boundary trials (the sample behind `mean_rt`/`var_rt`).
208    pub n_correct: usize,
209}
210
211/// Reduce choice-RT data to the `(Pc, MRT, VRT)` triple used by every
212/// estimator in this crate. This is the single source of truth for those
213/// statistics.
214///
215/// * Timed-out trials ([`Trial::timed_out`]) are excluded entirely.
216/// * `accuracy` is over all remaining ("usable") trials.
217/// * `mean_rt` and `var_rt` are over the **upper-boundary** trials only, per
218///   the EZ-diffusion convention (Wagenmakers et al., 2007). For the unbiased
219///   model the correct- and error-RT distributions coincide, so this is not a
220///   modelling choice so much as a convention; it does make the RT moments
221///   noisier when the upper boundary is the minority response.
222///
223/// Returns `None` when the statistics are undefined: no usable trials, or
224/// fewer than two upper-boundary trials (so the sample variance has no
225/// denominator).
226pub fn summary_stats(trials: &[Trial]) -> Option<SummaryStats> {
227    let n_usable = trials.iter().filter(|t| !t.timed_out).count();
228    if n_usable == 0 {
229        return None;
230    }
231
232    let correct_rts: Vec<f64> = trials
233        .iter()
234        .filter(|t| !t.timed_out && t.upper_boundary)
235        .map(|t| t.rt)
236        .collect();
237    let n_correct = correct_rts.len();
238    if n_correct < 2 {
239        return None;
240    }
241
242    let m = n_correct as f64;
243    let mean_rt = correct_rts.iter().sum::<f64>() / m;
244    let var_rt = correct_rts
245        .iter()
246        .map(|rt| (rt - mean_rt).powi(2))
247        .sum::<f64>()
248        / (m - 1.0);
249
250    Some(SummaryStats {
251        accuracy: n_correct as f64 / n_usable as f64,
252        mean_rt,
253        var_rt,
254        n_usable,
255        n_correct,
256    })
257}
258
259/// Scaling parameter (within-trial noise SD) assumed by [`ez_diffusion`] and
260/// [`fit_simulation`].
261///
262/// The EZ equations are invariant to the choice of `s` as long as it matches
263/// the data-generating process. This crate's simulator uses `noise_sd = 1.0`
264/// by default ([`Params::new`], [`Params::default`]), so the estimators assume
265/// the same. Wagenmakers et al. (2007) instead fix `s = 0.1`; recovered
266/// `drift_rate` and `boundary_separation` scale linearly with `s`.
267pub const EZ_SCALING_S: f64 = 1.0;
268
269/// Reasons [`ez_diffusion`] cannot return an estimate.
270#[derive(Debug, Clone, PartialEq, Eq)]
271pub enum EzError {
272    /// Fewer than two non-timed-out trials were supplied.
273    NotEnoughTrials(usize),
274    /// Fewer than two upper-boundary ("correct") trials, so mean and variance
275    /// of correct RT are undefined.
276    NotEnoughCorrect(usize),
277    /// Accuracy is exactly 0.5: `logit(Pc) = 0`, drift is not identifiable.
278    ChancePerformance,
279    /// The variance of correct RT is not positive.
280    NonPositiveVariance,
281    /// The EZ drift equation has no real solution for these statistics.
282    NoRealSolution,
283}
284
285impl std::fmt::Display for EzError {
286    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
287        match self {
288            EzError::NotEnoughTrials(n) => {
289                write!(f, "need >= 2 non-timed-out trials, got {n}")
290            }
291            EzError::NotEnoughCorrect(n) => {
292                write!(
293                    f,
294                    "need >= 2 upper-boundary trials for RT statistics, got {n}"
295                )
296            }
297            EzError::ChancePerformance => {
298                write!(f, "accuracy is exactly 0.5; drift rate is not identifiable")
299            }
300            EzError::NonPositiveVariance => {
301                write!(f, "variance of correct RT is not positive")
302            }
303            EzError::NoRealSolution => {
304                write!(
305                    f,
306                    "EZ drift equation has no real solution for these statistics"
307                )
308            }
309        }
310    }
311}
312
313impl std::error::Error for EzError {}
314
315/// Recover DDM parameters from choice-RT data with the **EZ-diffusion** method
316/// of Wagenmakers, van der Maas & Grasman (2007), *"An EZ-diffusion model for
317/// response time and accuracy"*, Psychonomic Bulletin & Review, 14(1), 3–22.
318///
319/// EZ inverts the closed-form Wiener first-passage equations for the
320/// *unbiased* diffusion model (start point fixed at `a/2`, no across-trial
321/// variability in drift, start, or non-decision time). It maps three summary
322/// statistics of the data onto three parameters:
323///
324/// | statistic | symbol | source |
325/// |-----------|--------|--------|
326/// | accuracy  | `Pc`   | proportion of trials hitting the **upper** boundary |
327/// | mean RT   | `MRT`  | mean RT of upper-boundary trials |
328/// | RT variance | `VRT` | sample variance (`/(m-1)`) of upper-boundary RT |
329///
330/// The upper boundary is treated as the "correct" response. For the unbiased
331/// model the correct and error RT distributions are identical, so restricting
332/// the RT moments to upper-boundary trials (as the paper specifies) matches
333/// the theory; it does, however, make the estimate noisier when the upper
334/// boundary is the minority response (drift rate far below zero).
335///
336/// # Formulas
337///
338/// With `s` = [`EZ_SCALING_S`], `s2 = s²`, and `L = logit(Pc) = ln(Pc/(1-Pc))`:
339///
340/// ```text
341///   v   = sign(Pc - 1/2) · s · ( L · (L·Pc² - L·Pc + Pc - 1/2) / VRT )^(1/4)   (Eq. 5)
342///   a   = s2 · L / v                                                           (Eq. 4)
343///   y   = -v·a / s2
344///   MDT = (a / 2v) · (1 - e^y) / (1 + e^y)                                      (Eq. 9)
345///   Ter = MRT - MDT                                                            (Eq. 8)
346/// ```
347///
348/// # Edge correction
349///
350/// `Pc` of exactly 0 or 1 has no EZ solution. Following the paper (p. 9,
351/// "Edge corrections"), it is nudged to `1/(2N)` or `1 - 1/(2N)` respectively,
352/// where `N` is the number of non-timed-out trials. `Pc == 0.5` exactly is
353/// returned as [`EzError::ChancePerformance`] rather than corrected, since the
354/// drift sign is then undefined.
355///
356/// # Returns
357///
358/// A [`Params`] with the recovered `drift_rate`, `boundary_separation` and
359/// `non_decision_time`; `starting_point` is set to `0.5` (the EZ assumption)
360/// and `noise_sd` to [`EZ_SCALING_S`]. Timed-out trials are excluded from all
361/// statistics.
362pub fn ez_diffusion(trials: &[Trial]) -> Result<Params, EzError> {
363    let n_usable = trials.iter().filter(|t| !t.timed_out).count();
364    if n_usable < 2 {
365        return Err(EzError::NotEnoughTrials(n_usable));
366    }
367
368    let stats = summary_stats(trials).ok_or_else(|| {
369        let n_correct = trials
370            .iter()
371            .filter(|t| !t.timed_out && t.upper_boundary)
372            .count();
373        EzError::NotEnoughCorrect(n_correct)
374    })?;
375
376    let mut pc = stats.accuracy;
377
378    // Edge correction (Wagenmakers et al., 2007, p. 9). `Pc == 0` cannot occur
379    // here: it would mean zero correct RTs, which `summary_stats` already
380    // rejects as `NotEnoughCorrect`.
381    if pc == 1.0 {
382        pc = 1.0 - 1.0 / (2.0 * n_usable as f64);
383    } else if pc == 0.5 {
384        return Err(EzError::ChancePerformance);
385    }
386
387    let mrt = stats.mean_rt;
388    let vrt = stats.var_rt;
389    if vrt.is_nan() || vrt <= 0.0 {
390        return Err(EzError::NonPositiveVariance);
391    }
392
393    let s = EZ_SCALING_S;
394    let s2 = s * s;
395    let l = (pc / (1.0 - pc)).ln();
396
397    // Eq. 5.
398    let bracket = l * (l * pc * pc - l * pc + pc - 0.5) / vrt;
399    if bracket.is_nan() || bracket < 0.0 {
400        return Err(EzError::NoRealSolution);
401    }
402    let v = (pc - 0.5).signum() * s * bracket.powf(0.25);
403
404    // Eq. 4.
405    let a = s2 * l / v;
406
407    // Eqs. 8-9.
408    let y = -v * a / s2;
409    let mdt = (a / (2.0 * v)) * ((1.0 - y.exp()) / (1.0 + y.exp()));
410    let ter = mrt - mdt;
411
412    Ok(Params {
413        drift_rate: v,
414        boundary_separation: a,
415        starting_point: 0.5,
416        non_decision_time: ter,
417        noise_sd: s,
418    })
419}
420
421// ---------------------------------------------------------------------------
422// Simulation-based fitter (Nelder–Mead over summary statistics)
423// ---------------------------------------------------------------------------
424
425/// Number of trials simulated per objective-function evaluation in
426/// [`fit_simulation`].
427///
428/// This is the main speed/accuracy knob. Each Nelder–Mead step evaluates the
429/// objective once or twice, and a fit takes ~150–300 evaluations, so the cost
430/// of a fit is roughly `250 * FIT_N_PER_EVAL` simulated trials.
431///
432/// * **Noise.** The objective compares simulated `(Pc, MRT, VRT)` against the
433///   data's. The per-evaluation Monte-Carlo error on those falls as
434///   `1/sqrt(n)`: at `n = 5000`, `SE(Pc) ≈ 0.006`, `SE(MRT)/MRT ≈ 0.5%`,
435///   `SE(VRT)/VRT ≈ 2–3%`. Because every evaluation reuses the same RNG seed
436///   (common random numbers, see [`fit_simulation`]), the objective is a
437///   *deterministic* surface and the noise that matters is its ruggedness, not
438///   the raw SE — 5000 is enough to keep the surface smooth enough for
439///   Nelder–Mead near the optimum.
440/// * **Speed.** 5000 trials is ~1 ms (release, parallelised), keeping a whole
441///   fit well under a second. `n = 1000` makes the surface too rugged and the
442///   simplex stalls; `n = 50_000` gives ~3x less noise for 10x the time and
443///   barely moves the estimate once the search is warm-started near the truth.
444///
445/// 5000 is the knee of that trade-off and the recommended default.
446pub const FIT_N_PER_EVAL: usize = 5_000;
447
448/// The RNG seed used for *every* objective evaluation within one
449/// [`fit_simulation`] call (common random numbers): holding it fixed makes the
450/// objective a deterministic surface, which Nelder–Mead requires — it has no
451/// defense against a stochastic objective.
452///
453/// The seed is *derived from the target statistics* rather than being a global
454/// constant. Each evaluation's 5000-trial simulation deviates from its
455/// expectation by one particular noise draw, and the fitted parameters absorb
456/// whatever offset compensates for it. A global constant would make that
457/// offset point the *same way* for every data set (a spurious directional
458/// bias); keying the seed to the data instead scatters it, so across data sets
459/// the error is mean-zero. The fit stays fully deterministic given
460/// `(trials, initial_guess, max_iters)`.
461fn fit_eval_seed(stats: &SummaryStats) -> u64 {
462    // splitmix64-style bit mixer over the data summary.
463    let mut h: u64 = 0x9E37_79B9_7F4A_7C15;
464    for x in [
465        stats.accuracy.to_bits(),
466        stats.mean_rt.to_bits(),
467        stats.var_rt.to_bits(),
468        stats.n_usable as u64,
469        stats.n_correct as u64,
470    ] {
471        h = (h ^ x).wrapping_mul(0xFF51_AFD7_ED55_8CCD);
472        h ^= h >> 33;
473    }
474    h.wrapping_mul(0xC4CE_B9FE_1A85_EC53)
475}
476
477/// Relative weights on the squared relative errors of `(Pc, MRT, VRT)` in the
478/// [`fit_simulation`] objective. Using *relative* errors already removes the
479/// raw-scale differences between the three; `VRT` is additionally halved
480/// because the sample variance carries roughly twice the relative sampling
481/// error of the sample mean, so equal weighting would let `VRT` noise steer
482/// the search.
483const FIT_WEIGHTS: [f64; 3] = [1.0, 1.0, 0.5];
484
485/// Reasons [`fit_simulation`] cannot return an estimate.
486#[derive(Debug, Clone, PartialEq, Eq)]
487pub enum FitError {
488    /// [`summary_stats`] of the target data is undefined (no usable trials, or
489    /// fewer than two upper-boundary trials).
490    NoData,
491    /// The optimizer ran but produced no best parameter vector.
492    NoSolution,
493    /// The optimizer returned an error.
494    Solver(String),
495}
496
497impl std::fmt::Display for FitError {
498    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
499        match self {
500            FitError::NoData => write!(
501                f,
502                "target data has no usable trials or fewer than two upper-boundary trials"
503            ),
504            FitError::NoSolution => write!(f, "optimizer produced no solution"),
505            FitError::Solver(msg) => write!(f, "optimizer error: {msg}"),
506        }
507    }
508}
509
510impl std::error::Error for FitError {}
511
512/// Sum-of-squared-relative-differences objective between a candidate parameter
513/// vector `[drift_rate, boundary_separation, non_decision_time]` and the target
514/// summary statistics. `starting_point` is fixed at `0.5` and `noise_sd` at
515/// [`EZ_SCALING_S`], matching the model both estimators assume.
516#[derive(Clone)]
517struct SimFitCost {
518    target: SummaryStats,
519    n_per_eval: usize,
520    seed: u64,
521}
522
523impl CostFunction for SimFitCost {
524    type Param = Vec<f64>;
525    type Output = f64;
526
527    fn cost(&self, p: &Self::Param) -> Result<Self::Output, ArgminError> {
528        let (v, a, t0) = (p[0], p[1], p[2]);
529
530        // Nelder–Mead searches unconstrained R^3; fence off the invalid region
531        // with a large finite penalty rather than an error.
532        if !v.is_finite() || !a.is_finite() || !t0.is_finite() || a <= 1e-6 || t0 < 0.0 {
533            return Ok(1e9);
534        }
535
536        let params = Params {
537            drift_rate: v,
538            boundary_separation: a,
539            starting_point: 0.5,
540            non_decision_time: t0,
541            noise_sd: EZ_SCALING_S,
542        };
543        let trials = simulate_n(&params, self.n_per_eval, self.seed);
544
545        let Some(cand) = summary_stats(&trials) else {
546            return Ok(1e9);
547        };
548
549        let sq_rel = |c: f64, t: f64| {
550            let d = (c - t) / t;
551            d * d
552        };
553        let cost = FIT_WEIGHTS[0] * sq_rel(cand.accuracy, self.target.accuracy)
554            + FIT_WEIGHTS[1] * sq_rel(cand.mean_rt, self.target.mean_rt)
555            + FIT_WEIGHTS[2] * sq_rel(cand.var_rt, self.target.var_rt);
556
557        Ok(cost)
558    }
559}
560
561/// The result of a [`fit_simulation`] run: the recovered parameters plus a
562/// little diagnostic detail about the search.
563#[derive(Debug, Clone, PartialEq)]
564pub struct SimFit {
565    /// Recovered parameters (`starting_point = 0.5`, `noise_sd` =
566    /// [`EZ_SCALING_S`]).
567    pub params: Params,
568    /// Number of Nelder–Mead iterations performed.
569    pub iterations: u64,
570    /// Objective value at `params` (weighted sum of squared relative errors
571    /// in `Pc`, `MRT`, `VRT`).
572    pub final_cost: f64,
573}
574
575/// A reasonable starting point for [`fit_simulation`]: the closed-form
576/// [`ez_diffusion`] estimate when it succeeds, otherwise a neutral default.
577///
578/// This is a deliberate design choice — EZ is essentially free (a handful of
579/// `ln`/`exp` calls) and lands close enough to the truth that the expensive
580/// simulation search only has to polish it, cutting the iteration count
581/// several-fold versus a cold start.
582pub fn default_fit_guess(trials: &[Trial]) -> Params {
583    ez_diffusion(trials).unwrap_or_else(|_| Params::new(1.0, 1.0, 0.5, 0.2))
584}
585
586/// Recover DDM parameters by **simulation-based fitting**: minimise, with
587/// Nelder–Mead, the discrepancy between the data's `(Pc, MRT, VRT)` and those
588/// same statistics computed from a fresh [`simulate_n`] run at the candidate
589/// parameters.
590///
591/// Unlike [`ez_diffusion`] this makes no closed-form approximation — the
592/// forward model *is* the simulator — so it has no analogue of EZ's
593/// discretisation-driven bias (the `dt` overshoot affects the candidate and
594/// the data identically and cancels). Its error is instead optimizer
595/// convergence plus the Monte-Carlo noise of each evaluation (see
596/// [`FIT_N_PER_EVAL`]).
597///
598/// Three parameters are fitted: `drift_rate`, `boundary_separation`,
599/// `non_decision_time`. `starting_point` is held at `0.5` and `noise_sd` at
600/// [`EZ_SCALING_S`].
601///
602/// # Arguments
603///
604/// * `initial_guess` — where the simplex is centred. Pass
605///   [`default_fit_guess`] (the EZ estimate) unless you have something better;
606///   warm-starting from the cheap closed-form fit is the intended use.
607/// * `max_iters` — total Nelder–Mead iteration budget. ~100–200 is plenty for
608///   this 3-parameter problem. The budget is split across two rounds: an
609///   initial search, then one simplex restart around the best point found (a
610///   standard guard against the simplex collapsing prematurely onto a ridge of
611///   the slightly rugged Monte-Carlo objective).
612///
613/// # Determinism
614///
615/// Every objective evaluation uses one RNG seed derived from the data (see
616/// [`fit_eval_seed`]), so the whole fit is deterministic given
617/// `(trials, initial_guess, max_iters)`. The estimate is conditioned on that
618/// single noise realisation of the evaluation simulator; averaging over seeds
619/// would cut its variance at proportional cost.
620pub fn fit_simulation(
621    trials: &[Trial],
622    initial_guess: Params,
623    max_iters: usize,
624) -> Result<SimFit, FitError> {
625    let target = summary_stats(trials).ok_or(FitError::NoData)?;
626
627    let cost = SimFitCost {
628        target,
629        n_per_eval: FIT_N_PER_EVAL,
630        seed: fit_eval_seed(&target),
631    };
632
633    let g = [
634        initial_guess.drift_rate,
635        initial_guess.boundary_separation,
636        initial_guess.non_decision_time,
637    ];
638
639    // Round 1: ~55% of the budget from a simplex around the guess.
640    let round1_iters = (max_iters * 55 / 100).max(1) as u64;
641    let (mut best, mut best_cost, mut iters) =
642        run_neldermead(cost.clone(), simplex_around(&g, 0.15, 0.05), round1_iters)?;
643
644    // Round 2: the remainder, restarting from round 1's best with a tighter
645    // simplex.
646    let round2_iters = (max_iters as u64).saturating_sub(iters).max(1);
647    let (b2, c2, i2) = run_neldermead(cost, simplex_around(&best, 0.05, 0.02), round2_iters)?;
648    iters += i2;
649    if c2 < best_cost {
650        best = b2;
651        best_cost = c2;
652    }
653
654    Ok(SimFit {
655        params: Params {
656            drift_rate: best[0],
657            boundary_separation: best[1],
658            starting_point: 0.5,
659            non_decision_time: best[2],
660            noise_sd: EZ_SCALING_S,
661        },
662        iterations: iters,
663        final_cost: best_cost,
664    })
665}
666
667/// A 4-vertex simplex around `center`: the point itself, plus one vertex per
668/// axis stepped by `frac` of that coordinate's magnitude (floored at `floor`
669/// so a near-zero coordinate still spreads).
670fn simplex_around(center: &[f64; 3], frac: f64, floor: f64) -> Vec<Vec<f64>> {
671    let step = |v: f64| (v.abs() * frac).max(floor);
672    vec![
673        center.to_vec(),
674        vec![center[0] + step(center[0]), center[1], center[2]],
675        vec![center[0], center[1] + step(center[1]), center[2]],
676        vec![center[0], center[1], center[2] + floor.max(0.05)],
677    ]
678}
679
680/// Run Nelder–Mead once and return `(best_param, best_cost, iterations)`.
681fn run_neldermead(
682    cost: SimFitCost,
683    simplex: Vec<Vec<f64>>,
684    max_iters: u64,
685) -> Result<([f64; 3], f64, u64), FitError> {
686    let solver = NelderMead::new(simplex)
687        .with_sd_tolerance(1e-10)
688        .map_err(|e| FitError::Solver(e.to_string()))?;
689
690    let result = Executor::new(cost, solver)
691        .configure(|state| state.max_iters(max_iters))
692        .run()
693        .map_err(|e| FitError::Solver(e.to_string()))?;
694
695    let state = result.state();
696    let best = state.get_best_param().ok_or(FitError::NoSolution)?;
697    Ok((
698        [best[0], best[1], best[2]],
699        state.get_best_cost(),
700        state.get_iter(),
701    ))
702}
703
704#[cfg(test)]
705mod tests {
706    use super::*;
707
708    fn prop_upper(trials: &[Trial]) -> f64 {
709        trials.iter().filter(|t| t.upper_boundary).count() as f64 / trials.len() as f64
710    }
711
712    fn mean_rt(trials: &[Trial]) -> f64 {
713        trials.iter().map(|t| t.rt).sum::<f64>() / trials.len() as f64
714    }
715
716    /// Closed-form probability that a Wiener process with drift `v` and
717    /// infinitesimal SD `s`, started at `z_frac * a`, is absorbed at the
718    /// upper boundary `a` rather than at `0`.
719    ///
720    /// `P = (e^{-2 v z / s^2} - 1) / (e^{-2 v a / s^2} - 1)`, with the
721    /// `v -> 0` limit `z / a`. This is the standard DDM choice probability
722    /// and gives the tests something real to check the sampler against.
723    fn analytic_p_upper(v: f64, a: f64, z_frac: f64, s: f64) -> f64 {
724        let z = z_frac * a;
725        if v.abs() < 1e-12 {
726            return z / a;
727        }
728        let k = -2.0 * v / (s * s);
729        (k * z).exp_m1() / (k * a).exp_m1()
730    }
731
732    /// Zero drift + centered start is a symmetric random walk: the sampler
733    /// should match the analytic 50/50 split over a large sample.
734    #[test]
735    fn zero_drift_centered_start_is_balanced() {
736        let params = Params::new(0.0, 1.0, 0.5, 0.0);
737        let trials = simulate_n(&params, 40_000, 0xC0FFEE);
738        let p = prop_upper(&trials);
739        assert!((p - 0.5).abs() < 0.02, "expected ~0.5 split, got {p}");
740    }
741
742    /// The empirical choice probability should track the closed-form DDM
743    /// absorption probability across a range of drifts and start points.
744    #[test]
745    fn choice_probability_matches_closed_form() {
746        for &(v, a, z) in &[
747            (1.0, 1.0, 0.5),
748            (2.5, 1.0, 0.5),
749            (-2.0, 1.0, 0.5),
750            (0.0, 1.0, 0.8),
751            (0.8, 1.4, 0.3),
752        ] {
753            let params = Params::new(v, a, z, 0.0);
754            let p = prop_upper(&simulate_n(&params, 60_000, 17));
755            let expected = analytic_p_upper(v, a, z, params.noise_sd);
756            assert!(
757                (p - expected).abs() < 0.03,
758                "v={v} a={a} z={z}: empirical {p:.3} vs analytic {expected:.3}"
759            );
760        }
761    }
762
763    /// Stronger drift toward the upper boundary should (a) send more trials
764    /// there and (b) shorten the mean response time.
765    #[test]
766    fn stronger_drift_favors_boundary_and_speeds_decisions() {
767        let weak = Params::new(0.5, 1.0, 0.5, 0.0);
768        let strong = Params::new(2.5, 1.0, 0.5, 0.0);
769
770        let weak_trials = simulate_n(&weak, 40_000, 7);
771        let strong_trials = simulate_n(&strong, 40_000, 7);
772
773        let (p_weak, p_strong) = (prop_upper(&weak_trials), prop_upper(&strong_trials));
774        let (rt_weak, rt_strong) = (mean_rt(&weak_trials), mean_rt(&strong_trials));
775
776        assert!(
777            p_strong > p_weak,
778            "stronger drift should favor the boundary more: {p_weak} -> {p_strong}"
779        );
780        assert!(
781            rt_strong < rt_weak,
782            "stronger drift should be faster: {rt_weak} -> {rt_strong}"
783        );
784    }
785
786    /// Drift sign controls *which* boundary is favored.
787    #[test]
788    fn negative_drift_favors_lower_boundary() {
789        let params = Params::new(-2.0, 1.0, 0.5, 0.0);
790        let trials = simulate_n(&params, 40_000, 42);
791        assert!(
792            prop_upper(&trials) < 0.2,
793            "negative drift should favor the lower boundary, got {}",
794            prop_upper(&trials)
795        );
796    }
797
798    /// Same seed -> bit-identical output; different seed -> different output.
799    #[test]
800    fn seeding_is_reproducible_and_seed_sensitive() {
801        let params = Params::new(0.8, 1.2, 0.4, 0.2);
802        let a = simulate_n(&params, 5_000, 2024);
803        let b = simulate_n(&params, 5_000, 2024);
804        let c = simulate_n(&params, 5_000, 2025);
805
806        assert_eq!(a, b, "identical seed must reproduce identical trials");
807        assert_ne!(a, c, "different seed should produce different trials");
808    }
809
810    /// Determinism must not depend on the rayon pool size.
811    #[test]
812    fn determinism_is_independent_of_thread_count() {
813        let params = Params::new(1.0, 1.0, 0.5, 0.0);
814        let reference = simulate_n(&params, 8_000, 99);
815
816        let one_thread = rayon::ThreadPoolBuilder::new()
817            .num_threads(1)
818            .build()
819            .unwrap()
820            .install(|| simulate_n(&params, 8_000, 99));
821
822        assert_eq!(reference, one_thread);
823    }
824
825    /// `non_decision_time` is a pure additive shift on `rt` and leaves the
826    /// diffusion path (hence the choice) untouched.
827    #[test]
828    fn non_decision_time_is_an_additive_shift() {
829        let base = Params::new(1.0, 1.0, 0.5, 0.0);
830        let shifted = Params::new(1.0, 1.0, 0.5, 0.3);
831
832        let a = simulate_n(&base, 3_000, 1);
833        let b = simulate_n(&shifted, 3_000, 1);
834
835        for (x, y) in a.iter().zip(b.iter()) {
836            assert_eq!(x.upper_boundary, y.upper_boundary);
837            assert!((y.rt - x.rt - 0.3).abs() < 1e-9);
838        }
839    }
840
841    /// A start biased toward the upper boundary favors upper responses even
842    /// with zero drift.
843    #[test]
844    fn biased_start_favors_near_boundary() {
845        let params = Params::new(0.0, 1.0, 0.8, 0.0);
846        let trials = simulate_n(&params, 40_000, 5);
847        assert!(
848            prop_upper(&trials) > 0.7,
849            "start near the upper boundary should favor upper responses"
850        );
851    }
852
853    /// End-to-end parameter recovery: simulate with known params, then check
854    /// that `ez_diffusion` inverts back to them.
855    ///
856    /// ## Tolerance
857    ///
858    /// EZ and this simulator share the same generative assumptions (unbiased
859    /// start, no across-trial variability in drift/start/Ter), so EZ's
860    /// well-documented bias at extreme parameters -- driven by across-trial
861    /// variability it cannot see -- does *not* apply here. The residual error
862    /// has two sources we can bound:
863    ///
864    /// 1. **Euler-Maruyama discretization.** With `dt = 1e-3` and `s = 1`, the
865    ///    process overshoots a boundary by `O(s*sqrt(dt)) ~= 0.03` per
866    ///    crossing, i.e. ~3% of `a = 1`. This inflates observed RT and, through
867    ///    Eqs. 4-5, the recovered `a` and `v` by a few percent, and shifts
868    ///    `Ter` by up to ~1-2 discretization steps plus the RT inflation.
869    /// 2. **Monte-Carlo error.** With `n = 200_000` the SE of `Pc` is
870    ///    `< 0.0012` and of `MRT` is well under 1 ms, contributing < 1%.
871    ///
872    /// So we allow **8% relative** error on `drift_rate` and
873    /// `boundary_separation` and **20 ms absolute** on `non_decision_time`.
874    /// These are set from the discretization-bias budget above, not tuned to
875    /// pass: a bug that (say) doubled `a` or dropped a factor of `s` would blow
876    /// straight through them. Drift is kept positive so the upper boundary is
877    /// the majority ("correct") response, matching the EZ coding convention.
878    #[test]
879    fn ez_diffusion_recovers_known_parameters() {
880        // (drift, boundary, start, t0)
881        let truths = [
882            Params::new(1.0, 1.0, 0.5, 0.20),
883            Params::new(2.0, 1.2, 0.5, 0.30),
884            Params::new(0.5, 1.5, 0.5, 0.15),
885            Params::new(3.0, 0.8, 0.5, 0.25),
886        ];
887
888        for (k, truth) in truths.iter().enumerate() {
889            let trials = simulate_n(truth, 200_000, 1000 + k as u64);
890            let est = ez_diffusion(&trials).expect("recovery should succeed");
891
892            let rel = |got: f64, want: f64| (got - want).abs() / want;
893
894            assert!(
895                rel(est.drift_rate, truth.drift_rate) < 0.08,
896                "case {k}: drift {:.4} vs true {:.4} ({:.1}%)",
897                est.drift_rate,
898                truth.drift_rate,
899                100.0 * rel(est.drift_rate, truth.drift_rate),
900            );
901            assert!(
902                rel(est.boundary_separation, truth.boundary_separation) < 0.08,
903                "case {k}: boundary {:.4} vs true {:.4} ({:.1}%)",
904                est.boundary_separation,
905                truth.boundary_separation,
906                100.0 * rel(est.boundary_separation, truth.boundary_separation),
907            );
908            assert!(
909                (est.non_decision_time - truth.non_decision_time).abs() < 0.020,
910                "case {k}: Ter {:.4} vs true {:.4}",
911                est.non_decision_time,
912                truth.non_decision_time,
913            );
914        }
915    }
916
917    /// Perfect accuracy triggers the `1 - 1/(2N)` edge correction rather than
918    /// a division-by-zero or NaN. Built by hand so `Pc` is exactly 1.
919    #[test]
920    fn ez_diffusion_edge_corrects_perfect_accuracy() {
921        let mut rng = ChaCha8Rng::seed_from_u64(3);
922        let trials: Vec<Trial> = (0..5_000)
923            .map(|_| Trial {
924                upper_boundary: true,
925                // spread RT so VRT > 0
926                rt: 0.4 + 0.05 * rng.sample::<f64, _>(StandardNormal),
927                timed_out: false,
928            })
929            .collect();
930        assert!(trials.iter().all(|t| t.upper_boundary));
931
932        let est = ez_diffusion(&trials).expect("edge correction should apply");
933        assert!(est.drift_rate.is_finite() && est.drift_rate > 0.0);
934        assert!(est.boundary_separation.is_finite() && est.boundary_separation > 0.0);
935        assert!(est.non_decision_time.is_finite());
936    }
937
938    /// Timed-out trials must not enter the summary statistics.
939    #[test]
940    fn ez_diffusion_excludes_timed_out_trials() {
941        let mut trials = simulate_n(&Params::new(1.0, 1.0, 0.5, 0.2), 5_000, 9);
942        let clean = ez_diffusion(&trials).unwrap();
943
944        // Injecting garbage timed-out trials should not change the estimate.
945        for i in 0..2_000 {
946            trials.push(Trial {
947                upper_boundary: i % 2 == 0,
948                rt: 10.0 + i as f64,
949                timed_out: true,
950            });
951        }
952        let with_junk = ez_diffusion(&trials).unwrap();
953
954        assert!((clean.drift_rate - with_junk.drift_rate).abs() < 1e-12);
955        assert!((clean.boundary_separation - with_junk.boundary_separation).abs() < 1e-12);
956        assert!((clean.non_decision_time - with_junk.non_decision_time).abs() < 1e-12);
957    }
958
959    #[test]
960    fn summary_stats_are_correct_and_exclude_timeouts() {
961        let trials = vec![
962            Trial {
963                upper_boundary: true,
964                rt: 0.5,
965                timed_out: false,
966            },
967            Trial {
968                upper_boundary: true,
969                rt: 0.7,
970                timed_out: false,
971            },
972            Trial {
973                upper_boundary: true,
974                rt: 0.9,
975                timed_out: false,
976            },
977            Trial {
978                upper_boundary: false,
979                rt: 0.6,
980                timed_out: false,
981            },
982            // excluded entirely:
983            Trial {
984                upper_boundary: true,
985                rt: 10.1,
986                timed_out: true,
987            },
988            Trial {
989                upper_boundary: false,
990                rt: 10.1,
991                timed_out: true,
992            },
993        ];
994        let s = summary_stats(&trials).unwrap();
995        assert_eq!(s.n_usable, 4);
996        assert_eq!(s.n_correct, 3);
997        assert!((s.accuracy - 0.75).abs() < 1e-12);
998        assert!((s.mean_rt - 0.7).abs() < 1e-12);
999        // sample variance of {0.5, 0.7, 0.9} = 0.04
1000        assert!((s.var_rt - 0.04).abs() < 1e-12);
1001
1002        assert!(summary_stats(&[]).is_none());
1003    }
1004
1005    #[test]
1006    fn ez_diffusion_and_summary_stats_agree() {
1007        // ez_diffusion must be driven by the same statistics summary_stats reports.
1008        let trials = simulate_n(&Params::new(1.3, 1.1, 0.5, 0.2), 20_000, 4);
1009        let s = summary_stats(&trials).unwrap();
1010        let est = ez_diffusion(&trials).unwrap();
1011
1012        // Re-derive Ter from the reported (v, a) and MRT; it must match.
1013        let (v, a) = (est.drift_rate, est.boundary_separation);
1014        let y = -v * a / (EZ_SCALING_S * EZ_SCALING_S);
1015        let mdt = (a / (2.0 * v)) * ((1.0 - y.exp()) / (1.0 + y.exp()));
1016        assert!((est.non_decision_time - (s.mean_rt - mdt)).abs() < 1e-9);
1017    }
1018
1019    #[test]
1020    fn fit_simulation_is_deterministic() {
1021        let trials = simulate_n(&Params::new(1.2, 1.0, 0.5, 0.25), 20_000, 11);
1022        let guess = default_fit_guess(&trials);
1023        let a = fit_simulation(&trials, guess.clone(), 80).unwrap();
1024        let b = fit_simulation(&trials, guess, 80).unwrap();
1025        assert_eq!(a, b);
1026    }
1027
1028    /// End-to-end recovery for the simulation fitter, the analogue of
1029    /// `ez_diffusion_recovers_known_parameters`.
1030    ///
1031    /// Tolerance, reasoned from this method's error sources rather than EZ's.
1032    /// The forward model here *is* the simulator, so the `dt` discretization
1033    /// overshoot hits the candidate and the target identically and cancels --
1034    /// there is no one-directional bias like the +3-4% EZ inherited on `a`.
1035    /// The error is instead per-evaluation Monte-Carlo noise
1036    /// ([`FIT_N_PER_EVAL`] = 5000 trials, one data-derived seed).
1037    ///
1038    /// `SE(Pc) ~ sqrt(p(1-p)/5000)`, and the fit drives candidate `Pc` to the
1039    /// target within that. Since `dPc ~= p(1-p) * d(v*a/s^2)`, the relative
1040    /// error this induces on `v*a` is `SE(Pc) / (p(1-p) * logit(Pc))`, which is
1041    /// strongly drift-dependent: ~1.5% at `v=3, a=0.8` (`Pc ~= 0.92`), ~3% at
1042    /// `v=1, a=1` (`Pc ~= 0.73`), and ~4% at `v=0.5, a=1.5` (`Pc ~= 0.68`,
1043    /// nearest chance, where the `Pc -> v` map is steepest). `VRT` (shift-
1044    /// invariant, no `Pc` term) anchors `a`, so most of this noise lands on
1045    /// `v`. Its sign is mean-zero across data sets because the eval seed is
1046    /// keyed to the data. Target sampling at `n = 150_000` adds `SE(Pc) <
1047    /// 0.0013` (~4x smaller) and the optimizer resolves the minimum to <1%
1048    /// (final costs ~1e-5 or below) -- both subdominant.
1049    ///
1050    /// So expected `|error|` on `v` is ~1.5% (high drift) to ~4% 1-sigma (the
1051    /// low-drift corner here). Tolerances: `drift_rate` **8%** (~2-sigma at the
1052    /// worst case -- 5% would do for `v >= 1`, the extra room is specifically
1053    /// for `Pc -> v` amplification near chance, not slack); `boundary_
1054    /// separation` **5%** (anchored by `VRT`, observed errors ~1-3%);
1055    /// `non_decision_time` **18 ms** (`Ter = MRT - MDT(v,a)`: `SE(MRT) ~= 2-5
1056    /// ms` plus `v,a` error propagating through an `MDT` of up to ~0.5 s).
1057    /// This budget differs from EZ's in kind: EZ's was a one-directional
1058    /// discretization allowance uniform across parameters; this is
1059    /// two-directional MC noise, worst for `v` and worst still at low drift.
1060    #[test]
1061    fn fit_simulation_recovers_known_parameters() {
1062        let truths = [
1063            Params::new(1.0, 1.0, 0.5, 0.20),
1064            Params::new(2.0, 1.2, 0.5, 0.30),
1065            Params::new(0.5, 1.5, 0.5, 0.15),
1066            Params::new(3.0, 0.8, 0.5, 0.25),
1067        ];
1068
1069        for (k, truth) in truths.iter().enumerate() {
1070            let trials = simulate_n(truth, 150_000, 2000 + k as u64);
1071            let guess = default_fit_guess(&trials);
1072            let fit = fit_simulation(&trials, guess, 150).expect("fit should succeed");
1073            let est = fit.params;
1074
1075            let rel = |got: f64, want: f64| (got - want).abs() / want;
1076
1077            assert!(
1078                rel(est.drift_rate, truth.drift_rate) < 0.08,
1079                "case {k}: drift {:.4} vs true {:.4} ({:.1}%), cost {:.2e}",
1080                est.drift_rate,
1081                truth.drift_rate,
1082                100.0 * rel(est.drift_rate, truth.drift_rate),
1083                fit.final_cost,
1084            );
1085            assert!(
1086                rel(est.boundary_separation, truth.boundary_separation) < 0.05,
1087                "case {k}: boundary {:.4} vs true {:.4} ({:.1}%), cost {:.2e}",
1088                est.boundary_separation,
1089                truth.boundary_separation,
1090                100.0 * rel(est.boundary_separation, truth.boundary_separation),
1091                fit.final_cost,
1092            );
1093            assert!(
1094                (est.non_decision_time - truth.non_decision_time).abs() < 0.018,
1095                "case {k}: Ter {:.4} vs true {:.4}, cost {:.2e}",
1096                est.non_decision_time,
1097                truth.non_decision_time,
1098                fit.final_cost,
1099            );
1100        }
1101    }
1102}