neighborlist-rs 0.1.9

High-performance neighborlist construction for atomistic systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# Rust API Documentation: neighborlist-rs

`neighborlist-rs` provides a high-performance Rust API for neighbor list construction.

## Basic Usage

To use `neighborlist-rs` in your Rust project, add it as a dependency in your `Cargo.toml`:

```toml
[dependencies]
neighborlist-rs = { git = "https://github.com/your-repo/neighborlist-rs.git" }
```

### Single System Search

```rust
use neighborlist_rs::{build_neighborlists, NeighborList};

fn main() -> Result<(), String> {
    let positions = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]];
    let cutoff = 1.5;
    
    // Non-periodic (Isolated)
    let result = build_neighborlists(&positions, cutoff, None, true)?;
    
    println!("Found {} edges", result.edge_index.len() / 2);
    
    // Periodic Boundary Conditions
    let cell_matrix = [
        [10.0, 0.0, 0.0],
        [0.0, 10.0, 0.0],
        [0.0, 0.0, 10.0]
    ];
    let pbc = [true, true, true];
    let result_pbc = build_neighborlists(
        &positions, 
        cutoff, 
        Some((&cell_matrix, pbc)), 
        true
    )?;
    
    Ok(())
}
```

### Batched Search

```rust
use neighborlist_rs::build_neighborlists_batch;

fn main() -> Result<(), String> {
    let positions = [
        [0.0, 0.0, 0.0], [1.0, 0.0, 0.0], // System 0
        [1.0, 1.0, 1.0], [9.0, 1.0, 1.0]  // System 1
    ];
    let batch = [0, 0, 1, 1];
    let cutoff = 2.5;
    
    let cell_1 = [
        [10.0, 0.0, 0.0],
        [0.0, 10.0, 0.0],
        [0.0, 0.0, 10.0]
    ];
    let pbc_1 = [true, true, true];
    
    let cells = [
        None,             // System 0 is isolated
        Some((cell_1, pbc_1)) // System 1 is periodic
    ];
    
    let result = build_neighborlists_batch(
        &positions,
        &batch,
        cutoff,
        Some(&cells),
        true
    )?;
    
    Ok(())
}
```

## Data Schema

### `NeighborList` Struct
- `edge_index: Vec<i64>`: A flat vector of length `2 * E`. It contains source indices followed by target indices: `[src_0, src_1, ..., src_E, dst_0, dst_1, ..., dst_E]`. This layout is designed for compatibility with GNN frameworks like PyTorch Geometric.
- `shifts: Vec<i32>`: A flat vector of length `3 * E`. It contains the periodic shift vectors for each edge: `[sx_0, sy_0, sz_0, sx_1, sy_1, sz_1, ...]`.

### Note on Directionality
The library currently enforces `i < j` for neighbor pairs in isolated systems and unique pairs in periodic systems. This means it returns **half-neighbors** (one direction only). If your application requires both directions (undirected graph for message passing), you should double the edges and negate the shifts for the reverse direction.