minimage 0.1.4

Minimum-image convention for periodic parallelepiped cells
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# minimage

<p align="center">
  <img src="assets/branding/minimage-logo-light.svg" width="360" alt="minimage">
</p>

**Minimum-image convention** for a periodic parallelepiped.

linkcell walks k-nearest neighbours. vesin builds cutoff pair lists.
Both need the same wrap: fold through H, pick one image, never the
self image. This crate is that wrap. `Cell` holds the 3x3 lattice and
a dump-cell origin. Constructors accept LAMMPS bounds plus `xy, xz,
yz` tilts, a CON lattice or length-angle box, an ASE-style 3x3 cell,
and a vesin box.

It is a LODE library. The Rust crate is the implementation. The C ABI
(`mi_*`) is the hourglass waist, the same shape as
[linkcell](https://github.com/d-SEAMS/linkcell) and
[readcon-core](https://github.com/lode-org/readcon-core). C++ is a
RAII header over that ABI.

Docs (orgmode first, HTML export):
[lode-org.github.io/minimage](https://lode-org.github.io/minimage/).
Org catalog: [lode-org.github.io](https://lode-org.github.io/).

## Install

Rust:

```
cargo add minimage
```

C and C++ consumers take the `staticlib` (`--features capi`, on by
default) plus `include/minimage.h` or `include/minimage.hpp`. Meson,
CMake, and pkg-config all install that archive and those headers.

```
pip install minimage
```

```python
import minimage

cell = minimage.Cell.ortho(10.0, 10.0, 10.0)
assert abs(cell.dist2([0.2, 0.0, 0.0], [9.4, 0.0, 0.0]) - 0.64) < 1e-12
```

### Meson

```
meson setup build
meson compile -C build
meson install -C build
```

As a wrap, Meson exposes `minimage_dep`:

```
[wrap-git]
url = https://github.com/lode-org/minimage.git
revision = v0.1.4
depth = 1

[provide]
minimage = minimage_dep
```

```meson
minimage_dep = dependency('minimage', fallback: ['minimage', 'minimage_dep'])
```

### CMake

```
cmake -B build -DCMAKE_INSTALL_PREFIX=$PREFIX
cmake --build build
cmake --install build
```

```cmake
find_package(minimage 0.1 REQUIRED)
target_link_libraries(app PRIVATE minimage::minimage)
```

### pkg-config

```
pkg-config --cflags --libs minimage
```

## Rust

```rust
use minimage::{dist2_many, reduce_pairs, Cell};

let sim = Cell::ortho(10.0, 10.0, 10.0)?;
let sheared = Cell::from_lammps_bounds(
    15.0, 8.660254037844386, 10.0, 5.0, 0.0, 0.0, 0.0, 0.0, 0.0,
)?;
let left = [0.2, 0.0, 0.0];
let right = [9.4, 0.0, 0.0];
assert!((sim.dist2(left, right) - 0.64).abs() < 1e-12);

let qs = [[9.4, 0.0, 0.0], [1.0, 0.0, 0.0]];
let mut out = [0.0; 2];
dist2_many(&sim, left, &qs, &mut out)?;

let pairs = [[0, 1], [0, 0], [0, 1]];
let mut kept = Vec::new();
reduce_pairs(&pairs, &mut kept)?;
assert_eq!(kept, vec![[0, 1]]);
```

`Cell::from_ase`, `Cell::from_con`, `Cell::from_con_box`, and
`Cell::from_vesin` take the same row-major 3x3 lattice. Displacement
is the wrapped vector from `p` to `q`.

## License

MIT. See [LICENSE](LICENSE).