vibe-sketcherDocumentation

vibesketcher.document.guest_loading

Reproducible guest loading: complete molecules packed into a periodic host (#203).

A loading request names a host structure, the guest components (SMILES, a document species or explicit atoms) with an explicit count or density each, a random seed, an orientation policy, a radius table, a collision scale, an attempt budget and the host-symmetry choice. The preview returns a derived model under a new ID with the requested and placed counts, the rejected trial insertions by cause, every guest’s parent identity and the source digest, or refusals with stable codes. Nothing is stored until the derived model is applied, and an applied loading can be undone while the derived model is unchanged (the same contract as vibesketcher.document.periodic_prepare).

Method. Guests are placed by random sequential insertion of rigid bodies, the trial-insertion scheme of Monte Carlo packing (Allen and Tildesley, Computer Simulation of Liquids, 2nd ed., 2017, sections 4.4 and 5.3): a uniformly random centre in the region and, with orientation="random", a uniformly random rotation from a unit quaternion (K. Shoemake, “Uniform random rotations”, Graphics Gems III, 1992, 124-132). A trial is accepted when no guest atom comes closer than collision_scale (r_i + r_j) to a host atom, an earlier guest or a periodic image of itself; overlap is judged per atom pair with a per-element radius, as in Packmol’s distance tolerance (L. Martinez, R. Andrade, E. G. Birgin and J. M. Martinez, J. Comput. Chem. 30, 2157-2164 (2009), doi:10.1002/jcc.21224). Packmol minimises an overlap penalty over all molecules at once; this module does not optimise and never moves an accepted guest, so it fills loosely packed regions and runs out of budget earlier near close packing, which it reports instead of hiding. Packmol is not used or required. Neighbour lookup is a linked-cell grid over lattice planes, as in vibesketcher.document.periodic_graph.neighbours().

Every guest keeps its own bond graph (from the SMILES, or explicit bonds), is stored whole (coordinates="unwrapped": its centre in the home cell, its atoms contiguous across the faces) or wrapped site by site with bond images, and never bonds to the host or another guest by proximity. A host symmetry is never assumed: symmetry="p1" treats the host as a P1 cell, and symmetry="orbit" places every guest together with its images under the host’s space-group operations (given, or found by spglib from the symmetry extra). Charged guests need an explicit compensation statement.

Geometric packing is not adsorption equilibrium, an accessible loading capacity or a thermodynamic ensemble; a loaded model is a reviewed starting geometry.

Module Attributes

MAX_ATTEMPTS

Trial insertions one request may make.

MAX_GUESTS

Guest molecules one request may ask for.

ORBIT_TOLERANCE

Two orbit copies whose atoms agree within this distance (angstrom) are one molecule.

CODES

Stable refusal and notice codes.

Functions

apply(document, loading, *[, source_sha256])

Add the loaded model to a copy of document; refusals and stale sources fail.

content_digest(structure)

Digest of a structure without its provenance (which records the digest).

parse_loading(data)

preview(host, loading[, document])

The loaded model, its counts, rejections, refusals and provenance; nothing is stored.

radius_of(symbol, table, overrides)

The collision radius: an override, or RDKit's van der Waals or covalent radius.

undo(document, identifier)

Remove a loaded model again, if it is unchanged since it was loaded.

Classes

GuestAtom(*, symbol, xyz)

GuestComponent(*[, label, smiles, species, ...])

One guest species and how many copies of it to place.

GuestLoading(*, source[, identifier, ...])

Region(*[, kind, lower, upper, axis, margin])

Where guest atoms may go: the whole cell, a fractional box or a slab's vacuum gap.

vibesketcher.document.guest_loading.MAX_ATTEMPTS = 1000000

Trial insertions one request may make.

vibesketcher.document.guest_loading.MAX_GUESTS = 25000

Guest molecules one request may ask for.

vibesketcher.document.guest_loading.ORBIT_TOLERANCE = 0.001

Two orbit copies whose atoms agree within this distance (angstrom) are one molecule. It is far below any collision distance: a guest near a special position is rejected as overlapping its image, never merged (which would break the symmetry).

vibesketcher.document.guest_loading.CODES: dict[str, str] = {'guest.bonds_perceived': "a guest's bonds were perceived from its geometry, not drawn", 'guest.budget_exhausted': 'the attempt budget ran out before every guest was placed', 'guest.charge_compensation_unstated': 'charged guests need a charge_compensation choice', 'guest.charge_not_compensated': 'the stated compensation does not balance the charges', 'guest.charged_cell': 'the loaded model carries a net charge by request', 'guest.host_charge_unstated': "the compensation needs the host's charge to be stated", 'guest.host_partial_occupancy': 'the host has partially occupied or disordered sites', 'guest.host_symmetry_record': "the host's recorded space group describes the host only", 'guest.multiplicity_unstated': "the loaded model's spin multiplicity is left unstated", 'guest.nothing_requested': 'every component asks for zero guests', 'guest.orbit_density': 'a density target is ambiguous under orbit placement', 'guest.orbit_region': 'orbit placement fills the whole cell, not a region', 'guest.partial_placement': 'fewer guests were placed than requested (partial result)', 'guest.region_empty': 'the region has no volume, or the host leaves no vacuum gap', 'guest.symmetry_unavailable': 'orbit placement needs operations or the symmetry extra', 'guest.too_many_sites': 'the loaded model would exceed the site limit'}

Stable refusal and notice codes.

class vibesketcher.document.guest_loading.GuestAtom(*, symbol, xyz)[source]

Bases: _Model

Parameters:
symbol: str
xyz: tuple[float, float, float]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.guest_loading.GuestComponent(*, label=None, smiles=None, species=None, atoms=<factory>, bonds=None, charge=None, count=None, density_g_cm3=None)[source]

Bases: _Model

One guest species and how many copies of it to place.

Parameters:
label: str | None
smiles: str | None
species: str | None
atoms: list[GuestAtom]
bonds: list[tuple[int, int, float]] | None

Bonds of explicit atoms as [i, j, order] (0-based); perceived when omitted.

charge: int | None

Net charge of explicit atoms; SMILES and species state their own.

count: int | None
density_g_cm3: float | None

Or a nominal density over the region’s volume (host volume not excluded).

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.guest_loading.Region(*, kind='cell', lower=None, upper=None, axis=2, margin=1.0)[source]

Bases: _Model

Where guest atoms may go: the whole cell, a fractional box or a slab’s vacuum gap.

Parameters:
kind: Literal['cell', 'box', 'vacuum_gap']
lower: _Frac | None
upper: _Frac | None
axis: int

lattice axis (0, 1 or 2) across the gap, and the clearance kept (angstrom).

Type:

vacuum_gap

margin: float
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.guest_loading.GuestLoading(*, source, identifier=None, guests, seed, symmetry, operations=None, symprec=0.001, orientation='random', radii='vdw', radius_overrides=<factory>, collision_scale=0.75, max_attempts=10000, on_exhausted='refuse', charge_compensation=None, region=<factory>, coordinates='unwrapped')[source]

Bases: _Model

Parameters:
  • source (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • identifier (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])] | None)

  • guests (Annotated[list[GuestComponent], MinLen(min_length=1), MaxLen(max_length=20)])

  • seed (Annotated[int, Ge(ge=0), Lt(lt=9223372036854775808)])

  • symmetry (Literal['p1', 'orbit'])

  • operations (Annotated[list[str] | None, MinLen(min_length=1), MaxLen(max_length=192)])

  • symprec (Annotated[float, Gt(gt=0), Le(le=1)])

  • orientation (Literal['random', 'as_is'])

  • radii (Literal['vdw', 'covalent'])

  • radius_overrides (Annotated[dict[str, float], MaxLen(max_length=118)])

  • collision_scale (Annotated[float, Ge(ge=0.3), Le(le=1.5), AllowInfNan(allow_inf_nan=False)])

  • max_attempts (Annotated[int, Ge(ge=1), Le(le=1000000)])

  • on_exhausted (Literal['refuse', 'partial'])

  • charge_compensation (Literal['guest_neutral', 'host_compensates', 'net_charge'] | None)

  • region (Region)

  • coordinates (Literal['unwrapped', 'wrapped'])

