### Build and Install with Meson

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Use Meson to set up, compile, and install the d-SEAMS core. This method involves setting an installation directory and updating the PATH and LD_LIBRARY_PATH environment variables.

```bash
export INST_DIR=$HOME/.local
cd src
meson setup bbdir --prefix $INST_DIR
meson compile -C bbdir
meson install -C bbdir
# if not done
export PATH=$PATH:$INST_DIR/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$INST_DIR/lib
cd ../
yodaStruct -c lua_inputs/config.yml
```

--------------------------------

### Install pydseamslib

Source: https://context7.com/d-seams/seams-core/llms.txt

Install the Python package from PyPI. Binary wheels are available for Linux and macOS. Verify the installation by checking the version.

```bash
pip install pydseamslib

# Verify installation
python -c "import pydseamslib; print(pydseamslib.__version__)"
# 2.0.0

# With optional ASE adapter
pip install pydseamslib[ase]
```

--------------------------------

### Install pydseamslib

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/quickstart.org

Install the pydseamslib package using pip. This is the first step to using d-SEAMS.

```bash
pip install pydseamslib
```

--------------------------------

### Install Seams Core with Nix

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Installs the Seams Core project into your user environment using Nix. This is a required step after optional build steps.

```bash
nix-env -if . # Required
```

--------------------------------

### Nix Shell Usage Examples for Compiler Argument

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Provides examples of how to use nix-shell to pass the compiler argument and run a command. Demonstrates switching between different compilers like gcc5 and clang.

```nix
# Usage Example
# nix-shell --argstr compiler gcc5 --run bash
# nix-shell --argstr compiler clang --run bash
```

--------------------------------

### Nix Project Structure Setup

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Sets up the Nix project structure, importing `nixpkgs` and defining an overlay for project-specific configurations. This file is intended to be tangled with `noweb`.

```nix
<<pR_headerComments>>
# something ? default value ---- Variable declration
# pattern : body ---- Function prototype
{ nixpkgs ? import ./nixpkgs
  , <<pR_arguments>>
   }:
  # Define
  let overlay = self: buildpkgs: with buildpkgs; {
  # All the other nix files
  <<overlayFiles>>
  }; in
  # Ensure reproducibility
  nixpkgs {
  config = {};
  overlays = [overlay];
  }
```

--------------------------------

### Install pixi Environment Manager

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/contributing/index.org

Installs the pixi environment and task manager, which is required for managing d-SEAMS dependencies and build processes.

```bash
curl -fsSL https://pixi.sh/install.sh | bash
```

--------------------------------

### Build d-SEAMS from Source

Source: https://context7.com/d-seams/seams-core/llms.txt

Build the d-SEAMS library from source using Meson and pixi. This involves cloning the repository, setting up the build directory, compiling, and installing.

```bash
git clone https://github.com/d-SEAMS/seams-core
cd seams-core
meson setup bbdir --prefix $HOME/.local -Dwith_python=true -Dwith_tests=true
meson compile -C bbdir
meson install -C bbdir
```

--------------------------------

### Install Dependencies with Spack

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Install necessary libraries and tools using Spack. This includes Eigen, Lua, and various build/analysis tools. Note that this method is currently not working.

```bash
spack install eigen@3.3.9 lua@5.2
spack install catch2 fmt yaml-cpp openblas boost cmake ninja meson
spack load catch2 fmt yaml-cpp openblas boost cmake ninja meson eigen@3.3.9 lua@5.2
luarocks install luafilesystem
```

--------------------------------

### Add Details in Lua

Source: https://github.com/d-seams/seams-core/blob/main/markdown/examples.md

Use this Lua snippet to add details within the nucleation example. Ensure the Lua environment is correctly set up.

```lua
print("Add details")
```

--------------------------------

### Install Dependencies with Conda

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Use this command to create and activate a Conda environment and install the Lua filesystem library. This is a fallback for MacOS users.

```bash
cd ~/seams-core
micromamba create -f environment.yml
micromamba activate dseams
luarocks install luafilesystem
```

--------------------------------

### Install pydseamslib with ASE dependency

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/howto/ase-integration.org

Install the pydseamslib library with the optional ASE dependency using pip.

