1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
.. Copyright (c) 2016-2024 The Regents of the University of Michigan
.. Part of GSD, released under the BSD 2-Clause License.
.. _fl-examples:
File layer examples
-------------------
The file layer python module `gsd.fl` allows direct low level access to read and
write **GSD** files of any schema. The **HOOMD** reader (`gsd.hoomd`) provides
higher level access to **HOOMD** schema files, see :ref:`hoomd-examples`.
View the page source to find unformatted example code.
Import the module
^^^^^^^^^^^^^^^^^
.. ipython:: python
import gsd.fl
Open a gsd file
^^^^^^^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd",
mode='w',
application="My application",
schema="My Schema",
schema_version=[1,0])
Use `gsd.fl.open` to open a gsd file.
.. note::
When creating a new file, you must specify the application name, schema
name, and schema version.
.. warning::
Opening a gsd file with a 'w' or 'x' mode overwrites any existing file with
the given name.
Close a gsd file
^^^^^^^^^^^^^^^^
.. ipython:: python
f.close()
Call the `close <gsd.fl.GSDFile.close>` method to close the file.
Write data
^^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd",
mode='w',
application="My application",
schema="My Schema",
schema_version=[1,0]);
f.write_chunk(name='chunk1', data=numpy.array([1,2,3,4], dtype=numpy.float32))
f.write_chunk(name='chunk2', data=numpy.array([[5,6],[7,8]], dtype=numpy.float32))
f.end_frame()
f.write_chunk(name='chunk1', data=numpy.array([9,10,11,12], dtype=numpy.float32))
f.write_chunk(name='chunk2', data=numpy.array([[13,14],[15,16]], dtype=numpy.float32))
f.end_frame()
f.close()
Add any number of named data chunks to each frame in the file with
`write_chunk <gsd.fl.GSDFile.write_chunk>`. The data must be a 1 or 2
dimensional numpy array of a simple numeric type (or a data type that will
automatically convert when passed to ``numpy.array(data)``. Call
`end_frame <gsd.fl.GSDFile.end_frame>` to end the frame and start the next one.
.. note::
While supported, implicit conversion to numpy arrays creates a copy of the
data in memory and adds conversion overhead.
.. warning::
Call `end_frame <gsd.fl.GSDFile.end_frame>` to write the last frame before
closing the file.
Read data
^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd", mode='r')
f.read_chunk(frame=0, name='chunk1')
f.read_chunk(frame=1, name='chunk2')
f.close()
`read_chunk <gsd.fl.GSDFile.read_chunk>` reads the named chunk at the given
frame index in the file and returns it as a numpy array.
Test if a chunk exists
^^^^^^^^^^^^^^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd", mode='r')
f.chunk_exists(frame=0, name='chunk1')
f.chunk_exists(frame=1, name='chunk2')
f.chunk_exists(frame=2, name='chunk1')
f.close()
`chunk_exists <gsd.fl.GSDFile.chunk_exists>` tests to see if a chunk by the
given name exists in the file at the given frame.
Discover chunk names
^^^^^^^^^^^^^^^^^^^^
.. ipython:: python
:okexcept:
f = gsd.fl.open(name="file.gsd", mode='r')
f.find_matching_chunk_names('')
f.find_matching_chunk_names('chunk')
f.find_matching_chunk_names('chunk1')
f.find_matching_chunk_names('other')
`find_matching_chunk_names <gsd.fl.GSDFile.find_matching_chunk_names>` finds all
chunk names present in a GSD file that start with the given string.
Read-only access
^^^^^^^^^^^^^^^^
.. ipython:: python
:okexcept:
f = gsd.fl.open(name="file.gsd", mode='r')
if f.chunk_exists(frame=0, name='chunk1'):
data = f.read_chunk(frame=0, name='chunk1')
data
# Fails because the file is open read only
f.write_chunk(name='error', data=numpy.array([1]))
f.close()
Writes fail when a file is opened in a read only mode.
Access file metadata
^^^^^^^^^^^^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd", mode='r')
f.name
f.mode
f.gsd_version
f.application
f.schema
f.schema_version
f.nframes
f.close()
Read file metadata from properties of the file object.
Open a file in read/write mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. ipython:: python
:okexcept:
f = gsd.fl.open(name="file.gsd",
mode='w',
application="My application",
schema="My Schema",
schema_version=[1,0])
f.write_chunk(name='double', data=numpy.array([1,2,3,4], dtype=numpy.float64));
f.end_frame()
f.nframes
f.read_chunk(frame=0, name='double')
Open a file in read/write mode to allow both reading and writing.
Use as a context manager
^^^^^^^^^^^^^^^^^^^^^^^^
.. ipython:: python
:okexcept:
with gsd.fl.open(name="file.gsd", mode='r') as f:
data = f.read_chunk(frame=0, name='double');
data
Use `gsd.fl.GSDFile` as a context manager for guaranteed file closure and
cleanup when exceptions occur.
Store string chunks
^^^^^^^^^^^^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd",
mode='w',
application="My application",
schema="My Schema",
schema_version=[1,0])
f.write_chunk(name='string', data="This is a string")
f.end_frame()
r = f.read_chunk(frame=0, name='string')
r
f.close()
Staring with GSD 3.4.0, the file layer can natively store strings in the file.
In previous versions, you need to convert strings to a numpy array of bytes and store
that data in the file.
Truncate
^^^^^^^^
.. ipython:: python
f = gsd.fl.open(name="file.gsd", mode='r+')
f.nframes
f.schema, f.schema_version, f.application
f.truncate()
f.nframes
f.schema, f.schema_version, f.application
f.close()
Truncating a gsd file removes all data chunks from it, but retains the same
schema, schema version, and application name. The file is not closed during this
process. This is useful when writing restart files on a Lustre file system when
file open operations need to be kept to a minimum.
|
