Amorphous polymer boxes and membranes¶
The polymer packer grows explicit chains from stated repeat units into a periodic box at a target density, or into a membrane that is periodic in plane with a nonperiodic normal and vacuum. A packing is reproducible. The same units, chains, cell, options and seed give the same model. Every chain keeps its own bond graph, is stored site by site with the periodic image each bond crosses, and is never bonded to another chain. The result is previewed as a derived periodic model with its chains, checks and refusals before anything is stored.
A packed cell is an unrelaxed starting geometry at the stated density. It is not an equilibrated morphology. Its density, chain dimensions and contacts are not predictions until the model has been relaxed and equilibrated by a calculation engine, which is a separate step.
The polymer drawing templates and sequence notation are not changed by the packer. A template or a drawn bracket is only read for its structural repeat unit (SRU).
Repeat units¶
units maps a label to one repeat unit, given in one of three ways:
smilesA SMILES with two connection markers.
[*:1]is the head and[*:2]the tail; without map numbers, the first*is the head.*CC*is polyethylene and[*:1]CC([*:2])Cpolypropylene.templateA polymer entry of the template library, such as
polymer-polystyrene. Its one SRU bracket is cut out with a marker on each of the two bonds that cross it. A template with two brackets, such aspolymer-pedot-pss, is refused as ambiguous.genericA bracketed generic structure drawn in the document, read the same way.
Each marker bonds to one atom by a single bond. Charged units and units with radicals are refused, because counter-ions and spin states are not placed. The unit is embedded once with RDKit’s ETKDGv3 and MMFF94 under a fixed seed, with hydrogen stand-ins on the markers. The stand-in directions are the bond directions.
Chains¶
chains lists groups of chains built the same way.
Field |
Meaning |
|---|---|
|
A homopolymer unit, an explicit list of unit labels, or fractions per label. |
|
For a composition: |
|
Chains in the group. |
|
Units per chain, or one length per chain. A sequence sets the length. |
|
|
|
End groups: |
|
A name for the chains. |
Tacticity is a configuration. An isotactic chain repeats one embedded
enantiomer of the unit, a syndiotactic chain alternates it with its mirror
image, and an atactic chain draws each unit from the seed. The packed chain
is checked from its coordinates. The sign of each backbone stereocentre’s
volume, spanned by its head-side, tail-side and side-group neighbours, gives
the meso and racemo diads, and the preview reports the meso fraction.
Side-chain stereocentres keep their embedded configuration in every unit,
which the notice polymer.side_chain_stereo reports.
The cell¶
Field |
Meaning |
|---|---|
|
|
|
Box: the three edges of an orthorhombic cell. |
|
Box: a cube from the target density. Membrane: the layer thickness. |
|
Membrane: the in-plane edges a and b. |
|
Membrane: the layer thickness instead of a density. |
|
Membrane: the vacuum on each side of the layer (default 10). |
The volume for a density is V = M / (rho N_A), with M the mass of every
chain and its end groups. A membrane’s cell has c = thickness + 2 vacuum,
and every atom stays in the layer. excluded lists fractional boxes that no
atom may enter, for example to keep a pore open for a later insertion.
How chains are grown¶
Each chain grows unit by unit as a self-avoiding walk, the chain-growth
construction of amorphous polymer cells by Theodorou and Suter
(Macromolecules 18, 1467, 1985). The first unit takes a uniformly random
orientation and position. Each next unit is placed with its head atom on the
previous tail’s bond direction at the sum of the covalent radii, which leaves
the torsion about the new bond free. That torsion, and each rotatable single
backbone bond inside the unit, takes one of the rotational-isomeric states in
torsion_states (Flory, Statistical Mechanics of Chain Molecules, 1969).
The default is trans at 180 degrees with weight 1 and gauche at plus and
minus 60 degrees with weight 0.5 each. Each drawn torsion is shifted by a
uniform offset of at most torsion_jitter_deg (default 10). Conjugated
bonds inside a unit keep the embedded torsion. A junction between two
conjugated atoms tries twelve evenly spaced torsions with equal weight.
Side-group rotors, such as methyls, turn uniformly.
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, to an atom of its
own chain more than three bonds away, or to a periodic image, and every atom
stays in the growth region and outside the excluded regions. The radii are
RDKit’s van der Waals or covalent radii, as in
guest loading. Among the free states, one is chosen with
probability proportional to its weight, as in Rosenbluth chain growth
(J. Chem. Phys. 23, 356, 1955). The hard core stands in for the energies
Theodorou and Suter minimise afterwards; nothing is relaxed here.
A step with no free state is retried step_retries times with fresh
internal torsions. The previous placement is then undone and drawn again
(backtracking), and after max_backtracks the chain is regrown from a new
start, at most max_regrowths times. Every candidate placement counts
against max_attempts. The default collision scale is 0.6. Crowded
backbones, such as the quaternary carbons of PMMA or polyisobutylene, open
their bond angles on relaxation and may need a smaller scale here.
The random numbers come from NumPy’s PCG64 generator seeded with seed.
Checks, refusals and provenance¶
A packed model is only applicable when every check passes:
topology: one connected component per chain, and no bond between chains;
valence: each chain sanitises in RDKit;
bond lengths: each bond’s image length lies within 0.75 to 1.3 times the sum of the covalent radii;
stoichiometry: the element count equals the units and end groups stated.
The preview also reports the unrelaxed density, the packed and requested
chains, the attempts, backtracks and regrowths, and the rejected placements
by cause: chain_contact, self_contact, intra_unit, outside_region and
excluded_region. Each chain records its sequence, length, tacticity and
meso fraction, end groups, formula and the connection points it consumed.
The packed model’s provenance (polymer) keeps the request, the radii, the
checks and every chain’s residues: for each residue its unit, its site IDs
and the parent atom indices in the embedded unit (SMILES atoms first, then
hydrogens).
When the budget runs out, the packing is refused with
polymer.budget_exhausted. With on_exhausted="partial", the chains packed
so far are kept, the notice polymer.partial_packing appears and the
incomplete chain is dropped.
Code |
Meaning |
|---|---|
|
Unusable repeat units or end groups. |
|
Charged or radical units. |
|
Tacticity missing, or stated without a stereocentre. |
|
Cell or size limits. |
|
The attempt or regrowth limit ran out. |
|
A topology, valence, bond-length or stoichiometry check failed. |
|
Crosslinking was requested. |
|
Notices. |
Crosslinking needs explicitly selected chemistry and a conversion, given as
crosslinking. It is not implemented, so such a request is refused. A
network is never inferred from contacts.
Applying adds the packed model to the document. The apply is revision-checked and refused while the preview has refusals. A packing can be undone while the packed model is unchanged. Saving and loading the document, and QVF export, keep the chains, their bond images and the record.
Examples¶
Four polyethylene 10-mers in a cubic box at 0.5 g/cm3:
from vibesketcher.document import new_document
from vibesketcher.document import polymer_packing as pp
packing = pp.parse_packing(
{
"identifier": "pe-box",
"units": {"PE": {"smiles": "*CC*"}},
"chains": [{"unit": "PE", "count": 4, "length": 10}],
"seed": 11,
"cell": {"density_g_cm3": 0.5},
}
)
preview = pp.preview(packing)
document = pp.apply(new_document(), packing)
A mixed-chain membrane: two methyl-ended polyethylene chains and two atactic ethylene-propylene random copolymers, 14 by 14 A in plane, with 8 A of vacuum on each side.
{
"identifier": "membrane",
"units": {"E": {"smiles": "*CC*"}, "P": {"smiles": "[*:1]CC([*:2])C"}},
"chains": [
{"unit": "E", "count": 2, "length": 8, "tail": "*C"},
{"composition": {"E": 0.5, "P": 0.5}, "count": 2, "length": 6,
"tacticity": "atactic"}
],
"seed": 5,
"cell": {"kind": "membrane", "lateral_angstrom": [14, 14],
"density_g_cm3": 0.5, "vacuum_angstrom": 8}
}
vibe-sketcher solid pack-polymer polymer.vsk --id ps --template S=polymer-polystyrene \
--chain S:2:8:isotactic --seed 3 --box 30,30,30
vibe-sketcher solid pack-polymer polymer.vsk --request membrane.json --apply
vibe-sketcher solid pack-polymer-undo polymer.vsk --structure membrane
solid pack-polymer without --apply prints the preview as JSON and exits
with status 3 when it is refused. --chain takes
UNIT:COUNT:LENGTH[:TACTICITY], and --unit and --template take
LABEL=VALUE. --request FILE reads the whole request as JSON, for
sequences, compositions and every option.
Fixed inclusions¶
The CNT composite builder grows chains around fixed
nanotube atoms. It hands the packer its own cell and growth region, the tube
atoms and a test for the tube interiors. Placements that overlap a tube atom
are rejected as inclusion_contact and those with an atom inside a tube as
inclusion_interior; the rejection counts report both.
In the browser¶
Open Solid-state builder… from the command palette and use the Pack polymer chains form. It sends the same request as the REST routes below; growth, checks and refusals all come from the server.
Enter the new ID and the repeat units, one per line:
LABEL=SMILESwith head and tail markers,LABEL=template:NAMEfor a template-library polymer orLABEL=generic:IDfor a drawn bracket.List the chain groups, one per line, as
UNIT:COUNT:LENGTH, optionally followed by:TACTICITY:HEAD:TAIL. A composition such asE=0.5,P=0.5stands in place of the unit and uses the Composition arrangement. For example,E:2:8::H:*Cgives two methyl-ended 8-mers.Set the seed and the cell: a periodic box from a target density or from explicit edges, or a membrane from its in-plane edges, a density or a layer thickness, and its vacuum. Only the controls of the chosen cell type are shown. Then set the radii, collision scale, attempt budget and what happens when it runs out.
Choose Preview packing. The panel shows the packed model’s formula and site count, a top-view schematic, the packed and requested chains, the cell, the unrelaxed density, the attempts, backtracks, regrowths and rejections, the topology, bond-length and valence checks and each chain’s formula. Refusals and notices are listed with their codes and messages exactly as the server returns them. A preview changes nothing.
Add reviewed packing adds the previewed model, checked against the previewed revision. Changing any input first discards the preview. Undo packing removes the model again while it is unchanged.
Explicit sequences, per-chain length lists, excluded regions and torsion states are only reachable through the request JSON of the CLI, REST or MCP.
REST and MCP¶
POST /api/documents/{id}/periodic/polymer/previewtakespackingand changes nothing.POST /api/documents/{id}/periodic/polymertakesrevisionandpacking.POST /api/documents/{id}/periodic/polymer/undotakesrevisionandstructure.
A stale revision is answered with 409. The MCP tools are
preview_polymer_packing and apply_polymer_packing (with undo).
Not yet covered¶
Equilibration is not run or queued here; a later step will hand a packed model, with its seed and history, to an admitted engine. Crosslinking chemistry, polyelectrolytes with counter-ions, and force-field or monomer libraries are not implemented, and their licences need review before one is selected.