============
Repositories
============


d-SEAMS 2 is not a monolith. The classifier is one C++ library.
Neighbour search is linkcell. Each language ships its own package
against that library.

.. table::

    +---------------------------------------------------------+---------------------------+-------------------------------------------+
    | repository                                              | product                   | role                                      |
    +=========================================================+===========================+===========================================+
    | `seams-core <https://github.com/d-SEAMS/seams-core>`_   | ``libyodaLib``, ``seams`` | C++ engine and CLI                        |
    +---------------------------------------------------------+---------------------------+-------------------------------------------+
    | `PydSEAMSlib <https://github.com/d-SEAMS/PydSEAMSlib>`_ | ``pydseams``              | Python helpers on ``yoda``                |
    +---------------------------------------------------------+---------------------------+-------------------------------------------+
    | `yodaStruct <https://github.com/d-SEAMS/yodaStruct>`_   | ``dseams``                | Lua/Fennel library                        |
    +---------------------------------------------------------+---------------------------+-------------------------------------------+
    | `linkcell <https://github.com/d-SEAMS/linkcell>`_       | ``lc_*``                  | Periodic linked-cell k-nearest neighbours |
    +---------------------------------------------------------+---------------------------+-------------------------------------------+

The front ends take seams-core as a Meson subproject (static library)
or as a flake input. They do not vendor a second engine.

A language binding that lived in the engine tree would force every
C++ user to take that language's toolchain, and every wheel or rock
to rebuild the same library. Splitting the repos keeps the Catch2
suite, the ``seams`` CLI, and the optional backends on one Meson
project, while Python and Lua version and release on their own
schedules.

.. mermaid::

   flowchart TB
     subgraph engine["seams-core"]
       LIB[libyodaLib]
       CLI[seams CLI]
     end
     subgraph fronts["Front ends"]
       PY[pydseams Frame]
       LUA["require(\"dseams\")"]
     end
     LC[linkcell]
     DUMP[LAMMPS / XYZ / chemfiles / con] --> LIB
     LC --> LIB
     LIB --> CLI
     LIB --> PY
     LIB --> LUA

Why ``yoda``
------------

The 2020 product was a single executable named ``yodaStruct``. That
binary is gone. The compiled C++ surface kept the name so existing
registrations stay findable: the Python module is ``pydseams.yoda``
(``_core`` and ``cyoda`` are aliases of ``yoda``). Lua helpers are
``require("dseams")``; ``require("yoda")`` still resolves to that table.
There is no ``yodaStruct`` executable in any of the three repositories.

Builds
------

- **Nix flake**: ``nix build`` / ``nix develop`` in each repo. Optional
  wrap-git backends stay off unless nixpkgs already provides them.

- **pixi**: locked conda-forge toolchain in seams-core.

- **Wheels**: cibuildwheel on PydSEAMSlib, CPython 3.12 limited ABI.

The 2020 CMake Nix derivation of ``yodaStruct`` is gone.
``-Dwith_python=true`` and ``-Dwith_lua=enabled`` are Meson errors that
name PydSEAMSlib and yodaStruct.

Ice score and the CHILL+ star
-----------------------------

Two classifiers live in ``libyodaLib``. They answer different questions
and they do not imply each other. The argument is
`CHILL+ versus cages <chill-plus-vs-cages.rst>`_.

``seams cages --graph`` chooses the bond graph the six-rings are found
on: ``cutoff``, ``knn``, ``knn-union``, or ``seeded`` (CLI default). On a
perfect cubic crystal the four graphs coincide. On a mixed nucleation
dump they do not.