System

Details

System class for arranging Molecules into a box.

class flowermd.base.system.System

Base class from which other systems inherit.

System class is used to create a system of molecules and arrange them into a box. If a force field is provided, the system will be parameterized. Two important properties of the system are hoomd_snapshot, which is the snapshot of the system in HOOMD format, and hoomd_forcefield, which is the list of HOOMD forces. These properties will be used to initialize the simulation object later.

System class is used to create a system of molecules and arrange them into a box. If a force field is provided, the system will be parameterized. Two important properties of the system are hoomd_snapshot, which is the snapshot of the system in HOOMD format, and hoomd_forcefield, which is the list of HOOMD forces. These properties will be used to initialize the simulation object later.

Parameters:

  • molecules (flowermd.Molecule or a list of Molecule objects, required) – The molecules to be placed in the system.

  • base_units (dict, default {}) – Dictionary of base units to use for scaling. Dictionary keys are “length”, “mass”, and “energy”. Values should be an unyt array of the desired base unit.

Warning

The force_field parameter in System class must be initialized from the pre-defined force field classes in flowermd.library.forcefields module that are based on xml-based force fields.

Forcefields defined as a list of Hoomd.md.force.Force objects must be directly passed to the flowermd.Simulation class. Please refer to the Simulation class documentation for more details.

apply_forcefield(r_cut, force_field=None, auto_scale=False, scale_charges=False, remove_charges=False, remove_hydrogens=False, pppm_resolution=(8, 8, 8), pppm_order=4, nlist_buffer=0.4)

Apply the forcefield to the system.

Parameters:

  • r_cut (float) – The cutoff radius for the Lennard-Jones interactions.

  • force_field (flowermd.ForceField or a list of ForceField objects,) – default=None The force field to be applied to the system for parameterization. If a list of force fields is provided, the length of the list must be equal to the number of molecule types in the system.

  • auto_scale (bool, default=False) – Set to true to use reduced simulation units. distance, mass, and energy are scaled by the largest value present in the system for each.

  • scale_charges (bool, default False) – Set to true to scale charges to net zero.

  • remove_charges (bool, default False) – Set to true to remove charges from the system.

  • remove_hydrogens (bool, default False) – Set to true to remove hydrogen atoms from the system. The masses and charges of the hydrogens are absorbed into the heavy atoms they were bonded to.

  • pppm_resolution (tuple, default=(8, 8, 8)) – The resolution used in hoomd.md.long_range.pppm.make_pppm_coulomb_force representing number of grid points in the x, y, and z directions.

  • ppmp_order (int, default=4) – The order used in hoomd.md.long_range.pppm.make_pppm_coulomb_force representing number of grid points in each direction to assign charges to.

  • nlist_buffer (float, default=0.4) – Neighborlist buffer for simulation cell.

property box

The box of the system.

property hoomd_forcefield

List of HOOMD forces.

property hoomd_snapshot

The snapshot of the system in form of a HOOMD snapshot.

property mass

Total mass of the system in amu.

property n_molecules

Total number of molecules in the system.

property n_particles

Total number of particles in the system.

property net_charge

Net charge of the system.

pickle_forcefield(file_path='forcefield.pickle')

Pickle the list of HOOMD forces.

This method useful for saving the Hoomd force objects generated by System.apply_forcefield() which can then be used to initialize a Simulation at a later time.

Parameters:

file_path (str, default "forcefield.pickle") – The path to save the pickle file to.

property reference_energy

The reference energy and unit of the system.

If auto_scale is set to True, this is the energy factor that is used to scale the system to reduced units. If auto_scale is set to False, the default value is 1.0 with the unit of kJ/mol.

property reference_length

The reference length and unit of the system.

If auto_scale is set to True, this is the length factor that is used to scale the system to reduced units. If auto_scale is set to False, the default value is 1.0 with the unit of nm.

property reference_mass

The reference mass and unit of the system.

If auto_scale is set to True, this is the mass factor that is used to scale the system to reduced units. If auto_scale is set to False, the default value is 1.0 with the unit of amu.

property reference_values

The reference values of the system in form of a dictionary.

remove_hydrogens()

Call this method to remove hydrogen atoms from the system.

The masses and charges of the hydrogens are absorbed into the heavy atoms they were bonded to.

to_gsd(file_name)

Write the system’s hoomd_snapshot to a GSD file.

visualize()

Visualize the system.

class flowermd.base.system.Pack

Bases: System

Uses PACKMOL via mbuild.packing.fill_box.

The box used for packing is expanded to allow PACKMOL to more easily place all the molecules.

Parameters:

  • density (float, required) – The desired density of the system (g/cm^3). Used to set the target_box attribute. Can be useful when initializing systems at low density and running a shrink simulation to achieve a target density.

  • packing_expand_factor (int, default 5) – The factor by which to expand the box for packing.

  • edge (float, default 0.2) – The space (nm) between the edge of the box and the molecules.

  • overlap (float, default 0.2) – Minimum separation (nm) between particles of different molecules.

Warning

Note that the default packing_expand_factor for pack is 5, which means that the box density will not be the same as the specified density. This is because in some cases PACKMOL will not be able to fit all the molecules into the box if the target box is too small, therefore, we need to expand the box by a factor (default:5) to allow PACKMOL to fit all the molecules.

In order to get the specified density there are two options:

1. set the packing_expand_factor to 1, which will not expand the box. However, this may result in PACKMOL errors if the box is too small.

2. Update the box volume after creating the simulation object to the target box length. This property is called target_box.

class flowermd.base.system.Lattice

Bases: System

Places the molecules in a lattice configuration.

Assumes two molecules per unit cell.

Parameters:

  • x (float, required) – The distance (nm) between lattice points in the x direction.

  • y (float, required) – The distance (nm) between lattice points in the y direction.

  • n (int, required) – The number of times to repeat the unit cell in x and y.

  • basis_vector (array-like, default [0.5, 0.5, 0]) – The vector between points in the unit cell.

Notes

The system is built in a way that the long axis of the molecules is aligned with the z direction, and the lattice is made by repeating and translating in the x and y directions.