deprecated.init.create_random Generates N randomly positioned particles of the same type.
deprecated.init.create_random_polymers Generates any number of randomly positioned polymers of configurable types.
deprecated.init.read_xml ## Reads initial system state from an XML file


Deprecated initialization routines.

hoomd.deprecated.init.create_random(N, phi_p=None, name='A', min_dist=0.7, box=None, seed=1, dimensions=3)

Generates N randomly positioned particles of the same type.

  • N (int) – Number of particles to create.
  • phi_p (float) – Packing fraction of particles in the simulation box (unitless).
  • name (str) – Name of the particle type to create.
  • min_dist (float) – Minimum distance particles will be separated by (in distance units).
  • box ( – Simulation box dimensions.
  • seed (int) – Random seed.
  • dimensions (int) – The number of dimensions in the simulation.

Deprecated since version 2.0: Random initialization is best left to specific methods tailored by the user for their work.

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


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

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 e n is related to the packing fraction by \(n = 2d/\pi \cdot \phi_P\), where d is the dimension, and assumes the particles have a radius of 0.5. All particles are created with the same type, given by name.

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

hoomd.deprecated.init.create_random_polymers(box, polymers, separation, seed=1)

Generates any number of randomly positioned polymers of configurable types.

  • box ( – Simulation box dimensions
  • polymers (list) – Specification for the different polymers to create (see below)
  • separation (dict) – Separation radii for different particle types (see below)
  • seed (int) – Random seed to use

Deprecated since version 2.0: Random initialization is best left to specific methods tailored by the user for their work.

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 5 B beads bonded in a branched pattern:

polymer2 = dict(bond_len=1.2, type=['B']*5,
                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 c (a,b) specifies that particle c a of the polymer be bonded to particle c 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:

    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.


                            polymers=[polymer1, polymer2],
                            separation=dict(A=0.35, B=0.35));

                            separation=dict(A=0.35, B=0.35), seed=52);

# create polymers in an orthorhombic box
                            separation=dict(A=0.35, B=0.35), seed=12345);

# create a triclinic box with tilt factors xy=0.1 xz=0.2 yz=0.3
init.create_random_polymers(box=data.boxdim(L=18, xy=0.1, xz=0.2, yz=0.3),
                            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 e may generate different systems even with the same seed due to programming changes.


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.


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).

hoomd.deprecated.init.read_xml(filename, restart=None, time_step=None, wrap_coordinates=False)

## Reads initial system state from an XML file

  • filename (str) – File to read
  • restart (str) – If it exists, read restart instead of filename.
  • time_step (int) – (if specified) Time step number to use instead of the one stored in the XML file
  • wrap_coordinates (bool) – Wrap input coordinates back into the box

Deprecated since version 2.0: GSD is the new default file format for HOOMD-blue. It can store everything that an XML file can in an efficient binary format that is easy to access. See hoomd.init.read_gsd.


deprecated.init.read_xml(filename="init.xml", restart="restart.xml")
deprecated.init.read_xml(filename="restart.xml", time_step=0)
system = deprecated.init.read_xml(filename="data.xml")

All particles, bonds, etc… are read from the given XML file, setting the initial condition of the simulation. After this command completes, the system is initialized allowing other commands in hoomd to be run.

For restartable jobs, specify the initial condition in filename and the restart file in restart. init.read_xml will read the restart file if it exists, otherwise it will read filename.

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.