File: fl-examples.rst

package info (click to toggle)
python-gsd 2.4.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 904 kB
  • sloc: python: 2,742; ansic: 1,881; makefile: 157; cpp: 109
file content (244 lines) | stat: -rw-r--r-- 6,782 bytes parent folder | download
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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
.. Copyright (c) 2016-2020 The Regents of the University of Michigan
.. This file is part of the General Simulation Data (GSD) project, released
.. under the BSD 2-Clause License.

.. _fl-examples:

File layer
----------

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.

Open a gsd file
^^^^^^^^^^^^^^^

.. ipython:: python

    f = gsd.fl.open(name="file.gsd",
                    mode='wb',
                    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='wb',
                    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='rb')
    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='rb')
    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

    f = gsd.fl.open(name="file.gsd", mode='rb')
    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

    f = gsd.fl.open(name="file.gsd", mode='rb')
    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
    @okexcept
    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='rb')
    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

    f = gsd.fl.open(name="file.gsd",
                    mode='wb+',
                    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.

Write a file in append mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. ipython:: python

    f = gsd.fl.open(name="file.gsd", mode='ab')
    f.write_chunk(name='int', data=numpy.array([10,20], dtype=numpy.int16));
    f.end_frame()
    f.nframes
    # Reads fail in append mode
    @okexcept
    f.read_chunk(frame=2, name='double')
    f.close()

Open a file in append mode to write additional chunks to an existing file,
but prevent reading.

Use as a context manager
^^^^^^^^^^^^^^^^^^^^^^^^

.. ipython:: python

    with gsd.fl.open(name="file.gsd", mode='rb') 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='wb+',
                    application="My application",
                    schema="My Schema",
                    schema_version=[1,0])
    f.mode
    s = "This is a string"
    b = numpy.array([s], dtype=numpy.dtype((bytes, len(s)+1)))
    b = b.view(dtype=numpy.int8)
    b
    f.write_chunk(name='string', data=b)
    f.end_frame()
    r = f.read_chunk(frame=0, name='string')
    r
    r = r.view(dtype=numpy.dtype((bytes, r.shape[0])));
    r[0].decode('UTF-8')
    f.close()

To store a string in a gsd file, convert it to a numpy array of bytes and store
that data in the file. Decode the byte sequence to get back a string.

Truncate
^^^^^^^^

.. ipython:: python

    f = gsd.fl.open(name="file.gsd", mode='ab')
    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.