Builder¶

System assembly: polymer chain construction from G-BigSMILES / CGSmiles notation and monomer libraries.

Quick reference¶

Symbol	Summary	Preferred for
`polymer(spec, ...)`	String → chain in one call	Quick prototyping
`polymer_system(spec, ...)`	G-BigSMILES → polydisperse multi-chain system	Bulk system setup
`prepare_monomer(bigsmiles)`	BigSMILES → 3D monomer with ports	Building monomer libraries
`PolymerBuilder`	Build chains from CGSmiles + library + connector + placer	Full control over assembly
`Connector`	Port selection rules + reaction binding	Defining which ports react
`ReactionPresets`	Named reaction chemistries (`"dehydration"`, …)	Reusing / registering chemistry
`Placer`	Geometric placement (separator + orienter)	Controlling inter-monomer geometry
`CovalentSeparator`	Covalent radii-based distance (buffer in Å)	Default monomer spacing
`LinearOrienter`	Linear chain orientation	Default growth direction

Canonical example¶

The one-call entry point auto-detects the notation and returns an Atomistic directly:

from molpy.builder import polymer

# G-BigSMILES: monomer repeat unit + chain length in one string
chain = polymer("{[<]CCO[>]}|5|", optimize=False, random_seed=42)
assert chain.__class__.__name__ == "Atomistic"
assert len(list(chain.atoms)) > 0

For full control, prepare a monomer library and drive PolymerBuilder step by step:

from molpy.builder import prepare_monomer
from molpy.builder.polymer import (
    Connector,
    CovalentSeparator,
    LinearOrienter,
    Placer,
    PolymerBuilder,
    ReactionPresets,
)

eo = prepare_monomer("{[<]CCO[>]}", optimize=False)

builder = PolymerBuilder(
    library={"EO": eo},
    connector=Connector(
        reacter=ReactionPresets.get("dehydration"),
        port_map={("EO", "EO"): (">", "<")},
    ),
    placer=Placer(CovalentSeparator(), LinearOrienter()),
)
result = builder.build("{[#EO]|3}")
chain = result.polymer
assert len(list(chain.atoms)) > 0

Custom reaction chemistry¶

ReactionPresets.register() is the extension point for naming your own chemistry and using it via the reaction_preset keyword everywhere:

from molpy.builder.polymer import ReactionPresets, ReactionPresetSpec
from molpy.reacter import form_single_bond, select_hydrogens, select_self

ReactionPresets.register(
    ReactionPresetSpec(
        name="cc_coupling_demo",
        description="C-C coupling, one H lost per side",
        anchor_selector_left=select_self,
        anchor_selector_right=select_self,
        leaving_selector_left=select_hydrogens(1),
        leaving_selector_right=select_hydrogens(1),
        bond_former=form_single_bond,
    )
)
assert "cc_coupling_demo" in ReactionPresets.list_presets()

Full API¶

Crystal¶

crystal ¶

Crystal lattice builder.

Tile a Bravais lattice over a range of unit cells and (optionally) clip the result to a geometric :class:molpy.core.region.Region.

Example

from molpy.builder import Lattice, build_crystal from molpy.core.region import BoxRegion lat = Lattice.fcc(a=3.52, species="Ni") structure = build_crystal(lat, repeats=(4, 4, 4))

or clip a 30 Å cube out of a larger tile:¶

structure = build_crystal(lat, BoxRegion(lengths=[30, 30, 30]))

Lattice ¶

Lattice(cell, basis=None)

Bravais lattice = cell matrix + list of basis :class:Site objects.

The cell matrix stores the three lattice vectors as rows::

cell = [[a1x, a1y, a1z],
        [a2x, a2y, a2z],
        [a3x, a3y, a3z]]

Construct directly with a matrix, or use :meth:from_vectors / :meth:sc / :meth:bcc / :meth:fcc / :meth:rocksalt.

bcc `classmethod` ¶

bcc(a, species)

Body-centered cubic lattice (2 atoms / cell).

cart_to_frac ¶

cart_to_frac(cart)

Cartesian → fractional: cart @ cell⁻¹.

fcc `classmethod` ¶

fcc(a, species)

Face-centered cubic lattice (4 atoms / cell).

frac_to_cart ¶

frac_to_cart(frac)

Fractional → Cartesian: frac @ cell.

from_vectors `classmethod` ¶

from_vectors(a1, a2, a3, basis=None)

Build a lattice from three lattice vectors.

rocksalt `classmethod` ¶

rocksalt(a, species_a, species_b)