```bash
pip install pydseamslib[ase]
```

--------------------------------

### Install Git Pre-Commit Hook

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Installs the pre-commit hook script to enforce code formatting with clang-format. Ensure clang-format is configured before running.

```bash
./scripts/git-pre-commit-format install
```

--------------------------------

### Activate Spack Environment

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Activate a Spack environment and install the Lua filesystem library. This is a prerequisite before building with Spack.

```bash
spack env activate $(pwd)
# After loading the packages
luarocks install luafilesystem
```

--------------------------------

### Install Cachix and Use Binary Cache

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Installs the Cachix tool and configures it to use the dseams binary cache for faster Nix builds. This is an optional step to speed up the initial build.

```bash
# Install cachix
nix-env -iA cachix -f https://cachix.org/api/v1/install
# Use the binary cache
cachix use dseams
```

--------------------------------

### Verify pydseamslib Installation

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/quickstart.org

Verify the installation by checking the installed version of the pydseamslib package.

```python
python -c "import pydseamslib; print(pydseamslib.__version__)"
```

--------------------------------

### Configure and Build with Spack (Ninja)

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Configure the project using CMake with the Ninja generator, specifying build type, installation prefix, and compiler flags for profiling and address sanitization. This method is not working at the moment.

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \
 -DCMAKE_EXPORT_COMPILE_COMMANDS=YES -GNinja \
 -DCMAKE_INSTALL_PREFIX=$HOME/.local \
 -DCMAKE_CXX_FLAGS="-pg -fsanitize=address " \
 -DCMAKE_EXE_LINKER_FLAGS=-pg -DCMAKE_SHARED_LINKER_FLAGS=-pg \
 -DBUILD_TESTING=NO
cmake --build build
```

--------------------------------

### Build and Install with Conda

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Configure, build, and install the d-SEAMS core using CMake after setting up the Eigen3 include directory. This command also runs the yodaStruct executable.

```bash
mkdir build
cd build
export EIGEN3_INCLUDE_DIR=$CONDA_PREFIX/include/eigen3
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=YES -DCMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX ../
make -j$(nproc)
make install
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CONDA_PREFIX/lib $CONDA_PREFIX/bin/yodaStruct -c lua_inputs/config.yml
```

--------------------------------

### Verify Python Package Installation

Source: https://context7.com/d-seams/seams-core/llms.txt

Run this command to verify that the pydseamslib Python package is installed correctly and the Trajectory class is accessible.

```python
python -c "from pydseamslib import Trajectory; print('OK')"
```

--------------------------------

### Example Commit Message Style

Source: https://github.com/d-seams/seams-core/blob/main/CONTRIBUTING.md

Follow this commit message structure for clarity and consistency. Include the file name or topic, a concise description, optional details, and mandatory co-authorship if applicable.

```gitcommit
fileName: Thing I did
Some subHeading things

So this change was to do that thing I thought was good. Also there was this
other person who thought so too, so then I ate a sandwich and we got the code
done. I am writing this but really, honestly, two people did this.


Co-authored-by: Joel Doe <joel@iexistreally.com>
```

--------------------------------

### LAMMPS Trajectory File Format Example

Source: https://context7.com/d-seams/seams-core/llms.txt

Illustrates the structure of a standard LAMMPS text dump file, including required columns and conventional atom type assignments for water simulations.

```text
ITEM: TIMESTEP
15000000
ITEM: NUMBER OF ATOMS
750
ITEM: BOX BOUNDS pp pp pp
-2.0000000000000000e+01 2.0000000000000000e+01
-2.0000000000000000e+01 2.0000000000000000e+01
 7.0316731227034523e+00 1.8723432986906221e+02
