# gsd.pygsd module

GSD reader written in pure Python.

`pygsd.py` is a pure Python implementation of a GSD reader. If your analysis tool is written in Python and you want to embed a GSD reader without requiring C code compilation or require the gsd Python package as a dependency, then use the following Python files from the `gsd/` directory to make a pure Python reader. It is not as high performance as the C reader.

- `gsd/`

  > - `__init__.py`

  > - `pygsd.py`

  > - `hoomd.py`

The reader reads from file-like Python objects, which may be useful for reading from in memory buffers, and in-database grid files, For regular files on the filesystem, and for writing gsd files, use `gsd.fl`.

The `GSDFile` in this module can be used with the `gsd.hoomd.HOOMDTrajectory` hoomd reader:

    >>> with gsd.pygsd.GSDFile('test.gsd', 'rb') as f:
    ...     t = gsd.hoomd.HOOMDTrajectory(f)
    ...     pos = t[0].particles.position

class gsd.pygsd.GSDFile(file)

  GSD file access interface.

  Implemented in pure Python and accepts any Python file-like object.

  Parameters

    file – File-like object to read.

  GSDFile implements an object oriented class interface to the GSD file layer. Use it to open an existing file in a read-only mode. For read-write access to files, use the full featured C implementation in `gsd.fl`. Otherwise, the two implementations can be used interchangeably.

  Examples

  Open a file in read-only mode:

      f = GSDFile(open('file.gsd', mode='rb'))
      if f.chunk_exists(frame=0, name='chunk'):
          data = f.read_chunk(frame=0, name='chunk')

  Access file metadata:

      f = GSDFile(open('file.gsd', mode='rb'))
      print(f.name, f.mode, f.gsd_version)
      print(f.application, f.schema, f.schema_version)
      print(f.nframes)

  Use as a context manager:

      with GSDFile(open('file.gsd', mode='rb')) as f:
          data = f.read_chunk(frame=0, name='chunk')

  __enter__()

    Implement the context manager protocol.

  __exit__(exc_type, exc_value, traceback)

    Implement the context manager protocol.

  __getstate__()

    Implement the pickle protocol.

  __setstate__(state)

    Implement the pickle protocol.

  property application

    Name of the generating application.

    Type

      str

  chunk_exists(frame, name)

    Test if a chunk exists.

    Parameters

      - frame (int) – Index of the frame to check

      - name (str) – Name of the chunk

    Returns

      True if the chunk exists in the file. False if it does not.

    Return type

      bool

    Example

    Handle non-existent chunks:

        with GSDFile(open('file.gsd', mode='rb')) as f:
            if f.chunk_exists(frame=0, name='chunk'):
                return f.read_chunk(frame=0, name='chunk')
            else:
                return None

  close()

    Close the file.

    Once closed, any other operation on the file object will result in a `ValueError`. `close()` may be called more than once. The file is automatically closed when garbage collected or when the context manager exits.

  end_frame()

    Not implemented.

  property file

    File-like object opened.

  find_matching_chunk_names(match)

    Find chunk names in the file that start with the string match.

    Parameters

      match (str) – Start of the chunk name to match

    Returns

      Matching chunk names

    Return type

      list[str]

  property gsd_version

    GSD file layer version number.

    The tuple is in the order (major, minor).

    Type

      tuple[int, int]

  property mode

    Mode of the open file.

    Type

      str

  property name

    file.name.

    Type

      (str)

  property nframes

    Number of frames in the file.

    Type

      int

  read_chunk(frame, name)

    Read a data chunk from the file and return it as a numpy array.

    Parameters

      - frame (int) – Index of the frame to read

      - name (str) – Name of the chunk

    Returns

      Data read from file.

    Return type

      `numpy.ndarray`

    Examples

    Read a 1D array:

        with GSDFile(name=filename, mode='rb') as f:
            data = f.read_chunk(frame=0, name='chunk1d')
            # data.shape == [N]

    Read a 2D array:

        with GSDFile(name=filename, mode='rb') as f:
            data = f.read_chunk(frame=0, name='chunk2d')
            # data.shape == [N,M]

    Read multiple frames:

        with GSDFile(name=filename, mode='rb') as f:
            data0 = f.read_chunk(frame=0, name='chunk')
            data1 = f.read_chunk(frame=1, name='chunk')
            data2 = f.read_chunk(frame=2, name='chunk')
            data3 = f.read_chunk(frame=3, name='chunk')

    Tip

    Each call invokes a disk read and allocation of a new numpy array for storage. To avoid overhead, don’t call `read_chunk()` on the same chunk repeatedly. Cache the arrays instead.

  property schema

    Name of the data schema.

    Type

      str

  property schema_version

    Schema version number.

    The tuple is in the order (major, minor).

    Type

      tuple[int, int]

  truncate()

    Not implemented.

  write_chunk(name, data)

    Not implemented.