Guest loading in periodic hosts¶
Guest loading packs complete molecules into a periodic host: a molecule in the pore of a framework, or solvent and ions in the vacuum of a slab. A loading is reproducible. The same host, guests, seed and options give the same model. Each guest keeps its own bond graph and is never bonded to the host or to another guest by proximity. The result is previewed as a derived model with its counts, rejections and parent identities before anything is stored. The host itself is never changed.
Geometric packing is not adsorption equilibrium. It is not an accessible loading capacity or a thermodynamic ensemble either. A loaded model is a reviewed starting geometry. Equilibrium loadings need a grand-canonical simulation, and calculations on the loaded model are a separate step.
The request¶
Field |
Meaning |
|---|---|
|
The host structure. |
|
ID of the loaded model (default |
|
Components, placed in the order given: each one of |
|
The random seed (required). |
|
|
|
|
|
|
|
Per-element radii in angstrom. |
|
Two atoms overlap when |
|
Trial insertions in total (default 10000, at most 1000000). |
|
|
|
|
|
|
|
|
A SMILES guest is embedded in 3D with RDKit’s ETKDG and MMFF94 under a fixed
seed, the same embedding the adsorbate builder uses, and keeps the bonds of
its SMILES, hydrogens included. A species guest uses its first stored
conformer, or its SMILES when it has none. Explicit atoms take their bonds as
[i, j, order]. When a geometry has no matching graph, its bonds are
perceived inside the molecule from covalent radii, stored as perceived
edges and reported with guest.bonds_perceived. Perceived edges wait for
review in the graph report.
A density_g_cm3 sets the count from the nominal density over the region’s
volume, n = rho V N_A / M, rounded to the nearest whole molecule. The
volume the host occupies is not subtracted.
How guests are placed¶
Guests are placed one at a time by random sequential insertion of rigid
bodies. Each trial draws a centre uniformly in the region and, with
orientation="random", a uniform random rotation from a unit quaternion
(Shoemake, Graphics Gems III, 1992). A trial is rejected when any atom comes
closer than collision_scale (r_i + r_j) to a host atom, an earlier guest or
a periodic image of its own molecule. It is also rejected when an atom leaves
the region or crosses a nonperiodic face of the cell. Overlap is judged per
atom pair from per-element radii, like the distance tolerance of Packmol
(Martinez et al., J. Comput. Chem. 30, 2157, 2009). Packmol optimises
all molecules at once. Here an accepted guest is never moved, so close packing
runs out of attempts sooner, and the preview says so. Packmol is neither used
nor required.
The random numbers come from NumPy’s PCG64 generator seeded with seed.
Molecules that cross a periodic cell face stay whole. With
coordinates="unwrapped", each guest’s centre lies in the home cell and its
atoms are contiguous, so some fractional coordinates lie outside 0 to 1. With
coordinates="wrapped", every site is wrapped into the cell and the guest’s
bonds carry the image they cross. In both cases the graph report counts each
guest as one molecule.
Host symmetry¶
A host’s symmetry is never assumed. The request states one of two choices:
p1The host is treated as a P1 cell. Guests are placed independently, and the loaded model has no symmetry beyond what chance gives it. When the host records a space group, the notice
guest.host_symmetry_recordsays that the record describes the host only.orbitEvery placed guest comes with its images under the host’s space-group operations, so the loaded model keeps the host’s space group. Give the operations as
x,y,zstrings inoperations, or leave them out to have spglib find them atsymprec; spglib needs thesymmetryextra. Copies that coincide atom for atom within 0.001 A are one molecule. A guest near a special position overlaps its own image and is rejected rather than merged.countthen counts orbits, and the preview reports the molecules placed. An orbit fills the whole cell, so aboxorvacuum_gapregion and a density target are refused.
Ions and charge¶
Charged guests, from formal charges in the SMILES, the species charge or an
explicit charge, need charge_compensation. Without it the loading is
refused.
guest_neutralThe placed guests carry no net charge, for example as many Na+ as Cl-. The host charge is unchanged.
host_compensatesThe guests cancel a stated host charge, for example cations in an anionic framework. The loaded model has charge 0.
net_chargeThe loaded model keeps the sum of the host and guest charges. A charged cell is reported as a notice.
host_compensates and net_charge need the host’s charge to be stated. A
stated host multiplicity becomes unspecified once guests are added.
Counts, refusals and provenance¶
The preview returns the requested counts per component, the placed counts,
the molecules placed (orbit copies included) and the attempts used. It counts
rejected trials by cause: host, guest, self_image, orbit_overlap and
outside_region. For each guest it records the component, its parent
identity (SMILES, species ID or explicit atoms), its charge, its site IDs, its
orbit and operation and the attempt that placed it. The digest of the host
(source_sha256) is included, and the loaded model’s provenance (guests)
keeps the same record.
When the attempt budget runs out, the loading is refused with
guest.budget_exhausted and the counts reached. With on_exhausted="partial",
the guests placed so far are kept, and the notice guest.partial_placement
appears.
Code |
Meaning |
|---|---|
|
The budget ran out. |
|
Empty or oversized requests. |
|
Charge refusals. |
|
Orbit refusals. |
|
No room, or a disordered host. |
|
Notices. |
Applying adds the loaded model next to its host. The apply is revision-checked
and refused while the preview has refusals. With the preview’s
source_sha256, it is also refused when the host has changed since. A loading
can be undone while the loaded model is unchanged. Saving and loading the
document, and QVF export, keep the guests, their bonds and the record.
Examples¶
A molecule in a pore: four benzene molecules in the primitive MOF-5 cell from the framework builder.
from vibesketcher.document import guest_loading as gl
from vibesketcher.document import new_document
from vibesketcher.document.solid_build import build, parse_recipe
document = build(
new_document(),
parse_recipe(
{
"kind": "framework",
"identifier": "mof5",
"node": "zn4o",
"linker": "bdc",
"cell": "primitive",
}
),
)
loading = gl.parse_loading(
{
"source": "mof5",
"guests": [{"smiles": "c1ccccc1", "count": 4}],
"seed": 7,
"symmetry": "p1",
}
)
preview = gl.preview(document.periodic_structures[0], loading, document)
document = gl.apply(document, loading, source_sha256=preview["source_sha256"])
Solvent and ions in a slab’s vacuum: water with one Na+ and one Cl- in the larger vacuum gap of an MgO(001) slab, at least 1.5 A from the surface.
vibe-sketcher solid crystal mgo.vsk --id mgo --prototype rocksalt --cell conventional
vibe-sketcher solid slab mgo.vsk --source mgo --id slab --miller 0,0,1 --layers 4 \
--repeat 3,3 --vacuum 30
vibe-sketcher solid load-guests mgo.vsk --source slab --smiles O:8 \
--smiles "[Na+]:1" --smiles "[Cl-]:1" --charge-compensation guest_neutral \
--region vacuum_gap --margin 1.5 --seed 11 --symmetry p1
vibe-sketcher solid load-guests mgo.vsk --source slab --smiles O:8 \
--smiles "[Na+]:1" --smiles "[Cl-]:1" --charge-compensation guest_neutral \
--region vacuum_gap --margin 1.5 --seed 11 --symmetry p1 --apply
vibe-sketcher solid load-guests-undo mgo.vsk --structure slab-loaded
solid load-guests without --apply prints the preview as JSON and exits
with status 3 when it is refused. --smiles and --species take
VALUE:COUNT or VALUE:density=G_CM3. --request FILE reads the whole
request as JSON, for explicit atoms and every option.
In the browser¶
Open Solid-state builder… from the command palette and use the Load guests into a host form. It sends the same request as the REST routes below, so every placement, count and refusal comes from the server.
Choose the Host structure and, optionally, a new ID.
List the guests, one per line: a SMILES or
species:IDof a drawn species, then a whole count ordensity=G_CM3, for examplec1ccccc1 4orO density=1.0.Set the seed, the host symmetry choice (
P1or orbit, with optionalx,y,zoperations separated by semicolons), the orientation, radii, collision scale, attempt budget and what happens when it runs out. Charged guests need a charge compensation choice. The box corners and the vacuum gap’s axis and margin appear only for their region.Choose Preview loading. The panel shows the loaded model’s formula and site count, a top-view schematic, the placed and requested counts per component, the attempts and the rejected trials by cause. Refusals and notices are listed with their codes and messages exactly as the server returns them. A preview changes nothing.
Add reviewed loading adds the previewed model, checked against the previewed revision and the host digest. Changing any input first discards the preview. Undo loading removes the added model again while it is unchanged.
REST and MCP¶
POST /api/documents/{id}/periodic/guests/previewtakesloadingand changes nothing.POST /api/documents/{id}/periodic/gueststakesrevision,loadingand optionally the preview’ssource_sha256.POST /api/documents/{id}/periodic/guests/undotakesrevisionandstructure.
A stale revision is answered with 409. The MCP tools are
preview_guest_loading and apply_guest_loading (with undo).