The API common to all models

The Mosaic Python API

This module provides abstract base classes that define the Mosaic Python API and implement validation code. They also provide a few convenience functions implemented in terms of the raw API.

Concrete implementations subclass the abstract base classes and implement all the abstract properties.

class mosaic.api.MosaicAtom

Atom inside a MosaicUniverse

See the data model documentation for atoms.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

label

An ASCII string not containing dots and identifying the atom uniquely inside its parent fragment. See the data model documentation.

name

An ASCII string describing the type of the atom. For ‘real’ atoms in the chemical sense, this must be the chemical element symbol. See the data model documentation.

number_of_atoms

The number of atoms associated with the atom (always 1)

number_of_sites

The number of sites associated with the atom. See the data model documentation.

type

A string identifying the type of the atom. See the data model documentation.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicConfiguration

Configuration

See the data model documentation for configurations.

cell_parameters

An array containing the parameters defining the shape and size of the cell. See the data model documentation.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

lattice_vectors()

Returns:a sequence of arrays of shape (3,) containing the lattice vectors for the simulation cell. Return type:tuple

positions

An array containing an (x, y, z) position for each site. See the data model documentation.

universe

The MosaicUniverse for which the property is defined.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicDataItem

Base class for top-level data items

Instances of subclasses of MosaicDataItem can be stored in files.

class mosaic.api.MosaicFragment

Fragment inside a MosaicUniverse

See the data model documentation for fragments.

Fragments implement the Mapping interface. Valid keys are strings identifying atoms or sub-fragments, using dots to separate subsequent labels. For polymer fragments, integer keys are valid as well to refer to a specific sub-fragment in the chain.

atom_to_site_index_mapping()

Returns:an array whose element [s] is the site index corresponding to the first site of the atom with atom index s. Return type:numpy.ndarray

atoms

Sequence of atoms, may be empty. See the data model documentation.

bonds

Sequence of bonds, may be empty. Each bond is repreented by a tuple (atom_ref_1, atom_ref_2, bond_order). See the data model documentation and the bond reference documentation.

fragments

Sequence of sub-fragments, may be empty. See the data model documentation.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

is_polymer

True if the fragment is a polymer. See the data model documentation.

label

An ASCII string not containing dots and identifying the fragment uniquely inside its parent fragment. See the data model documentation.

number_of_atoms

The number of atoms in the fragment (including the atoms in sub-fragments).

number_of_bonds

The number of bonds associated with the fragment, including the bonds inside sub-fragments.

number_of_sites

The number of sites associated with the fragment, i.e. the sum of the numbers of sites of all the fragment’s atoms, including those of sub-fragments.

polymer_type

String identifying the polymer type if is_polymer is true. See the data model documentation.

recursive_atom_iterator()

An iterator over the atoms in the fragment, including the atoms in sub-fragments.

recursive_atom_path_iterator()

An iterator over the atom paths in the fragment, including the atoms in sub-fragments.

recursive_bond_iterator()

An iterator over the bonds in the fragment, including the bonds in sub-fragments.

site_to_atom_index_mapping()

Returns:an array whose element [s] is the atom index corresponding to site index s. Return type:numpy.ndarray

species

An ASCII string describing the species of the fragment (e.g. what kind of molecule or moiety it represents). See the data model documentation.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicLabel

Label

See the data model documentation for labels.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

name

An ASCII string describing the label. See the data model documentation.

strings

A sequence of strings representing a label for each atom or site. See the data model documentation.

type

A string identifying the type of the label. See the data model documentation.

universe

The MosaicUniverse for which the property is defined.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicProperty

Property

See the data model documentation for properties.

data

An array containing the property’s values. See the data model documentation.

element_shape

The shape of the sub-array containing the propery for one atom or site.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

name

An ASCII string describing the property. See the data model documentation.

type

A string identifying the type of the property. See the data model documentation.

units

A string identifying the physical units of the property. See the data model documentation.

universe

The MosaicUniverse for which the property is defined.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicSelection

Selection

See the data model documentation for selections.

indices

An array containing the indices of the contained atoms or sites. See the data model documentation.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

number_of_atoms

The number of atoms in the selection.

number_of_sites

The number of sites in the selection.

type

A string identifying the type of the selection. See the data model documentation.

universe

The MosaicUniverse for which the selection is defined.

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

class mosaic.api.MosaicUniverse

Universe

See the data model documentation for universes.

atom_to_site_index_mapping()

Returns:an array whose element [s] is the site index corresponding to the first site of the atom with atom index s. Return type:numpy.ndarray

atom_to_template_index_mapping()

Returns:an array whose element [s] is the template atom index corresponding to atom index s. Return type:numpy.ndarray

bond_index_array()

Returns an integer array of shape (N, 2), where N is the total number of bonds in the universe. The entries [i, 0] and [i, 1] refer to the two atoms that are connected by bond i. The entry [i, 0] is smaller than the entry [i, 1].

Returns:the bond index array Return type:numpy.ndarray

cell_parameter_array_shape

The shape of a valid cell_parameters array in a MosaicConfiguration.

cell_shape

A string identifying the cell shape. See the data model documentation.

convention

An ASCII string naming the conventions used inside the definitions of fragements and atoms. See the data model documentation.

is_equivalent(other)

Check for equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Returns:True if other is equivalent to self Return type:bool

molecules

A sequence of molecule specifications. Each element is a two-element tuple, whose first element is a MosaicFragment and whose second element is an integer specifying the number of copies of the molecule. See the data model documentation.