ITEM: ATOMS id mol type x y z c_peratom
1 1 2  1.62441 -0.745636 131.621 -28.449
2 1 1  2.11159 -0.763153 132.444   9.609
3 1 1  0.72705 -0.969064 131.868   9.366
```

--------------------------------

### Specify Lua Build Dependency

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Adds Lua as a build dependency for a Nix derivation, requiring a Nix lua setup.

```nix
lua
```

--------------------------------

### Define Compiler Argument

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Enables argument parsing for Nix commands, allowing the 'compiler' argument to be passed. Example usage with nix-shell is provided.

```nix
compiler ? "clang"
```

--------------------------------

### Build with Nix

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Initiate the build process using Nix from the root directory. This is the recommended method but is noted as not working at the moment.

```bash
# Make sure there are no artifacts
rm -rf build
```

--------------------------------

### Nix Package Definition Entry Point

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Sets up the main Nix package definition file. It imports definitions from a 'let' block and then imports the source.

```nix
# Define
let
  <<nn_pkgVars>>
in
  import src
```

--------------------------------

### Build d-SEAMS Core from Source

Source: https://context7.com/d-seams/seams-core/llms.txt

Provides commands for cloning the d-SEAMS repository, setting up a Conda/micromamba environment, configuring the build with Meson, and compiling/installing the core library and Python bindings.

```bash
# Clone
git clone https://github.com/d-SEAMS/seams-core && cd seams-core

# Conda/micromamba environment (recommended for macOS)
micromamba create -f environment.yml
micromamba activate dseams

# Configure with Meson (core library + Python bindings + tests)
meson setup bbdir \
  --prefix $HOME/.local \
  -Dwith_python=true \
  -Dwith_tests=true

# Build and install
Meson compile -C bbdir
Meson install -C bbdir

# Run tests
Meson test -C bbdir --timeout 120
```

--------------------------------

### Include Core Nix Inputs

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Lists essential Nix inputs required for the project, including lib, boost, and cmake.

```nix
lib
boost
cmake
```

--------------------------------

### Clone and Build d-SEAMS Project

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/contributing/index.org

Clones the d-SEAMS repository and sets up the build environment using pixi. This includes configuring the Meson build system and compiling the C++ library and Python extensions.

```bash
git clone https://github.com/d-SEAMS/seams-core.git
cd seams-core
```

```bash
pixi run setup
```

```bash
pixi run build
```

--------------------------------

### Fetch GitHub Repository Configuration

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Defines how to fetch a repository from GitHub using configuration from a JSON file. This is useful for managing external dependencies.

```nix
let
  data = builtins.fromJSON (builtins.readFile path);
in
  fetchFromGitHub { inherit (data) owner repo rev sha256; }
```

--------------------------------

### Enter Pure Nix Development Shell

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Enters a pure Nix shell environment from the project root. This ensures a consistent development environment.

```bash
# From the project root
nix-shell --pure
```

--------------------------------

### Fetch JSON Source with Nix

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

A Nix helper function to fetch source code described in a `<package>.src.json` file, utilizing `fetchFromGitHub`.

```nix
{ fetchFromGitHub }:

# fetches the source described in the <package>.src.json
```

--------------------------------

### LAMMPS Trajectory File Structure

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/data-formats.org

This is an example of a single frame in the standard text format of a LAMMPS dump file. It includes timestep, atom count, box bounds, and atom data.

```text
ITEM: TIMESTEP
15000000
ITEM: NUMBER OF ATOMS
750
ITEM: BOX BOUNDS pp pp pp
-2.0000000000000000e+01 2.0000000000000000e+01
-2.0000000000000000e+01 2.0000000000000000e+01
7.0316731227034523e+00 1.8723432986906221e+02
ITEM: ATOMS id mol type x y z c_peratom
1 1 2 1.62441 -0.745636 131.621 -28.449
2 1 1 2.11159 -0.763153 132.444 9.60885
3 1 1 0.727051 -0.969064 131.868 9.36579
```

--------------------------------

### Default Nix Build Configuration

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

A `default.nix` file that imports Nix packages from a local `./nix` directory and passes them to `yodaStruct`.

```nix
let
  buildpkgs = import ./nix {};
in
buildpkgs.yodaStruct
```

--------------------------------

### Build Project with Nix and CMake

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Drops into a pure Nix shell for development builds. Uses CMake to configure the build with Ninja as the generator, enabling debug mode and other specified options. Finally, it builds the project using Ninja.

```bash
nix-shell --pure --run bash --show-trace --verbose
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DNO_WARN=TRUE \
 -DFIND_EIGEN=TRUE \
 -DCMAKE_EXPORT_COMPILE_COMMANDS=1 \
 -G "Ninja"
