vibe-sketcherDocumentation

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

MAX_CHAINS

Chains one request may ask for, and repeat units one chain may have.

MAX_ATTEMPTS

Candidate placements (one per torsion state tried) one request may make.

MAX_UNIT_ATOMS

Real atoms one repeat unit or end group may have (hydrogens included).

BOND_LENGTH_WINDOW

Bond images are checked against covalent radii within these factors.

INCLUSION_CHAIN

The grid's chain index of an inclusion atom.

Functions

anchor_of(p, which)

The chain-local index of a placement's head or tail anchor.

apply(document, packing)

Add the packed model to a copy of document; refusals fail.

chain_symbols_by(placed)

The chain's atom symbols in chain-local order (by fragment start).

content_digest(structure)

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

parse_packing(data)

preview(packing[, document, inclusion])

The packed model, its chains, checks, refusals and provenance; nothing is stored.

undo(document, identifier)

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

Classes

Cell(*[, kind, lengths_angstrom, ...])

A periodic orthorhombic box, or a membrane periodic in a and b with vacuum along c.

ChainSpec(*[, label, count, length, ...])

A group of chains built the same way.

Crosslinking(*, chemistry, conversion)

Explicit crosslinking chemistry and conversion (not implemented: refused).

Inclusion(label, lengths, pbc, lower, upper, ...)

Fixed atoms the chains grow around, in a cell the caller states (#241).

PolymerPacking(*, identifier, units, chains, ...)

Region(*, lower, upper)

A fractional box no atom may enter (an exclusion rule), such as a pore kept open.

RepeatUnit(*[, smiles, template, generic])

One structural repeat unit with a head and a tail connection point.

TorsionState(*, angle_deg, weight)

Exceptions

PolymerRefused(code, message)

A repeat unit or end group cannot be used; code is a stable refusal code.

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: _Model

One structural repeat unit with a head and a tail connection point.

smiles marks the two points with * ([*:1] head and [*:2] tail, or the first and second marker in SMILES order); template is a polymer entry of the template library and generic a bracketed generic of the document, each read for the atoms of its one SRU bracket.

Parameters:
  • smiles (Annotated[str | None, MinLen(min_length=1), MaxLen(max_length=4000)])

  • template (Annotated[str | None, MinLen(min_length=1), MaxLen(max_length=200)])

  • generic (Annotated[str | None, MinLen(min_length=1), MaxLen(max_length=64)])

smiles: str | None
template: str | None
generic: str | None
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: _Model

A group of chains built the same way.

Parameters:
  • label (Annotated[str | None, MaxLen(max_length=80)])

  • count (Annotated[int, Ge(ge=1), Le(le=500)])

  • length (Annotated[int | None, Ge(ge=1), Le(le=2000)])

  • 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)])

label: str | None
count: int
length: int | None

Repeat units per chain, or one length per chain in lengths.

lengths: list[int] | None
unit: str | None

a homopolymer unit, an explicit sequence or a composition.

Type:

Exactly one of

sequence: list[str] | None
composition: dict[str, float] | None
arrangement: Literal['random', 'alternating', 'block']
tacticity: Literal['isotactic', 'syndiotactic', 'atactic'] | None
head: str

H or a SMILES with one * marker, such as *C for methyl.

Type:

End groups

tail: str
chain_lengths()[source]
Return type:

list[int]

units_named()[source]
Return type:

set[str]

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: _Model

A periodic orthorhombic box, or a membrane periodic in a and b with vacuum along c.

Parameters:
  • kind (Literal['box', 'membrane'])

  • lengths_angstrom (tuple[float, float, float] | None)

  • density_g_cm3 (Annotated[float | None, Gt(gt=0), Le(le=5), AllowInfNan(allow_inf_nan=False)])

  • lateral_angstrom (tuple[float, float] | None)

  • 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

density_g_cm3: float | None
lateral_angstrom: tuple[float, float] | None

in-plane edges a and b, and the polymer layer thickness or a density.

Type:

Membrane

thickness_angstrom: float | None
vacuum_angstrom: float

the vacuum on each side of the layer (angstrom).

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:
  • angle_deg (Annotated[float, Ge(ge=-180), Le(le=180), AllowInfNan(allow_inf_nan=False)])

  • weight (Annotated[float, Gt(gt=0), Le(le=1000), AllowInfNan(allow_inf_nan=False)])

angle_deg: float
weight: float
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: _Model

A fractional box no atom may enter (an exclusion rule), such as a pore kept open.

Parameters:
lower: tuple[float, float, float]
upper: 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.polymer_packing.Crosslinking(*, chemistry, conversion)[source]

Bases: _Model

Explicit crosslinking chemistry and conversion (not implemented: refused).

Parameters:
  • chemistry (Annotated[str, MinLen(min_length=1), MaxLen(max_length=200)])

  • conversion (Annotated[float, Gt(gt=0), Le(le=1), AllowInfNan(allow_inf_nan=False)])

chemistry: str
conversion: float
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: dict[str, RepeatUnit]
chains: list[ChainSpec]
seed: int
cell: Cell
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']
radius_overrides: dict[str, float]
collision_scale: float
max_attempts: int
step_retries: int

Fresh internal-torsion draws for a step before the chain is regrown.

max_backtracks: int

Placements one chain may undo (backtracking) before it is regrown from a new start.

max_regrowths: int

Regrowths of one chain from a new start before the request gives up.

on_exhausted: Literal['refuse', 'partial']
excluded: list[Region]
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.parse_packing(data)[source]
Parameters:

data (dict[str, Any])

Return type:

PolymerPacking

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

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

Parameters:

structure (PeriodicStructure)

Return type:

str

exception vibesketcher.document.polymer_packing.PolymerRefused(code, message)[source]

Bases: ValueError

A repeat unit or end group cannot be used; code is a stable refusal code.

Parameters:
Return type:

None

class vibesketcher.document.polymer_packing.Inclusion(label, lengths, pbc, lower, upper, volume, symbols, xyz, forbidden=None)[source]

Bases: object

Fixed atoms the chains grow around, in a cell the caller states (#241).

lengths, pbc, lower and upper replace the request’s cell: the orthorhombic edges, the periodic axes and the growth region’s corners (nonperiodic axes only). volume is the region volume the unrelaxed density is reported over. xyz are Cartesian positions of the fixed atoms; forbidden maps an (n, 3) array of unwrapped Cartesian chain positions to an (n,) boolean array, true where a position lies in a forbidden interior.

Parameters:
label: str
lengths: ndarray
pbc: tuple[bool, bool, bool]
lower: ndarray
upper: ndarray
volume: float
symbols: list[str]
xyz: ndarray
forbidden: Callable[[ndarray], ndarray] | None = None
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 inclusion the chains grow in its cell and region around its fixed atoms; the request’s cell is not used.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.polymer_packing.anchor_of(p, which)[source]

The chain-local index of a placement’s head or tail anchor.

Parameters:
  • p (_Placed)

  • which (Literal['head', 'tail'])

Return type:

int

vibesketcher.document.polymer_packing.chain_symbols_by(placed)[source]

The chain’s atom symbols in chain-local order (by fragment start).

Parameters:

placed (list[_Placed])

Return type:

list[str]

vibesketcher.document.polymer_packing.apply(document, packing)[source]

Add the packed model to a copy of document; refusals fail.

Parameters:
Return type:

Document

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

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

Parameters:
Return type:

Document