lammpsio.Snapshot¶

class lammpsio.Snapshot(N, box, step=None, num_types=None)¶

Particle configuration.

A Snapshot holds the data for N particles, the simulation Box, and the timestep.

Parameters:

N (int) – Number of particles in configuration.
box (Box) – Simulation box.
step (int) – Simulation time step. Default of None means time step is not specified.
num_types (int) – Number of particle types. If None, the number of types is deduced from typeid.

Example

Here is a 3-particle configuration in a cubic box centered at the origin at step 10:

snapshot = lammpsio.Snapshot(
    N=3,
    box=lammpsio.Box([-5, -5, -5], [5, 5, 5]),
    step=10
)

All values of indexes follow the LAMMPS 1-indexed convention, but the arrays themselves are 0-indexed. Snapshot will lazily initialize these per-particle arrays as they are accessed to save memory. Hence, accessing a per-particle property will allocate it to default values. If you want to check if an attribute has been set, use the corresponding has_ method instead (e.g., has_position to check if the position data is allocated):

snapshot.position = [[0, 0, 0], [1, -1, 1], [1.5, 2.5, -3.5]]
snapshot.typeid[2] = 2
if not snapshot.has_mass():
    snapshot.mass = [2., 2., 10.]

Methods:

`from_hoomd_gsd`(frame)	Create from a HOOMD GSD frame.
`has_angles`()	Check if configuration has angles.
`has_bonds`()	Check if configuration has bonds.
`has_charge`()	Check if configuration has charges.
`has_dihedrals`()	Check if configuration has dihedrals.
`has_id`()	Check if configuration has particle IDs.
`has_image`()	Check if configuration has images.
`has_impropers`()	Check if configuration has impropers.
`has_mass`()	Check if configuration has masses.
`has_molecule`()	Check if configuration has molecule tags.
`has_position`()	Check if configuration has positions.
`has_typeid`()	Check if configuration has types.
`has_velocity`()	Check if configuration has velocities.
`reorder`(order[, check_order])	Reorder the particles in place.
`to_hoomd_gsd`([type_map])	Create a HOOMD GSD frame.

Attributes:

`N`	Number of particles.
`angles`	Angle data.
`bonds`	Bond data.
`box`	Simulation box.
`charge`	Charges.
`dihedrals`	Dihedral data.
`id`	Particle IDs.
`image`	Images.
`impropers`	Improper data.
`mass`	Masses.
`molecule`	Molecule tags.
`num_types`	Number of atom types.
`position`	Positions.
`step`	Simulation time step.
`type_label`	Labels for `typeid`.
`typeid`	Types.
`velocity`	Velocities.

classmethod from_hoomd_gsd(frame)¶

Create from a HOOMD GSD frame.

Parameters:

frame (gsd.hoomd.Frame) – HOOMD GSD frame to convert.

Returns:

Snapshot – Snapshot created from HOOMD GSD frame.
dict – A map from the Snapshot.typeid to the HOOMD type.

Deprecated since version 0.7.0: Use Snapshot.type_label instead.

Example

Create snapshot from a GSD file:

frame = gsd.hoomd.Frame()
frame.configuration.box = [10, 10, 10, 0, 0, 0]
frame.particles.N = 3
snapshot, type_map = lammpsio.Snapshot.from_hoomd_gsd(frame)

This creates a Snapshot from the provided HOOMD GSD frame as well as the corresponding dictionary of typeids mapped from the HOOMD GSD frame.

to_hoomd_gsd(type_map=None)¶

Create a HOOMD GSD frame.

Parameters:

type_map (dict) –

A map from the Snapshot.typeid to a HOOMD type. If not specified, the typeids are used as the types.

Deprecated since version 0.7.0: Use Snapshot.type_label instead.

Returns:

Converted HOOMD GSD frame.

Return type:

gsd.hoomd.Frame

Example

Convert snapshot to a GSD file:

frame = snapshot.to_hoomd_gsd()