ninja
```

--------------------------------

### Get Final Ice Type Classification (Low-Level)

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/quickstart.org

Obtain the final ice type classification for each atom using _core.getIceTypePlus. This function writes classification data to a file and returns the classified point cloud.

```python
# Write the full CHILL+ classification to disk and get the typed cloud back.
# This writes an output file and classifies each atom.
cloud = _core.getIceTypePlus(
    yCloud=cloud,
    nList=nList,
    path=".",
    firstFrame=1,
    isSlice=False,
    outputFileName="ice_classification.dat",
)
```

--------------------------------

### Test Build with Nix and Clean Build Directory

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Tests the project build using Nix. If a CMake error occurs, this snippet shows how to clean the build directory and attempt the build again, including garbage collection as a worst-case scenario.

```bash
nix-build .
# Outputs are in ./result
# If you get a CMake error
rm -rf build
nix-store --delete /nix/store/$whatever # $whatever is the derivation complaining
nix-collect-garbage # then try again [worst case scenario]
```

--------------------------------

### Run yodaStruct Tests

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Executes the yodaStruct test suite using the yodaStruct_test binary. This process involves entering the Nix environment, building, and then running the tests.

```bash
./testBuild.sh
# At this point the binary and library are copied into the root
# One might, in a foolhardy attempt, use gdb at this point
# Here be dragons :)
# USE NIX
# Anyway
gdb --args ./yodaStruct -c lua_inputs/config.yml
# quit gdb with quit
# Go run the test binary
cd shellBuild
./yodaStruct_test
```

--------------------------------

### Run Full Topological Unit Matching Bulk Analysis

Source: https://context7.com/d-seams/seams-core/llms.txt

Executes the complete topological unit matching pipeline for bulk ice, including optional cluster analysis. Ensure necessary input files and directories are prepared.

```python
from pydseamslib import _core
import os

cloud  = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nList  = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)
hbonds = _core.populateHbonds("input/traj/exampleTraj.lammpstrj", cloud, nList, 1, 1)
hbonds_idx = _core.neighbourListByIndex(yCloud=cloud, nList=hbonds)
rings  = _core.ringNetwork(nList=hbonds_idx, maxDepth=6)

os.makedirs("output/tum", exist_ok=True)
_core.topoUnitMatchingBulk(
    path="output/tum/",
    rings=rings,
    nList=hbonds_idx,
    yCloud=cloud,
    firstFrame=1,
    onlyTetrahedral=True,
)
# Writes cage counts (DDC/HC), per-atom cage type, and cluster statistics
```

--------------------------------

### Run full CHILL+ classification and write to file

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Runs full CHILL+ classification, writes results to a file, and sets the iceType field on each atom. Requires a point cloud, neighbor list, path, frame information, and output file name.

```python
cloud = _core.getIceTypePlus(yCloud, nList, path, firstFrame, isSlice, outputFileName)
```

--------------------------------

### Nix Call Package for SharkML

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Demonstrates how to call the SharkML Nix package expression using callPackage. This is typically used to add the package to a Nix environment.

```nix
sharkML = callPackage ./pkgs/sharkML/sharkML.nix { };
```

--------------------------------

### Run and Debug Project Executable

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Executes the 'yodaStruct' tool with a specified configuration file. For debugging, it launches 'yodaStruct' under GDB with the same configuration.

```bash
# Test
cd ../
yodaStruct -c lua_inputs/config.yml
# Debug
gdb --args yodaStruct -c lua_inputs/config.yml
```

--------------------------------

### Compute q6 bond order parameter

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Computes the q6 bond order parameter for each atom. Requires a point cloud and its neighbor list.

```python
q6 = _core.getq6(yCloud, nList, isSlice)
```

--------------------------------

### Define Catch2 Package in Nix

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Creates a Nix derivation for the Catch2 testing framework. This is a header-only library, and the derivation ensures it's correctly packaged for use in Nix projects.

```nix
{ clangStdenv, fetchurl }:

