Package hoomd_script.init

Data initialization commands. More...

Functions
def	reset
	Resets all hoomd_script variables.
def	read_xml
	Reads initial system state from an XML file.
def	create_random
	Generates N randomly positioned particles of the same type.
def	create_random_polymers
	Generates any number of randomly positioned polymers of configurable types.

---

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_random	(		N,
			phi_p,
			name = "A",
			min_dist = 0.7
	)

Generates N randomly positioned particles of the same type.

Parameters:

	N	Number of particles to create
	phi_p	Packing fraction of particles in the simulation box
	name	Name of the particle type to create
	min_dist	Minimum distance particles will be separated by

Examples:

 init.create_random(N=2400, phi_p=0.20)
 init.create_random(N=2400, phi_p=0.40, min_dist=0.5)

N particles are randomly placed in the simulation box. 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 assuming the particles have a radius of 0.5. All particles are created with the same type, given by name.

def hoomd_script.init.create_random_polymers	(		box,
			polymers,
			separation,
			seed = 1
	)

Generates any number of randomly positioned polymers of configurable types.

Parameters:

	box	BoxDim specifying the simulation box to generate the polymers in
	polymers	Specification for the different polymers to create (see below)
	separation	Separation radii for different particle types (see below)
	seed	Random 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.

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

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

 polymer2 = dict(bond_len=1.2, type=['B']*4, 
                 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.

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.

Examples:

 init.create_random_polymers(box=hoomd.BoxDim(35), 
                             polymers=[polymer1, polymer2], 
                             separation=dict(A=0.35, B=0.35));
 
 init.create_random_polymers(box=hoomd.BoxDim(31), 
                             polymers=[polymer1], 
                             separation=dict(A=0.35, B=0.35), seed=52);
 
 init.create_random_polymers(box=hoomd.BoxDim(18,10,25), 
                             polymers=[polymer2], 
                             separation=dict(A=0.35, B=0.35), seed=12345);

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.

Note:

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 ___ (which isn't written yet) 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.

4. The bond type is named 'polymer' must be used in specifying bond coefficients in command such as bond.harmonic

def hoomd_script.init.read_xml

(

filename

)

Reads initial system state from an XML file.

Parameters:

filename

File to read

Examples:

 init.read_xml(filename="data.xml")
 init.read_xml(filename="directory/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.

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.

Note:

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.

Example:

 init.create_random(N=1000, phi_p = 0.2)
 lj = pair.lj(r_cut=3.0)
 .... setup and run simulation
 del lj
 init.reset()
 init.create_random(N=2000, phi_p = 0.2)
 .... setup and run simulation