create_atoms

mdhelper.algorithm.topology.create_atoms(dims: ndarray[float] | Quantity | Topology, N: int = None, N_p: int = 1, *, lattice: str = None, length: float | Quantity = 0.34, flexible: bool = False, bonds: bool = False, angles: bool = False, dihedrals: bool = False, randomize: bool = False, length_unit: Unit = None, wrap: bool = False) → Any

Generates initial particle positions for coarse-grained simulations.

Parameters:

dimsnumpy.ndarray, openmm.unit.Quantity, or openmm.app.Topology

System dimensions, provided as an array or obtained from an OpenMM topology.

Reference unit: \(\mathrm{nm}\).

Nint, optional

Total number of particles (monomers). Must be provided for random melts or polymers.

N_pint, default: 1

Number of particles (monomers) \(N_p\) in each segment (polymer chain).

Valid values: \(1\leq N_\mathrm{p}\leq N\), with \(N\) divisible by \(N_\mathrm{p}\).

latticestr, keyword-only, optional

Lattice type, with the relevant length scale specified in length. If lattice is not specified, particle positions will be assigned randomly.

Tip

To build walls with the correct periodicity, set the \(z\)-dimension to 0 in dims and flexible=True. This function will then return the wall particle positions and the \(x\)- and \(y\)-dimensions closest to those specified in dims that also satisfy the lattice periodicity.

Keep in mind that walls should only be built in the \(z\)-direction.

Valid values:

• "fcc": Face-centered cubic (FCC) lattice, determined by the particle size \(a\).

• "hcp": Hexagonal close-packed (HCP) lattice, determined by the particle size \(a\).

• "cubic": Cubic crystal system, determined by the particle size \(a\).

• "honeycomb": Honeycomb lattice (e.g., graphene), determined by the bond length \(b\).

lengthfloat or openmm.unit.Quantity, default: 0.34

For random polymer positions, length is the bond length used in the random walk. For lattice systems, length is either the particle size or the bond length, depending on the lattice type. Has no effect if N_p=1 or lattice=None.

Reference unit: \(\mathrm{nm}\).

flexiblebool, default: False

Specifies whether the dimensions provided in dims can be changed to satisfy the lattice periodicity, if applicable. For example, if the provided \(z\)-dimension can hold a non-integer 19.7 replicas of a lattice, then it is updated to reflect the width of 20 replicas. To ignore a direction (and make that dimension constant), such as when creating walls, set that dimension to 0 in dims.

bondsbool, default: False

Determines whether bond information is returned for polymeric systems. Has no effect if N_p=1.

anglesbool, default: False

Determines whether angle information is returned for polymeric systems. Has no effect if N_p=1.

dihedralsbool, default: False

Determines whether dihedral information is returned for polymeric systems. Has no effect if N_p=1.

randomizebool, default: False

Determines whether the order of the replicated polymer positions are randomized. Has no effect if N_p=1.

length_unitopenmm.unit.Unit, optional

Length unit. If not specified, it is determined automatically from dims or length.

wrapbool, default: False

Determines whether particles outside the simulation box are wrapped back into the main unit cell.

Returns:

positionsnumpy.ndarray or openmm.unit.Quantity

Generated particle positions.

Shape: \((N,\,3)\).

Reference unit: \(\mathrm{nm}\).

bondsnumpy.ndarray

Pairs of all bonded particle indices. Only returned if bonds=True.

Shape: \((N_\mathrm{bonds},\,2)\).

anglesnumpy.ndarray

Triples of all particle indices that form an angle. Only returned if angles=True.

Shape: \((N_\mathrm{angles},\,3)\).

dihedralsnumpy.ndarray

Quadruples of all particle indices that form a dihedral. Only returned if dihedrals=True.

Shape: \((N_\mathrm{dihedrals},\,4)\).

dimensionsnumpy.ndarray or openmm.unit.Quantity

Dimensions for lattice systems. Only returned if lattice is not None.

Shape: \((3,)\).

Reference unit: \(\mathrm{nm}\).