Skip to main content

linkcell/
vesin_abi.rs

1//! vesin-compatible CPU entry points.
2//!
3//! [`vesin_neighbors`] has the same layout and calling convention as
4//! vesin's C API: row-major box, `ij` / `S` / distance / vector outputs,
5//! half or full lists, and a Verlet skin. Fully periodic cells run here.
6//! A non-periodic axis or a CUDA device is forwarded to the platform
7//! vesin library (`libvesin.so`, `libvesin.dylib`, or `libvesin.dll`)
8//! when the loader can see it.
9
10use std::cell::RefCell;
11use std::ffi::CString;
12#[cfg(unix)]
13use std::os::raw::c_int;
14use std::os::raw::{c_char, c_void};
15#[cfg(feature = "parallel")]
16use std::sync::Mutex;
17
18use crate::cell::Cell;
19use crate::pairs::{pairs_within_columns, PairColumns};
20use crate::skin::SkinList;
21use crate::Error;
22
23const VESIN_CPU: i32 = 1;
24const VESIN_CUDA: i32 = 2;
25
26/// Options block, identical in layout to `VesinOptions`.
27#[repr(C)]
28#[derive(Clone, Copy)]
29pub struct VesinOptions {
30    /// Spherical cutoff.
31    pub cutoff: f64,
32    /// Both `(i, j, S)` and `(j, i, -S)` when true.
33    pub full: bool,
34    /// Group rows by `i` when true.
35    pub sorted: bool,
36    _pad0: [u8; 6],
37    /// Full-list width. Zero means no padding.
38    pub padded_to: usize,
39    /// `VesinCellList` (2) or `VesinAutoAlgorithm` (0). Brute force is CPU-unsupported upstream.
40    pub algorithm: i32,
41    _pad1: u32,
42    /// Verlet skin. Negative selects `0.1 * cutoff` on the CPU.
43    pub skin: f64,
44    /// Thread count. Zero uses the process default.
45    pub n_threads: i32,
46    /// Store integer shifts.
47    pub return_shifts: bool,
48    /// Store distances (not squared).
49    pub return_distances: bool,
50    /// Store shifted vectors `q + H S - p`.
51    pub return_vectors: bool,
52    _pad2: u8,
53}
54
55impl VesinOptions {
56    /// CPU options. `skin < 0` is resolved inside [`NeighborCalc::compute`].
57    pub fn cpu(
58        cutoff: f64,
59        full: bool,
60        skin: f64,
61        n_threads: i32,
62        shifts: bool,
63        distances: bool,
64        vectors: bool,
65    ) -> Self {
66        Self {
67            cutoff,
68            full,
69            sorted: false,
70            _pad0: [0; 6],
71            padded_to: 0,
72            algorithm: 2,
73            _pad1: 0,
74            skin,
75            n_threads,
76            return_shifts: shifts,
77            return_distances: distances,
78            return_vectors: vectors,
79            _pad2: 0,
80        }
81    }
82
83    /// Ask for rows grouped by the first index.
84    pub fn sorted(mut self, sorted: bool) -> Self {
85        self.sorted = sorted;
86        self
87    }
88
89    /// Pad a full list to this many rows per point.
90    pub fn padded_to(mut self, n: usize) -> Self {
91        self.padded_to = n;
92        self
93    }
94}
95
96/// CPU or CUDA tag, identical in layout to `VesinDevice`.
97#[repr(C)]
98#[derive(Clone, Copy)]
99pub struct VesinDevice {
100    /// 1 is the CPU, 2 is CUDA.
101    pub kind: i32,
102    /// Device index. Zero on the CPU.
103    pub device_id: i32,
104}
105
106/// Output list, identical in layout to `VesinNeighborList`.
107#[repr(C)]
108pub struct VesinNeighborList {
109    /// Number of rows.
110    pub length: usize,
111    /// Device the buffers live on.
112    pub device: VesinDevice,
113    /// `length` pairs.
114    pub pairs: *mut [usize; 2],
115    /// `length` shifts, or null.
116    pub shifts: *mut [i32; 3],
117    /// `length` distances, or null.
118    pub distances: *mut f64,
119    /// `length` vectors, or null.
120    pub vectors: *mut [f64; 3],
121    /// Owned [`Opaque`] state.
122    pub opaque: *mut c_void,
123}
124
125struct Opaque {
126    calc: NeighborCalc,
127}
128
129/// Reused buffers for repeated `lc_vesin_neighbors` calls through the C ABI.
130#[derive(Default)]
131pub struct NeighborCalc {
132    skin_list: Option<SkinList>,
133    skin_tag: (u64, u64, bool),
134    pairs: Vec<[usize; 2]>,
135    shifts: Vec<[i32; 3]>,
136    distances: Vec<f64>,
137    vectors: Vec<[f64; 3]>,
138}
139
140impl NeighborCalc {
141    /// Index pairs from the last [`Self::compute`].
142    pub fn pairs(&self) -> &[[usize; 2]] {
143        &self.pairs
144    }
145
146    /// Integer shifts, empty unless they were requested.
147    pub fn shifts(&self) -> &[[i32; 3]] {
148        &self.shifts
149    }
150
151    /// Distances, empty unless they were requested.
152    pub fn distances(&self) -> &[f64] {
153        &self.distances
154    }
155
156    /// Shifted vectors, empty unless they were requested.
157    pub fn vectors(&self) -> &[[f64; 3]] {
158        &self.vectors
159    }
160}
161
162impl NeighborCalc {
163    /// One neighbour list.
164    ///
165    /// `periodic` is three axis flags. A false flag returns
166    /// [`Error::Partial`] from this function; the C entry tries vesin.
167    pub fn compute(
168        &mut self,
169        xyz: &[[f64; 3]],
170        cell: &Cell,
171        periodic: [bool; 3],
172        mut opt: VesinOptions,
173    ) -> Result<(), Error> {
174        if !periodic[0] || !periodic[1] || !periodic[2] {
175            return Err(Error::Partial);
176        }
177        if !opt.cutoff.is_finite() || opt.cutoff <= 0.0 {
178            return Err(Error::BadCutoff);
179        }
180        if !opt.skin.is_finite() {
181            return Err(Error::BadCutoff);
182        }
183        if opt.n_threads < 0 {
184            return Err(Error::BadCutoff);
185        }
186        if opt.padded_to > 0 && !opt.full {
187            return Err(Error::Padded);
188        }
189        for p in xyz {
190            if !p[0].is_finite() || !p[1].is_finite() || !p[2].is_finite() {
191                return Err(Error::NonFinite);
192            }
193        }
194        if xyz.is_empty() {
195            return Err(Error::Empty);
196        }
197        if opt.skin < 0.0 {
198            opt.skin = 0.1 * opt.cutoff;
199        }
200        let threads = if opt.n_threads == 0 {
201            std::thread::available_parallelism()
202                .map(|n| n.get())
203                .unwrap_or(1)
204        } else {
205            opt.n_threads as usize
206        };
207        let half = !opt.full;
208        let want_vec = opt.return_vectors;
209        with_threads(threads, || {
210            let cols = if opt.skin > 0.0 {
211                let tag = (opt.cutoff.to_bits(), opt.skin.to_bits(), half);
212                if self.skin_tag != tag {
213                    self.skin_list = None;
214                    self.skin_tag = tag;
215                }
216                if self.skin_list.is_none() {
217                    self.skin_list = Some(SkinList::new(*cell, opt.cutoff, opt.skin, half)?);
218                }
219                let list = self.skin_list.as_mut().unwrap();
220                list.update(xyz, want_vec)?;
221                list.columns().clone()
222            } else {
223                self.skin_list = None;
224                let mut cols = PairColumns::default();
225                pairs_within_columns(xyz, cell, opt.cutoff, None, None, half, &mut cols)?;
226                cols
227            };
228            self.emit(xyz, cell, &cols, opt)
229        })
230    }
231
232    fn emit(
233        &mut self,
234        xyz: &[[f64; 3]],
235        cell: &Cell,
236        cols: &PairColumns,
237        opt: VesinOptions,
238    ) -> Result<(), Error> {
239        let n_atoms = xyz.len();
240        let vectors_ready = opt.return_vectors
241            && self
242                .skin_list
243                .as_ref()
244                .is_some_and(|s| s.vectors().len() == cols.len());
245        let cached_vec = if vectors_ready {
246            self.skin_list.as_ref().unwrap().vectors().to_vec()
247        } else {
248            Vec::new()
249        };
250        self.pairs.clear();
251        self.shifts.clear();
252        self.distances.clear();
253        self.vectors.clear();
254        if opt.padded_to > 0 {
255            return self.emit_padded(xyz, cell, cols, opt, &cached_vec, n_atoms);
256        }
257        let mut order: Vec<usize> = (0..cols.len()).collect();
258        if opt.sorted {
259            order.sort_by_key(|&k| cols.i[k]);
260        }
261        self.pairs.reserve(order.len());
262        if opt.return_shifts {
263            self.shifts.reserve(order.len());
264        }
265        if opt.return_distances {
266            self.distances.reserve(order.len());
267        }
268        if opt.return_vectors {
269            self.vectors.reserve(order.len());
270        }
271        for k in order {
272            self.push_row(xyz, cell, cols, k, opt, &cached_vec);
273        }
274        Ok(())
275    }
276
277    fn emit_padded(
278        &mut self,
279        xyz: &[[f64; 3]],
280        cell: &Cell,
281        cols: &PairColumns,
282        opt: VesinOptions,
283        cached_vec: &[[f64; 3]],
284        n_atoms: usize,
285    ) -> Result<(), Error> {
286        let mut buckets: Vec<Vec<usize>> = vec![Vec::new(); n_atoms];
287        for (k, &i_raw) in cols.i.iter().enumerate() {
288            let i = i_raw as usize;
289            if i >= n_atoms {
290                return Err(Error::Overflow);
291            }
292            buckets[i].push(k);
293        }
294        for (i, bucket) in buckets.iter().enumerate() {
295            if bucket.len() > opt.padded_to {
296                let _ = i;
297                return Err(Error::Padded);
298            }
299        }
300        let rows = n_atoms * opt.padded_to;
301        self.pairs.reserve(rows);
302        if opt.return_shifts {
303            self.shifts.reserve(rows);
304        }
305        if opt.return_distances {
306            self.distances.reserve(rows);
307        }
308        if opt.return_vectors {
309            self.vectors.reserve(rows);
310        }
311        for (i, bucket) in buckets.iter().enumerate() {
312            for &k in bucket {
313                self.push_row(xyz, cell, cols, k, opt, cached_vec);
314            }
315            for _ in bucket.len()..opt.padded_to {
316                self.pairs.push([i, usize::MAX]);
317                if opt.return_shifts {
318                    self.shifts.push([0, 0, 0]);
319                }
320                if opt.return_distances {
321                    self.distances.push(0.0);
322                }
323                if opt.return_vectors {
324                    self.vectors.push([0.0, 0.0, 0.0]);
325                }
326            }
327        }
328        Ok(())
329    }
330
331    fn push_row(
332        &mut self,
333        xyz: &[[f64; 3]],
334        cell: &Cell,
335        cols: &PairColumns,
336        k: usize,
337        opt: VesinOptions,
338        cached_vec: &[[f64; 3]],
339    ) {
340        let i = cols.i[k] as usize;
341        let j = cols.j[k] as usize;
342        self.pairs.push([i, j]);
343        if opt.return_shifts {
344            self.shifts.push(cols.shift[k]);
345        }
346        if opt.return_distances {
347            self.distances.push(cols.dist2[k].sqrt());
348        }
349        if opt.return_vectors {
350            if !cached_vec.is_empty() {
351                self.vectors.push(cached_vec[k]);
352            } else {
353                let s = cols.shift[k];
354                let t = cell.lattice_shift(s[0], s[1], s[2]);
355                let p = xyz[i];
356                let q = xyz[j];
357                self.vectors
358                    .push([q[0] + t[0] - p[0], q[1] + t[1] - p[1], q[2] + t[2] - p[2]]);
359            }
360        }
361    }
362}
363
364fn with_threads<R: Send>(n: usize, f: impl FnOnce() -> R + Send) -> R {
365    #[cfg(feature = "parallel")]
366    {
367        struct Slot {
368            n: usize,
369            pool: rayon::ThreadPool,
370        }
371        static SLOTS: Mutex<Vec<Slot>> = Mutex::new(Vec::new());
372        let n = n.max(1);
373        let mut slots = SLOTS.lock().unwrap_or_else(|e| e.into_inner());
374        if slots.iter().all(|s| s.n != n) {
375            let pool = crate::place::build_pool(n);
376            slots.push(Slot { n, pool });
377        }
378        let slot = slots.iter().find(|s| s.n == n).unwrap();
379        // The pool outlives the mutex; install while the lock is held so
380        // the slot cannot move.
381        slot.pool.install(f)
382    }
383    #[cfg(not(feature = "parallel"))]
384    {
385        let _ = n;
386        f()
387    }
388}
389
390thread_local! {
391    static LAST: RefCell<CString> = RefCell::new(CString::new("").expect("empty"));
392}
393
394fn set_last(msg: &str) -> *const c_char {
395    let c = CString::new(msg).unwrap_or_else(|_| CString::new("error").expect("plain"));
396    LAST.with(|slot| {
397        *slot.borrow_mut() = c;
398        slot.borrow().as_ptr()
399    })
400}
401
402fn box_of(rows: [[f64; 3]; 3]) -> Result<Cell, Error> {
403    Cell::from_vectors(rows[0], rows[1], rows[2], [0.0, 0.0, 0.0]).map_err(|_| Error::BadBox)
404}
405
406type VesinFn = unsafe extern "C" fn(
407    *const [f64; 3],
408    usize,
409    *const [[f64; 3]; 3],
410    *const [bool; 3],
411    VesinDevice,
412    VesinOptions,
413    *mut VesinNeighborList,
414    *mut *const c_char,
415) -> i32;
416
417fn foreign_vesin() -> Option<VesinFn> {
418    use std::sync::OnceLock;
419    static FOREIGN: OnceLock<Option<VesinFn>> = OnceLock::new();
420    *FOREIGN.get_or_init(load_foreign_vesin)
421}
422
423#[cfg(all(unix, target_os = "macos"))]
424const VESIN_LIB: &[u8] = b"libvesin.dylib\0";
425#[cfg(all(unix, not(target_os = "macos")))]
426const VESIN_LIB: &[u8] = b"libvesin.so\0";
427
428#[cfg(unix)]
429fn load_foreign_vesin() -> Option<VesinFn> {
430    unsafe {
431        extern "C" {
432            fn dlopen(name: *const c_char, flags: c_int) -> *mut c_void;
433            fn dlsym(handle: *mut c_void, symbol: *const c_char) -> *mut c_void;
434        }
435        let handle = dlopen(VESIN_LIB.as_ptr().cast(), 1);
436        if handle.is_null() {
437            return None;
438        }
439        let sym = dlsym(handle, b"vesin_neighbors\0".as_ptr().cast());
440        if sym.is_null() || sym == lc_vesin_neighbors as *mut c_void {
441            return None;
442        }
443        Some(std::mem::transmute::<*mut c_void, VesinFn>(sym))
444    }
445}
446
447#[cfg(windows)]
448fn load_foreign_vesin() -> Option<VesinFn> {
449    unsafe {
450        #[link(name = "kernel32")]
451        extern "system" {
452            fn LoadLibraryA(name: *const u8) -> *mut c_void;
453            fn GetProcAddress(module: *mut c_void, name: *const u8) -> *mut c_void;
454        }
455        let handle = LoadLibraryA(b"libvesin.dll\0".as_ptr());
456        if handle.is_null() {
457            return None;
458        }
459        let sym = GetProcAddress(handle, b"vesin_neighbors\0".as_ptr());
460        if sym.is_null() || sym == lc_vesin_neighbors as *mut c_void {
461            return None;
462        }
463        Some(std::mem::transmute::<*mut c_void, VesinFn>(sym))
464    }
465}
466
467#[cfg(not(any(unix, windows)))]
468fn load_foreign_vesin() -> Option<VesinFn> {
469    None
470}
471
472/// Fully periodic CPU lists are computed here.
473///
474/// The symbol is `lc_vesin_neighbors`, not `vesin_neighbors`. A program
475/// that links both this crate and vesin keeps vesin's symbol. A drop-in
476/// object that calls this function is `include/vesin_alias.c`.
477///
478/// # Safety
479///
480/// `points` is `n_points` coordinate triples. `box_` is three lattice
481/// rows. `periodic` is three booleans. `neighbors` is a zero-initialised
482/// or previously returned list. `error_message` is writable.
483#[no_mangle]
484pub unsafe extern "C" fn lc_vesin_neighbors(
485    points: *const [f64; 3],
486    n_points: usize,
487    box_: *const [[f64; 3]; 3],
488    periodic: *const [bool; 3],
489    device: VesinDevice,
490    options: VesinOptions,
491    neighbors: *mut VesinNeighborList,
492    error_message: *mut *const c_char,
493) -> i32 {
494    if error_message.is_null() {
495        return 1;
496    }
497    unsafe {
498        *error_message = std::ptr::null();
499    }
500    if points.is_null() || box_.is_null() || periodic.is_null() || neighbors.is_null() {
501        unsafe {
502            *error_message = set_last("null pointer");
503        }
504        return 1;
505    }
506    let periodic = unsafe { *periodic };
507    let forward = device.kind == VESIN_CUDA || !periodic[0] || !periodic[1] || !periodic[2];
508    if forward {
509        if let Some(f) = foreign_vesin() {
510            return unsafe {
511                f(
512                    points,
513                    n_points,
514                    box_,
515                    &periodic,
516                    device,
517                    options,
518                    neighbors,
519                    error_message,
520                )
521            };
522        }
523        let msg = if device.kind == VESIN_CUDA {
524            Error::Device.to_string()
525        } else {
526            Error::Partial.to_string()
527        };
528        unsafe {
529            *error_message = set_last(&msg);
530        }
531        return 1;
532    }
533    if device.kind != VESIN_CPU && device.kind != 0 {
534        unsafe {
535            *error_message = set_last(&Error::Device.to_string());
536        }
537        return 1;
538    }
539    let rows = unsafe { *box_ };
540    let cell = match box_of(rows) {
541        Ok(c) => c,
542        Err(e) => {
543            unsafe {
544                *error_message = set_last(&e.to_string());
545            }
546            return 1;
547        }
548    };
549    let xyz = unsafe { std::slice::from_raw_parts(points, n_points) };
550    let opaque = unsafe { &mut *neighbors };
551    if opaque.opaque.is_null() {
552        let boxed = Box::new(Opaque {
553            calc: NeighborCalc::default(),
554        });
555        opaque.opaque = Box::into_raw(boxed).cast();
556    }
557    let state = unsafe { &mut *(opaque.opaque as *mut Opaque) };
558    if let Err(e) = state.calc.compute(xyz, &cell, periodic, options) {
559        unsafe {
560            *error_message = set_last(&e.to_string());
561        }
562        return 1;
563    }
564    opaque.length = state.calc.pairs.len();
565    opaque.device = VesinDevice {
566        kind: VESIN_CPU,
567        device_id: 0,
568    };
569    opaque.pairs = state.calc.pairs.as_mut_ptr();
570    opaque.shifts = if options.return_shifts {
571        state.calc.shifts.as_mut_ptr()
572    } else {
573        std::ptr::null_mut()
574    };
575    opaque.distances = if options.return_distances {
576        state.calc.distances.as_mut_ptr()
577    } else {
578        std::ptr::null_mut()
579    };
580    opaque.vectors = if options.return_vectors {
581        state.calc.vectors.as_mut_ptr()
582    } else {
583        std::ptr::null_mut()
584    };
585    0
586}
587
588/// Release a list produced by [`lc_vesin_neighbors`].
589///
590/// # Safety
591///
592/// `neighbors` is null or a list this library filled. Not a list vesin itself allocated.
593#[no_mangle]
594pub unsafe extern "C" fn lc_vesin_free(neighbors: *mut VesinNeighborList) {
595    if neighbors.is_null() {
596        return;
597    }
598    unsafe {
599        let nl = &mut *neighbors;
600        if !nl.opaque.is_null() {
601            drop(Box::from_raw(nl.opaque.cast::<Opaque>()));
602        }
603        std::ptr::write_bytes(nl, 0, 1);
604    }
605}
606
607#[cfg(test)]
608mod tests {
609    use super::*;
610
611    #[test]
612    fn options_match_the_vesin_layout() {
613        assert_eq!(std::mem::size_of::<VesinOptions>(), 48);
614        assert_eq!(std::mem::size_of::<VesinNeighborList>(), 56);
615        assert_eq!(std::mem::align_of::<VesinOptions>(), 8);
616    }
617
618    #[test]
619    fn cpu_list_matches_columns() {
620        let xyz = [[0.2, 0.0, 0.0], [9.4, 0.0, 0.0], [1.0, 2.0, 3.0]];
621        let cell = Cell::ortho(10.0, 10.0, 10.0).unwrap();
622        let mut calc = NeighborCalc::default();
623        let opt = VesinOptions {
624            cutoff: 4.0,
625            full: true,
626            sorted: false,
627            _pad0: [0; 6],
628            padded_to: 0,
629            algorithm: 2,
630            _pad1: 0,
631            skin: 0.0,
632            n_threads: 1,
633            return_shifts: true,
634            return_distances: true,
635            return_vectors: true,
636            _pad2: 0,
637        };
638        calc.compute(&xyz, &cell, [true, true, true], opt).unwrap();
639        assert!(!calc.pairs.is_empty());
640        assert_eq!(calc.pairs.len(), calc.distances.len());
641        assert_eq!(calc.pairs.len(), calc.vectors.len());
642        let mut again = NeighborCalc::default();
643        let mut opt2 = opt;
644        opt2.skin = 0.4;
645        again
646            .compute(&xyz, &cell, [true, true, true], opt2)
647            .unwrap();
648        assert_eq!(again.pairs.len(), calc.pairs.len());
649    }
650}