vibesketcher.document.polymer_packing¶
Amorphous polymer boxes and membranes grown from stated repeat units (#205).
A packing request names the repeat units (a SMILES with two connection
markers, a polymer template from the library or a bracketed repeat unit drawn
in the document), the chains to build from them (homopolymer, explicit
sequence or a composition with an arrangement, chain lengths, tacticity and
end groups), the cell (a periodic box, or a membrane periodic in plane with a
nonperiodic normal and vacuum), a target density or explicit lengths, the
torsion states, a radius table, a collision scale, attempt limits and the
seed. The preview returns a derived periodic model under a new ID with each
chain’s sequence, its parent repeat-unit map and the connection markers it
consumed, the checks below and refusals with stable codes. Nothing is stored
until the model is applied, and an applied packing can be undone while the
model is unchanged (the contract of vibesketcher.document.guest_loading).
The drawing templates and sequence notation are not changed. A template or drawn bracket is only read for its structural repeat unit (SRU): the atoms in the bracket, with a connection marker on each of the two bonds crossing it.
Method. Each chain is grown unit by unit as a self-avoiding walk in the cell,
the chain-growth construction of amorphous polymer cells by D. N. Theodorou and
U. W. Suter (Macromolecules 18, 1467-1478 (1985), doi:10.1021/ma00149a018).
The repeat unit is embedded once with RDKit (ETKDGv3 and MMFF94 under a fixed
seed, the embedding of the framework builder) with hydrogen stand-ins on its
connection markers; the stand-in directions are the bond directions. A new
unit is placed so that its head atom sits on the previous tail’s bond
direction at the covalent bond length and its own head direction points back,
which leaves the torsion about the new bond free. That torsion, and each
rotatable single backbone bond inside the unit, takes one of the stated
rotational-isomeric states (P. J. Flory, Statistical Mechanics of Chain
Molecules, 1969; default trans 180 deg with weight 1 and gauche +-60 deg with
weight 0.5, of the order of polyethylene’s first-order weight, A. Abe, R. L.
Jernigan and P. J. Flory, J. Am. Chem. Soc. 88, 631-639 (1966),
doi:10.1021/ja00956a001), plus a uniform offset of at most
torsion_jitter_deg. Conjugated bonds inside a unit keep the embedded
torsion, a conjugated junction tries twelve evenly spaced torsions with equal
weight, and side-group rotors (methyls, ester alkyls) turn uniformly. Every
junction state is tried; a state is free when no atom of the new unit comes
closer than collision_scale (r_i + r_j) to an atom of another chain, of
its own chain more than three bonds away, or of a periodic image, and stays
inside the growth region and outside the excluded regions. A free state is
chosen with probability proportional to its weight, the selection of
Rosenbluth growth (M. N. Rosenbluth and A. W. Rosenbluth, J. Chem. Phys. 23,
356-359 (1955), doi:10.1063/1.1741967). Long-range interactions are a hard
core here, not the energies Theodorou and Suter minimise afterwards; nothing
is relaxed. A step with no free state is retried with fresh internal
torsions, then the previous placement is undone and redrawn (backtracking),
and past max_backtracks the chain is regrown from a new start, within the
stated limits. Crowded backbones (quaternary carbons, as in PMMA or
polyisobutylene) open their bond angles on relaxation and may need a smaller
collision scale here. Neighbour lookup is a linked-cell grid (Allen and
Tildesley, Computer Simulation of Liquids, 2nd ed., 2017, 5.3).
Tacticity is a configuration, not a torsion: an isotactic chain repeats one embedded enantiomer of a unit with a backbone stereocentre, a syndiotactic chain alternates it with its mirror image, and an atactic chain draws each from the seed. The placed chain is checked from its coordinates: the sign of each backbone stereocentre’s (head-side, tail-side, side group) volume gives meso and racemo diads.
Every chain keeps its own bond graph and is stored wrapped site by site with bond images; no bond joins two chains (crosslinking needs explicit chemistry and conversion and is refused, never inferred from contacts). The checks are one connected component per chain and no bond between chains, valence by RDKit sanitisation of each chain, every bond’s image length against covalent radii, and the element count against the stated units and end groups. A packed cell at the target density is an unrelaxed starting geometry, not an equilibrated morphology.
Fixed inclusions (#241). preview() also takes an Inclusion: a
cell and growth region stated by the caller, fixed atoms (such as a nanotube
bundle) entered in the collision grid before the first chain, and a test for
forbidden interiors (such as the inside of a tube). A placement that overlaps an
inclusion atom is rejected as inclusion_contact and one with an atom in a
forbidden interior as inclusion_interior; the inclusion atoms themselves are
not part of the derived model, which the caller combines with them.
Module Attributes
Chains one request may ask for, and repeat units one chain may have. |
|
Candidate placements (one per torsion state tried) one request may make. |
|
Real atoms one repeat unit or end group may have (hydrogens included). |
|
Bond images are checked against covalent radii within these factors. |
|
The grid's chain index of an inclusion atom. |
Functions
|
The chain-local index of a placement's head or tail anchor. |
|
Add the packed model to a copy of |
|
The chain's atom symbols in chain-local order (by fragment start). |
|
Digest of a structure without its provenance (which records the digest). |
|
|
|
The packed model, its chains, checks, refusals and provenance; nothing is stored. |
|
Remove a packed model again, if it is unchanged since it was packed. |
Classes
|
A periodic orthorhombic box, or a membrane periodic in a and b with vacuum along c. |
|
A group of chains built the same way. |
|
Explicit crosslinking chemistry and conversion (not implemented: refused). |
|
Fixed atoms the chains grow around, in a cell the caller states (#241). |
|
|
|
A fractional box no atom may enter (an exclusion rule), such as a pore kept open. |
|
One structural repeat unit with a head and a tail connection point. |
|
Exceptions
|
A repeat unit or end group cannot be used; |
- vibesketcher.document.polymer_packing.MAX_CHAINS = 500¶
Chains one request may ask for, and repeat units one chain may have.
- vibesketcher.document.polymer_packing.MAX_ATTEMPTS = 5000000¶
Candidate placements (one per torsion state tried) one request may make.
- vibesketcher.document.polymer_packing.MAX_UNIT_ATOMS = 300¶
Real atoms one repeat unit or end group may have (hydrogens included).
- vibesketcher.document.polymer_packing.BOND_LENGTH_WINDOW = (0.75, 1.3)¶
Bond images are checked against covalent radii within these factors.
- class vibesketcher.document.polymer_packing.RepeatUnit(*, smiles=None, template=None, generic=None)[source]¶
Bases:
_ModelOne structural repeat unit with a head and a tail connection point.
smilesmarks the two points with*([*:1]head and[*:2]tail, or the first and second marker in SMILES order);templateis a polymer entry of the template library andgenerica bracketed generic of the document, each read for the atoms of its one SRU bracket.- Parameters:
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.ChainSpec(*, label=None, count=1, length=None, lengths=None, unit=None, sequence=None, composition=None, arrangement='random', tacticity=None, head='H', tail='H')[source]¶
Bases:
_ModelA group of chains built the same way.
- Parameters:
lengths (Annotated[list[int] | None, MinLen(min_length=1), MaxLen(max_length=500)])
unit (str | None)
sequence (Annotated[list[str] | None, MinLen(min_length=1), MaxLen(max_length=2000)])
composition (Annotated[dict[str, float] | None, MinLen(min_length=1), MaxLen(max_length=10)])
arrangement (Literal['random', 'alternating', 'block'])
tacticity (Literal['isotactic', 'syndiotactic', 'atactic'] | None)
head (Annotated[str, MinLen(min_length=1), MaxLen(max_length=2000)])
tail (Annotated[str, MinLen(min_length=1), MaxLen(max_length=2000)])
- arrangement: Literal['random', 'alternating', 'block']¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.Cell(*, kind='box', lengths_angstrom=None, density_g_cm3=None, lateral_angstrom=None, thickness_angstrom=None, vacuum_angstrom=10.0)[source]¶
Bases:
_ModelA periodic orthorhombic box, or a membrane periodic in a and b with vacuum along c.
- Parameters:
kind (Literal['box', 'membrane'])
density_g_cm3 (Annotated[float | None, Gt(gt=0), Le(le=5), AllowInfNan(allow_inf_nan=False)])
thickness_angstrom (Annotated[float | None, Gt(gt=0), Le(le=1000), AllowInfNan(allow_inf_nan=False)])
vacuum_angstrom (Annotated[float, Ge(ge=0), Le(le=500), AllowInfNan(allow_inf_nan=False)])
- kind: Literal['box', 'membrane']¶
- lengths_angstrom: tuple[float, float, float] | None¶
the three edge lengths (angstrom); or a density sets a cube.
- Type:
Box
- lateral_angstrom: tuple[float, float] | None¶
in-plane edges a and b, and the polymer layer thickness or a density.
- Type:
Membrane
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.TorsionState(*, angle_deg, weight)[source]¶
Bases:
_Model- Parameters:
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.Region(*, lower, upper)[source]¶
Bases:
_ModelA fractional box no atom may enter (an exclusion rule), such as a pore kept open.
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.Crosslinking(*, chemistry, conversion)[source]¶
Bases:
_ModelExplicit crosslinking chemistry and conversion (not implemented: refused).
- Parameters:
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.polymer_packing.PolymerPacking(*, identifier, units, chains, seed, cell, torsion_states=<factory>, torsion_jitter_deg=10.0, radii='vdw', radius_overrides=<factory>, collision_scale=0.6, max_attempts=200000, step_retries=8, max_backtracks=200, max_regrowths=20, on_exhausted='refuse', excluded=<factory>, crosslinking=None)[source]¶
Bases:
_Model- Parameters:
identifier (str)
units (Annotated[dict[str, RepeatUnit], MinLen(min_length=1), MaxLen(max_length=10)])
chains (Annotated[list[ChainSpec], MinLen(min_length=1), MaxLen(max_length=20)])
cell (Cell)
torsion_states (Annotated[list[TorsionState], MinLen(min_length=1), MaxLen(max_length=12)])
torsion_jitter_deg (Annotated[float, Ge(ge=0), Le(le=60), AllowInfNan(allow_inf_nan=False)])
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'])
crosslinking (Crosslinking | None)
- units: dict[str, RepeatUnit]¶
- torsion_states: list[TorsionState]¶
- torsion_jitter_deg: float¶
Each drawn torsion is its state plus a uniform offset within this many degrees.
- radii: Literal['vdw', 'covalent']¶
- max_backtracks: int¶
Placements one chain may undo (backtracking) before it is regrown from a new start.
- on_exhausted: Literal['refuse', 'partial']¶
- crosslinking: Crosslinking | None¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- vibesketcher.document.polymer_packing.content_digest(structure)[source]¶
Digest of a structure without its provenance (which records the digest).
- Parameters:
structure (PeriodicStructure)
- Return type:
- exception vibesketcher.document.polymer_packing.PolymerRefused(code, message)[source]¶
Bases:
ValueErrorA repeat unit or end group cannot be used;
codeis a stable refusal code.
- class vibesketcher.document.polymer_packing.Inclusion(label, lengths, pbc, lower, upper, volume, symbols, xyz, forbidden=None)[source]¶
Bases:
objectFixed atoms the chains grow around, in a cell the caller states (#241).
lengths,pbc,lowerandupperreplace the request’s cell: the orthorhombic edges, the periodic axes and the growth region’s corners (nonperiodic axes only).volumeis the region volume the unrelaxed density is reported over.xyzare Cartesian positions of the fixed atoms;forbiddenmaps an(n, 3)array of unwrapped Cartesian chain positions to an(n,)boolean array, true where a position lies in a forbidden interior.- Parameters:
- lengths: ndarray¶
- lower: ndarray¶
- upper: ndarray¶
- xyz: ndarray¶
- vibesketcher.document.polymer_packing.INCLUSION_CHAIN = -1¶
The grid’s chain index of an inclusion atom.
- vibesketcher.document.polymer_packing.preview(packing, document=None, *, inclusion=None)[source]¶
The packed model, its chains, checks, refusals and provenance; nothing is stored.
With
inclusionthe chains grow in its cell and region around its fixed atoms; the request’s cell is not used.
- vibesketcher.document.polymer_packing.anchor_of(p, which)[source]¶
The chain-local index of a placement’s head or tail anchor.
- vibesketcher.document.polymer_packing.chain_symbols_by(placed)[source]¶
The chain’s atom symbols in chain-local order (by fragment start).
- vibesketcher.document.polymer_packing.apply(document, packing)[source]¶
Add the packed model to a copy of
document; refusals fail.- Parameters:
document (Document)
packing (PolymerPacking)
- Return type: