Skip to content

Commit 1587508

Browse files
HaoZekeHaoZeke
committed
docs(lua): refresh generated API reference
1 parent aa364a7 commit 1587508

3 files changed

Lines changed: 130 additions & 51 deletions

File tree

‎docs/orgmode/reference/lua.org‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,9 @@ Cutoff neighbour list by atom ID. Calls
113113
~core.neighListO(opts.cutoff or 3.5, cloud, opts.type or 1)~.
114114
Returns a Lua table of rows (self ID first).
115115

116-
* ~neighbors_pair~(cloud[, opts])
116+
* Pair neighbours
117117

118-
I-J cutoff neighbour list. Calls
118+
~neighbors_pair(cloud[, opts])~ returns an I-J cutoff neighbour list. Calls
119119
~core.neighListPair(opts.cutoff or 3.5, cloud, opts.type_i or 1,
120120
opts.type_j or 2)~. Like-type pairs reuse ~neighListO~.
121121

@@ -134,9 +134,10 @@ Partial three-dimensional radial distribution function. Calls
134134
(default 2), ~opts.cutoff~ (default 12.0), and ~opts.bins~ (default
135135
~floor(cutoff / 0.05)~). Returns ~{r = {...}, g = {...}}~.
136136

137-
* ~running_cn~(cloud[, opts])
137+
* Running coordination number
138138

139-
Running integral of the partial ~g_IJ~. Uses the same options and
139+
~running_cn(cloud[, opts])~ is the running integral of the partial
140+
~g_IJ~. Uses the same options and
140141
defaults as ~rdf~ and calls ~core.calcRunningCN~. Returns
141142
~{r = {...}, cn = {...}}~, with ~rhoJ = nJ / volume~.
142143

@@ -196,9 +197,9 @@ length-unit bins.
196197
- Site mode requires both ~opts.table~ and ~opts.kind~ and returns
197198
~{centres, rho, axis, site_kind}~.
198199

199-
* ~site_table~(spec)
200+
* Site mapping table
200201

201-
Parses a comma-separated mapping such as
202+
~site_table(spec)~ parses a comma-separated mapping such as
202203
~"1=cationHead,2=anion,3=tail"~. The result is a ~SiteTable~ userdata
203204
accepted by ~density~, ~pairs~, and ~domain~. Site kinds are exposed
204205
on ~dseams.core.Kind~ (alias ~SiteKind~), including ~polar~ and

‎docs/source/howto/fennel.rst‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,9 @@ Run it from the repository root:
5454
5555
Fennel ``require`` falls through to Lua ``package.path``, so
5656
``(require :dseams)`` returns the same table as ``require("dseams")``:
57-
``read``, ``neighbors``, ``knn``, ``chill_plus``, ``chill``, ``cages``, and
58-
``.core``. Names stay snake\ :sub:`case`\.
57+
``read``, ``neighbors``, ``neighbors_pair``, ``cn``, ``rdf``, ``running_cn``,
58+
``knn``, ``chill_plus``, ``chill``, ``cages``, ``hbonds``, ``density``,
59+
``site_table``, ``pairs``, ``domain``, and ``.core``. Names stay snake\ :sub:`case`\.
5960

6061
Scripts that mention ``readFrameOnlyOne``, ``functionScript``, or
6162
``trajectory`` as a global expect the 2020 driver. Rewrite them to
@@ -65,10 +66,11 @@ shape.
6566
``lua/dseams.fnl``
6667
------------------
6768

68-
``lua/dseams.fnl`` wraps that table with kebab-case names
69-
(``chill-plus``) and re-exports ``.core``. Load it with ``fennel.dofile``
70-
under a name that is not ``dseams``, so the inner ``(require :dseams)``
71-
still hits the Lua module:
69+
``lua/dseams.fnl`` wraps that table with kebab-case names such as
70+
``neighbors-pair``, ``running-cn``, ``chill-plus``, and ``site-table``; it
71+
re-exports ``.core``. Load it with ``fennel.dofile`` under a name that is
72+
not ``dseams``, so the inner ``(require :dseams)`` still hits the Lua
73+
module:
7274

7375
.. code:: fennel
7476

‎docs/source/reference/lua.rst‎

