Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
hoomd_script.init Namespace Reference

Data initialization commands. More...


def is_initialized
 Tests if the system has been initialized. More...
def reset
 Resets all hoomd_script variables. More...
def create_empty
 Create an empty system. More...
def read_xml
 Reads initial system state from an XML file. More...
def read_bin
 Reads initial system state from a binary file. More...
def create_random
 Generates N randomly positioned particles of the same type. More...
def create_random_polymers
 Generates any number of randomly positioned polymers of configurable types. More...
def read_snapshot
 Initializes the system from a snapshot. More...

Detailed Description

Data initialization commands.

Commands in the init package initialize the particle system. Initialization via any of the commands here must be done before any other command in hoomd_script can be run.

See Also
Quick Start Tutorial

Function Documentation

def hoomd_script.init.create_empty (   N,
  particle_types = ['A'],
  bond_types = [],
  angle_types = [],
  dihedral_types = [],
  improper_types = [] 

Create an empty system.

NNumber of particles to create
boxa data.boxdim object that defines the simulation box
particle_typesList of particle type names (must not be zero length)
bond_typesList of bond type names (may be zero length)
angle_typesList of angle type names (may be zero length)
dihedral_typesList of Dihedral type names (may be zero length)
improper_typesList of improper type names (may be zero length)


1 system = init.create_empty(N=1000, box=data.boxdim(L=10)
2 system = init.create_empty(N=64000, box=data.boxdim(L=1, dimensions=2, volume=1000), particle_types=['A', 'B'])
3 system = init.create_empty(N=64000, box=data.boxdim(L=20), bond_types=['polymer'], dihedral_types=['dihedralA', 'dihedralB'], improper_types=['improperA', 'improperB', 'improperC'])

After init.create_empty returns, the requested number of particles will have been created with DEFAULT VALUES and further initialization MUST be performed. See hoomd_script.data for full details on how such initialization can be performed.

Specifically, all created particles will be:

  • At position 0,0,0
  • Have velocity 0,0,0
  • In box image 0,0,0
  • Have orientation 1,0,0,0
  • Have the type particle_types[0]
  • Have charge 0
  • Have a mass of 1.0

The particle, bond, angle, dihedral, and improper types will be created and set to the names specified. Use these type names later in the job script to refer to particles (i.e. in lj.set_params)

The resulting empty system must have its particles fully initialized via python code, BEFORE any other hoomd_script commands are executed. For example, if the pair.lj command were to be run before the initial particle positions were set, all particles would have position 0,0,0 and the memory initialized by the neighbor list would be so large that the memory allocation would fail.
See Also
def hoomd_script.init.create_random (   N,
  phi_p = None,
  name = "A",
  min_dist = 0.7,
  box = None,
  seed = 1 

Generates N randomly positioned particles of the same type.

NNumber of particles to create
phi_pPacking fraction of particles in the simulation box (unitless)
nameName of the particle type to create
min_distMinimum distance particles will be separated by (in distance units)
boxSimulation box dimensions (data.boxdim object)
seedRandom seed

Either phi_p or box must be specified. If phi_p is provided, it overrides the value of box.


1 init.create_random(N=2400, phi_p=0.20)
2 init.create_random(N=2400, phi_p=0.40, min_dist=0.5)
3 system = init.create_random(N=2400, box=data.boxdim(L=20))

N particles are randomly placed in the simulation box.

When phi_p is set, the dimensions of the created box are such that the packing fraction of particles in the box is phi_p. The number density n is related to the packing fraction by \(n = 6/\pi \cdot \phi_P\) assuming the particles have a radius of 0.5. All particles are created with the same type, given by name.

The result of init.create_random can be saved in a variable and later used to read and/or change particle properties later in the script. See hoomd_script.data for more information.

analyze_imd, dump_dcd, and init_reset.
def hoomd_script.init.create_random_polymers (   box,
  seed = 1 

Generates any number of randomly positioned polymers of configurable types.

boxSimulation box dimensions (data.boxdim object)
polymersSpecification for the different polymers to create (see below)
separationSeparation radii for different particle types (see below)
seedRandom seed to use

Any number of polymers can be generated, of the same or different types, as specified in the argument polymers. Parameters for each polymer include bond length, particle type list, bond list, and count.

The syntax is best shown by example. The below line specifies that 600 block copolymers A6B7A6 with a bond length of 1.2 be generated.

1 polymer1 = dict(bond_len=1.2, type=['A']*6 + ['B']*7 + ['A']*6,
2  bond="linear", count=600)

Here is an example for a second polymer, specifying just 100 polymers made of 5 B beads bonded in a branched pattern

1 polymer2 = dict(bond_len=1.2, type=['B']*5,
2  bond=[(0, 1), (1,2), (1,3), (3,4)] , count=100)

The polymers argument can be given a list of any number of polymer types specified as above. count randomly generated polymers of each type in the list will be generated in the system.

In detail:

  • bond_len defines the bond length of the generated polymers. This should not necessarily be set to the equilibrium bond length! The generator is dumb and doesn't know that bonded particles can be placed closer together than the separation (see below). Thus bond_len must be at a minimum set at twice the value of the largest separation radius. An error will be generated if this is not the case.
  • type is a python list of strings. Each string names a particle type in the order that they will be created in generating the polymer.
  • bond can be specified as "linear" in which case the generator connects all particles together with bonds to form a linear chain. bond can also be given a list if python tuples (see example above).
    • Each tuple in the form of (a,b) specifies that particle a of the polymer be bonded to particle b. These bonds are given the default type name of 'polymer' to be used when specifying parameters to bond forces such as bond.harmonic.
    • A tuple with three elements (a,b,type) can be used as above, but with a custom name for the bond. For example, a simple branched polymer with different bond types on each branch could be defined like so:
      1 bond=[(0,1), (1,2), (2,3,'branchA'), (3,4,'branchA), (2,5,'branchB'), (5,6,'branchB')]

separation must contain one entry for each particle type specified in polymers ('A' and 'B' in the examples above). The value given is the separation radius of each particle of that type. The generated polymer system will have no two overlapping particles.


1 init.create_random_polymers(box=data.boxdim(L=35),
2  polymers=[polymer1, polymer2],
3  separation=dict(A=0.35, B=0.35));
5 init.create_random_polymers(box=data.boxdim(L=31),
6  polymers=[polymer1],
7  separation=dict(A=0.35, B=0.35), seed=52);
9 # create polymers in an orthorhombic box
10 init.create_random_polymers(box=data.boxdim(Lx=18,Ly=10,Lz=25),
11  polymers=[polymer2],
12  separation=dict(A=0.35, B=0.35), seed=12345);
14 # create a triclinic box with tilt factors xy=0.1 xz=0.2 yz=0.3
15 init.create_random_polymers(box=data.boxdim(L=18, xy=0.1, xz=0.2, yz=0.3),
16  polymeres=[polymer2],
17  separation=dict(A=0.35, B=0.35));

With all other parameters the same, create_random_polymers will always create the same system if seed is the same. Set a different seed (any integer) to create a different random system with the same parameters. Note that different versions of HOOMD may generate different systems even with the same seed due to programming changes.

1. For relatively dense systems (packing fraction 0.4 and higher) the simple random generation algorithm may fail to find room for all the particles and print an error message. There are two methods to solve this. First, you can lower the separation radii allowing particles to be placed closer together. Then setup integrate.nve with the limit option set to a relatively small value. A few thousand time steps should relax the system so that the simulation can be continued without the limit or with a different integrator. For extremely troublesome systems, generate it at a very low density and shrink the box with the command update.box_resize to the desired final size.
2. The polymer generator always generates polymers as if there were linear chains. If you provide a non-linear bond topology, the bonds in the initial configuration will be stretched significantly. This normally doesn't pose a problem for harmonic bonds (bond.harmonic) as the system will simply relax over a few time steps, but can cause the system to blow up with FENE bonds (bond.fene).
3. While the custom bond list allows you to create ring shaped polymers, testing shows that such conformations have trouble relaxing and get stuck in tangled configurations. If you need to generate a configuration of rings, you may need to write your own specialized initial configuration generator that writes HOOMD XML input files (see XML File Format). HOOMD's built-in polymer generator attempts to be as general as possible, but unfortunately cannot work in every possible case.

The result of init.create_random_polymers can be saved in a variable and later used to read and/or change particle properties later in the script. See hoomd_script.data for more information.

def hoomd_script.init.is_initialized ( )

Tests if the system has been initialized.

Returns True if a previous init.create* or init.read* command has completed successfully and initialized the system. Returns False otherwise.

def hoomd_script.init.read_bin (   filename,
  time_step = None 

Reads initial system state from a binary file.

filenameFile to read


1 init.read_bin(filename="data.bin.gz")
2 init.read_bin(filename="directory/data.bin")
3 system = init.read_bin(filename="data.bin.gz")

All particles, bonds, etc... are read from the binary file given, setting the initial condition of the simulation. Binary restart files also include state information needed to continue integrating time forward as if the previous job had never stopped. For more information see dump.bin.

After this command completes, the system is initialized allowing other commands in hoomd_script to be run.

The presence or lack of a .gz extension determines whether init.read_bin will attempt to decompress the data before reading it.

The result of init.read_bin can be saved in a variable and later used to read and/or change particle properties later in the script. See hoomd_script.data for more information.

init.read_bin is deprecated. It currently maintains all of its old functionality, but there are a number of new features in HOOMD-blue that it does not support.
  • Triclinic boxes
See Also
def hoomd_script.init.read_snapshot (   snapshot)

Initializes the system from a snapshot.

snapshotThe snapshot to initialize the system from

Snapshots temporarily store system data. Snapshots contain the complete simulation state in a single object. They can be used to start or restart a simulation.

Example use cases in which a simulation may be started from a snapshot include user code that generates initial particle positions.

Snapshots do not yet have a python API, so they can only be generated by C++ plugins. A future version of HOOMD-blue will allow fast access to snapshot data in python.


1 snapshot = my_system_create_routine(.. parameters ..)
2 system = init.read_snapshot(snapshot)
See Also
def hoomd_script.init.read_xml (   filename,
  time_step = None,
  wrap_coordinates = False 

Reads initial system state from an XML file.

filenameFile to read
time_step(if specified) Time step number to use instead of the one stored in the XML file
wrap_coordinatesWrap input coordinates back into the box


1 init.read_xml(filename="data.xml")
2 init.read_xml(filename="directory/data.xml")
3 init.read_xml(filename="restart.xml", time_step=0)
4 system = init.read_xml(filename="data.xml")

All particles, bonds, etc... are read from the XML file given, setting the initial condition of the simulation. After this command completes, the system is initialized allowing other commands in hoomd_script to be run. For more details on the file format read by this command, see XML File Format.

All values are read in native units, see Units for more information.

If time_step is specified, its value will be used as the initial time step of the simulation instead of the one read from the XML file.

If wrap_coordinates is set to True, input coordinates will be wrapped into the box specified inside the XML file. If it is set to False, out-of-box coordinates will result in an error.

The result of init.read_xml can be saved in a variable and later used to read and/or change particle properties later in the script. See hoomd_script.data for more information.

See Also
box_resize, box_resize_rigid, and init_xml.
def hoomd_script.init.reset ( )

Resets all hoomd_script variables.

After calling init.reset() all global variables used in hoomd_script are cleared and all allocated memory is freed so the simulation can begin anew without needing to launch hoomd again.

There is a very important memory management issue that must be kept in mind when using reset(). If you have saved a variable such as an integrator or a force for changing parameters, that saved object must be deleted before the reset() command is called. If all objects are not deleted, then a memory leak will result causing repeated runs of even a small simulation to eventually run the system out of memory. reset() will throw an error if it detects that this is the case.
When using the python data access in hoomd scripts, iterators must also be deleted
1 for p in sysdef.particles:
2  # do something
4 del p
5 init.reste()


1 init.create_random(N=1000, phi_p = 0.2)
2 lj = pair.lj(r_cut=3.0)
3 .... setup and run simulation
4 del lj
5 init.reset()
6 init.create_random(N=2000, phi_p = 0.2)
7 .... setup and run simulation

Documentation for HOOMD-blue v0.11.3-1371-ge0dfd60
Generated on Mon Apr 14 2014 07:30:05 for HOOMD-blue by doxygen 1.8.5