==================
Ionic-liquid dumps
==================


A multi-type dump is not an ice frame. Keep CHILL and cages on
one species with ``--type I``. Use ``seams rdf`` for a partial
g\ :sub:`IJ`\(r) under the dump minimum image. Use ``seams density-z``
for a type-resolved :math:`\rho(z)` in a slit.

Pick one type
-------------

``--type`` / ``-t`` is unchanged. ``0`` guesses type 2 then type 1.
Classification still filters the cloud to that type. A dump
whose interesting species is not that guess needs the integer
type of the species you want.

.. code:: bash

    seams read FILE
    seams chill-plus FILE --type 2
    seams cages FILE --type 2

Unlike-type neighbours
----------------------

``nneigh::neighListPair(rcut, cloud, typeI, typeJ)`` builds I-J
pairs. ``I == J`` is the like-type list (``neighListO``). Distances
use ``gen::periodicDistSq``, so a sheared dump box uses the same
MIC as the ice neighbour lists.

Partial g(r)
------------

.. code:: bash

    seams rdf FILE --types 1,2 --cutoff 6.0
    seams rdf FILE --types 1,2 --cutoff 6.0 --bins 60
    seams rdf FILE --type 2 --cutoff 6.0

``--types I,J`` selects the pair. The default is ``I = J = --type``
(a like-type g(r) of the guessed or requested species).
``--cutoff`` is rmax. ``--bins`` is optional (default ``rmax / 0.1``).

Stdout is a comment header then ``r g count`` rows. The
normalization volume is ``det(H)`` from the dump box, not the
product of bound spans. Tilt ``xy xz yz`` is included when the
dump carries it.

``seams rdf`` is not an ice score. Do not run CHILL or cages on
the ions.

Site kinds and ion vertices
---------------------------

LAMMPS ``type`` is not chemistry: type 1 is oxygen in water and a
cation head in an IL. Hold a ``site::Table`` of type-to-kind (and
optional atom-ID overrides). ``Table::of`` looks up the override
first, then the type, else ``unspecified``. ``indicesOf(polar)`` is
the union of ``cationHead``, ``anion``, and explicit ``polar``;
``indicesOf(apolar)`` is ``tail`` plus explicit ``apolar``.
``site::ionCloud`` emits one vertex per ``molID`` that carries a
cation head or anion: the unweighted COM of those tagged atoms,
unwrapped with ``gen::relDist`` to the first atom of the group, with
``Point::type`` 1 (cation) or 2 (anion). A long-chain cation COM
sits on the polar head, not halfway down the tail. Family is an
input on the table; it is not inferred from types.

On that ion cloud, ``nneigh::nearestUnlike(cloud, 1, 2)`` is each
ion's nearest unlike neighbour and the MIC distance.
``nneigh::mutualNearestUnlike`` keeps the mutual edges. Those
are contact pairs. They are not first-shell membership and
not a coordination number.

Polar and apolar domains
------------------------

.. code:: bash

    seams domains FILE --site '1=cationHead,2=anion,3=tail' --subset polar
    seams domains FILE --site '1=cationHead,2=anion,3=tail' --subset apolar

``seams domains`` builds the mask from ``site::indicesOf`` and walks
Stoddard's clusters on that subset. It does not run CHILL or
``q_6``. Neighbours are the dump-MIC cutoff list (``--cutoff``).
Stdout is ``subset polar n N largest L P P_inf`` with
``P_inf = L / N``. Missing ``--site`` exits 2. ``--family`` still only
gates ice scores.

Confined layers
---------------

A slit or slab dump needs type-resolved :math:`\rho(z)`, not bulk CHILL.

.. code:: bash

    seams density-z FILE
    seams density-z FILE --type 1 --bins 80
    seams density-z FILE --type 2 --axis z

``--type 0`` (default) histograms every atom. ``--type I`` keeps one
LAMMPS type. ``--axis`` is the Cartesian coordinate (``x``, ``y``, or
``z``; default ``z``). ``--bins`` is optional (default the bound span
over :math:`0.1`).

Stdout is ``# z rho`` then one row per bin. The slice volume is
:math:`A_\perp \times dz`. :math:`A_\perp` comes from dump H (``ly*lz``
for ``x``, ``lx*lz`` for ``y``, ``lx*ly`` for ``z``) using the recovered
edge lengths, not bound spans. This is not a 2-periodic MIC.
The integral of ``rho * A * dz`` is the number of selected atoms.

Confined IL work is this histogram plus the existing in-plane
``rdf2::rdf2Danalysis_AA`` sampler. Do not run CHILL on
``--family confinedIL``.

Molten salt is ``seams rdf`` / ``cn`` plus ``ionCloud`` when the melt
is multi-site. DES adds explicit donor H-bonds. Electrolyte is
ion--O rdf/cn plus water H-bonds. Silica / BeF2 is rdf/cn plus
Franzblau on the M--X graph and ``getq6`` on the tetrahedral
cation (``steinhardtQlVoronoi`` otherwise).

Read the box
------------

``seams read FILE`` prints ``box Lx Ly Lz`` and, when the dump is
triclinic (``box.size() >= 6``), the tilt ``xy xz yz``. Bound spans
are not edge lengths; see `Sheared
cells <sheared-cells.rst>`_.

Family gate
-----------

``--family`` names the material. The default is ``waterIce``.
``seams chill``, ``chill-plus``, and ``cages`` refuse (exit 2) when
``--family`` is ``ionicLiquid``, ``moltenSalt``, ``des``, ``electrolyte``,
``confinedIL``, ``confinedWater``, or ``networkFormer``. The message
names the family. Unflagged ``seams chill`` stays the historical
water path and is not an IL classifier.

.. code:: bash

    seams rdf FILE --types 1,2 --cutoff 6.0
    seams cn FILE --types 1,2 --cutoff 6.0
    seams cn FILE --ions --site '1=cationHead,2=anion'
    seams pairs FILE --site '1=cationHead,2=anion'
    seams domains FILE --site '1=cationHead,2=anion,3=tail' --subset polar
    seams density-z FILE --type 1 --bins 80
    seams chill FILE --family ionicLiquid   # exits 2

Flags and the rest of the surface live on
`seams CLI <../reference/cli.rst>`_. Formats live on
`data formats <../reference/data-formats.rst>`_.