Rocksalt (NaCl) structure — two interpenetrating FCC sublattices.

sc `classmethod` ¶

sc(a, species)

Simple cubic lattice (1 atom / cell).

with_site ¶

with_site(site)

Return a new lattice with site appended to the basis.

Site `dataclass` ¶

Site(label, species, fractional, charge=0.0, attrs=None)

Lattice basis site in fractional coordinates.

Attributes:

Name	Type	Description
`label`	`str`	Site identifier (e.g. `"A"`, `"B1"`).
`species`	`str`	Chemical species or type name (e.g. `"Ni"`, `"Cl"`).
`fractional`	`tuple[float, float, float]`	Fractional coordinates `(u, v, w)` relative to the cell.
`charge`	`float`	Partial charge (default `0.0`).
`attrs`	`dict[str, Any] \| None`	Optional auxiliary attributes.

build_crystal ¶

build_crystal(lattice, region=None, *, repeats=None)

Tile lattice and (optionally) clip to a Cartesian region.

Parameters:

Name	Type	Description	Default
`lattice`	`Lattice`	Bravais lattice with basis sites.	required
`region`	`Region \| None`	Geometric region in Cartesian space (e.g. :class:`molpy.core.region.BoxRegion`, `SphereRegion`, or any `Region` combination via `& \| ~`). Atoms outside the region are discarded.	`None`
`repeats`	`tuple[int, int, int] \| None`	Number of unit cells along each lattice vector, `(nx, ny, nz)`. If omitted, the tile range is inferred from `region.bounds`. At least one of `region` or `repeats` must be provided.	`None`

Returns:

Type	Description
`Atomistic`	class:`Atomistic` containing the kept atoms and a `box` set to the
`Atomistic`	full tiled super-cell (`cell` scaled row-wise by `repeats`).

Polymer¶

polymer ¶

Polymer assembly — start here.

One-call entry points (most users need only these):

:func:polymer — build a single chain from G-BigSMILES / CGSmiles
:func:polymer_system — build a polydisperse multi-chain system
:func:prepare_monomer — BigSMILES → 3D Atomistic with ports
:func:generate_3d — embed an existing Atomistic in 3D

Step-by-step (advanced) API:

:class:PolymerBuilder + :class:Connector — direct graph assembly with explicit port mapping and reaction control
:class:Placer family (:class:CovalentSeparator, :class:VdWSeparator, :class:LinearOrienter) — geometric placement
:class:ReactionPresets / :class:ReactionPresetSpec — named reaction chemistry; ReactionPresets.register() is the extension point for custom chemistries
Sequence generators and polydispersity distributions for system planning

Internal machinery (importable but not part of the public surface): GBigSmilesCompiler, SystemPlanner, PolydisperseChainGenerator.

Chain `dataclass` ¶

Chain(dp, monomers, mass)

Represents a single polymer chain.

Attributes:

Name	Type	Description
`dp`	`int`	Degree of polymerization (number of monomers)
`monomers`	`list[str]`	List of monomer identifiers in the chain
`mass`	`float`	Total mass of the chain (g/mol)

Connector ¶

Connector(reacter, *, port_map=None, overrides=None)

Select ports and execute reactions between adjacent monomers.

Port selection strategy (applied in order):

Explicit port_map lookup for (left_label, right_label)
Compatibility: > on left pairs with < on right
Single-port: each side has exactly one unconsumed port
Common name: both sides share a port name (for $ ports)
Raise AmbiguousPortsError

Parameters:

Name	Type	Description	Default
`reacter`	`Reacter`	Default :class:`molpy.reacter.Reacter` executed at every connection.	required
`port_map`	`dict[tuple[str, str], tuple[str, str]] \| None`	Optional explicit mapping `{(left_label, right_label): (left_port, right_port)}`.	`None`
`overrides`	`dict[tuple[str, str], Reacter] \| None`	Optional per-pair reacter overrides keyed like `port_map`.	`None`

Attributes:

Name	Type	Description
`default`		The default reacter.
`port_map`		Explicit port mapping (may be empty).
`overrides`		Per-pair reacter overrides (may be empty).

connect ¶

connect(left, right, left_type, right_type, port_atom_L, port_atom_R, typifier=None)

Execute the chemical reaction between two structures.

get_reacter ¶

get_reacter(left_type, right_type)

Get the appropriate Reacter for a structure pair.

select_ports ¶

select_ports(left, right, left_ports, right_ports, ctx)

Select which ports to connect.

Parameters:

Name	Type	Description	Default
`left`	`Atomistic`	Left Atomistic structure.	required
`right`	`Atomistic`	Right Atomistic structure.	required
`left_ports`	`Mapping[str, list[Atom]]`	Available ports on left (name -> list[Atom]).	required
`right_ports`	`Mapping[str, list[Atom]]`	Available ports on right (name -> list[Atom]).	required
`ctx`	`ConnectorContext`	Context with step info and labels.	required

Returns:

Type	Description
`tuple[str, int, str, int, None]`	(left_port_name, left_idx, right_port_name, right_idx, None)

ConnectorContext ¶

Bases: dict[str, Any]

Shared context passed to the connector during linear build.

Keys: - step: int (current connection step index) - left_label: str (label of left monomer) - right_label: str (label of right monomer) - sequence: list[str] (full sequence being built)

CovalentSeparator ¶

CovalentSeparator(buffer=0.0)

Separator based on typical bond lengths (for bonded atoms).

Uses realistic bond lengths based on element types. Typical bond lengths: - C-C: 1.54 Å (single), 1.34 Å (double) - C-O: 1.43 Å (single), 1.23 Å (double) - C-N: 1.47 Å (single) - O-H: 0.96 Å - N-H: 1.01 Å

Initialize covalent separator.

Parameters:

Name	Type	Description	Default
`buffer`	`float`	Additional buffer distance in Angstroms (default: 0.0) Can be negative to account for slight compression	`0.0`

get_separation ¶

get_separation(left_struct, right_struct, left_port, right_port)

Calculate separation based on typical bond lengths.

Parameters:

Name	Type	Description	Default
`left_struct`	`Atomistic`	Previous structure in sequence	required
`right_struct`	`Atomistic`	Next structure to place	required
`left_port`	`Atom`	Connection port on left structure	required
`right_port`	`Atom`	Connection port on right structure	required

Returns:

Type	Description
`float`	Separation distance = typical_bond_length + buffer

DPDistribution ¶

Bases: Protocol

Protocol for distributions that sample degree of polymerization directly.

Distributions implementing this protocol can sample DP values without requiring monomer mass information. This is suitable for distributions defined in DP space (e.g., Poisson, Uniform).

dp_pmf ¶

dp_pmf(dp_array)

Probability mass function for DP values.

Parameters:

Name	Type	Description	Default
`dp_array`	`ndarray`	Array of DP values	required

Returns:

Type	Description
`ndarray`	Array of probability mass values

sample_dp ¶

sample_dp(rng)

Sample degree of polymerization from distribution.

Parameters:

Name	Type	Description	Default
`rng`	`Generator`	NumPy random number generator	required

Returns:

Type	Description
`int`	Degree of polymerization (>= 1)

FlorySchulzPolydisperse ¶

FlorySchulzPolydisperse(a, random_seed=None)

Flory-Schulz (geometric) distribution for degree of polymerization.

PMF: P(N = k) = a^2 * k * (1 - a)^(k-1), k = 1, 2, ...

Parameters:

Name	Type	Description	Default
`a`	`float`	Probability parameter (0 < a < 1), related to extent of reaction.	required
`random_seed`	`int \| None`	Optional random seed.	`None`

dp_pmf ¶

dp_pmf(dp_array)

Flory-Schulz PMF.

sample_dp ¶

sample_dp(rng)

Sample DP from Flory-Schulz distribution (>= 1).

LinearOrienter ¶

Orienter for linear polymer arrangement.

Aligns the next monomer so that: 1. The two port atoms are separated by the specified distance 2. The port connection axis of the next monomer aligns with the port connection axis of the previous monomer 3. The monomer extends in a linear fashion

get_orientation ¶

get_orientation(left_struct, right_struct, left_port, right_port, separation)

Calculate linear alignment transformation.

Strategy: 1. Get direction vector from left port anchor (outward) 2. Place right structure so its port anchor is at the target position 3. Align right structure's port direction with left port direction

Parameters:

Name	Type	Description	Default
`left_struct`	`Atomistic`	Previous structure in sequence	required
`right_struct`	`Atomistic`	Next structure to place	required
`left_port`	`Atom`	Connection port on left structure	required
`right_port`	`Atom`	Connection port on right structure	required
`separation`	`float`	Distance between port anchors	required

Returns:

Type	Description
`tuple[ndarray, ndarray]`	Tuple of (translation_vector, rotation_matrix)

MassDistribution ¶

Bases: Protocol

Protocol for distributions that sample molecular weight directly.

Distributions implementing this protocol sample mass values directly from the distribution without converting through DP. This is suitable for distributions defined in mass space (e.g., Schulz-Zimm).