Lines changed: 115 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ Public names
3333
+--------------------+----------+----------------------------------------------------+
3434
| ``cn`` | function | site-site coordination number |
3535
+--------------------+----------+----------------------------------------------------+
36+
| ``rdf`` | function | partial three-dimensional RDF |
37+
+--------------------+----------+----------------------------------------------------+
38+
| ``running_cn`` | function | running site-site coordination number |
39+
+--------------------+----------+----------------------------------------------------+
3640
| ``knn`` | function | k-nearest graph by atom ID |
3741
+--------------------+----------+----------------------------------------------------+
3842
| ``chill_plus`` | function | CHILL+ state names; no file |
@@ -41,6 +45,16 @@ Public names
4145
+--------------------+----------+----------------------------------------------------+
4246
| ``cages`` | function | seeded HC/DDC per-atom flags |
4347
+--------------------+----------+----------------------------------------------------+
48+
| ``hbonds`` | function | hydrogen-bond adjacency table |
49+
+--------------------+----------+----------------------------------------------------+
50+
| ``density`` | function | Cartesian number-density profile |
51+
+--------------------+----------+----------------------------------------------------+
52+
| ``site_table`` | function | parse a type-to-site mapping |
53+
+--------------------+----------+----------------------------------------------------+
54+
| ``pairs`` | function | mutual nearest cation-anion pairs |
55+
+--------------------+----------+----------------------------------------------------+
56+
| ``domain`` | function | largest mapped-site domain statistics |
57+
+--------------------+----------+----------------------------------------------------+
4458
| ``core`` | table | ``require("dseams_core")``; compiled registrations |
4559
+--------------------+----------+----------------------------------------------------+
4660

@@ -94,15 +108,13 @@ stack). A freshly written Lua table is not accepted.
94108

95109
.. table::
96110

97-
+-------------------+------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
98-
| style | examples | nList / rings in | result |
99-
+===================+==============================================================================================================================+==================+==================================+
100-
| new | ``neighListO``, ``neighListPair``, ``neighbourListByIndex``, ``kNearestNeighbourList``, ``ringNetwork``, ``cageAffiliation``, ``getCorrelPlus``, ``calcCN``, ``calcRDF3D``, ``calcRunningCN`` | Lua table | Lua table (or void / name table) |
101-
+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
102-
| new, userdata out | ``getHbondNetwork``, ``getHbondNetworkFromClouds``, ``getHbondNetworkFromDonors`` | Lua table | C++ vector userdata |
103-
+-------------------+------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
104-
| legacy | ``neighborList``, ``bondNetworkByIndex``, ``getPrimitiveRings``, ``readFrame*``, ``chillPlus_*``, ``chill_*`` | userdata | userdata |
105-
+-------------------+------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
111+
+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
112+
| style | examples | nList / rings in | result |
113+
+========+==============================================================================================================================================================================================================================================================================================+==================+==================================+
114+
| new | ``neighListO``, ``neighListPair``, ``neighbourListByIndex``, ``kNearestNeighbourList``, ``ringNetwork``, ``cageAffiliation``, ``getCorrelPlus``, ``calcCN``, ``calcRDF3D``, ``calcRunningCN``, ``getHbondNetwork*``, ``densityByType``, ``densityByKind``, ``contactPairs``, ``domainStats`` | Lua table | Lua table (or void / name table) |
115+
+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
116+
| legacy | ``neighborList``, ``bondNetworkByIndex``, ``getPrimitiveRings``, ``readFrame*``, ``chillPlus_*``, ``chill_*`` | userdata | userdata |
117+
+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+----------------------------------+
106118

107119
``sol2`` does not apply C++ default arguments on a raw bind. Wrapped
108120
names spell optionals in Lua (``sol::optional``). Legacy names need
@@ -115,29 +127,30 @@ Suffix-dispatching loader. Returns a ``PointCloud``.
115127

116128
.. table::
117129