clangStdenv.mkDerivation rec {
  name = "catch-${version}";
  version = "2.5.0";

  src = fetchurl {
      url = "https://github.com/catchorg/Catch2/releases/download/v2.5.0/catch.hpp";
      sha256 = "a87d5c0417aaf1c3d16565244a1b643e1999d5838d842823731bc18560268f94";
  };

  # This is a header only library. No unpacking needed. Seems like we need to create
  # _some_ folder, otherwise we get errors.
  unpackCmd = "mkdir fake_dir";

  installPhase = ''
    mkdir -p $out/include/catch
    cp ${src} $out/include/catch/catch.hpp
  '';

  meta = {
    description = "A modern, C++-native, header-only, test framework for unit-tests, TDD and BDD - using C++11, C++14, C++17 and later";
    homepage = http://catch-lib.net;
  };
}
```

--------------------------------

### Nix Call Package for yaml-cpp

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Demonstrates how to call the yaml-cpp Nix package expression using callPackage. This is typically used to add the package to a Nix environment.

```nix
yamlCpp = callPackage ./pkgs/yaml-cpp/yaml-cpp.nix { };
```

--------------------------------

### d-SEAMS Project Structure Overview

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/contributing/index.org

Provides a hierarchical view of the d-SEAMS project directory, detailing the location of source files, tests, input data, and configuration files.

```text
seams-core/
  src/
    include/
      internal/
      external/
    mol_sys.cpp
    neighbours.cpp
    bond.cpp
    bop.cpp
    ring.cpp
    franzblau.cpp
    bulkTUM.cpp
    topo_one_dim.cpp
    topo_two_dim.cpp
    ...
  python/
    bindings.cpp
    pydseamslib/
      __init__.py
      adapters/
        _ase.py
  tests/
    python/
    *.cpp
  input/
    traj/
  Meson.build
  pixi.toml
  pyproject.toml
```

--------------------------------

### Run Full CHILL+ Classification and Write Output

Source: https://context7.com/d-seams/seams-core/llms.txt

Applies CHILL+ phase-assignment rules to `c_ij` correlations, sets `iceType` on each atom, and writes per-frame classification data to disk. Ensure the output directory exists.

```python
from pydseamslib import _core
from collections import Counter
import os

cloud = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nList = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)
cloud = _core.getCorrelPlus(yCloud=cloud, nList=nList, isSlice=False)

os.makedirs("output", exist_ok=True)
cloud = _core.getIceTypePlus(
    yCloud=cloud,
    nList=nList,
    path="output/",
    firstFrame=1,
    isSlice=False,
    outputFileName="chillPlus.txt",
)

counts = Counter(pt.iceType.name for pt in cloud.pts)
print("Ice type statistics for frame 1:")
for name, n in sorted(counts.items()):
    print(f"  {name:16s}: {n:4d}")
# output/chillPlus.txt now contains per-atom classifications for OVITO/VMD
```

--------------------------------

### Nix Call Package for yodaStruct

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Demonstrates how to call the yodaStruct Nix package expression using callPackage. This is typically used to add the program to a Nix environment.

```nix
yodaStruct = callPackage ./yodaStruct.nix { };
```

--------------------------------

### Build hydrogen bond network

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Builds a hydrogen bond network by reading hydrogen positions from a LAMMPS dump file and applying geometric criteria. Requires an oxygen point cloud and its neighbor list.

```python
hbonds = _core.populateHbonds(filename, yCloud, nList, targetFrame, Htype)
```

--------------------------------

### Build Neighbor List (Low-Level)

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/quickstart.org

Build a neighbor list for oxygen atoms within a specified distance cutoff using _core.neighListO. This is a prerequisite for hydrogen bond computation.

```python
# Build a neighbour list for oxygens within 3.5 Angstroms
nList = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)

print(f"Neighbour list has {len(nList)} entries (one per atom)")
# Each entry is a list of atom IDs: [self, neighbour1, neighbour2, ...]
print(f"Atom 0 neighbours: {len(nList[0]) - 1}")
```

--------------------------------

### Build Index-based Neighbor List Directly

Source: https://context7.com/d-seams/seams-core/llms.txt

Combines the functionality of `neighListO` and `neighbourListByIndex` into a single call, directly generating an index-based neighbor list.

```python
from pydseamslib import _core

