=======
API map
=======


Lookup for the C++ identifiers in ``src/include/internal``. Generated
pages under ``api/`` are the Doxygen comments from those headers,
converted by doxyrest, the same path as rgpot. This is not a dump
of ``pydseams.yoda`` and it is not a tutorial.

Fronts
------

Four fronts, one engine (``libyodaLib``). Flags live on
`seams CLI <cli.rst>`_. Formats live on
`data formats <data-formats.rst>`_.

.. table::

    +-----------------+---------------------------------------------------------+----------------------------------------------------------------------+
    | Front           | Package                                                 | First call                                                           |
    +=================+=========================================================+======================================================================+
    | CLI             | this repo (``seams``)                                   | ``seams read FILE``, ``seams chill-plus FILE``, ``seams cages FILE`` |
    +-----------------+---------------------------------------------------------+----------------------------------------------------------------------+
    | Python Frame    | `PydSEAMSlib <https://github.com/d-SEAMS/PydSEAMSlib>`_ | ``pydseams.Frame`` from ``pydseams.read(...)``                       |
    +-----------------+---------------------------------------------------------+----------------------------------------------------------------------+
    | Lua             | `yodaStruct <https://github.com/d-SEAMS/yodaStruct>`_   | ``require("dseams")``                                                |
    +-----------------+---------------------------------------------------------+----------------------------------------------------------------------+
    | Compiled Python | PydSEAMSlib                                             | ``pydseams.yoda`` (``_core`` and ``cyoda`` are aliases)              |
    +-----------------+---------------------------------------------------------+----------------------------------------------------------------------+

Doxyrest wiring
---------------

``pixi run -e docs doxybuild`` runs from ``docs/source``:

1. ``doxygen Doxyfile_seams.cfg`` -- ``INPUT`` is
   ``../../src/include/internal`` (``EXTRACT_ALL=YES``, private members
   off). ``src/include/external`` and ``tests/`` are excluded.

2. ``doxyrest -c doxyrest-config.lua`` -- reads ``xml/index.xml``, writes
   =api/index.rst~ with title ``API Reference``.

The book includes that tree as ``api/index`` (Reference toctree), not
as a second hand list of functions.

.. toctree::
   :maxdepth: 2
   :caption: C++ (doxygen)

   ../api/index

The groups below are Breathe of the same XML. That is the interned
API, not a hand table.

.. doxygengroup:: nneigh
   :members:
   :content-only:

.. doxygengroup:: chill
   :members:
   :content-only:

.. doxygengroup:: primitive
   :members:
   :content-only:

.. doxygengroup:: ring
   :members:
   :content-only:

.. doxygengroup:: prism3
   :members:
   :content-only:

.. doxygengroup:: cage
   :members:
   :content-only:

.. doxygengroup:: bond
   :members:
   :content-only:

.. doxygengroup:: sinp
   :members:
   :content-only:

.. doxygengroup:: clump
   :members:
   :content-only:

.. doxygengroup:: gen
   :members:
   :content-only:

.. doxygengroup:: rdf2
   :members:
   :content-only:

.. doxygengroup:: molSys
   :members:
   :content-only:

Headers
-------

Every file under ``src/include/internal``.

.. table::

    +---------------------------+---------------------------+-----------------------------------------------+
    | Header                    | Namespace                 | Role                                          |
    +===========================+===========================+===============================================+
    | ``mol_sys.hpp``           | ``molSys``                | ``Point``, ``PointCloud``, bond and ice enums |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``seams_input.hpp``       | ``sinp``                  | LAMMPS / XYZ / chemfiles / readcon readers    |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``seams_output.hpp``      | ``sout``                  | dump, cage, ring, and cluster writers         |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``neighbours.hpp``        | ``nneigh``                | cutoff, k-nearest, skin neighbour lists       |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``bop.hpp``               | ``chill``, ``sph``        | CHILL, CHILL+, ``q6``, Steinhardt ``ql``      |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``franzblau.hpp``         | ``primitive``             | Franzblau primitive rings                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``ring.hpp``              | ``ring``                  | ring helpers and ``strucType``                |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``topo_bulk.hpp``         | ``ring``, ``prism3``      | HC / DDC search, bulk polygons                |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``topo_one_dim.hpp``      | ``ring``                  | ice-nanotube prisms                           |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``topo_two_dim.hpp``      | ``ring``                  | monolayer polygons                            |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``cage.hpp``              | ``cage``                  | ``Cage``, ``cageType``, ``iceType``           |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``cage_affiliation.hpp``  | ``ring``                  | claim-free HC / DDC flags                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``cage_canon.hpp``        | ``cage``                  | nauty canonical certificates                  |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``bulkTUM.hpp``           | ``tum3``                  | topological unit matching                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``bond.hpp``              | ``bond``                  | geometric hydrogen bonds                      |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``absOrientation.hpp``    | ``absor``                 | Horn absolute orientation                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``pntCorrespondence.hpp`` | ``pntToPnt``              | reference / target point sets                 |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``shapeMatch.hpp``        | ``match``                 | prism shape-matching                          |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``cluster.hpp``           | ``clump``                 | Stillinger ice clusters                       |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``order_parameter.hpp``   | ``topoparam``             | height% and coverage area                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``rdf2d.hpp``             | ``rdf2``                  | in-plane radial distribution                  |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``selection.hpp``         | ``gen``, ``ring``         | type and slice selections                     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``generic.hpp``           | ``gen``                   | periodic distance, angles, medians            |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``structure_desc.hpp``    | ``chill``                 | SOAP, template overlay, linear classifier     |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``voronoi_qlm.hpp``       | ``chill``                 | Voronoi-weighted Steinhardt                   |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``ira_sofi.hpp``          | ``ira``                   | IRA match and SOFI point groups               |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``sphericart_ylm.hpp``    | ``seams::sphericart_ylm`` | batched Cartesian ``Y_lm``                    |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``steinhardt_device.hpp`` | ``seams::steinhardt``     | host / MPI / offload Steinhardt kernel        |
    +---------------------------+---------------------------+-----------------------------------------------+
    | ``simd_distance.hpp``     | ``seams``                 | Highway periodic distance                     |
    +---------------------------+---------------------------+-----------------------------------------------+

``pydseams.yoda`` and ``dseams.core`` register the C++ spellings from
these headers. The generated pages are ``api/index``.