Merge pull request #2 from ifilot/develop

Adding brambletool

.github/workflows/stats.yml

@@ -0,0 +1,22 @@
+name: stats
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+  pull_request:
+    branches: [ "master", "develop" ]
+
+jobs:
+  build-stats:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: sudo apt update && sudo apt install -y cloc
+    - name: Collect package statistics
+      run:  cloc . --report-file=stats.txt
+    - name: Store package statistics
+      uses: actions/upload-artifact@v3
+      with:
+        name: stats
+        path: ./stats.txt

README.md

@@ -7,7 +7,8 @@
 
 ## Purpose
 
-Atomic pattern recognition utility based on the CNA algorithm. Bramble is the refactored version of [Barnacle](https://gitlab.tue.nl/inorganic-materials-chemistry/barnacle).
+Atomic pattern recognition utility based on the CNA algorithm. For detailed explanation
+of Bramble, [see the documentation](https://bramble.imc-tue.nl).
 
 ## Compilation
 
@@ -17,12 +18,20 @@ 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
+
 ```bash
 mkdir build && cd build
 cmake ../src
 make -j
 ```
 
+To test that Bramble is working, run the test suite
+
+```bash
+make test
+```
+
 ## Usage
 
 ```bash

docs/background.rst

@@ -43,12 +43,12 @@ following equation
 .. math::
 
    r_{\text{cut}} = \left( \frac{1 + \sqrt{2}}{2} \right)
-   \left( \frac{1}{6} \sum_{j=1}^{6} | \vec{r}_{ij} \right).
+   \left( \frac{1}{6} \sum_{j=1}^{6} | \vec{r}_{ij} | \right).
 
 Based on this cut-off distance, all the neighbors of the atom are determined
 and based on these atoms a binary adjacency matrix is constructed wherein each
-element is a one if the distance between those atoms is smaller than
-:math:`r_{\text{cut}}` or a zero otherwise. This adjacency matrix is essentially
+element is a ``1`` if the distance between those atoms is smaller than
+:math:`r_{\text{cut}}` or a ``0`` otherwise. This adjacency matrix is essentially
 a representation of the neighborhood graph between the atoms. For each node in
 this neighborhood graph a triplet of values, i.e. the so-called CNA
 indices, is assigned. These indices are:
@@ -60,7 +60,7 @@ indices, is assigned. These indices are:
 Finally, the indices of each node are collected and a fingerprint is constructed
 based on how many times each CNA triplet is found within the graph.
 
-We here provide a example for an atom at the FCC(111) termination. Such
+We here provide an example for an atom at the FCC(111) termination. Such
 an atom has 9 neighbors based on the value of :math:`r_{\text{cut}}`.
 A schematic representation of this geometry is given below.
 
@@ -100,6 +100,7 @@ is one. Thus, these atoms have the triplet (3,1,1).
 
 .. figure:: _static/img/background/graph.png
     :align: center
+    :width: 256
 
     Neighborhood graph of an FCC(111) atom. There are two types of atoms,
     one type with (4,2,1) CNA indices and another type with (3,1,1) CNA
@@ -113,14 +114,12 @@ is one. Thus, these atoms have the triplet (3,1,1).
    multiplicity, i.e. the number of atoms having a particular CNA triplet, is
    **not** used.
 
-
 We can readily observe that there 3 atoms with the (4,2,1) triplet and 6
 atoms with the (3,1,1) triplet. This would then yield a CNA signature
-of **3(4,2,1)6(3,1,1)**. Below, a list of CNA patterns is given for very common
+of ``3(4,2,1)6(3,1,1)``. Below, a list of CNA patterns is given for very common
 surface terminations and bulk atoms is given.
 
-.. list-table:: CNA pattern for common crystal motifs.
-   :widths: 25 25
+.. list-table:: CNA pattern for some common crystal motifs.
    :header-rows: 1
 
    * - Structure

docs/examples.rst → docs/gallery.rst

@@ -1,8 +1,11 @@
-.. _examples:
-.. index:: Examples
+.. _gallery:
+.. index:: Gallery
 
-Examples
-========
+Gallery
+=======
+
+On this page, you can find a series of example images constructed using
+:program:`Bramble`.
 
 .. figure:: _static/img/examples/nanoparticles.png
     :align: center
@@ -11,4 +14,8 @@ Examples
     atoms of cobalt nanoparticles of varying size. Details of this work
     can be found in the `publication <https://pubs.acs.org/doi/10.1021/acscatal.1c00651>`_.
 
+*****
+
 ..  youtube:: 9P0frhULKpw
+
+*****

docs/index.rst

@@ -28,7 +28,7 @@ requests are ideally submitted via the `github issue tracker
 
    installation
    background
-   examples
+   gallery
    user_interface
    pattern_library
    publications

docs/installation.rst

@@ -55,18 +55,22 @@ Typical output should look as follows::
     Running tests...
     Test project /mnt/d/PROGRAMMING/CPP/bramble/build
         Start 1: test_basic
-    1/6 Test #1: test_basic .......................   Passed    0.00 sec
+    1/8 Test #1: test_basic .......................   Passed    0.00 sec
         Start 2: test_geo
-    2/6 Test #2: test_geo .........................   Passed    0.01 sec
+    2/8 Test #2: test_geo .........................   Passed    0.03 sec
         Start 3: test_xyz
-    3/6 Test #3: test_xyz .........................   Passed    0.01 sec
+    3/8 Test #3: test_xyz .........................   Passed    0.02 sec
         Start 4: test_error
-    4/6 Test #4: test_error .......................   Passed    0.01 sec
+    4/8 Test #4: test_error .......................   Passed    0.01 sec
         Start 5: test_poscar
-    5/6 Test #5: test_poscar ......................   Passed    0.01 sec
+    5/8 Test #5: test_poscar ......................   Passed    0.01 sec
         Start 6: test_cna
-    6/6 Test #6: test_cna .........................   Passed    0.08 sec
+    6/8 Test #6: test_cna .........................   Passed    0.03 sec
+        Start 7: test_fingerprint
+    7/8 Test #7: test_fingerprint .................   Passed    0.01 sec
+        Start 8: test_pattern_library
+    8/8 Test #8: test_pattern_library .............   Passed    0.01 sec
 
-    100% tests passed, 0 tests failed out of 6
+    100% tests passed, 0 tests failed out of 8
 
-    Total Test time (real) =   0.14 sec
+    Total Test time (real) =   0.25 sec

docs/user_interface.rst

@@ -3,3 +3,160 @@
 
 User Interface
 ==============
+
+:program:`Bramble` is shipped with two executables, ``bramble`` and ``brambletool``.
+The former is to perform the CNA analysis, the latter is to build, edit, and
+validate the pattern library.
+
+Bramble
+-------
+
+To perform the CNA analysis, launch ``./bramble`` with the following three
+mandatory command line arguments::
+
+    ./bramble -p <pattern-file> -i <geometry-file> -o <output-file>
+
+* ``-i``, ``--input`` ``<geometry-file>``
+    File containing the geometry of the system. :program:`Bramble` supports
+
+    * VASP `POSCAR/CONTCAR <https://www.vasp.at/wiki/index.php/POSCAR>`_ files
+    * `XYZ <http://openbabel.org/wiki/XYZ_(format)>`_ files
+    * `ReaxFF GEO <https://www.scm.com/doc/plams/interfaces/reaxff.html>`_ files
+* ``-p``, ``--pattern`` ``<pattern-file>``
+    Pattern library encoded in a JSON file. Details of the pattern library can
+    be found :ref:`here <pattern_library>`.
+* ``-o``, ``--output`` ``<output-file>``
+    Where to write the output to.
+
+*Example*: ``./bramble -p ../patterns/patterns.json -i ../src/test/data/co_np.geo -o result.txt``
+
+Typical output looks as follows::
+
+    --------------------------------------------------------------
+    Executing Bramble v.0.2.0
+    Author: Ivo Filot <i.a.w.filot@tue.nl>
+    Documentation: https://bramble.imc-tue.nl
+    --------------------------------------------------------------
+    Compilation time: May 18 2023 20:20:12
+    Git Hash: acfc9bc
+    --------------------------------------------------------------
+    Loading ../src/test/data/co_np.geo as .geo file.
+    Geometry file contains 3375 atoms.
+    Calculating interatomic distances...
+    Completed calculation of interatomic distances.
+    Start common neighbor analysis...
+    Common neighbor analysis completed.
+    --------------------------------------------------------------
+    Done in 0.10766 seconds.
+
+Bramble Tool
+------------
+
+To create, edit or validate a pattern library, one can use ``brambletool``.
+
+.. tip::
+    It is recommended to always use the ``.json`` extension for the pattern
+    library filename.
+
+Create a pattern library
+************************
+
+To create a new pattern library, run::
+
+    ./brambletool -c -p <new_pattern_library.json>
+
+Adding patterns
+***************
+
+.. tip::
+    It is commended to enclose the full pattern description in quotation
+    marks to ensure proper parsing. Also note that each element of the pattern
+    entry should be separated by semicolons.
+
+To add a new pattern entry to the library, run::
+
+    ./brambletool -a "<key>;<fingerprint>;<description>;<color>" -p <pattern_library.json>
+
+The entries for ``<key>``, ``<fingerprint>`` and ``<color>`` are automatically
+validated. The entry ``<key>`` should only contain alphanumerical characters,
+underscores and dashes. The ``<fingerprint>`` entry should be a valid CNA
+fingerprint composed of a series of ``n(x,y,z)`` triplets. Finally, the
+``<color>`` entry should be a valid hexadecimal color code. Do **not** start
+the color code with a leading ``#``.
+
+Editing patterns
+****************
+
+Patterns are edited based on the entry key. To edit a pattern, run::
+
+    ./brambletool -e "<key>;<fingerprint>;<description>;<color>" -p <pattern_library.json>
+
+Removing patterns
+*****************
+
+Patterns are removed based on their entry key:
+
+    ./brambletool -d "<key>" -p <pattern_library.json>
+
+Listing patterns
+*****************
+
+To list all patterns in the library, one can run::
+
+    ./brambletool -l -p <pattern_library.json>
+
+Typical output looks as follows::
+
+    --------------------------------------------------------------
+    Running bramble-tool v.0.2.0
+    Author: Ivo Filot <i.a.w.filot@tue.nl>
+    Documentation: https://bramble.imc-tue.nl
+    --------------------------------------------------------------
+    Compilation time: May 18 2023 20:20:11
+    Git Hash: acfc9bc
+    --------------------------------------------------------------
+    Printing list of patterns:
+                   SC(223)   ffffff 4(6,7,3)2(5,5,3)3(4,3,3)2(3,2,2)
+                   SC(135)   ffffff 4(5,5,3)2(4,4,2)2(2,1,1)
+                   SC(123)   ffffff 2(6,7,3)2(5,5,3)2(4,4,2)1(4,3,3)2(3,2,2)
+                   SC(123)   ffffff 2(5,5,3)4(4,4,2)1(2,1,1)
+                   SC(112)   ffffff 3(6,7,3)2(5,5,3)1(4,4,2)2(4,3,3)2(3,2,2)
+                   SC(112)   ffffff 1(6,7,3)4(5,5,3)1(4,4,2)2(3,2,2)1(2,1,1)
+                   SC(011)   ffffff 4(0,0,0)
+                   SC(001)   ffffff 5(0,0,0)
+                   SC bulk   ffffff 6(0,0,0)
+    --------------------------------------------------------------
+    Done.
+
+Validating patterns
+*******************
+
+When receiving a third-party JSON library, it is good practice to first validate
+all the entries before running ``bramble``. To do so, run::
+
+    ./brambletool -v -p <pattern_library.json>
+
+Typical output looks as follows::
+
+    --------------------------------------------------------------
+    Running bramble-tool v.0.2.0
+    Author: Ivo Filot <i.a.w.filot@tue.nl>
+    Documentation: https://bramble.imc-tue.nl
+    --------------------------------------------------------------
+    Compilation time: May 18 2023 20:20:11
+    Git Hash: acfc9bc
+    --------------------------------------------------------------
+    Validating list of patterns:
+                   SC(223)   ffffff [V] 4(6,7,3)2(5,5,3)3(4,3,3)2(3,2,2) [V]
+                   SC(135)   ffffff [V] 4(5,5,3)2(4,4,2)2(2,1,1) [V]
+                   SC(123)   ffffff [V] 2(6,7,3)2(5,5,3)2(4,4,2)1(4,3,3)2(3,2,2) [V]
+                   SC(123)   ffffff [V] 2(5,5,3)4(4,4,2)1(2,1,1) [V]
+                   SC(112)   ffffff [V] 3(6,7,3)2(5,5,3)1(4,4,2)2(4,3,3)2(3,2,2) [V]
+                   SC(112)   ffffff [V] 1(6,7,3)4(5,5,3)1(4,4,2)2(3,2,2)1(2,1,1) [V]
+                   SC(011)   ffffff [V] 4(0,0,0) [V]
+                   SC(001)   ffffff [V] 5(0,0,0) [V]
+                   SC bulk   ffffff [V] 6(0,0,0) [V]
+    --------------------------------------------------------------
+    Done.
+
+Observe that all valid entries are marked by ``[V]``.

patterns/patterns.json

@@ -5,7 +5,7 @@
       {
          "label": "Unknown",
          "fingerprint": "",
-         "color": "7b7b7b"
+         "color": "000000"
       },
       "fcc_bulk":
       {

patterns/patterns2.json

@@ -0,0 +1,17 @@
+{
+    "patterns":
+    {
+        "fcc_bulk":
+        {
+            "label": "12(4,2,1)",
+            "fingerprint": "FCC Bulk",
+            "color": "0b3d05"
+        },
+        "unknown":
+        {
+            "label": "Unknown",
+            "fingerprint": "",
+            "color": "000000"
+        }
+    }
+}

src/CMakeLists.txt

@@ -80,9 +80,15 @@ include_directories(${CMAKE_CURRENT_SOURCE_DIR}
 
 # Add sources
 file(GLOB SOURCES "*.cpp")
-list(REMOVE_ITEM SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+list(REMOVE_ITEM
+     SOURCES
+     ${CMAKE_CURRENT_SOURCE_DIR}/bramble.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/brambletool.cpp)
+
 add_library(bramblesources STATIC ${SOURCES})
-add_executable(bramble ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+
+add_executable(bramble ${CMAKE_CURRENT_SOURCE_DIR}/bramble.cpp)
+add_executable(brambletool ${CMAKE_CURRENT_SOURCE_DIR}/brambletool.cpp)
 
 # Set newer C++ version
 add_definitions(-std=c++17 -march=native)
@@ -92,6 +98,10 @@ target_link_libraries(bramble
                       bramblesources
                       ${Boost_LIBRARIES})
 
+target_link_libraries(brambletool
+                      bramblesources
+                      ${Boost_LIBRARIES})
+
 if(NOT DISABLE_TEST)
     message("[USER] Performing unit tests")
     enable_testing ()