118-
+--------------------------------+--------------------+------------------------------------------------------------------------------------+
119-
| suffix | backend | notes |
120-
+================================+====================+====================================================================================+
121-
| ``.xyz`` | ``readXYZ`` | whole file; ``opts.frame`` unused |
122-
+--------------------------------+--------------------+------------------------------------------------------------------------------------+
123-
| ``.con`` | ``readCon`` | errors if this build has no readcon |
124-
+--------------------------------+--------------------+------------------------------------------------------------------------------------+
125-
| ``.pdb`` / ``.gro`` / ``.dcd`` | ``readChemfiles`` | errors if this build has no chemfiles; ``opts.type`` defaults to ``-1`` (keep all) |
126-
+--------------------------------+--------------------+------------------------------------------------------------------------------------+
127-
| other (LAMMPS dump) | ``readLammpsTrjO`` | ``opts.frame`` defaults to 1. If ``opts.type`` is nil, tries type 2 then type 1 |
128-
+--------------------------------+--------------------+------------------------------------------------------------------------------------+
129-
130-
``opts.frame`` is the 1-based frame index (default 1). ``opts.type`` is
131-
the LAMMPS type ID to keep. There is no region. ``dseams.read`` calls
132-
``core.readLammpsTrjO``, which keeps every atom of that type.
130+
+--------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------+
131+
| suffix | backend | notes |
132+
+================================+=========================================+===========================================================================================================+
133+
| ``.xyz`` | ``readXYZ`` | whole file; ``opts.frame`` unused |
134+
+--------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------+
135+
| ``.con`` | ``readCon`` | errors if this build has no readcon |
136+
+--------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------+
137+
| ``.pdb`` / ``.gro`` / ``.dcd`` | ``readChemfiles`` | errors if this build has no chemfiles; ``opts.type`` defaults to ``-1`` (keep all) |
138+
+--------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------+
139+
| other (LAMMPS dump) | ``readLammpsTrj`` or ``readLammpsTrjO`` | ``opts.all = true`` keeps all atoms. Otherwise ``opts.type`` selects a type; nil tries type 2 then type 1 |
140+
+--------------------------------+-----------------------------------------+-----------------------------------------------------------------------------------------------------------+
141+
142+
``opts.frame`` is the 1-based frame index (default 1). ``opts.all = true``
143+
calls ``core.readLammpsTrj`` and keeps every atom. Otherwise
144+
``opts.type`` is the LAMMPS type ID to keep. There is no region in the
145+
high-level helper.
133146

134147
A dump slice that shrinks ``nop`` is
135148
``dseams.core.readLammpsTrjreduced(path, frame, type, true, lo, hi)``.
136149
``core.readLammpsTrjO`` takes the same five arguments after the path
137150
and only sets ``inSlice``. An axis with ``lo == hi`` is unconstrained,
138-
so ``{0,0,0}`` / ``{50,0,0}`` is ``x`` in ``[0, 50]``, ``y`` and ``z``
139-
open. The ``O`` in ``readLammpsTrjO`` is historical; the type argument
140-
is any LAMMPS type.
151+
so ``{0,0,0}`` / ``{50,0,0}`` is ``x`` in ``[0, 50]``, ``y`` and ``z`` open.
152+
The ``O`` in ``readLammpsTrjO`` is historical; the type argument is any
153+
LAMMPS type.
141154

142155
~neighbors~(cloud[, opts])
143156
--------------------------
@@ -146,12 +159,11 @@ Cutoff neighbour list by atom ID. Calls
146159
``core.neighListO(opts.cutoff or 3.5, cloud, opts.type or 1)``.
147160
Returns a Lua table of rows (self ID first).
148161

149-
~neighbors_pair~(cloud[, opts])
150-
-------------------------------
162+
Pair neighbours
163+
---------------
151164

152-
I-J cutoff neighbour list. Calls
153-
``core.neighListPair(opts.cutoff or 3.5, cloud, opts.type_i or 1,
154-
opts.type_j or 2)``. Like-type pairs reuse ``neighListO``.
165+
``neighbors_pair(cloud[, opts])`` returns an I-J cutoff neighbour list. Calls
166+
``core.neighListPair(opts.cutoff or 3.5, cloud, opts.type_i or 1, opts.type_j or 2)``. Like-type pairs reuse ``neighListO``.
155167

156168
~cn~(cloud[, opts])
157169
-------------------
@@ -162,14 +174,21 @@ Site-site coordination number. Calls ``core.calcCN`` with
162174
``floor(cutoff / 0.1)``). ``rhoJ`` is ``nJ / volume`` from the
163175
partial RDF.
164176