cloud    = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nListIdx = _core.getNewNeighbourListByIndex(yCloud=cloud, cutoff=3.5)
print(f"Index-based entries: {len(nListIdx)}")
```

--------------------------------

### Run d-SEAMS Tests

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/contributing/index.org

Executes both C++ (Catch2) and Python (pytest) test suites for the d-SEAMS project. Ensure you are in the project's root directory before running these commands.

```bash
pixi run test
```

```bash
pixi run pytest
```

--------------------------------

### Configure Nix Package Channel Source

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Defines the source for a Nix package channel using a JSON file. Specifies the owner, repository, branch, revision, and SHA256 hash.

```json
{
  "owner": "NixOS",
  "repo": "nixpkgs-channels",
  "branch": "nixos-unstable",
  "rev": "ae002fe44e96b868c62581e8066d559ca2179e01",
  "sha256": "1bawyz3ksw2sihv6vsgbvhdm4kn63xrrj5bavg6mz5mxml9rji89"
}
```

--------------------------------

### Build index-based neighbor list directly

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Builds an index-based neighbor list by combining neighbor search and index conversion. Useful for direct neighbor list creation.

```python
nListIdx = _core.getNewNeighbourListByIndex(yCloud, cutoff)
```

--------------------------------

### populateHbonds

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Builds a hydrogen bond network by reading hydrogen positions from a LAMMPS dump file and applying geometric criteria.

```APIDOC
## populateHbonds

### Description
Build a hydrogen bond network by reading hydrogen positions from the trajectory and applying geometric criteria.

### Method
`populateHbonds(filename, yCloud, nList, targetFrame, Htype)`

### Parameters
- **filename** (str) - Path to LAMMPS dump file.
- **yCloud** (PointCloudDouble) - Oxygen point cloud.
- **nList** (list[list[int]]) - Oxygen neighbour list.
- **targetFrame** (int) - Frame number (1-indexed).
- **Htype** (int) - Hydrogen atom type.

### Returns
- list[list[int]] - A list of lists with the same structure as the neighbour list, but containing only hydrogen-bonded pairs.
```

--------------------------------

### populateHbonds

Source: https://context7.com/d-seams/seams-core/llms.txt

Constructs the hydrogen bond network by analyzing oxygen neighbor lists and re-reading hydrogen atom positions. It returns a list of hydrogen-bonded pairs.

```APIDOC
## populateHbonds — build hydrogen bond network

Constructs the hydrogen bond network by re-reading hydrogen atom positions from the trajectory and applying geometric criteria against the oxygen neighbour list. Returns a neighbour-list-structured list containing only hydrogen-bonded pairs.

```python
from pydseamslib import _core

cloud = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nList = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)

hbonds = _core.populateHbonds(
    filename="input/traj/exampleTraj.lammpstrj",
    yCloud=cloud,
    nList=nList,
    targetFrame=1,
    Htype=1,          # LAMMPS atom type for hydrogen
)

```
```

--------------------------------

### Parse Nix Package Channel Specification from JSON

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Parses the Nix package channel specification from a JSON file using builtins.fromJSON and builtins.readFile.

```nix
spec = builtins.fromJSON (builtins.readFile ./default.src.json);
```

--------------------------------

### Compute Hydrogen Bonds (Low-Level)

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/quickstart.org

Compute the hydrogen bond network using _core.populateHbonds, which requires the trajectory file, atom cloud, neighbor list, and hydrogen atom type.

```python
# Build the hydrogen bond network.
# Htype=1 is the hydrogen atom type in the LAMMPS file.
hbonds = _core.populateHbonds(
    filename="input/traj/exampleTraj.lammpstrj",
    yCloud=cloud,
    nList=nList,
    targetFrame=1,
    Htype=1,
)

print(f"H-bond list has {len(hbonds)} entries")
# Count average number of H-bonds per oxygen
total_hbonds = sum(len(hb) - 1 for hb in hbonds)  # subtract self from each
avg_hbonds = total_hbonds / len(hbonds)
print(f"Average H-bonds per oxygen: {avg_hbonds:.2f}")
```

--------------------------------

### getq6

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Computes the q6 bond order parameter for each atom in the point cloud.

```APIDOC
## getq6