This creates a GSD frame for the HOOMD-blue simulation package from the Snapshot object.

property N¶

Number of particles.

Type:: int

property box¶

Simulation box.

Type:: Box

property step¶

Simulation time step.

Type:: int

property id¶

Particle IDs.

The default value on initialization runs from 1 to N.

Type:: (N,) numpy.ndarray of int

has_id()¶

Check if configuration has particle IDs.

Returns:: True if particle IDs have been initialized.
Return type:: bool

property position¶

Positions.

The default value on initialization is 0 for all entries.

Type:: (N, 3) numpy.ndarray of float

has_position()¶

Check if configuration has positions.

Returns:: True if positions have been initialized.
Return type:: bool

property image¶

Images.

The default value on initialization is 0 for all entries.

Type:: (N, 3) numpy.ndarray of int

has_image()¶

Check if configuration has images.

Returns:: True if images have been initialized.
Return type:: bool

property velocity¶

Velocities.

The default value on initialization is 0 for all entries.

Type:: (N, 3) numpy.ndarray of float

has_velocity()¶

Check if configuration has velocities.

Returns:: True if velocities have been initialized.
Return type:: bool

property molecule¶

Molecule tags.

The default value on initialization is 0 for all entries.

Type:: (N,) numpy.ndarray of int

has_molecule()¶

Check if configuration has molecule tags.

Returns:: True if molecule tags have been initialized.
Return type:: bool

property num_types¶

Number of atom types.

Type:: int

property typeid¶

Types.

The default value on initialization is 1 for all entries.

Type:: (N,) numpy.ndarray of int

has_typeid()¶

Check if configuration has types.

Returns:: True if types have been initialized.
Return type:: bool

property charge¶

Charges.

The default value on initialization is 0 for all entries.

Type:: (N,) numpy.ndarray of float

has_charge()¶

Check if configuration has charges.

Returns:: True if charges have been initialized.
Return type:: bool

property mass¶

Masses.

The default value on initialization is 1 for all entries.

Type:: (N,) numpy.ndarray of float

has_mass()¶

Check if configuration has masses.

Returns:: True if masses have been initialized.
Return type:: bool

property type_label¶

Labels for typeid.

Type:: LabelMap

property bonds¶

Bond data.

Type:: Bonds

has_bonds()¶

Check if configuration has bonds.

Returns:: True if bonds is initialized and there is at least one bond.
Return type:: bool

property angles¶

Angle data.

Type:: Angles

has_angles()¶

Check if configuration has angles.

Returns:: True if angles is initialized and there is at least one angle.
Return type:: bool

property dihedrals¶

Dihedral data.

Type:: Dihedrals

has_dihedrals()¶

Check if configuration has dihedrals.

Returns:: True if dihedrals is initialized and there is at least one dihedral.
Return type:: bool

property impropers¶

Improper data.

Type:: Impropers

has_impropers()¶

Check if configuration has impropers.

Returns:: True if impropers is initialized and there is at least one improper.
Return type:: bool

reorder(order, check_order=True)¶

Reorder the particles in place.

Parameters:

order (list) – New order of indexes.
check_order (bool) – If True, validate the new order before applying it.

Example

Reorder the particles in a snapshot

snapshot.bonds = lammpsio.Bonds(N=3, num_types=1)
bond_id = [1, 3, 2]
members = [[1, 2],
           [2, 3],
           [3, 1]]
typeid = [1, 1, 1]

snapshot.bonds.id = bond_id
snapshot.bonds.typeid = typeid
snapshot.bonds.members = members

snapshot.bonds.reorder(numpy.sort(numpy.array(bond_id)) - 1,
                       check_order=True)

This reorders the particle data with the same ordering as the bonds. To ensure only the right unique indexes are used, the check_order parameter is set to True. In LAMMPS, all the IDs are 1-indexed, while, Python is 0-indexed. Thus the bond_id is also decreased by 1 to match the Python convention.