number_of_atoms

The number of atoms in the universe.

number_of_bonds

The number of bonds in the universe.

number_of_molecules

The number of molecules in the universe.

number_of_sites

The number of sites in the universe.

number_of_template_atoms

The number of template atoms in the universe, i.e. the total number of atoms in all fragment definitions. It is equal to the number of atoms iff all molecule repetition counts are 1.

number_of_template_sites

The number of template sites in the universe, i.e. the total number of sites in all fragment definitions. It is equal to the number of sites iff all molecule repetition counts are 1.

recursive_atom_iterator()

An iterator over the atoms in the universe.

site_to_atom_index_mapping()

Returns:an array whose element [s] is the atom index corresponding to site index s. Return type:numpy.ndarray

site_to_template_index_mapping()

Returns:an array whose element [s] is the template site index corresponding to site index s. Return type:numpy.ndarray

symmetry_transformations

A sequence of symmetry transformations, possibly empty. Each symmetry tranformation is defined by a two-element tuple, whose first item is a rotation matrix and whose second item is a translation vector. See the data model documentation.

template_site_to_template_atom_index_mapping()

Returns:an array whose element [s] is the template atom index corresponding to template site index s. Return type:numpy.ndarray

validate()

Verify that the object satisfies the constraints of the Mosaic data model.

Raises ValueError:  if the object is not valid Mosaic data

validate_equivalence(other)

Verify the equivalence of Python objects representing Mosaic data. The two objects can belong to different models; only the common API functionality is used for the test.

Parameters:other – an arbitrary Python object Raises ValueError:  if other is not equivalent to self

The immutable model

Immutable model

This experimental module implements the Mosaic API in terms of immutable data structures as implemented in ImmutablePy. The use of immutable data structures avoids many nasty bugs, such as modifying a universe after creating a configuration object that refer to it, invalidating the configuration. However, the immutable data structures from ImmutablePy are not very efficient at the moment.

The mutable model

Mutable model

This is the main in-memory representation of Mosaic data. Like most Python code, it uses mutable data structures, which are efficient but can become inconsistent if not used carefully.

The array model

Array model

An array model stores all data in NumPy arrays, in particular the tree structure defining the fragments in universes. The array model is an in-memory version of the HDF5 storage layout. It is used for HDF5 I/O, but can also be of use for interfacing with C or Fortran code.

HDF5 I/O

HDF5 I/O

Any model implementing the Mosaic API can be written to a HDF5 file, but will be implicitly converted to a mosaic.array_model representation. Data items read from a HDF5 file are always represented by an mosaic.array_model.

The HDF5 storage layout is designed for clarity rather than simplicity, the files should be as self-documenting as possible.

A common pattern for generating an HDF5 file is:

with HDF5Store('molecule.h5', 'w') as writer:
   writer.store("universe", universe)
   writer.store("configuration1", configuration1)
   writer.store("configuration2", configuration2)

A common pattern for reading from an HDF5 file is:

items = {}
for id, data in HDF5Store('molecule.h5'):
   items[id] = data

class mosaic.hdf5.HDF5Store(hdf5_group_or_filename, file_mode=None)

I/O handler for HDF5 files

This class handles the translation of references between Mosaic data items in memory and HDF5 object references in a file. When writing data, references are allowed only to data items that have been written earlier using the same HDF5Store instance.

An HDF5Store can be used like a file, in which case it must be closed after the last store or retrieve operation, or as a context manager in a with-statement. For reading, it also behaves like an iterator yielding (name, data_item) pairs.

retrieve(path_or_node)

Parameters:path_or_node (str or h5py.Node) – a HDF5 path, relative to the group used by the HDF5Store, or an HDF5 node Returns:a Mosaic data item Return type:mosaic.api.MosaicDataItem

store(path, data)

Parameters:

• path (str) – a HDF5 path, relative to the group used by the HDF5Store
• data (mosaic.api.MosaicDataItem) – a Mosaic data item

XML I/O

XML I/O

The XML representation of Mosaic data consists of a single element <mosaic version="x.y">...</mosaic> that can contain any number of Mosaic data items, each of which is identified by a unique id. The classes XMLWriter and XMLReader handle the translation between Mosaic data items in memory that can reference each other and XML elements that reference each other by id.

A common pattern for generating an XML file is:

with XMLWriter('molecule.xml') as writer:
   writer.store("universe", universe)
   writer.store("configuration1", configuration1)
   writer.store("configuration2", configuration2)

A common pattern for reading from an XML file is:

items = {}
for id, data in XMLReader('molecule.xml'):
   items[id] = data

class mosaic.xml_io.XMLReader(xml_file)

Input handler for XML files

This class handles the translation of references by id in an XML file to in-memory references between data items.

An XMLReader is used as an iterator over (id, data_item) pairs.

The current implementation does not do any validation, it assumes the XML input to be correct.

class mosaic.xml_io.XMLWriter(xml_file)

Output handler for XML files

This class handles the translation of references between Mosaic data items in memory to XML references by id. References are allowed only to data items that have been written earlier using the same XMLWriter instance.

An XMLWriter can be used like a file, in which case it must be closed after the last store operation, or as a context manager in a with-statement.

store(xml_id, data)

Parameters:

• xml_id (str) – the id of the XML element representing the data item
• data (mosaic.api.MosaicDataItem) – a Mosaic data item