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
Trial insertions one request may make. |
|
Guest molecules one request may ask for. |
|
Two orbit copies whose atoms agree within this distance (angstrom) are one molecule. |
|
Stable refusal and notice codes. |
Functions
|
Add the loaded model to a copy of |
|
Digest of a structure without its provenance (which records the digest). |
|
|
|
The loaded model, its counts, rejections, refusals and provenance; nothing is stored. |
|
The collision radius: an override, or RDKit's van der Waals or covalent radius. |
|
Remove a loaded model again, if it is unchanged since it was loaded. |
Classes
|
|
|
One guest species and how many copies of it to place. |
|
|
|
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- 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:
_ModelOne guest species and how many copies of it to place.
- Parameters:
- bonds: list[tuple[int, int, float]] | None¶
Bonds of explicit atoms as
[i, j, order](0-based); perceived when omitted.
- 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:
_ModelWhere guest atoms may go: the whole cell, a fractional box or a slab’s vacuum gap.
- Parameters:
- kind: Literal['cell', 'box', 'vacuum_gap']¶
- axis: int¶
lattice axis (0, 1 or 2) across the gap, and the clearance kept (angstrom).
- Type:
vacuum_gap
- 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)])
symmetry (Literal['p1', 'orbit'])
operations (Annotated[list[str] | None, MinLen(min_length=1), MaxLen(max_length=192)])
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)])
on_exhausted (Literal['refuse', 'partial'])
charge_compensation (Literal['guest_neutral', 'host_compensates', 'net_charge'] | None)
region (Region)
coordinates (Literal['unwrapped', 'wrapped'])
- source: _ID¶
- guests: list[GuestComponent]¶
- symmetry: Literal['p1', 'orbit']¶
- operations: list[str] | None¶
operations as
x,y,zstrings; found by spglib when omitted.- Type:
Orbit placement
- orientation: Literal['random', 'as_is']¶
- radii: Literal['vdw', 'covalent']¶
- on_exhausted: Literal['refuse', 'partial']¶
- 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.content_digest(structure)[source]¶
Digest of a structure without its provenance (which records the digest).
- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.guest_loading.radius_of(symbol, table, overrides)[source]¶
The collision radius: an override, or RDKit’s van der Waals or covalent radius.
- vibesketcher.document.guest_loading.preview(host, loading, document=None)[source]¶
The loaded model, its counts, rejections, refusals and provenance; nothing is stored.
- Parameters:
host (PeriodicStructure)
loading (GuestLoading)
document (Document | None)
- Return type:
- 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:
document (Document)
loading (GuestLoading)
source_sha256 (str | None)
- Return type: