=========
``d-SEAMS``
=========

:Author: `d-SEAMS core team <https://dseams.info>`_

.. raw:: html

   <p class="dseams-hero">
     <img class="dseams-hero-logo dseams-hero-logo--light"
          src="_static/dSeamsLogo.png"
          alt="d-SEAMS"
          width="320"
          height="334"
          loading="eager" />
     <img class="dseams-hero-logo dseams-hero-logo--dark"
          src="_static/dSeamsLogo.png"
          alt="d-SEAMS"
          width="320"
          height="334"
          loading="eager" />
   </p>

.. grid:: 1 2 3 3
   :gutter: 2
   :padding: 1 1 0 0
   :class-container: sd-text-center

   .. grid-item-card:: Read
      :link: quickstart
      :link-type: doc
      :class-card: sd-shadow-sm

      Load a LAMMPS frame and print nop, frame, and box.

   .. grid-item-card:: Classify
      :link: tutorials/bulk-ice
      :link-type: doc
      :class-card: sd-shadow-sm

      CHILL+ four-neighbour star: cubic, hexagonal, interfacial, water.

   .. grid-item-card:: Score
      :link: explanation/chill-plus-vs-cages
      :link-type: doc
      :class-card: sd-shadow-sm

      Cage membership: HC is ice Ih, DDC is ice Ic, else water.

Overview
--------

d-SEAMS (Deferred Structural Elucidation Analysis for Molecular
Simulations) classifies ice in molecular-dynamics trajectories. This
repository is the C++ engine (``libyodaLib``) and the ``seams`` CLI.

.. code:: bash

    seams read water.lammpstrj
    seams chill-plus water.lammpstrj --cutoff 3.5
    seams cages water.lammpstrj

Scripting front ends are separate packages:

- Python: ``pydseams`` (`docs <https://d-seams.github.io/PydSEAMSlib/>`_,
  `PydSEAMSlib <https://github.com/d-SEAMS/PydSEAMSlib>`_), compiled
  module ``yoda``

- Lua/Fennel: ``dseams`` (`docs <https://d-seams.github.io/yodaStruct/>`_,
  `yodaStruct <https://github.com/d-SEAMS/yodaStruct>`_),
  ``require("dseams")``

The header **Ecosystem** menu on every page jumps between the engine,
the bindings, and linkcell.

Build with a Nix flake (``nix build``, ``nix develop``) or with
``pixi run setup && pixi run build && pixi run test``.

Suite stack
-----------

.. 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
     CLI --> OUT[stdout counts]
     PY --> ASE[ASE / solvis extras]

Documentation structure
-----------------------

This documentation follows the `Diataxis <https://diataxis.fr/>`_
framework.

.. toctree::
   :maxdepth: 1
   :caption: Getting Started

   quickstart

.. toctree::
   :maxdepth: 1
   :caption: Tutorials

   tutorials/index
   tutorials/bulk-ice

.. toctree::
   :maxdepth: 1
   :caption: How-to

   howto/index
   howto/install
   howto/classify-cli
   howto/ase-integration
   howto/solvis
   howto/confined-ice
   howto/faq
   howto/troubleshooting

.. toctree::
   :maxdepth: 1
   :caption: Explanation

   explanation/index
   explanation/architecture
   explanation/chill-plus-vs-cages
   explanation/citation

.. toctree::
   :maxdepth: 2
   :caption: Reference

   reference/index
   reference/cli
   reference/data-formats
   reference/nix
   reference/api
   api/index
   reference/glossary
   changelog

.. toctree::
   :maxdepth: 1
   :caption: Development

   contributing/index

Related projects
----------------

`pydseams <https://d-seams.github.io/PydSEAMSlib/>`_
    Python Frame API on ``yoda``

`dseams (Lua) <https://d-seams.github.io/yodaStruct/>`_
    ``require("dseams")`` and Fennel

`linkcell <https://github.com/d-SEAMS/linkcell>`_
    periodic linked-cell k-nearest neighbours

`dseams.info <https://dseams.info>`_
    project site

License
-------

MIT. Cite the 2020 JCIM paper (DOI
`10.1021/acs.jcim.0c00031 <https://doi.org/10.1021/acs.jcim.0c00031>`_).
See `Citation <explanation/citation.rst>`_.