mass_pdf ¶

mass_pdf(mass_array)

Probability density function for mass values.

Parameters:

Name	Type	Description	Default
`mass_array`	`ndarray`	Array of mass values (g/mol)	required

Returns:

Type	Description
`ndarray`	Array of probability density values

sample_mass ¶

sample_mass(rng)

Sample molecular weight from distribution.

Parameters:

Name	Type	Description	Default
`rng`	`Generator`	NumPy random number generator	required

Returns:

Type	Description
`float`	Molecular weight (g/mol, > 0)

Placer ¶

Placer(separator, orienter)

Combined placer for positioning structures during assembly.

Uses a Separator to determine distance and an Orienter to determine orientation.

Initialize placer.

Parameters:

Name	Type	Description	Default
`separator`	`Separator`	Separator for calculating distance	required
`orienter`	`LinearOrienter`	Orienter for calculating orientation	required

place_monomer ¶

place_monomer(left_struct, right_struct, left_port, right_port)

Position right_struct relative to left_struct.

Modifies right_struct's atomic coordinates in-place.

Parameters:

Name	Type	Description	Default
`left_struct`	`Atomistic`	Previous structure in sequence	required
`right_struct`	`Atomistic`	Next structure to place	required
`left_port`	`Atom`	Connection port on left structure	required
`right_port`	`Atom`	Connection port on right structure	required

PoissonPolydisperse ¶

PoissonPolydisperse(lambda_param, random_seed=None)

Poisson distribution for the degree of polymerization (DP).

Zero-truncated: sampled k=0 is mapped to k=1.

Parameters:

Name	Type	Description	Default
`lambda_param`	`float`	Mean of the Poisson distribution (> 0).	required
`random_seed`	`int \| None`	Optional random seed.	`None`

dp_pmf ¶

dp_pmf(dp_array)

Zero-truncated Poisson PMF.

sample_dp ¶

sample_dp(rng)

Sample DP from zero-truncated Poisson distribution (>= 1).

PolymerBuildResult `dataclass` ¶

PolymerBuildResult(polymer, connection_history=list(), total_steps=0)

Result of building a polymer.

PolymerBuilder ¶

PolymerBuilder(library, connector=None, *, reacter=None, typifier=None, placer=None)

Build polymers from CGSmiles notation with support for arbitrary topologies.

This builder parses CGSmiles strings and constructs polymers using a graph-based approach, supporting:

