Bramble

Purpose

Tip

Detailed documentation can be found here.

Bramble is a single atom pattern recognition algorithm based on the Common Neighbor Analysis method. It can efficiently construct CNA fingerprints per atom and connect these fingerprints to a (customizable) pattern library to add labels to the fingerprints.

For fingerprints that are (still) unknown or for atoms that have a more amorphous chemical environment, Bramble comes bundled with a similarity analysis tool. Although relatively computationally expensive to execute, it yields a powerful similarity metric by which the extent that two chemical environments are the same can be probed.

Compilation

Ensure you have the necessary dependencies installed on your system.

sudo apt install -y build-essential cmake libboost-all-dev pkg-config libeigen3-dev libtclap-dev

Next, clone the repository and combile Bramble using

mkdir build && cd build
cmake ../src
make -j

To test that Bramble is working, run the test suite

make test

For debugging purposes, one can run

CTEST_OUTPUT_ON_FAILURE=TRUE make test

CUDA support

To compile bramble with CUDA support, run

cmake ../src -DMOD_CUDA=1 -DCUDA_ARCH=sm_89

where the value for DCUDA_ARCH should match the architecture of your graphical card. A nice overview is given here. For example, for a RTX 4090, -DCUDA_ARCH=sm_89.

Docker container

Rather than compiling Bramble yourself, you can also make direct use of the Bramble docker container. This container is built on top of the NVidia CUDA container allowing you to use the CUDA-enabled version of Bramble.

To use the Docker container, first download it from Docker Hub

docker pull ivofilot/bramble

Next, launch the container and link a volume on your hard drive to interact with. This folder should contain the files you wish to work with.

docker run --name bramble -v "D:/bramble-data":/home/bramble/data -d ivofilot/bramble:latest

This will launch the bramble image, which you check using

docker ps

To execute Bramble, simply log into the container and use the same kind of commands you would normally use for running Bramble.

docker exec -it bramble /bin/bash

Go to the /home/bramble/data folder and make sure you have copied patterns.json and pa_fcc111.txt to this folder. Since the bramble executable is available from the path, you can directly invoke it. To perform a pattern identification, run

cd /home/bramble/data
bramble -p patterns.json -i POSCAR_Rh111 -o pa_fcc111.txt