deploy: eb01ac3

Luthaf · Jul 31, 2024 · d41646e · d41646e
commit d41646e
Show file tree

Hide file tree

Showing 86 changed files with 11,294 additions and 0 deletions.
diff --git a/.nojekyll b/.nojekyll
diff --git a/index.html b/index.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta http-equiv="refresh" content="0;URL=latest/index.html" />
+  </head>
+  <body></body>
+</html>
diff --git a/latest/.buildinfo b/latest/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 8c4643be54f30dfe8d5c51462bf6dd9f
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/latest/_images/Arpitan.png b/latest/_images/Arpitan.png
diff --git a/latest/_images/Catalan.png b/latest/_images/Catalan.png
diff --git a/latest/_images/Lombardy.png b/latest/_images/Lombardy.png
diff --git a/latest/_images/Occitan.png b/latest/_images/Occitan.png
diff --git a/latest/_images/benchmark.png b/latest/_images/benchmark.png
diff --git a/latest/_sources/benchmarks.rst.txt b/latest/_sources/benchmarks.rst.txt
@@ -0,0 +1,28 @@
+.. _benchmarks:
+
+Benchmarks
+==========
+
+Here are the result of a benchmark of multiple neighbor list implementations.
+The benchmark runs on multiple super-cell of diamond carbon, up to 30'000 atoms,
+with multiple cutoffs, and using either CPU or CUDA hardware.
+
+The results below are for an AMD 3955WX CPU and an NVIDIA 4070 Ti SUPER GPU; if
+you want to run it on your own system, the corresponding script is in vesin's
+`GitHub repository <bench-script_>`_.
+
+.. _bench-script: https://github.com/Luthaf/vesin/blob/main/benchmarks/benchmark.py
+
+.. figure:: benchmark.png
+    :align: center
+
+    Speed comparison between multiple neighbor list implementations: vesin, `ase
+    <https://wiki.fysik.dtu.dk/ase/ase/neighborlist.html>`_, `matscipy
+    <http://libatoms.github.io/matscipy/tools/neighbour_list.html>`_, `pymatgen
+    <https://pymatgen.org/pymatgen.core.html#pymatgen.core.structure.IStructure.get_neighbor_list>`_,
+    `torch_nl <https://github.com/felixmusil/torch_nl/>`_, and `NNPOps
+    <https://github.com/openmm/NNPOps/>`_.
+
+    Missing points indicate that a specific code could not run the calculation
+    (for example, NNPOps requires the cell to be twice the cutoff in size, and
+    can't run with large cutoffs and small cells).
diff --git a/latest/_sources/c-api.rst.txt b/latest/_sources/c-api.rst.txt
@@ -0,0 +1,17 @@
+.. _c-api:
+
+C API reference
+===============
+
+Vesin's C API is defined in the ``vesin.h`` header. The main function is
+:c:func:`vesin_neighbors`, which runs a neighbors list calculation.
+
+.. doxygenfunction:: vesin_neighbors
+
+.. doxygenfunction:: vesin_free
+
+.. doxygenstruct:: VesinNeighborList
+
+.. doxygenstruct:: VesinOptions
+
+.. doxygenenum:: VesinDevice
diff --git a/latest/_sources/index.rst.txt b/latest/_sources/index.rst.txt
@@ -0,0 +1,264 @@
+Vesin: we are all neighbors
+===========================
+
+.. |occ| image:: /static/images/Occitan.png
+    :width: 18px
+
+.. |arp| image:: /static/images/Arpitan.png
+    :width: 18px
+
+.. |lomb| image:: /static/images/Lombardy.png
+    :width: 18px
+
+.. |cat| image:: /static/images/Catalan.png
+    :width: 18px
+
+.. list-table::
+    :align: center
+    :widths: auto
+    :header-rows: 1
+
+    - * English 🇺🇸⁠/⁠🇬🇧
+      * Occitan |occ|
+      * French 🇫🇷
+      * Arpitan |arp|
+      * Gallo‑Italic |lomb|
+      * Catalan |cat|
+      * Spanish 🇪🇸
+      * Italian 🇮🇹
+    - * neighbo(u)r
+      * vesin
+      * voisin
+      * vesin
+      * visin
+      * veí
+      * vecino
+      * vicino
+
+
+``vesin`` is a lightweight neighbor list calculator for molecular systems and
+three-dimensional graphs. It is written in C++ and can be used as a standalone
+library from C or Python. ``vesin`` is designed to be :ref:`fast <benchmarks>`
+and easy to use.
+
+Installation
+------------
+
+.. tab-set::
+
+    .. tab-item:: Python
+        :sync: python
+
+        You can install the code with ``pip``:
+
+        .. code-block:: bash
+
+            pip install vesin
+
+    .. tab-item:: C/C++ (CMake)
+        :sync: cxx
+
+        If you use CMake as your build system, the simplest thing to do is to
+        add https://github.com/Luthaf/vesin to your project.
+
+        .. code-block:: cmake
+
+            # assuming the code is in the `vesin/` directory (for example using
+            # git submodule)
+            add_subdirectory(vesin)
+
+            target_link_libraries(your-target vesin)
+
+        Alternatively, you can use CMake's `FetchContent
+        <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ module
+        to automatically download the code:
+
+        .. code-block:: cmake
+
+            include(FetchContent)
+            FetchContent_Declare(
+                vesin
+                GIT_REPOSITORY https://github.com/Luthaf/vesin.git
+            )
+
+            FetchContent_MakeAvailable(vesin)
+
+            target_link_libraries(your-target vesin)
+
+    .. tab-item:: C/C++ (single file build)
+
+        We support merging all files in the vesin library to a single one that
+        can then be included in your own project and built with the same build
+        system as the rest of your code.
+
+        You can generate this single file to build with the following commands:
+
+        .. code-block:: bash
+
+            git clone https://github.com/Luthaf/vesin.git
+            cd vesin
+            python create-single-cpp.py
+
+        Then you'll need to copy both ``include/vesin.h`` and
+        ``vesin-single-build.cpp`` in your project and configure your build
+        system accordingly.
+
+
+    .. tab-item:: C/C++ (global installation)
+
+        You can build and install vesin in some global location (referred to as
+        ``$PREFIX`` below), and then use the right compiler flags to give this
+        location to your compiler. In this case, compilation of ``vesin`` and
+        your code happen separately.
+
+        .. code-block:: bash
+
+            git clone https://github.com/Luthaf/vesin.git
+            cd vesin
+            mkdir build && cd build
+            cmake -DCMAKE_INSTALL_PREFIX=$PREFIX <other options> ..
+            cmake --install .
+
+        You can then compile your code, adding ``$PREFIX/include`` to the
+        compiler include path, ``$PREFIX/lib`` to the linker library path; and
+        linking to vesin (typically with ``-lvesin``). If you are building vesin
+        as a shared library, you'll also need to define ``VESIN_SHARED`` as a
+        preprocessor constant (``-DVESIN_SHARED`` when compiling the code).
+
+        Some relevant cmake options you can customize:
+
+        +------------------------------+-----------------------------------------------+----------------+
+        | Option                       | Description                                   | Default        |
+        +==============================+===============================================+================+
+        | ``CMAKE_BUILD_TYPE``         | Type of build: Debug or Release               | Release        |
+        +------------------------------+-----------------------------------------------+----------------+
+        | ``CMAKE_INSTALL_PREFIX``     | Prefix where the library will be installed    | ``/usr/local`` |
+        +------------------------------+-----------------------------------------------+----------------+
+        | ``BUILD_SHARED_LIBS``        | Default to building and installing a shared   | OFF            |
+        |                              | library instead of a static one               |                |
+        +------------------------------+-----------------------------------------------+----------------+
+
+
+Usage example
+-------------
+
+.. tab-set::
+
+    .. tab-item:: Python
+        :sync: python
+
+        .. py:currentmodule:: vesin
+
+        There are two ways to use vesin from Python, you can use the
+        :py:class:`NeighborList` class:
+
+        .. code-block:: Python
+
+            import numpy as np
+            from vesin import NeighborList
+
+            # positions can be anything compatible with numpy's ndarray
+            positions = [
+                (0, 0, 0),
+                (0, 1.3, 1.3),
+            ]
+            box = 3.2 * np.eye(3)
+
+            calculator = NeighborList(cutoff=4.2, full_list=True)
+            i, j, S, d = calculator.compute(
+                points=points,
+                box=box,
+                periodic=True,
+                quantities="ijSd"
+            )
+
+        Alternatively, you can use the :py:func:`ase_neighbor_list` function,
+        which mimics the API of :py:func:`ase.neighborlist.neighbor_list`:
+
+        .. code-block:: Python
+
+            import ase
+            from vesin import ase_neighbor_list
+
+            atoms = ase.Atoms(...)
+
+            i, j, S, d = ase_neighbor_list("ijSd", atoms, cutoff=4.2)
+
+
+    .. tab-item:: C and C++
+        :sync: cxx
+
+        .. code-block:: c++
+
+            #include <string.h>
+            #include <stdio.h>
+            #include <stdlib.h>
+
+            #include <vesin.h>
+
+            int main() {
+                // points can be any pointer to `double[3]`
+                double points[][3] = {
+                    {0, 0, 0},
+                    {0, 1.3, 1.3},
+                };
+                size_t n_points = 2;
+
+                // box can be any `double[3][3]` array
+                double box[3][3] = {
+                    {3.2, 0.0, 0.0},
+                    {0.0, 3.2, 0.0},
+                    {0.0, 0.0, 3.2},
+                };
+                bool periodic = true;
+
+                // calculation setup
+                VesinOptions options;
+                options.cutoff = 4.2;
+                options.full = true;
+
+                // decide what quantities should be computed
+                options.return_shifts = true;
+                options.return_distances = true;
+                options.return_vectors = false;
+
+                VesinNeighborList neighbors;
+                memset(&neighbors, 0, sizeof(VesinNeighborList));
+
+                const char* error_message = NULL;
+                int status = vesin_neighbors(
+                    points, n_points, box, periodic,
+                    VesinCPU, options,
+                    &neighbors,
+                    &error_message,
+                );
+
+                if (status != EXIT_SUCCESS) {
+                    fprintf(stderr, "error: %s\n", error_message);
+                    return 1;
+                }
+
+                // use neighbors as needed
+                printf("we have %d pairs\n", neighbors.length);
+
+                vesin_free(&neighbors);
+
+                return 0;
+            }
+
+
+API Reference
+-------------
+
+.. toctree::
+    :maxdepth: 1
+
+    python-api
+    c-api
+
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    benchmarks
diff --git a/latest/_sources/python-api.rst.txt b/latest/_sources/python-api.rst.txt
@@ -0,0 +1,11 @@
+.. _python-api:
+
+Python API reference
+====================
+
+.. currentmodule:: vesin
+
+.. autoclass:: NeighborList
+    :members:
+
+.. autofunction:: ase_neighbor_list