From 88590d682adda6eef34c39d29aa3c3b46f279c55 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Thu, 19 Nov 2026 15:51:03 +0000 Subject: [PATCH] fix(docs): preserve Lua API in Org exports --- .github/workflows/ci_docs.yml | 10 +- docs/export.el | 19 +++- docs/orgmode/reference/lua.org | 125 +++++++++++++++++++++--- docs/source/reference/lua.rst | 168 ++++++++++++++++++++++++++++----- 4 files changed, 278 insertions(+), 44 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index d3928bd..e4ed954 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -14,12 +14,16 @@ jobs: - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.12" - - name: Install Doxygen - run: sudo apt-get update && sudo apt-get install -y doxygen + - name: Install Doxygen and Emacs + run: sudo apt-get update && sudo apt-get install -y doxygen emacs-nox + - name: Check generated RST matches Org + run: | + (cd docs && emacs --batch --load export.el) + git diff --exit-code -- docs/source - name: Install Sphinx (Shibuya, sphinx-design, mermaid, Breathe) run: pip install -r docs/requirements.txt - name: Build HTML from Doxygen XML and RST - run: sphinx-build -b html docs/source docs/build + run: sphinx-build -W -b html docs/source docs/build - name: Add SEO metadata run: python3 tools/seo.py docs/build - name: Validate SEO metadata on every page diff --git a/docs/export.el b/docs/export.el index c125505..595e638 100644 --- a/docs/export.el +++ b/docs/export.el @@ -3,12 +3,23 @@ ;; Org under orgmode/ is the source. RST under ./source/ is generated ;; and committed so CI stays `sphinx-build docs/source`. (require 'package) -(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t) (package-initialize) -(unless (package-installed-p 'ox-rst) - (package-refresh-contents) - (package-install 'ox-rst)) +(defconst yoda-ox-rst-version '(20250428 534)) +(defconst yoda-ox-rst-revision + "b73eff187eebac24b457688bfd27f09eff434860") + +(let ((installed (cadr (assq 'ox-rst package-alist)))) + (unless (and installed + (equal (package-desc-version installed) + yoda-ox-rst-version)) + (when installed + (package-delete installed t)) + (require 'package-vc) + (package-vc-install + `(ox-rst + :url "https://github.com/msnoigrs/ox-rst" + :rev ,yoda-ox-rst-revision)))) (require 'ox-rst) (require 'ox-publish) diff --git a/docs/orgmode/reference/lua.org b/docs/orgmode/reference/lua.org index 2294897..ec662d6 100644 --- a/docs/orgmode/reference/lua.org +++ b/docs/orgmode/reference/lua.org @@ -31,6 +31,13 @@ local nl = dseams.core.neighListO(3.5, cloud, 2) - ~chill_plus~ :: CHILL+ state names, no output file. - ~chill~ :: CHILL labels, no dump on disk. - ~cages~ :: seeded HC/DDC per-atom flags. +- ~cages_by_signature~ :: closed cages selected by their face census. +- ~guest_occupancy~ :: assign guest atoms to periodic cage centres. +- ~fingerprint~ :: label-independent bonded-topology keys. +- ~topology_library~ :: serialize topology keys under a label. +- ~classify_topology~ :: name atoms from one or more key libraries. +- ~ion_environment~ :: classify ion hydration shells by ice flags. +- ~shell_ring_census~ :: count rings that intersect a shell. - ~hbonds~ :: hydrogen-bond adjacency table. - ~density~ :: Cartesian number-density profile. - ~site_table~ :: parse a type-to-site mapping. @@ -100,7 +107,7 @@ raw bind. Wrapped names spell optionals in Lua (~sol::optional~). Names without a Lua wrapper need every argument the bound C++ signature requires. -* ~read~(path[, opts]) +* @@rst:``read(path[, opts])``@@ Suffix-dispatching loader. Returns a ~PointCloud~. @@ -133,7 +140,7 @@ The type argument is any LAMMPS type (the ~O~ is historical). # proseguard:on proselint.Uncomparables #+end_export -* ~neighbors~(cloud[, opts]) +* @@rst:``neighbors(cloud[, opts])``@@ Cutoff neighbour list by atom ID. Calls ~core.neighListO(opts.cutoff or 3.5, cloud, opts.type or 1)~. @@ -145,7 +152,7 @@ Hands back a Lua table of rows (self ID first). ~core.neighListPair(opts.cutoff or 3.5, cloud, opts.type_i or 1, opts.type_j or 2)~. Like-type pairs reuse ~neighListO~. -* ~cn~(cloud[, opts]) +* @@rst:``cn(cloud[, opts])``@@ Site-site coordination number. Calls ~core.calcCN~ with ~opts.type_i~ (default 1), ~opts.type_j~ (default 2), @@ -153,7 +160,7 @@ Site-site coordination number. Calls ~core.calcCN~ with ~floor(cutoff / 0.1)~). ~rhoJ~ is ~nJ / volume~ from the partial RDF. -* ~rdf~(cloud[, opts]) +* @@rst:``rdf(cloud[, opts])``@@ Partial three-dimensional radial distribution function. Calls ~core.calcRDF3D~ with ~opts.type_i~ (default 1), ~opts.type_j~ @@ -167,7 +174,7 @@ Shared options and defaults match ~rdf~. The call is ~core.calcRunningCN~. Hands back ~{r = r, cn = cn}~, with ~rhoJ = nJ / volume~. -* ~knn~(cloud[, opts]) +* @@rst:``knn(cloud[, opts])``@@ #+begin_export rst .. @@ -193,12 +200,12 @@ state names). Writes no file. Mutates ~cloud~. # proseguard:on proselint.Uncomparables #+end_export -* ~chill~(cloud[, opts]) +* @@rst:``chill(cloud[, opts])``@@ Same pipeline with ~core.getCorrel~ and ~core.getIceTypeNoPrint~. Mutates ~cloud~. Writes no file. -* ~cages~(cloud[, opts]) +* @@rst:``cages(cloud[, opts])``@@ #+begin_export rst .. @@ -223,7 +230,99 @@ local aff = dseams.cages(cloud, {type = 2}) local filled = dseams.cages(cloud, {type = 2, complete = true}) #+end_src -* ~seededCageAffiliation~(strictRings, strictNList, permRings, permNList[, ringAdjacentCompletion]) +* @@rst:``cages_by_signature(cloud, spec[, opts])``@@ + +Closed polyhedra whose faces match a ring-size census. ~spec~ is a +comma-separated census such as ~"4:6,6:8"~, or one of the named +signatures ~"sodalite"~, ~"alpha"~, ~"512"~, ~"51262"~, ~"hc"~, and +~"ddc"~. The helper builds a cutoff neighbour graph with +~opts.cutoff~ (default 3.5) and ~opts.type~ (default 1), converts it +to cloud indices, enumerates primitive rings through ~opts.max_ring~ +(default 8), and calls ~core.findBySignature~. + +The result is an array of +~{signature=, faces=, vertices=, certificate=}~ tables. The ~"hc"~ +and ~"ddc"~ names select the corresponding TUM finders. + +#+begin_src lua +local sod = dseams.cages_by_signature(cloud, "sodalite", {type = 1}) +print(#sod, sod[1] and #sod[1].vertices) +#+end_src + +* @@rst:``guest_occupancy(cloud, cages, guests[, opts])``@@ + +Assign guest atoms such as methane, THF, or ions to cages. ~cages~ +is an array of zero-based cloud-index lists and ~guests~ is an array +of zero-based cloud indices. Each guest is assigned to the nearest +periodic cage centroid within ~opts.radius~ (default 4.0). + +The result is +~{guestsPerCage=, cageOfGuest=, centreDistance=, occupied=, multiply=, free=}~. +~cageOfGuest~ contains zero-based cage indices and uses ~-1~ for a +free guest. ~core.periodicCentroid(cloud, atoms)~ computes a centroid +after unwrapping every cage atom to its minimum image about the first +atom. + +* @@rst:``fingerprint(rows[, opts])``@@ + +Compute label-independent topology keys for a bonded graph represented +as index rows, such as the result of ~core.neighbourListByIndex~. +~opts.hops~ defaults to 2 and ~opts.max_ring~ defaults to 7. +~opts.colours~ may supply one integer class per row so vertices of +different species cannot match. + +The result is +~{key=, method=, atomKeys=, classes=, ringCensus=, hops=}~. ~method~ +is ~"nauty"~ when the engine links nauty and ~"wl"~ otherwise. + +* @@rst:``topology_library(rows, label[, opts])``@@ + +Serialize the frame's distinct topology keys under ~label~. +~opts.library~ may contain an existing library to extend. ~opts.hops~, +~opts.max_ring~, and ~opts.colours~ have the same meanings and defaults +as for ~fingerprint~. + +* @@rst:``classify_topology(rows, library[, opts])``@@ + +Name every atom from a key-library string. ~library~ may instead be a +Lua sequence of library strings made at different hop counts; in that +case the deepest library containing an atom's key supplies its name and +~opts.hops~ is ignored. + +The result is ~{labels=, counts=, depth=, matched=}~. An unmatched atom +has an empty string in ~labels~, depth 0, and contributes to +~counts.unmatched~. + +#+begin_src lua +local lib2 = dseams.topology_library(rows, "Ic", {hops = 2}) +local lib3 = dseams.topology_library(rows, "Ic", {hops = 3}) +local named = dseams.classify_topology(rows, {lib2, lib3}) +print(named.matched, named.depth[1]) +#+end_src + +* @@rst:``ion_environment(cloud, ice, ions[, opts])``@@ + +Classify each ion from its first water shell against ~ice~, a +one-based per-atom boolean list. ~ions~ contains zero-based cloud +indices. ~opts.type~ is the water atom type (default 1), and +~opts.cutoff~ is the shell radius (default 3.5). A shell is ~"ice"~ +when every member is labelled, ~"liquid"~ when none is labelled, and +~"front"~ otherwise. + +The result is +~{ion=, shell=, iceFraction=, state=, members=, nIce=, nFront=, nLiquid=}~. +~members[i]~ lists ion ~i~'s shell. + +* @@rst:``shell_ring_census(rings, shell[, opts])``@@ + +Count rings that have at least one vertex in ~shell~. ~rings~ and +~shell~ contain zero-based cloud indices, as returned by +~core.ringNetwork~ and ~ion_environment~. Rings larger than +~opts.max_ring~ (default 7) are ignored. ~census[s + 1]~ is the count +of rings of size ~s~. Passing ~env.members[i]~ as ~shell~ gives the +hydration-shell ring census for ion ~i~. + +* @@rst:``seededCageAffiliation(strictRings, strictNList, permRings, permNList[, ringAdjacentCompletion])``@@ Compiled name on ~dseams.core~. Mutual-graph seeds, permissive-graph fill. Hands back ~{hc = hc, ddc = ddc}~, each a 1-based array of @@ -319,7 +418,7 @@ build directory: meson test -C bbdir dseams_legacy_chain #+end_src -* ~hbonds~(cloud[, opts]) +* @@rst:``hbonds(cloud[, opts])``@@ Hydrogen-bond adjacency for the selected sites. The neighbour graph uses ~opts.cutoff~ (default 3.5) and ~opts.type~ (default 1). @@ -334,7 +433,7 @@ uses ~opts.cutoff~ (default 3.5) and ~opts.type~ (default 1). Hands back a nested Lua table. Supplying neither ~path~ nor ~h_cloud~ is an error. -* ~density~(cloud[, opts]) +* @@rst:``density(cloud[, opts])``@@ #+begin_export rst .. @@ -364,21 +463,21 @@ userdata accepted by ~density~, ~pairs~, and ~domain~. Site kinds live on ~dseams.core.Kind~ (alias ~SiteKind~), including ~polar~ and ~apolar~. -* ~pairs~(cloud, opts) +* @@rst:``pairs(cloud, opts)``@@ Requires ~opts.table~. Maps the cloud to ionic sites and returns mutual nearest unlike pairs as ~{pairs = pairs, count = count, n_cation = n_cation, n_anion = n_anion}~. Each pair contains the original atom IDs. -* ~domain~(cloud, opts) +* @@rst:``domain(cloud, opts)``@@ Requires ~opts.table~ and ~opts.kind~. The graph joins mapped sites within ~opts.cutoff~ (default 3.5). Hands back ~{site_kind = site_kind, n = n, largest = largest, percolation = percolation}~. ~n~ is the selected site count and ~percolation = largest / n~. -* ~core~ +* @@rst:``core``@@ ~require("dseams_core")~ returns this table. Every name from ~luaApi::registerAll~ (~src/lua_api.cpp~) lives here. diff --git a/docs/source/reference/lua.rst b/docs/source/reference/lua.rst index 2be281d..582290b 100644 --- a/docs/source/reference/lua.rst +++ b/docs/source/reference/lua.rst @@ -54,6 +54,27 @@ Public names ``cages`` seeded HC/DDC per-atom flags. +``cages_by_signature`` + closed cages selected by their face census. + +``guest_occupancy`` + assign guest atoms to periodic cage centres. + +``fingerprint`` + label-independent bonded-topology keys. + +``topology_library`` + serialize topology keys under a label. + +``classify_topology`` + name atoms from one or more key libraries. + +``ion_environment`` + classify ion hydration shells by ice flags. + +``shell_ring_census`` + count rings that intersect a shell. + ``hbonds`` hydrogen-bond adjacency table. @@ -154,8 +175,8 @@ raw bind. Wrapped names spell optionals in Lua (``sol::optional``). Names without a Lua wrapper need every argument the bound C++ signature requires. -~read~(path[, opts]) --------------------- +``read(path[, opts])`` +---------------------- Suffix-dispatching loader. Returns a ``PointCloud``. @@ -191,8 +212,8 @@ The type argument is any LAMMPS type (the ``O`` is historical). .. # proseguard:on proselint.Uncomparables -~neighbors~(cloud[, opts]) --------------------------- +``neighbors(cloud[, opts])`` +---------------------------- Cutoff neighbour list by atom ID. Calls ``core.neighListO(opts.cutoff or 3.5, cloud, opts.type or 1)``. @@ -204,8 +225,8 @@ Pair neighbours ``neighbors_pair(cloud[, opts])`` returns an I-J cutoff neighbour list. Calls ``core.neighListPair(opts.cutoff or 3.5, cloud, opts.type_i or 1, opts.type_j or 2)``. Like-type pairs reuse ``neighListO``. -~cn~(cloud[, opts]) -------------------- +``cn(cloud[, opts])`` +--------------------- Site-site coordination number. Calls ``core.calcCN`` with ``opts.type_i`` (default 1), ``opts.type_j`` (default 2), @@ -213,8 +234,8 @@ Site-site coordination number. Calls ``core.calcCN`` with ``floor(cutoff / 0.1)``). ``rhoJ`` is ``nJ / volume`` from the partial RDF. -~rdf~(cloud[, opts]) --------------------- +``rdf(cloud[, opts])`` +---------------------- Partial three-dimensional radial distribution function. Calls ``core.calcRDF3D`` with ``opts.type_i`` (default 1), ``opts.type_j`` @@ -229,8 +250,8 @@ Shared options and defaults match ``rdf``. The call is ``core.calcRunningCN``. Hands back ``{r = r, cn = cn}``, with ``rhoJ = nJ / volume``. -~knn~(cloud[, opts]) --------------------- +``knn(cloud[, opts])`` +---------------------- .. # proseguard:off proselint.Uncomparables @@ -256,14 +277,14 @@ state names). Writes no file. Mutates ``cloud``. .. # proseguard:on proselint.Uncomparables -~chill~(cloud[, opts]) ----------------------- +``chill(cloud[, opts])`` +------------------------ Same pipeline with ``core.getCorrel`` and ``core.getIceTypeNoPrint``. Mutates ``cloud``. Writes no file. -~cages~(cloud[, opts]) ----------------------- +``cages(cloud[, opts])`` +------------------------ .. # proseguard:off proselint.Uncomparables @@ -286,8 +307,107 @@ other vertices already carry an HC or DDC label. local aff = dseams.cages(cloud, {type = 2}) local filled = dseams.cages(cloud, {type = 2, complete = true}) -~seededCageAffiliation~(strictRings, strictNList, permRings, permNList[, ringAdjacentCompletion]) -------------------------------------------------------------------------------------------------- +``cages_by_signature(cloud, spec[, opts])`` +------------------------------------------- + +Closed polyhedra whose faces match a ring-size census. ``spec`` is a +comma-separated census such as ``"4:6,6:8"``, or one of the named +signatures ``"sodalite"``, ``"alpha"``, ``"512"``, ``"51262"``, ``"hc"``, and +``"ddc"``. The helper builds a cutoff neighbour graph with +``opts.cutoff`` (default 3.5) and ``opts.type`` (default 1), converts it +to cloud indices, enumerates primitive rings through ``opts.max_ring`` +(default 8), and calls ``core.findBySignature``. + +The result is an array of +``{signature=, faces=, vertices=, certificate=}`` tables. The ``"hc"`` +and ``"ddc"`` names select the corresponding TUM finders. + +.. code:: lua + + local sod = dseams.cages_by_signature(cloud, "sodalite", {type = 1}) + print(#sod, sod[1] and #sod[1].vertices) + +``guest_occupancy(cloud, cages, guests[, opts])`` +------------------------------------------------- + +Assign guest atoms such as methane, THF, or ions to cages. ``cages`` +is an array of zero-based cloud-index lists and ``guests`` is an array +of zero-based cloud indices. Each guest is assigned to the nearest +periodic cage centroid within ``opts.radius`` (default 4.0). + +The result is +``{guestsPerCage=, cageOfGuest=, centreDistance=, occupied=, multiply=, free=}``. +``cageOfGuest`` contains zero-based cage indices and uses ``-1`` for a +free guest. ``core.periodicCentroid(cloud, atoms)`` computes a centroid +after unwrapping every cage atom to its minimum image about the first +atom. + +``fingerprint(rows[, opts])`` +----------------------------- + +Compute label-independent topology keys for a bonded graph represented +as index rows, such as the result of ``core.neighbourListByIndex``. +``opts.hops`` defaults to 2 and ``opts.max_ring`` defaults to 7. +``opts.colours`` may supply one integer class per row so vertices of +different species cannot match. + +The result is +``{key=, method=, atomKeys=, classes=, ringCensus=, hops=}``. ``method`` +is ``"nauty"`` when the engine links nauty and ``"wl"`` otherwise. + +``topology_library(rows, label[, opts])`` +----------------------------------------- + +Serialize the frame's distinct topology keys under ``label``. +``opts.library`` may contain an existing library to extend. ``opts.hops``, +``opts.max_ring``, and ``opts.colours`` have the same meanings and defaults +as for ``fingerprint``. + +``classify_topology(rows, library[, opts])`` +-------------------------------------------- + +Name every atom from a key-library string. ``library`` may instead be a +Lua sequence of library strings made at different hop counts; in that +case the deepest library containing an atom's key supplies its name and +``opts.hops`` is ignored. + +The result is ``{labels=, counts=, depth=, matched=}``. An unmatched atom +has an empty string in ``labels``, depth 0, and contributes to +``counts.unmatched``. + +.. code:: lua + + local lib2 = dseams.topology_library(rows, "Ic", {hops = 2}) + local lib3 = dseams.topology_library(rows, "Ic", {hops = 3}) + local named = dseams.classify_topology(rows, {lib2, lib3}) + print(named.matched, named.depth[1]) + +``ion_environment(cloud, ice, ions[, opts])`` +--------------------------------------------- + +Classify each ion from its first water shell against ``ice``, a +one-based per-atom boolean list. ``ions`` contains zero-based cloud +indices. ``opts.type`` is the water atom type (default 1), and +``opts.cutoff`` is the shell radius (default 3.5). A shell is ``"ice"`` +when every member is labelled, ``"liquid"`` when none is labelled, and +``"front"`` otherwise. + +The result is +``{ion=, shell=, iceFraction=, state=, members=, nIce=, nFront=, nLiquid=}``. +``members[i]`` lists ion ``i``'s shell. + +``shell_ring_census(rings, shell[, opts])`` +------------------------------------------- + +Count rings that have at least one vertex in ``shell``. ``rings`` and +``shell`` contain zero-based cloud indices, as returned by +``core.ringNetwork`` and ``ion_environment``. Rings larger than +``opts.max_ring`` (default 7) are ignored. ``census[s + 1]`` is the count +of rings of size ``s``. Passing ``env.members[i]`` as ``shell`` gives the +hydration-shell ring census for ion ``i``. + +``seededCageAffiliation(strictRings, strictNList, permRings, permNList[, ringAdjacentCompletion])`` +--------------------------------------------------------------------------------------------------- Compiled name on ``dseams.core``. Mutual-graph seeds, permissive-graph fill. Hands back ``{hc = hc, ddc = ddc}``, each a 1-based array of @@ -378,8 +498,8 @@ build directory: meson test -C bbdir dseams_legacy_chain -~hbonds~(cloud[, opts]) ------------------------ +``hbonds(cloud[, opts])`` +------------------------- Hydrogen-bond adjacency for the selected sites. The neighbour graph uses ``opts.cutoff`` (default 3.5) and ``opts.type`` (default 1). @@ -396,8 +516,8 @@ uses ``opts.cutoff`` (default 3.5) and ``opts.type`` (default 1). Hands back a nested Lua table. Supplying neither ``path`` nor ``h_cloud`` is an error. -~density~(cloud[, opts]) ------------------------- +``density(cloud[, opts])`` +-------------------------- .. # proseguard:off rgoswami.ReviewRegister @@ -425,16 +545,16 @@ userdata accepted by ``density``, ``pairs``, and ``domain``. Site kinds live on ``dseams.core.Kind`` (alias ``SiteKind``), including ``polar`` and ``apolar``. -~pairs~(cloud, opts) --------------------- +``pairs(cloud, opts)`` +---------------------- Requires ``opts.table``. Maps the cloud to ionic sites and returns mutual nearest unlike pairs as ``{pairs = pairs, count = count, n_cation = n_cation, n_anion = n_anion}``. Each pair contains the original atom IDs. -~domain~(cloud, opts) ---------------------- +``domain(cloud, opts)`` +----------------------- Requires ``opts.table`` and ``opts.kind``. The graph joins mapped sites within ``opts.cutoff`` (default 3.5). Hands back