Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions .github/workflows/ci_docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 15 additions & 4 deletions docs/export.el
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
125 changes: 112 additions & 13 deletions docs/orgmode/reference/lua.org
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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~.

Expand Down Expand Up @@ -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)~.
Expand All @@ -145,15 +152,15 @@ 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),
~opts.cutoff~ (default 4.5), and ~opts.bins~ (default
~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~
Expand All @@ -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
..
Expand All @@ -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
..
Expand All @@ -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
Expand Down Expand Up @@ -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).
Expand All @@ -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
..
Expand Down Expand Up @@ -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.
Expand Down
Loading
Loading