165-
~core.calcRunningCN~(cloud, typeI, typeJ, rmax, bins)
166-
-----------------------------------------------------
177+
~rdf~(cloud[, opts])
178+
--------------------
179+
180+
Partial three-dimensional radial distribution function. Calls
181+
``core.calcRDF3D`` with ``opts.type_i`` (default 1), ``opts.type_j``
182+
(default 2), ``opts.cutoff`` (default 12.0), and ``opts.bins`` (default
183+
``floor(cutoff / 0.05)``). Returns ``{r = {...}, g = {...}}``.
167184

168-
Running integral of ``g_IJ``. Returns ``{r, cn}`` with
169-
``rhoJ = nJ / volume``. There is no ``dseams.running_cn`` helper;
170-
call the compiled name on ``dseams.core``. Ice-score ``--family``,
171-
contact pairs, polar/apolar domains, and type-resolved ``rho(z)``
172-
are the ``seams`` CLI in seams-core 2.5.0.
185+
Running coordination number
186+
---------------------------
187+
188+
``running_cn(cloud[, opts])`` is the running integral of the partial
189+
``g_IJ``. Uses the same options and
190+
defaults as ``rdf`` and calls ``core.calcRunningCN``. Returns
191+
``{r = {...}, cn = {...}}``, with ``rhoJ = nJ / volume``.
173192

174193
~knn~(cloud[, opts])
175194
--------------------
@@ -207,6 +226,63 @@ index list, keeps six-membered rings, and returns
207226
``core.seededCageAffiliation(...)``: a table ``{hc = ..., ddc = ...}``
208227
of per-atom flags.
209228

229+
~hbonds~(cloud[, opts])
230+
-----------------------
231+
232+
Hydrogen-bond adjacency for the selected sites. The neighbour graph
233+
uses ``opts.cutoff`` (default 3.5) and ``opts.type`` (default 1).
234+
235+
- With ``opts.path``, the helper reads hydrogens from that trajectory;
236+
``opts.frame`` defaults to 1 and ``opts.h_type`` defaults to 1.
237+
238+
- With ``opts.h_cloud``, the helper uses the supplied hydrogen
239+
``PointCloud`` instead.
240+
241+
- ``opts.dist`` and ``opts.angle`` use the engine defaults 2.42 and 30.0
242+
when omitted.
243+
244+
Returns a nested Lua table. Supplying neither ``path`` nor ``h_cloud`` is
245+
an error.
246+
247+
~density~(cloud[, opts])
248+
------------------------
249+
250+
Cartesian number density along ``opts.axis``: ``"x"``, ``"y"``, ``"z"``,
251+
or the corresponding zero-based index. The default axis is ``"z"``.
252+
``opts.bins`` defaults to the axis span divided into approximately 0.1
253+
length-unit bins.
254+
255+
- Type mode uses ``opts.type`` (default 0) and returns
256+
``{centres, rho, axis, atom_type}``.
257+
258+
- Site mode requires both ``opts.table`` and ``opts.kind`` and returns
259+
``{centres, rho, axis, site_kind}``.
260+
261+
Site mapping table
262+
------------------
263+
264+
``site_table(spec)`` parses a comma-separated mapping such as
265+
``"1=cationHead,2=anion,3=tail"``. The result is a ``SiteTable`` userdata
266+
accepted by ``density``, ``pairs``, and ``domain``. Site kinds are exposed
267+
on ``dseams.core.Kind`` (alias ``SiteKind``), including ``polar`` and
268+
``apolar``.
269+
270+
~pairs~(cloud, opts)
271+
--------------------
272+
273+
Requires ``opts.table``. Maps the cloud to ionic sites and returns
274+
mutual nearest unlike pairs as
275+
``{pairs, count, n_cation, n_anion}``. Each pair contains the original
276+
atom IDs.
277+
278+
~domain~(cloud, opts)
279+
---------------------
280+
281+
Requires ``opts.table`` and ``opts.kind``. The graph joins mapped sites
282+
within ``opts.cutoff`` (default 3.5). Returns
283+
``{site_kind, n, largest, percolation}``, where ``n`` is the selected site
284+
count and ``percolation = largest / n``.
285+
210286
``core``
211287
--------
212288

0 commit comments

Comments
 (0)