index | modules | gitlab | page source

# ULM files

Simple and efficient pythonic file-format

Stores ndarrays as binary data and Python’s built-in datatypes (bool, int, float, complex, str, dict, list, tuple, None) as json.

`ase.io.ulm.``open`(filename, mode='r', index=None, tag=None)

  Open ulm-file.

  filename: str
    Filename.
  mode: str
    Mode. Must be ‘r’ for reading, ‘w’ for writing to a new file (overwriting an existing one) or ‘a’ for appending to an existing file.
  index: int
    Index of item to read. Defaults to 0.
  tag: str
    Magic ID string.

  Returns a `Reader` or a `Writer` object. May raise `InvalidULMFileError`.

exception `ase.io.ulm.``InvalidULMFileError`

## File layout

When there is only a single item:

    0: "- of Ulm" (magic prefix, ascii)
    8: "                " (tag, ascii)
    24: version (int64)
    32: nitems (int64)
    40: 48 (position of offsets, int64)
    48: p0 (offset to json data, int64)
    56: array1, array2, ... (8-byte aligned ndarrays)
    p0: n (length of json data, int64)
    p0+8: json data
    p0+8+n: EOF

Examples

Writing:

    >>> import numpy as np
    >>> import ase.io.ulm as ulm
    >>> with ulm.open('x.ulm', 'w') as w:
    ...     w.write(a=np.ones(7), b=42, c='abc')
    ...     w.write(d=3.14)

Reading:

    >>> r = ulm.open('x.ulm')
    >>> print(r.c)
    abc
    >>> r.close()

To see what’s inside ‘x.ulm’ do this:

    $ ase ulm x.ulm
    x.ulm  (tag: "", 1 item)
    item #0:
    {
        a: <ndarray shape=(7,) dtype=float64>,
        b: 42,
        c: abc,
        d: 3.14}

class `ase.io.ulm.``Writer`(fd, mode='w', tag='', data=None)

  Create writer object.

  fd: str
    Filename.
  mode: str
    Mode. Must be ‘w’ for writing to a new file (overwriting an existing one) and ‘a’ for appending to an existing file.
  tag: str
    Magic ID string.
  `add_array`(name, shape, dtype=<class 'float'>)

    Add ndarray object.

    Set name, shape and dtype for array and fill in the data in chunks later with the fill() method.

  `child`(name)

    Create child-writer object.

  `close`()

    Close file.

  `fill`(a)

    Fill in ndarray chunks for array currently beeing written.

  `sync`()

    Write data dictionary.

    Write bool, int, float, complex and str data, shapes and dtypes for ndarrays.

  `write`(*args, **kwargs)

    Write data.

    Examples:

        writer.write('n', 7)
        writer.write(n=7)
        writer.write(n=7, s='abc', a=np.zeros(3), abc=obj)

    If obj is not one of the supported data types (bool, int, float, complex, tupl, list, dict, None or ndarray) then it must have a obj.write(childwriter) method.

class `ase.io.ulm.``Reader`(fd, index=0, data=None, _little_endian=None)

  Create reader.

  `asdict`()

    Read everything now and convert to dict.

  `get`(attr, value=None)

    Get attr or value if no such attr.

  `get_tag`()

    Return special tag string.

  `keys`()

    Return list of keys.

## More examples

In the following we append to the ulm-file from above and demonstrae how to write a big array in chunks:

    >>> w = ulm.open('x.ulm', 'a')
    >>> w.add_array('bigarray', (10, 1000), float)
    >>> for i in range(10):
    ...     w.fill(np.ones(1000))
    ...
    >>> w.close()

Now read first and second items:

    >>> with ulm.open('x.ulm') as r:
    ...     print(r.keys())
    dict_keys(['a', 'b', 'c', 'd'])
    >>> with ulm.open('x.ulm', index=1) as r:
    ...     print(r.keys())
    dict_keys(['bigarray'])

To get all the data, it is possible to iterate over the items in the file.

    >>> for i, r in enumerate(ulm.Reader('x.ulm')):
    ...     for k in r.keys():
    ...         print(i, k)
    0 a
    0 b
    0 c
    0 d
    1 bigarray
    >>> r.close()

The different parts (items) of the file are numbered by the index argument:

    >>> r = ulm.Reader('x.ulm')
    >>> r[1].bigarray.shape
    (10, 1000)
    >>> r.close()

## Versions

1. Initial version.
2. Added support for big endian machines. Json data may now have _little_endian=False item.
3. Changed magic string from “AFFormat” to “- of Ulm”.

Documentation v: 3.19.0

Versions
  3.20.0b1 (development)
  3.19.0 (latest stable)