### Description
Compute the q6 bond order parameter for each atom.

### Method
`getq6(yCloud, nList, isSlice)`

### Parameters
- **yCloud** (PointCloudDouble) - Input point cloud.
- **nList** (list[list[int]]) - Index-based neighbour list.
- **isSlice** (bool) - Whether to process a slice of the point cloud.

### Returns
- list - List of q6 values for each atom.
```

--------------------------------

### Specify Boost Runtime Dependency

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Adds Boost as a runtime dependency, typically linked against, hence specified as a buildInput.

```nix
boost
```

--------------------------------

### Run yodaStruct Command

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Executes the yodaStruct command-line tool with a specified configuration file. The paths in the config file are relative to the directory from which this command is run.

```bash
yodaStruct -c lua_inputs/config.yml
```

--------------------------------

### AtomStateType Enumeration

Source: https://context7.com/d-seams/seams-core/llms.txt

Demonstrates the AtomStateType enumeration used for classifying atoms into different ice phases or water states. Lists all available variants.

```python
from pydseamslib._core import AtomStateType

# All variants:
# AtomStateType.cubic          – cubic ice (Ic)
# AtomStateType.hexagonal      – hexagonal ice (Ih)
# AtomStateType.water          – liquid/amorphous water
# AtomStateType.interfacial    – interfacial ice
# AtomStateType.clathrate      – clathrate hydrate
# AtomStateType.interClathrate – interfacial clathrate
```

--------------------------------

### Fetch Tarball for Nix Package Source

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Defines a function to fetch the tarball for the Nix package source based on the parsed JSON specification. Includes URL and SHA256 hash.

```nix
fetchTarball = import ./fetchTarball-compat.nix;
src = fetchTarball {
  url = "https://github.com/${spec.owner}/${spec.repo}/archive/${spec.rev}.tar.gz";
  sha256 = spec.sha256;
};
```

--------------------------------

### Define Nix Derivation with Dependencies

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Defines a Nix derivation for a project, specifying build and runtime dependencies. Uses lib.cleanSource to manage source code.

```nix
{
clangStdenv,
<<yS_inputs>>
}:
  clangStdenv.mkDerivation {
  name = "yodaStruct";
  src = lib.cleanSource ../.;
  nativeBuildInputs = [
  <<yS_buildDeps>>
  ];
  buildInputs = [
  <<yS_runDeps>>
  ];
  }
```

--------------------------------

### Generate Compile Commands for Language Server

Source: https://github.com/d-seams/seams-core/blob/main/README.md

Generates a compile_commands.json file within a pure Nix environment, which is necessary for language servers like ccls to provide features such as code completion and navigation. The file is then copied to the project root.

```bash
# Pure environment
nix-shell --pure
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ../
cp compile_commands.json ../
```

--------------------------------

### Trajectory.__init__

Source: https://context7.com/d-seams/seams-core/llms.txt

Loads a LAMMPS trajectory frame, setting up neighbor lists, H-bond networks, and ring lists. It allows filtering by atom type and specifies a cutoff radius.

```APIDOC
## Trajectory.__init__ — load a trajectory frame

High-level entry point that reads a LAMMPS dump file, selecting atoms of a given type, and sets up lazy-computed neighbour list, H-bond network, and ring list.

