HOOMD¶
gsd.hoomd
provides high-level access to HOOMD schema GSD files.
View the page source to find unformatted example code that can be easily copied.
Define a snapshot¶
In [1]: s = gsd.hoomd.Snapshot()
In [2]: s.particles.N = 4
In [3]: s.particles.types = ['A', 'B']
In [4]: s.particles.typeid = [0,0,1,1]
In [5]: s.particles.position = [[0,0,0],[1,1,1], [-1,-1,-1], [1,-1,-1]]
In [6]: s.configuration.box = [3, 3, 3, 0, 0, 0]
gsd.hoomd
represents the state of a single frame with an instance of the
class gsd.hoomd.Snapshot
. Instantiate this class to create a system
configuration. All fields default to None
and are only written into the file
if not None
and do not match the data in the first frame, or defaults specified
in the schema.
Create a hoomd gsd file¶
In [7]: gsd.hoomd.open(name='test.gsd', mode='wb')
Out[7]: <gsd.hoomd.HOOMDTrajectory at 0x7f93f9155ba8>
Append frames to a gsd file¶
In [8]: def create_frame(i):
...: s = gsd.hoomd.Snapshot()
...: s.configuration.step = i
...: s.particles.N = 4+i
...: s.particles.position = numpy.random.random(size=(4+i,3))
...: return s
...:
In [9]: t = gsd.hoomd.open(name='test.gsd', mode='wb')
In [10]: t.extend( (create_frame(i) for i in range(10)) )
In [11]: t.append( create_frame(10) )
In [12]: len(t)
Out[12]: 11
Use gsd.hoomd.open()
to open a GSD file with the high level interface
gsd.hoomd.HOOMDTrajectory
. It behaves like a python list
, with
gsd.hoomd.HOOMDTrajectory.append()
and gsd.hoomd.HOOMDTrajectory.extend()
methods.
Note
gsd.hoomd.HOOMDTrajectory
currently doesn’t support files opened in
append mode.
Tip
When using gsd.hoomd.HOOMDTrajectory.extend()
, pass in a generator or
generator expression to avoid storing the entire trajectory in RAM before
writing it out.
Randomly index frames¶
In [13]: t = gsd.hoomd.open(name='test.gsd', mode='rb') In [14]: snap = t[5] In [15]: snap.configuration.step Out[15]: 5 In [16]: snap.particles.N Out[16]: 9 In [17]: snap.particles.position Out[17]: array([[0.6058369 , 0.2824726 , 0.4119033 ], [0.02011489, 0.40808463, 0.75461286], [0.8920138 , 0.5223734 , 0.66687876], [0.7770543 , 0.9370431 , 0.35893524], [0.84588414, 0.22120892, 0.6887794 ], [0.24513623, 0.4556149 , 0.3307478 ], [0.8481325 , 0.444387 , 0.92860514], [0.605203 , 0.52054554, 0.5750037 ], [0.5712408 , 0.0222868 , 0.1130439 ]], dtype=float32)
gsd.hoomd.HOOMDTrajectory
supports random indexing of frames in the file. Indexing
into a trajectory returns a gsd.hoomd.Snapshot
.
Slicing and selection¶
Use the slicing operator to select individual frames or a subset of a trajectory.
In [18]: t = gsd.hoomd.open(name='test.gsd', mode='rb')
In [19]: for s in t[5:-2]:
....: print(s.configuration.step, end=' ')
....:
5 6 7 8
In [20]: every_2nd_frame = t[::2] # create a view of a trajectory subset
In [21]: for s in every_2nd_frame[:4]:
....: print(s.configuration.step, end=' ')
....:
0 2 4 6
Slicing a trajectory creates a trajectory view, which can then be queried for length or sliced again. Selecting individual frames from a view works exactly like selecting individual frames from the original trajectory object.
Pure python reader¶
In [22]: f = gsd.pygsd.GSDFile(open('test.gsd', 'rb'))
In [23]: t = gsd.hoomd.HOOMDTrajectory(f);
In [24]: t[3].particles.position
Out[24]:
array([[0.16555013, 0.01798811, 0.29542455],
[0.97881854, 0.7098888 , 0.73944134],
[0.60747623, 0.1383629 , 0.04565979],
[0.72224534, 0.09241979, 0.11540996],
[0.54017764, 0.908462 , 0.13864072],
[0.6259134 , 0.5007839 , 0.57675624],
[0.7390836 , 0.4128058 , 0.67003036]], dtype=float32)
You can use GSD without needing to compile C code to read GSD files using
gsd.pygsd.GSDFile
in combination with gsd.hoomd.HOOMDTrajectory
. It only
supports the rb
mode and does not read files as fast as the C implementation.
It takes in a python file-like object, so it can be used with in-memory IO classes, and
grid file classes that access data over the internet.
Access state data¶
In [25]: with gsd.hoomd.open(name='test2.gsd', mode='wb') as t:
....: s = gsd.hoomd.Snapshot()
....: s.particles.types = ['A', 'B']
....: s.state['hpmc/convex_polygon/N'] = [3, 4]
....: s.state['hpmc/convex_polygon/vertices'] = [[-1, -1],
....: [1, -1],
....: [1, 1],
....: [-2, -2],
....: [2, -2],
....: [2, 2],
....: [-2, 2]]
....: t.append(s)
....:
State data is stored in the state
dictionary as numpy arrays. Place data into this dictionary directly
without the ‘state/’ prefix and gsd will include it in the output. Shape vertices are stored in a packed
format. In this example, type ‘A’ has 3 vertices (the first 3 in the list) and type ‘B’ has 4 (the next 4).
In [26]: with gsd.hoomd.open(name='test2.gsd', mode='rb') as t:
....: s = t[0]
....: print(s.state['hpmc/convex_polygon/N'])
....: print(s.state['hpmc/convex_polygon/vertices'])
....:
[3 4]
[[-1. -1.]
[ 1. -1.]
[ 1. 1.]
[-2. -2.]
[ 2. -2.]
[ 2. 2.]
[-2. 2.]]
Access read state data in the same way.