vibe-sketcherDocumentation

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:

smiles

A 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])C polypropylene.

template

A 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 as polymer-pedot-pss, is refused as ambiguous.

generic

A 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

unit, sequence or composition

A homopolymer unit, an explicit list of unit labels, or fractions per label.

arrangement

For a composition: random (drawn from the seed), alternating (equal fractions) or block.

count

Chains in the group.

length or lengths

Units per chain, or one length per chain. A sequence sets the length.

tacticity

isotactic, syndiotactic or atactic; required when a unit has a backbone stereocentre, refused otherwise.

head, tail

End groups: H (default) or a SMILES with one marker, such as *C for methyl.

label

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

kind

box (periodic in a, b and c) or membrane (periodic in a and b).

lengths_angstrom

Box: the three edges of an orthorhombic cell.

density_g_cm3

Box: a cube from the target density. Membrane: the layer thickness.

lateral_angstrom

Membrane: the in-plane edges a and b.

thickness_angstrom

Membrane: the layer thickness instead of a density.

vacuum_angstrom

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

polymer.unit_unreadable, polymer.unit_markers, polymer.unit_ambiguous, polymer.unit_unknown

Unusable repeat units or end groups.

polymer.charged, polymer.open_shell

Charged or radical units.

polymer.tacticity_unstated, polymer.tacticity_inapplicable

Tacticity missing, or stated without a stereocentre.

polymer.box_too_small, polymer.too_many_sites

Cell or size limits.

polymer.budget_exhausted, polymer.partial_packing

The attempt or regrowth limit ran out.

polymer.check_failed

A topology, valence, bond-length or stoichiometry check failed.

polymer.crosslinking_unavailable

Crosslinking was requested.

polymer.unrelaxed, polymer.side_chain_stereo

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.

  1. Enter the new ID and the repeat units, one per line: LABEL=SMILES with head and tail markers, LABEL=template:NAME for a template-library polymer or LABEL=generic:ID for a drawn bracket.

  2. List the chain groups, one per line, as UNIT:COUNT:LENGTH, optionally followed by :TACTICITY:HEAD:TAIL. A composition such as E=0.5,P=0.5 stands in place of the unit and uses the Composition arrangement. For example, E:2:8::H:*C gives two methyl-ended 8-mers.

  3. 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.

  4. 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.

  5. 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/preview takes packing and changes nothing.

  • POST /api/documents/{id}/periodic/polymer takes revision and packing.

  • POST /api/documents/{id}/periodic/polymer/undo takes revision and structure.

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.