============
Contributing
============


This repository is the C++ engine (``libyodaLib``) and the ``seams`` CLI.
Python bindings are `PydSEAMSlib <https://github.com/d-SEAMS/PydSEAMSlib>`_.
Lua/Fennel is `yodaStruct <https://github.com/d-SEAMS/yodaStruct>`_.
Do not add a language binding here.

Documentation is authored in ``docs/orgmode/`` and exported with
``docs/export.el`` (ox-rst) before Sphinx. Run ``pixi run -e docs docbld``
to export, run doxyrest, and build the Shibuya site.

Prerequisites
-------------

Two supported compiler shells:

- `pixi <https://pixi.sh>`_ (locked conda-forge toolchain)

- ``nix develop`` (flake inputs: compiler, Eigen, BLAS, Catch2, gdb)

.. code:: bash

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

pixi provides a compiler, Eigen, BLAS/LAPACK, Catch2, Meson, Ninja,
Highway and chemfiles. Optional pixi features add IRA, sphericart,
nauty, MPI, the docs stack, and the Coq/SymPy proofs.

``-Dwith_python=true`` and ``-Dwith_lua=enabled`` are Meson errors that
name the front-end repositories.

Clone and build
---------------

.. code:: bash

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

pixi:

.. code:: bash

    pixi run setup
    pixi run build
    pixi run test

``pixi run setup`` configures ``bbdir/`` with tests and the ``seams`` CLI
(``-Dwith_tests=true -Dwith_python=false``). ``pixi run build`` compiles
``libyodaLib`` and ``seams``. ``pixi run test`` runs the Catch2 suite.

Nix:

.. code:: bash

    nix develop
    meson setup bbdir -Dwith_tests=true
    meson compile -C bbdir
    meson test -C bbdir
    ./bbdir/seams read input/traj/exampleTraj.lammpstrj

``nix build`` is the same package plus the install check.

Project structure
-----------------

.. code:: text

    seams-core/
      src/                   C++ engine
        seams_cli.cpp        seams (Argum)
        include/internal/    engine headers
        include/external/    vendored headers (argum, backward, ...)
        mol_sys.cpp          PointCloud
        neighbours.cpp       cutoff / knn / knn-union lists
        bond.cpp             hydrogen bonds
        bop.cpp              CHILL / CHILL+
        ring.cpp             ring classification
        franzblau.cpp        Franzblau shortest-path rings
        cage_affiliation.cpp HC / DDC ice score
        bulkTUM.cpp          topological unit matching
        topo_one_dim.cpp     nanotubes
        topo_two_dim.cpp     sheets
      tests/                 Catch2 binaries
      input/traj/            example LAMMPS dumps
      input/xyz/             fixtures
      input/con/             eOn .con fixture
      meson.build            Meson project
      meson_options.txt      with_tests, with_cli, optional backends
      flake.nix              nix build / nix develop
      pixi.toml              pixi workspace

Core concepts
-------------

``PointCloud``
    Atom positions, types, box, and per-atom ice labels.

``neighListO`` / ``kNearestNeighbourList``
    Cutoff and k-nearest
    graphs. ``bondGraphFromName`` accepts ``cutoff``, ``knn``, ``knn-union``.

``populateHbonds``
    Geometric hydrogen bonds. Needs hydrogens
    (re-read from a dump, or an explicit H cloud).

``getCorrelPlus`` / ``getIceTypePlus``
    CHILL+. Four-neighbour
    ``c_ij``, then cubic / hexagonal / interfacial / clathrate / water.

``cageAffiliation`` / ``seededCageAffiliation``
    Ice score on
    six-rings. HC = Ih, DDC = Ic, neither = water. Not the CHILL+ star.

``ringNetwork``
    Franzblau primitive rings up to a depth.

Tests
-----

.. code:: bash

    pixi run test
    nix develop --command meson test -C bbdir

C++ tests are Catch2. Python tests live in
`PydSEAMSlib <https://github.com/d-SEAMS/PydSEAMSlib>`_.

Optional pixi environments: ``pixi run -e ira ...``, ``sphericart``,
``nauty``, ``mpi``, ``docs``, ``formalanalysis``, ``repro``.

Style
-----

Install the clang-format hook:

.. code:: bash

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

Commit subjects follow ``fileName: description of change``. See
``CONTRIBUTING.md`` in the repository root.