```python
from pydseamslib import Trajectory

# Load frame 1, selecting oxygen atoms (type=2), using 3.5 Å cutoff
traj = Trajectory(
    filename="input/traj/exampleTraj.lammpstrj",
    frame=1,
    atom_type=2,
    cutoff=3.5,
)

print(f"Atoms loaded : {traj.n_atoms}")   # 250 (oxygen only)
print(f"Box [Å]      : {traj.box}")       # [Lx, Ly, Lz]

# Lazy properties — computed on first access, cached thereafter
print(f"Neighbour list entries   : {len(traj.neighbor_list)}")   # 250
print(f"H-bond list entries      : {len(traj.hbonds)}")          # 250
print(f"Primitive rings found    : {len(traj.rings)}")           # varies
```
```

--------------------------------

### Nix Build Expression for SharkML

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

Defines a standard cmake-based build for the SharkML library using Nix. It includes dependencies like boost, openblas, and liblapack.

```nix
# A standard cmake-based build
{ clangStdenv, fetchJSON, cmake, boost, openblas, liblapack }:
clangStdenv.mkDerivation {
  name = "sharkML-master";
  src = fetchJSON ./sharkML.src.json;
  nativeBuildInputs = [ cmake boost openblas liblapack ];
}
```

--------------------------------

### YAML Cpp Nix Package Definition

Source: https://github.com/d-seams/seams-core/blob/main/literateNix.org

This is a placeholder for the Nix expression to build the yaml-cpp library. The actual implementation is missing in the provided source.

```nix
{ stdenv, fetchurl, cmake }:
stdenv.mkDerivation {
  name = "yaml-cpp-0.6.3";
  src = fetchurl {
    url = "https://github.com/jbeder/yaml-cpp/archive/refs/tags/yaml-cpp-0.6.3.tar.gz";
    sha256 = "04z4v11488988888888888888888888888888888888888888888";
  };
  nativeBuildInputs = [ cmake ];
  buildInputs = [ ];
  meta = {
    description = "A C++ YAML parser and emitter that loads or saves YAML data into C++ objects.";
    homepage = https://github.com/jbeder/yaml-cpp;
    license = lib.licenses.mit;
    platforms = lib.platforms.unix;
  };
}

```

--------------------------------

### `getIceTypePlus` — run full CHILL+ classification and write output

Source: https://context7.com/d-seams/seams-core/llms.txt

Applies the CHILL+ phase-assignment rules to the c_ij correlations computed by `getCorrelPlus`. Sets `iceType` on every atom and writes per-frame classification data to disk.

```APIDOC
## `getIceTypePlus` — run full CHILL+ classification and write output

### Description
Applies the CHILL+ phase-assignment rules to the c_ij correlations computed by `getCorrelPlus`. Sets `iceType` on every atom and writes per-frame classification data to disk.

### Usage
```python
from pydseamslib import _core
from collections import Counter
import os

cloud = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nList = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)
cloud = _core.getCorrelPlus(yCloud=cloud, nList=nList, isSlice=False)

os.makedirs("output", exist_ok=True)
cloud = _core.getIceTypePlus(
    yCloud=cloud,
    nList=nList,
    path="output/",
    firstFrame=1,
    isSlice=False,
    outputFileName="chillPlus.txt",
)

counts = Counter(pt.iceType.name for pt in cloud.pts)
print("Ice type statistics for frame 1:")
for name, n in sorted(counts.items()):
    print(f"  {name:16s}: {n:4d}")
# output/chillPlus.txt now contains per-atom classifications for OVITO/VMD
```
```

--------------------------------

### Classify 3D Rings with `bulkPolygonRingAnalysis`

Source: https://context7.com/d-seams/seams-core/llms.txt

Classifies primitive rings by polygon type for bulk three-dimensional ice. Requires ring network data and system information.

```python
from pydseamslib import _core
import os

cloud  = _core.readLammpsTrjreduced("input/traj/exampleTraj.lammpstrj", 1, 2, False, [0,0,0], [0,0,0])
nList  = _core.neighListO(rcutoff=3.5, yCloud=cloud, typeI=2)
hbonds = _core.populateHbonds("input/traj/exampleTraj.lammpstrj", cloud, nList, 1, 1)
hbonds_idx = _core.neighbourListByIndex(yCloud=cloud, nList=hbonds)
rings  = _core.ringNetwork(nList=hbonds_idx, maxDepth=6)

os.makedirs("output/ringsB", exist_ok=True)
_core.bulkPolygonRingAnalysis(
    path="output/ringsB/",
    rings=rings,
    nList=hbonds_idx,
    yCloud=cloud,
    maxDepth=6,
    firstFrame=1,
)
```

--------------------------------

### Compute CHILL+ bond-order correlations

Source: https://github.com/d-seams/seams-core/blob/main/docs/orgmode/reference/api.org

Computes CHILL+ bond-order correlations and populates the c_ij field on each atom in the returned cloud. Requires a point cloud and its neighbor list.

```python
cloud = _core.getCorrelPlus(yCloud, nList, isSlice)
```