vibe-sketcherDocumentation

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

source

The host structure.

identifier

ID of the loaded model (default SOURCE-loaded).

guests

Components, placed in the order given: each one of smiles, species (a document species) or atoms (with bonds and charge), and either count or density_g_cm3.

seed

The random seed (required).

symmetry

p1 or orbit (required); see below.

orientation

random (uniform random rotations) or as_is.

radii

vdw (RDKit’s van der Waals radii) or covalent (Cordero et al. 2008).

radius_overrides

Per-element radii in angstrom.

collision_scale

Two atoms overlap when d < scale (r_i + r_j); default 0.75.

max_attempts

Trial insertions in total (default 10000, at most 1000000).

on_exhausted

refuse (default) or partial.

charge_compensation

guest_neutral, host_compensates or net_charge; required for charged guests.

region

cell (default), box with fractional lower and upper corners, or vacuum_gap with an axis and a margin in angstrom.

coordinates

unwrapped (default) or wrapped.

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:

p1

The 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_record says that the record describes the host only.

orbit

Every 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,z strings in operations, or leave them out to have spglib find them at symprec; spglib needs the symmetry extra. 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. count then counts orbits, and the preview reports the molecules placed. An orbit fills the whole cell, so a box or vacuum_gap region 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_neutral

The placed guests carry no net charge, for example as many Na+ as Cl-. The host charge is unchanged.

host_compensates

The guests cancel a stated host charge, for example cations in an anionic framework. The loaded model has charge 0.

net_charge

The 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

guest.budget_exhausted, guest.partial_placement

The budget ran out.

guest.nothing_requested, guest.too_many_sites

Empty or oversized requests.

guest.charge_compensation_unstated, guest.charge_not_compensated, guest.host_charge_unstated

Charge refusals.

guest.symmetry_unavailable, guest.orbit_region, guest.orbit_density

Orbit refusals.

guest.region_empty, guest.host_partial_occupancy

No room, or a disordered host.

guest.host_symmetry_record, guest.multiplicity_unstated, guest.bonds_perceived, guest.charged_cell

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.

  1. Choose the Host structure and, optionally, a new ID.

  2. List the guests, one per line: a SMILES or species:ID of a drawn species, then a whole count or density=G_CM3, for example c1ccccc1 4 or O density=1.0.

  3. Set the seed, the host symmetry choice (P1 or orbit, with optional x,y,z operations 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.

  4. 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.

  5. 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/preview takes loading and changes nothing.

  • POST /api/documents/{id}/periodic/guests takes revision, loading and optionally the preview’s source_sha256.

  • POST /api/documents/{id}/periodic/guests/undo takes revision and structure.

A stale revision is answered with 409. The MCP tools are preview_guest_loading and apply_guest_loading (with undo).