Linear chains: {[#A][#B][#C]}
Branched structures: {[#A]([#B])[#C]}
Cyclic structures: {[#A]1[#B][#C]1}
Repeat operators: {[#A]|10}

Attributes:

Name	Type	Description
`library`		Mapping from monomer label to port-annotated Atomistic template.
`connector`		:class:`Connector` choosing ports and reactions between adjacent monomers.
`typifier`		Optional typifier applied during assembly.
`placer`		Optional :class:`Placer` for geometric placement (distances in Å).

Example::

builder = PolymerBuilder(
    library={"EO": eo_monomer},
    connector=Connector(port_map={("EO", "EO"): (">", "<")}, reacter=rxn),
)
result = builder.build("{[#EO]|10}")
chain = result.polymer

Initialize the polymer builder.

Provide either connector or reacter, not both.

build ¶

build(cgsmiles)

Build a polymer from a CGSmiles string.

Parameters:

Name	Type	Description	Default
`cgsmiles`	`str`	CGSmiles notation string (e.g., "{[#EO]\|10}")	required

Returns:

Type	Description
`PolymerBuildResult`	PolymerBuildResult containing the assembled polymer and metadata

ReactionPresetSpec `dataclass` ¶

ReactionPresetSpec(name, description, anchor_selector_left, anchor_selector_right, leaving_selector_left, leaving_selector_right, bond_former)

Immutable specification for a reaction preset.

Attributes:

Name	Type	Description
`name`	`str`	Unique preset name
`description`	`str`	Human-readable description
`anchor_selector_left`	`Selector`	Maps left port atom to anchor atom
`anchor_selector_right`	`Selector`	Maps right port atom to anchor atom
`leaving_selector_left`	`Selector`	Identifies left leaving group
`leaving_selector_right`	`Selector`	Identifies right leaving group
`bond_former`	`BondFormer`	Creates bond between anchor atoms

ReactionPresets ¶

Class-level registry of named reaction presets.

The public extension point for custom polymerization chemistry: :meth:register a :class:ReactionPresetSpec once, then refer to it by name everywhere a reaction_preset keyword is accepted (polymer(), polymer_system(), builders).

Attributes:

Name	Type	Description
`_presets`	`dict[str, ReactionPresetSpec]`	Class-level registry mapping preset name to :class:`ReactionPresetSpec` (managed via :meth:`register`; built-ins `"dehydration"` and `"condensation"` are pre-registered).

Example::

reacter = ReactionPresets.get("dehydration")
# reacter is ready to use with PolymerBuilder

get `classmethod` ¶

get(name)

Create a Reacter instance from a named preset.

Parameters:

Name	Type	Description	Default
`name`	`str`	Preset name (e.g. `"dehydration"`).	required

Returns:

Type	Description
`Reacter`	Configured Reacter instance.

Raises:

Type	Description
`KeyError`	If preset name is not registered.

get_spec `classmethod` ¶

get_spec(name)

Return the raw spec for a preset without creating a Reacter.

Parameters:

Name	Type	Description	Default
`name`	`str`	Preset name.	required

Raises:

Type	Description
`KeyError`	If preset name is not registered.

list_presets `classmethod` ¶

list_presets()

Return sorted list of registered preset names.

register `classmethod` ¶

register(spec)

Register a reaction preset.

Parameters:

Name	Type	Description	Default
`spec`	`ReactionPresetSpec`	Preset specification to register.	required

Raises:

Type	Description
`ValueError`	If a preset with the same name is already registered.

SchulzZimmPolydisperse ¶

SchulzZimmPolydisperse(Mn, Mw, random_seed=None)

Schulz-Zimm molecular weight distribution for polydisperse polymer chains.

Implements :class:MassDistribution - sampling is done directly in molecular-weight space.

The probability density is:

.. math::

f(M) = \frac{z^{z+1}}{\Gamma(z+1)}
       \frac{M^{z-1}}{M_n^{z}}
       \exp\left(-\frac{z M}{M_n}\right),

where z = Mn / (Mw - Mn). This is equivalent to a Gamma distribution with shape z and scale theta = Mw - Mn.

Parameters:

Name	Type	Description	Default
`Mn`	`float`	Number-average molecular weight (g/mol).	required
`Mw`	`float`	Weight-average molecular weight (g/mol), must satisfy Mw > Mn.	required
`random_seed`	`int \| None`	Optional random seed.	`None`

mass_pdf ¶

mass_pdf(mass_array)

Probability density function for mass values.

sample_mass ¶

sample_mass(rng)

Sample molecular weight from Schulz-Zimm (Gamma) distribution.

SequenceGenerator ¶

Bases: Protocol

Protocol for sequence generators.

A sequence generator controls how monomers are arranged in a single chain.

expected_composition ¶

expected_composition()

Return expected long-chain monomer fractions.

Returns:

Type	Description
`dict[str, float]`	Dictionary mapping monomer identifiers to expected fractions

generate_sequence ¶

generate_sequence(dp, rng)

Generate a monomer sequence of specified degree of polymerization.

Parameters:

Name	Type	Description	Default
`dp`	`int`	Degree of polymerization (number of monomers)	required
`rng`	`Generator`	numpy random Generator	required

Returns:

Type	Description
`list[str]`	List of monomer identifiers (strings)

SystemPlan `dataclass` ¶

SystemPlan(chains, total_mass, target_mass)

Represents a complete system plan with all chains.

Attributes:

Name	Type	Description
`chains`	`list[Chain]`	List of all chains in the system
`total_mass`	`float`	Total mass of all chains (g/mol)
`target_mass`	`float`	Target total mass that was requested (g/mol)

UniformPolydisperse ¶

UniformPolydisperse(min_dp, max_dp, random_seed=None)

Uniform distribution over degree of polymerization (DP).

All integer DP values between min_dp and max_dp (inclusive) are equally likely.

Parameters:

Name	Type	Description	Default
`min_dp`	`int`	Lower bound (>= 1).	required
`max_dp`	`int`	Upper bound (>= min_dp).	required
`random_seed`	`int \| None`	Optional random seed.	`None`

dp_pmf ¶

dp_pmf(dp_array)

PMF: equal probability for all integer DP in [min_dp, max_dp].

sample_dp ¶

sample_dp(rng)

Sample DP uniformly from [min_dp, max_dp].

VdWSeparator ¶

VdWSeparator(buffer=0.0)

Separator based on van der Waals radii.

Calculates separation as sum of VdW radii of the two port anchor atoms, plus an optional buffer distance.

NOTE: VdW radii are designed for non-bonded contacts (~3-4 Å). For bonded atoms, use CovalentSeparator instead.

Initialize VdW separator.

Parameters:

Name	Type	Description	Default
`buffer`	`float`	Additional buffer distance in Angstroms (default: 0.0)	`0.0`

get_separation ¶

get_separation(left_struct, right_struct, left_port, right_port)

Calculate separation based on VdW radii.

Parameters:

Name	Type	Description	Default
`left_struct`	`Atomistic`	Previous structure in sequence	required
`right_struct`	`Atomistic`	Next structure to place	required
`left_port`	`Atom`	Connection port on left structure	required
`right_port`	`Atom`	Connection port on right structure	required

Returns:

Type	Description
`float`	Separation distance = vdw_left + vdw_right + buffer

WeightedSequenceGenerator ¶

WeightedSequenceGenerator(monomer_weights)

Sequence generator based on monomer weights/proportions.

Each selection is independent (no memory of previous selections).

expected_composition ¶

expected_composition()

Return expected long-chain monomer fractions.

generate_sequence ¶

generate_sequence(dp, rng)

Generate a sequence of specified degree of polymerization.

Parameters:

Name	Type	Description	Default
`dp`	`int`	Degree of polymerization (number of monomers)	required
`rng`	`Generator`	numpy random Generator	required

Returns:

Type	Description
`list[str]`	List of monomer identifiers

generate_3d ¶

generate_3d(mol, add_hydrogens=True, optimize=True)

Generate 3D coordinates for a molecular structure via RDKit.

Thin re-export of :func:molpy.adapter.rdkit.generate_3d for use inside polymer-building workflows.

Parameters:

Name	Type	Description	Default
`mol`	`Atomistic`	Atomistic structure (typically from parser.parse_molecule)	required
`add_hydrogens`	`bool`	Add implicit hydrogens before embedding	`True`
`optimize`	`bool`	Run force-field geometry optimization after embedding	`True`

Returns:

Type	Description
`Atomistic`	New Atomistic with 3D coordinates and (optionally) explicit hydrogens

Raises:

Type	Description
`ImportError`	if RDKit is not installed

polymer ¶

polymer(spec, *, library=None, reaction_preset='dehydration', use_placer=True, add_hydrogens=True, optimize=True, random_seed=None, backend='default', amber_config=None)

Build a single polymer chain from a string specification.

Auto-detects notation type (for the default backend):

G-BigSMILES (contains | annotation): polymer("{[<]CCOCC[>]}|10|")
CGSmiles + inline fragments (contains .{#): polymer("{[#EO]|10}.{#EO=[<]COC[>]}")
Pure CGSmiles (requires library kwarg): polymer("{[#EO]|10}", library={"EO": eo_monomer})

For the Amber backend:

polymer("{[#EO]|10}", library={"EO": eo}, backend="amber")

Parameters:

Name	Type	Description	Default
`spec`	`str`	Polymer specification string.	required
`library`	`Mapping[str, Atomistic] \| None`	Monomer library (required for pure CGSmiles and Amber).	`None`
`reaction_preset`	`str`	Reaction preset name.	`'dehydration'`
`use_placer`	`bool`	Enable geometric placement (default backend only).	`True`
`add_hydrogens`	`bool`	Add hydrogens during 3D generation.	`True`
`optimize`	`bool`	Optimize geometry.	`True`
`random_seed`	`int \| None`	Random seed for reproducibility.	`None`
`backend`	`Backend`	Builder backend — `"default"` or `"amber"`.	`'default'`
`amber_config`	`Any`	Optional object whose attributes override :class:`~molpy.builder.polymer.ambertools.AmberPolymerBuilder` keyword arguments (e.g. force_field, charge_method). When None, defaults are used.	`None`

Returns:

Type	Description
`Atomistic \| Any`	Atomistic (default backend) or AmberBuildResult (amber backend).

polymer_system ¶

polymer_system(spec, *, reaction_preset='dehydration', add_hydrogens=True, optimize=True, random_seed=None)

Build a multi-chain polymer system from G-BigSMILES.

Example::

chains = polymer_system(
    "{[<]CCOCC[>]}|schulz_zimm(1500,3000)||5e5|",
    random_seed=42,
)

Parameters:

Name	Type	Description	Default
`spec`	`str`	G-BigSMILES specification string.	required
`reaction_preset`	`str`	Reaction preset name.	`'dehydration'`
`add_hydrogens`	`bool`	Add hydrogens during 3D generation.	`True`
`optimize`	`bool`	Optimize geometry.	`True`
`random_seed`	`int \| None`	Random seed for reproducibility.	`None`

Returns:

Type	Description
`list[Atomistic]`	List of Atomistic structures (one per chain).

prepare_monomer ¶

prepare_monomer(bigsmiles, typifier=None, *, add_hydrogens=True, optimize=True, gen_angle=True, gen_dihe=True)

Parse, embed in 3D, augment topology, and optionally typify a monomer.

Bundles the four-step pattern that appears in every polymer-building workflow::

m = mp.parser.parse_monomer(bigsmiles)
m = generate_3d(m, add_hydrogens=True, optimize=True)
m = m.get_topo(gen_angle=True, gen_dihe=True)
m = typifier.typify(m)

Parameters:

Name	Type	Description	Default
`bigsmiles`	`str`	BigSMILES string (e.g. `"{[][<]OCCOCCOCCO[>][]}"`).	required
`typifier`		Optional typifier instance (e.g. `OplsTypifier`). When provided, force-field types are assigned before returning.	`None`
`add_hydrogens`	`bool`	Add implicit hydrogens during 3D generation.	`True`
`optimize`	`bool`	Run force-field geometry optimisation after embedding.	`True`
`gen_angle`	`bool`	Generate angle interactions from bonds.	`True`
`gen_dihe`	`bool`	Generate dihedral interactions from bonds.	`True`

Returns:

Type	Description
`Atomistic`	Fully prepared Atomistic monomer ready for reactions or export.

Polymer entry functions¶

High-level entry functions (polymer, polymer_system, prepare_monomer, generate_3d).

dsl ¶

Declarative polymer-building entry functions.

Start here for polymer construction:

polymer() — auto-detect notation, build a single chain
polymer_system() — G-BigSMILES → polydisperse multi-chain system
prepare_monomer() — BigSMILES → 3D Atomistic with ports
generate_3d() — embed an existing Atomistic in 3D

generate_3d ¶

generate_3d(mol, add_hydrogens=True, optimize=True)

Generate 3D coordinates for a molecular structure via RDKit.

Thin re-export of :func:molpy.adapter.rdkit.generate_3d for use inside polymer-building workflows.

Parameters:

Name	Type	Description	Default
`mol`	`Atomistic`	Atomistic structure (typically from parser.parse_molecule)	required
`add_hydrogens`	`bool`	Add implicit hydrogens before embedding	`True`
`optimize`	`bool`	Run force-field geometry optimization after embedding	`True`

Returns:

Type	Description
`Atomistic`	New Atomistic with 3D coordinates and (optionally) explicit hydrogens

Raises:

Type	Description
`ImportError`	if RDKit is not installed

polymer ¶

polymer(spec, *, library=None, reaction_preset='dehydration', use_placer=True, add_hydrogens=True, optimize=True, random_seed=None, backend='default', amber_config=None)

Build a single polymer chain from a string specification.

Auto-detects notation type (for the default backend):

G-BigSMILES (contains | annotation): polymer("{[<]CCOCC[>]}|10|")
CGSmiles + inline fragments (contains .{#): polymer("{[#EO]|10}.{#EO=[<]COC[>]}")
Pure CGSmiles (requires library kwarg): polymer("{[#EO]|10}", library={"EO": eo_monomer})

For the Amber backend:

polymer("{[#EO]|10}", library={"EO": eo}, backend="amber")

Parameters:

Name	Type	Description	Default
`spec`	`str`	Polymer specification string.	required
`library`	`Mapping[str, Atomistic] \| None`	Monomer library (required for pure CGSmiles and Amber).	`None`
`reaction_preset`	`str`	Reaction preset name.	`'dehydration'`
`use_placer`	`bool`	Enable geometric placement (default backend only).	`True`
`add_hydrogens`	`bool`	Add hydrogens during 3D generation.	`True`
`optimize`	`bool`	Optimize geometry.	`True`
`random_seed`	`int \| None`	Random seed for reproducibility.	`None`
`backend`	`Backend`	Builder backend — `"default"` or `"amber"`.	`'default'`
`amber_config`	`Any`	Optional object whose attributes override :class:`~molpy.builder.polymer.ambertools.AmberPolymerBuilder` keyword arguments (e.g. force_field, charge_method). When None, defaults are used.	`None`

Returns:

Type	Description
`Atomistic \| Any`	Atomistic (default backend) or AmberBuildResult (amber backend).

polymer_system ¶

polymer_system(spec, *, reaction_preset='dehydration', add_hydrogens=True, optimize=True, random_seed=None)

Build a multi-chain polymer system from G-BigSMILES.

Example::

chains = polymer_system(
    "{[<]CCOCC[>]}|schulz_zimm(1500,3000)||5e5|",
    random_seed=42,
)

Parameters:

Name	Type	Description	Default
`spec`	`str`	G-BigSMILES specification string.	required
`reaction_preset`	`str`	Reaction preset name.	`'dehydration'`
`add_hydrogens`	`bool`	Add hydrogens during 3D generation.	`True`
`optimize`	`bool`	Optimize geometry.	`True`
`random_seed`	`int \| None`	Random seed for reproducibility.	`None`

Returns:

Type	Description
`list[Atomistic]`	List of Atomistic structures (one per chain).

prepare_monomer ¶

prepare_monomer(bigsmiles, typifier=None, *, add_hydrogens=True, optimize=True, gen_angle=True, gen_dihe=True)

Parse, embed in 3D, augment topology, and optionally typify a monomer.

Bundles the four-step pattern that appears in every polymer-building workflow::

m = mp.parser.parse_monomer(bigsmiles)
m = generate_3d(m, add_hydrogens=True, optimize=True)
m = m.get_topo(gen_angle=True, gen_dihe=True)
m = typifier.typify(m)

Parameters:

Name	Type	Description	Default
`bigsmiles`	`str`	BigSMILES string (e.g. `"{[][<]OCCOCCOCCO[>][]}"`).	required
`typifier`		Optional typifier instance (e.g. `OplsTypifier`). When provided, force-field types are assigned before returning.	`None`
`add_hydrogens`	`bool`	Add implicit hydrogens during 3D generation.	`True`
`optimize`	`bool`	Run force-field geometry optimisation after embedding.	`True`
`gen_angle`	`bool`	Generate angle interactions from bonds.	`True`
`gen_dihe`	`bool`	Generate dihedral interactions from bonds.	`True`

Returns:

Type	Description
`Atomistic`	Fully prepared Atomistic monomer ready for reactions or export.

Builder¶

Quick reference¶

Canonical example¶

Custom reaction chemistry¶

Related¶

Full API¶

Crystal¶

crystal ¶

or clip a 30 Å cube out of a larger tile:¶

Lattice ¶

bcc classmethod ¶

cart_to_frac ¶

fcc classmethod ¶

frac_to_cart ¶

from_vectors classmethod ¶

rocksalt classmethod ¶

sc classmethod ¶

with_site ¶

Site dataclass ¶

build_crystal ¶

Polymer¶

polymer ¶

Chain dataclass ¶

Connector ¶

connect ¶

get_reacter ¶

select_ports ¶

ConnectorContext ¶

CovalentSeparator ¶

get_separation ¶

DPDistribution ¶

dp_pmf ¶

sample_dp ¶

FlorySchulzPolydisperse ¶

dp_pmf ¶

sample_dp ¶

LinearOrienter ¶

get_orientation ¶

MassDistribution ¶

mass_pdf ¶

sample_mass ¶

Placer ¶

place_monomer ¶

PoissonPolydisperse ¶

dp_pmf ¶

sample_dp ¶

PolymerBuildResult dataclass ¶

PolymerBuilder ¶

build ¶

ReactionPresetSpec dataclass ¶

ReactionPresets ¶

get classmethod ¶

get_spec classmethod ¶

list_presets classmethod ¶

register classmethod ¶

SchulzZimmPolydisperse ¶

mass_pdf ¶

sample_mass ¶

SequenceGenerator ¶

expected_composition ¶

generate_sequence ¶

SystemPlan dataclass ¶

UniformPolydisperse ¶

dp_pmf ¶

sample_dp ¶

VdWSeparator ¶

get_separation ¶

WeightedSequenceGenerator ¶

expected_composition ¶

generate_sequence ¶

generate_3d ¶

polymer ¶

polymer_system ¶

prepare_monomer ¶

Polymer entry functions¶

dsl ¶

generate_3d ¶

polymer ¶

polymer_system ¶

prepare_monomer ¶

bcc `classmethod` ¶

fcc `classmethod` ¶

from_vectors `classmethod` ¶

rocksalt `classmethod` ¶

sc `classmethod` ¶

Site `dataclass` ¶

Chain `dataclass` ¶

PolymerBuildResult `dataclass` ¶

ReactionPresetSpec `dataclass` ¶

get `classmethod` ¶

get_spec `classmethod` ¶

list_presets `classmethod` ¶

register `classmethod` ¶

SystemPlan `dataclass` ¶