Skip to main content

hop_accel/
lib.rs

1#![forbid(unsafe_code)]
2//! Safe CPU acceleration facade for independent HOP recurrence states.
3
4use hop_core::{CompanionMatrix, CoreError, Field, Result};
5
6/// Applies one companion transition to every state in the batch.
7///
8/// The stable implementation is intentionally safe and deterministic. Future
9/// SIMD/GPU backends can implement the same semantics behind an explicit
10/// feature without changing callers.
11pub fn transition_batch(
12    companion: &CompanionMatrix,
13    states: &[Vec<Field>],
14) -> Result<Vec<Vec<Field>>> {
15    states
16        .iter()
17        .map(|state| companion.try_apply(state))
18        .collect()
19}
20
21/// Jumps every independent state forward by the same number of transitions.
22pub fn jump_batch(
23    companion: &CompanionMatrix,
24    states: &[Vec<Field>],
25    steps: u64,
26) -> Result<Vec<Vec<Field>>> {
27    if let Some(state) = states
28        .iter()
29        .find(|state| state.len() != companion.dimension())
30    {
31        return Err(CoreError::DimensionMismatch {
32            expected: companion.dimension(),
33            actual: state.len(),
34        });
35    }
36    if steps == 0 {
37        return Ok(states.to_vec());
38    }
39    let power = companion.mat_pow(steps);
40    states
41        .iter()
42        .map(|state| {
43            Ok(power
44                .iter()
45                .map(|row| {
46                    row.iter()
47                        .zip(state)
48                        .fold(Field::zero(), |acc, (a, b)| acc + (*a * *b))
49                })
50                .collect())
51        })
52        .collect()
53}
54
55#[cfg(test)]
56mod tests {
57    use super::*;
58
59    #[test]
60    fn batch_matches_scalar_execution() {
61        let companion = CompanionMatrix::from_coeffs(&[4, 3, 2]);
62        let states = vec![
63            vec![Field::one(), Field::zero(), Field::zero()],
64            vec![Field::from(3), Field::from(5), Field::from(8)],
65        ];
66        let batch = jump_batch(&companion, &states, 89).expect("valid batch");
67        for (state, result) in states.iter().zip(batch) {
68            assert_eq!(result, companion.jump(state, 89).expect("valid state"));
69        }
70    }
71
72    #[test]
73    fn transition_batch_matches_one_scalar_step() {
74        let companion = CompanionMatrix::from_coeffs(&[4, 3, 2]);
75        let states = vec![
76            vec![Field::one(), Field::zero(), Field::zero()],
77            vec![Field::from(3), Field::from(5), Field::from(8)],
78        ];
79        let batch = transition_batch(&companion, &states).unwrap();
80        for (state, result) in states.iter().zip(batch) {
81            assert_eq!(result, companion.try_apply(state).unwrap());
82        }
83    }
84
85    #[test]
86    fn rejects_entire_batch_before_jump_work_and_handles_identity() {
87        let companion = CompanionMatrix::from_coeffs(&[4, 3, 2]);
88        let invalid = vec![
89            vec![Field::one(), Field::zero(), Field::zero()],
90            vec![Field::one()],
91        ];
92        assert!(matches!(
93            jump_batch(&companion, &invalid, u64::MAX),
94            Err(CoreError::DimensionMismatch { .. })
95        ));
96        let states = vec![vec![Field::one(), Field::zero(), Field::zero()]];
97        assert_eq!(jump_batch(&companion, &states, 0).unwrap(), states);
98        assert!(jump_batch(&companion, &[], 123).unwrap().is_empty());
99    }
100}