source: _ID
identifier: _ID | None
guests: list[GuestComponent]
seed: int
symmetry: Literal['p1', 'orbit']
operations: list[str] | None

operations as x,y,z strings; found by spglib when omitted.

Type:

Orbit placement

symprec: float
orientation: Literal['random', 'as_is']
radii: Literal['vdw', 'covalent']
radius_overrides: dict[str, float]
collision_scale: float
max_attempts: int
on_exhausted: Literal['refuse', 'partial']
charge_compensation: Literal['guest_neutral', 'host_compensates', 'net_charge'] | None
region: Region
coordinates: Literal['unwrapped', 'wrapped']
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibesketcher.document.guest_loading.parse_loading(data)[source]
Parameters:

data (dict[str, Any])

Return type:

GuestLoading

vibesketcher.document.guest_loading.content_digest(structure)[source]

Digest of a structure without its provenance (which records the digest).

Parameters:

structure (PeriodicStructure)

Return type:

str

vibesketcher.document.guest_loading.radius_of(symbol, table, overrides)[source]

The collision radius: an override, or RDKit’s van der Waals or covalent radius.

Parameters:
Return type:

float

vibesketcher.document.guest_loading.preview(host, loading, document=None)[source]

The loaded model, its counts, rejections, refusals and provenance; nothing is stored.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.guest_loading.apply(document, loading, *, source_sha256=None)[source]

Add the loaded model to a copy of document; refusals and stale sources fail.

Parameters:
Return type:

Document

vibesketcher.document.guest_loading.undo(document, identifier)[source]

Remove a loaded model again, if it is unchanged since it was loaded.

Parameters:
Return type:

Document