<!-- https://docs.dseams.info/user/howto/bindings.md -->

# Use a language binding {#use-a-language-binding}

This repository builds the engine, the C API `libseams` (`include/seams.h`),
the C ABI `libseams_lang` (`bindings/cxx/seams_lang.h`), and the `seams`
command.

[C](../../stable/c.md) and [C++](../../stable/cpp.md) document those libraries.

Every other language is its own repository, with its own documentation,
tests, and releases. A binding’s version is the seams-core version it was
built against. The Python release for this engine is `pydseamslib` 2.14.0.
Each repository’s README has the install command.

## Languages {#languages}

| Language | Repository | Package | Links |
| --- | --- | --- | --- |
| Python | d-SEAMS/PydSEAMSlib | pydseamslib | libseams, libseams_lang |
| Lua, Fennel | d-SEAMS/yodaStruct | Git source, require("dseams") | libseams |
| R | d-SEAMS/dseams-r | dseams | libseams_lang |
| Julia | d-SEAMS/Dseams.jl | Dseams, engine from libseams_jll | libseams_lang, libseams |
| Rust | d-SEAMS/dseams-rs | crates dseams-sys, dseams | libseams |
| Fortran | d-SEAMS/dseams-fortran | fpm Git dependency dseams | libseams |

`import dseams` is the array API over `libseams`: `dseams.Frame`,
`chill_plus`, `q4q6`, `neighbours`, `rings`, and `from_ase`.
`import pydseams` and `import pydseamslib` are the trajectory package.
`pydseams.read` opens a dump. `dseams.userframe` is the Frame over
`libseams_lang`, documented on the
[Python Frame](../../reference/python-frame.md) page.
`Dseams` calls `libseams_lang` for a frame and `libseams` for the
re-exported `seams_*` functions. `libseams_jll` supplies the engine
binary. The same repository includes `Seams`, an example of the
`libseams` C API.
The R package compiles the engine it ships, and the calls in its README
use `libseams_lang`.

## Ice Ih {#ice-ih}

`input/traj/ice1h.lammpstrj` is one orthorhombic frame of ice Ih: 128
oxygens, every atom LAMMPS type 1. The path is relative to a seams-core
checkout. `dseams.Frame` stores the coordinates and the three edge
lengths. Published CHILL+ labels every oxygen hexagonal, so `counts[1]`
is 128. The ring histogram holds 256 six-rings, so `histogram[6]` is 256.
The mean local q6 at 3.5 Å is 0.625855. The cutoff neighbour list holds
512 directed pairs, four per oxygen, so `offsets[-1]` is 512.

```python
>>> import numpy as np
>>> import dseams
>>> def ice():
...     xyz, edges, reading = [], [], False
...     handle = open("input/traj/ice1h.lammpstrj")
...     try:
...         while True:
...             line = handle.readline()
...             if line == "":
...                 break
...             if line.startswith("ITEM: BOX BOUNDS"):
...                 edges = []
...                 for _ in range(3):
...                     lo, hi = handle.readline().split()[:2]
...                     edges.append(float(hi) - float(lo))
...             elif line.startswith("ITEM: ATOMS"):
...                 reading = True
...             elif reading:
...                 parts = line.split()
...                 if len(parts) < 5:
...                     break
...                 xyz.append([float(v) for v in parts[2:5]])
...     finally:
...         handle.close()
...     return xyz, edges
>>> xyz, edges = ice()
>>> len(xyz)
128
>>> frame = dseams.Frame()
>>> frame.set_frame(np.asarray(xyz), np.asarray(edges))
>>> frame.count()
128
>>> offsets, columns = frame.neighbours(3.5)
>>> int(offsets[-1])
512
>>> sizes, symmetry, histogram, fraction = frame.rings(3.5, 6)
>>> int(histogram[6])
256
>>> q4, q6 = frame.q4q6(3.5)
>>> round(float(q6.mean()), 6)
0.625855
>>> labels, counts = frame.chill_plus()
>>> int(counts[1])
128
```

These four commands print that census. `seams rings` prints two lines,
and the other three commands print one line each. `seams steinhardt`
also prints the Lechner-Dellago q6-bar. `seams cn` with this cutoff and
type prints `nI 128`, the number of atoms in the coordination sum.

```bash
seams read input/traj/ice1h.lammpstrj
seams rings input/traj/ice1h.lammpstrj --cutoff 3.5 --type 1
seams steinhardt input/traj/ice1h.lammpstrj --cutoff 3.5 --l 6 --type 1
seams chill-plus input/traj/ice1h.lammpstrj --cutoff 3.5 --type 1
```

```text
nop 128 frame 1 box 15.6457 14.7071 18.073
nop 128 rings 256
6 256
nop 128 q6 0.625855 q6bar 0.562449
nop 128 hexagonal 128
```

`dseams.from_ase` returns positions and a nine-number LAMMPS cell for
`set_frame`. The [Python Frame](../../reference/python-frame.md) page
runs that round trip on this file.

## What the bindings share {#what-the-bindings-share}

The classifiers run in the engine, and every binding calls those
functions. `seams_q4q6` in `include/seams.h` and `seams_frame_q4_q6` in
`bindings/cxx/seams_lang.h` compute cutoff-shell q4 and q6.
`seams steinhardt` prints the local mean and the Lechner-Dellago average
for each degree named by `--l`. The default is `4,6`. The accepted
degrees are 3, 4, 6, 8, and 12. Degrees 3 and 12 are the Zeron hydrate
pair. [Local q4 and q6](q4-q6.md) is that command.

## Recordings {#recordings}

Each binding below has a short screencast.
The full set is on the [videos](../../videos/index.md) page.

### C {#c}

### C++ {#id2}

### Fortran {#fortran}

### Python {#python}

### Rust {#rust}

### Julia {#julia}

### R {#r}

### Lua and Fennel {#lua-and-fennel}
