HDF5 IO

The CUDS to HDF5 file adapters.

Classes

H5CUDS(handle) Access to CUDS-hdf5 formatted files.
DataContainerTable(root[, name, record]) A proxy class to an HDF5 group node with serialised DataContainers.
IndexedDataContainerTable(root[, name, ...]) A proxy class to an HDF5 group node with serialised DataContainers.
H5Particles(group) An HDF5 backed particle container.
H5Lattice(group) H5Lattice object to use H5CUDS lattices.
H5Mesh(group, meshFile) H5Mesh.
H5CUDSItems(root, record[, name]) A proxy class to an HDF5 group node with serialised CUDS items.

Table descriptions

Implementation

class simphony.io.h5_cuds.H5CUDS(handle)[source]

Bases: object

Access to CUDS-hdf5 formatted files.

add_dataset(container)[source]

Add a CUDS container

Parameters:

container ({ABCMesh, ABCParticles, ABCLattice}) – The CUDS container to be added.

Raises:
  • TypeError: – If the container type is not supported by the engine.
  • ValueError: – If there is already a dataset with the given name.
close()[source]

Closes a file

get_dataset(name)[source]

Get the dataset

Parameters:name (str) – name of CUDS container to be retrieved.
Returns:A proxy of the dataset named name that is stored internally in the File.
Return type:container
Raises:ValueError: – If there is no dataset with the given name
get_dataset_names()[source]

Returns the names of the all the datasets in the engine workspace.

iter_datasets(names=None)[source]

Returns an iterator over a subset or all of the containers.

Parameters:names (sequence of str, optional) – names of specific containers to be iterated over. If names is not given, then all containers will be iterated over.
classmethod open(filename, mode='a', title='')[source]

Returns a SimPhony file and returns an opened CudsFile

Parameters:
  • filename (str) – Name of file to be opened.
  • mode (str) –

    The mode to open the file:

    • w – Write; a new file is created (an existing file with the same name would be deleted).
    • a – Append; an existing file is opened for reading and writing, and if the file does not exist it is created.
    • r – ReadOnly; This is a very restrictive mode that will through errors at any attempt to modify the data.
  • title (str) – Title attribute of root node (only applies to a file which is being created)
  • Raises (Raises) –
  • ------
  • ValueError – If the file has an incompatible version
remove_dataset(name)[source]

Remove a dataset from the engine

Parameters:name (str) – name of CUDS container to be deleted
Raises:ValueError: – If there is no dataset with the given name
valid()[source]

Checks if file is valid (i.e. open)

class simphony.io.h5_particles.H5BondItems(root, name='bonds')[source]

Bases: simphony.io.h5_cuds_items.H5CUDSItems

A proxy class to an HDF5 group node with serialised Bonds

The class implements the Mutable-Mapping api where each Bond instance is mapped to uid.

class simphony.io.h5_particles.H5ParticleItems(root, name='particles')[source]

Bases: simphony.io.h5_cuds_items.H5CUDSItems

A proxy class to an HDF5 group node with serialised Particles

The class implements the Mutable-Mapping api where each Particle instance is mapped to uid.

class simphony.io.h5_particles.H5Particles(group)[source]

Bases: simphony.cuds.abc_particles.ABCParticles

An HDF5 backed particle container.

add_bonds(iterable)[source]

Add a set of bonds.

If the bonds have an uid then they are used. If any of the bond’s uid is None then a uid is generated for the bond.

Returns:uid – uid of bond
Return type:uuid.UUID
Raises:ValueError : – if an uid is given which already exists.
add_particles(iterable)[source]

Add a set of particles.

If the particles have a uid set then they are used. If any of the particle’s uid is None then a new uid is generated for the particle.

Returns:uid – uid of particle.
Return type:uuid.UUID
Raises:ValueError : – Any particle uid already exists in the container.
count_of(item_type)[source]

Return the count of item_type in the container.

Parameters:item_type (CUDSItem) – The CUDSItem enum of the type of the items to return the count of.
Returns:count – The number of items of item_type in the container.
Return type:int
Raises:ValueError : – If the type of the item is not supported in the current container.
data
get_bond(uid)[source]
get_particle(uid)[source]
has_bond(uid)[source]

Checks if a bond with uid “uid” exists in the container.

has_particle(uid)[source]

Checks if a particle with uid “uid” exists in the container.

iter_bonds(ids=None)[source]

Get iterator over particles

iter_particles(ids=None)[source]

Get iterator over particles

name

The name of the container

remove_bonds(uids)[source]
remove_particles(uids)[source]
update_bonds(iterable)[source]
update_particles(iterable)[source]
class simphony.io.h5_lattice.H5Lattice(group)[source]

Bases: simphony.cuds.abc_lattice.ABCLattice

H5Lattice object to use H5CUDS lattices.

count_of(item_type)[source]

Return the count of item_type in the container.

Parameters:item_type (CUDSItem) – The CUDSItem enum of the type of the items to return the count of.
Returns:count – The number of items of item_type in the container.
Return type:int
Raises:ValueError : – If the type of the item is not supported in the current container.
classmethod create_new(group, primitive_cell, size, origin, record=None)[source]

Create a new lattice in H5CUDS file.

Parameters:
  • group (HDF5 group in PyTables file) – reference to a group (folder) in PyTables file where the tables for lattice and data will be located
  • primitive_cell (PrimitiveCell) – primitive cell specifying the 3D Bravais lattice
  • size (int[3]) – number of lattice nodes (in the direction of each axis).
  • origin (float[3]) – origin of lattice
  • record (tables.IsDescription) – A class that describes column types for PyTables table.
data
get_node(index)[source]

Get a copy of the node corresponding to the given index.

Parameters:index (int[3]) – node index coordinate
Returns:
Return type:A reference to a LatticeNode object
iter_nodes(indices=None)[source]

Get an iterator over the LatticeNodes described by the ids.

Parameters:indices (iterable set of int[3], optional) – node index coordinates
Returns:
Return type:A generator for LatticeNode objects
name
origin
size
update_nodes(nodes)[source]

Updates H5Lattice data for a LatticeNode

Parameters:nodes (iterable of LatticeNode objects) – reference to LatticeNode objects

Mesh File

This module contains the implentation to store, acces, and modify a file storing mesh data

class simphony.io.h5_mesh.H5Mesh(group, meshFile)[source]

Bases: simphony.cuds.abc_mesh.ABCMesh

H5Mesh.

Interface of the mesh file driver. Stores general mesh information Points and Elements such as Edges, Faces and Cells and provide the methods to interact with them. The methods are divided in four diferent blocks:

  1. methods to get the related item with the provided uid;
  2. methods to add a new item or replace;
  3. generator methods that return iterators over all or some of the mesh items and;
  4. inspection methods to identify if there are any edges, faces or cells described in the mesh.
data

Data – Data relative to the mesh

name

String – Name of the mesh

See also

get_point, get_edge, get_face, get_cell, add_point, add_edge, add_face, add_cell, update_point, update_edge, update_face, update_cell, iter_points, iter_edges, iter_faces, iter_cells, has_edges, has_faces, has_cells, _create_points_table, _create_edges_table, _create_faces_table, _create_cells_table

add_cells(cells)[source]

Adds a new set of cells to the mesh container.

Parameters:cells (iterable of Cell) – Cells to be added to the mesh container
Raises:KeyError – If other cell with the same uid was already in the mesh
add_edges(edges)[source]

Adds a new set of edges to the mesh container.

Parameters:edges (iterable of Edge) – Edges to be added to the mesh container
Raises:KeyError – If other edge with the same uid was already in the mesh
add_faces(faces)[source]

Adds a new set of faces to the mesh container.

Parameters:faces (iterable of Face) – Faces to be added to the mesh container
Raises:KeyError – If other face with the same uid was already in the mesh
add_points(points)[source]

Adds a new set of points to the mesh container.

Parameters:points (iterable of Point) – Points to be added to the mesh container
Raises:KeyError – If other point with the same uid was already in the mesh
count_of(item_type)[source]

Return the count of item_type in the container.

Parameters:item_type (CUDSItem) – The CUDSItem enum of the type of the items to return the count of.
Returns:count – The number of items of item_type in the container.
Return type:int
Raises:ValueError : – If the type of the item is not supported in the current container.
data
get_cell(uid)[source]

Returns an cell with a given uid.

Returns the cell stored in the mesh identified by uid . If such cell do not exists a exception is raised.

Parameters:uid (UUID) – uid of the desired cell.
Returns:Cell identified by uid
Return type:Cell
Raises:Exception – If the cell identified by uid was not found
get_edge(uid)[source]

Returns an edge with a given uid.

Returns the edge stored in the mesh identified by uid. If such edge do not exists a exception is raised.

Parameters:uid (UUID) – uid of the desired edge.
Returns:Edge identified by uid
Return type:Edge
Raises:Exception – If the edge identified by uid was not found
get_face(uid)[source]

Returns an face with a given uid.

Returns the face stored in the mesh identified by uid. If such face do not exists a exception is raised.

Parameters:uid (UUID) – uid of the desired face.
Returns:Face identified by uid
Return type:Face
Raises:Exception – If the face identified by uid was not found
get_point(uid)[source]

Returns a point with a given uid.

Returns the point stored in the mesh identified by uid. If such point do not exists an exception is raised.

Parameters:uid (UUID) – uid of the desired point.
Returns:Mesh point identified by uid
Return type:Point
Raises:Exception – If the point identified by uid was not found
has_cells()[source]

Check if the mesh container has cells

Returns:True of there are cells inside the mesh, False otherwise
Return type:bool
has_edges()[source]

Check if the mesh container has edges

Returns:True of there are edges inside the mesh, False otherwise
Return type:bool
has_faces()[source]

Check if the mesh container has faces

Returns:True of there are faces inside the mesh, False otherwise
Return type:bool
iter_cells(uids=None)[source]

Returns an iterator over cells.

Parameters:uids (iterable of uuid.UUID or None) – When the uids are provided, then the cells are returned in the same order the uids are returned by the iterable. If uids is None, then all cells are returned by the interable and there is no restriction on the order that they are returned.
Returns:Iterator over the selected cells
Return type:iter
iter_edges(uids=None)[source]

Returns an iterator over edges.

Parameters:uids (iterable of uuid.UUID or None) – When the uids are provided, then the edges are returned in the same order the uids are returned by the iterable. If uids is None, then all edges are returned by the interable and there is no restriction on the order that they are returned.
Returns:Iterator over the selected edges
Return type:iter
iter_faces(uids=None)[source]

Returns an iterator over faces.

Parameters:uids (iterable of uuid.UUID or None) – When the uids are provided, then the faces are returned in the same order the uids are returned by the iterable. If uids is None, then all faces are returned by the interable and there is no restriction on the order that they are returned.
Returns:Iterator over the faces
Return type:iter
iter_points(uids=None)[source]

Returns an iterator over points.

Parameters:uids (iterable of uuid.UUID or None) – When the uids are provided, then the points are returned in the same order the uids are returned by the iterable. If uids is None, then all points are returned by the interable and there is no restriction on the order that they are returned.
Returns:Iterator over the points
Return type:iter
name
update_cells(cells)[source]

Updates the information of every cell in cells.

Gets the mesh cells identified by the same uids as the ones provided in cells and updates their information.

Parameters:cellss (iterable of Cell) – Cells to be updated.
Raises:KeyError – If any cell was not found in the mesh container.
update_edges(edges)[source]

Updates the information of an edge.

Gets the mesh edges identified by the same uids as the ones provided edges and updates their information.

Parameters:edges (iterable of Edge) – Edges to be updated.
Raises:KeyError – If any edge was not found in the mesh container.
update_faces(faces)[source]

Updates the information of a face.

Gets the mesh faces identified by the same uids as the ones provided in faces and updates their information.

Parameters:faces (iterable of Face) – Faces to be updated.
Raises:KeyError – If any face was not found in the mesh container.
update_points(points)[source]

Updates the information of a point.

Gets the mesh points identified by the same uids as the ones provided points and updates their information.

Parameters:points (iterable of Point) – Points to be updated
Raises:KeyError – If any point was not found in the mesh container.
class simphony.io.h5_cuds_items.H5CUDSItems(root, record, name='items')[source]

Bases: _abcoll.MutableMapping

A proxy class to an HDF5 group node with serialised CUDS items.

The class implements the Mutable-Mapping api where each item instance is mapped to uuid.

add_safe(item)[source]

Add item while checking for a unique uid.

Note

The item is expected to already have a uid set.

add_unsafe(item)[source]

Add item without checking for a unique uid.

Note

The item is expected to already have a uid set.

itersequence(sequence)[source]

Iterate over a sequence of row ids.

update_existing(item)[source]

Update an item if it already exists.

valid

A PyTables table is opened/created and the object is valid.

class simphony.io.data_container_table.DataContainerTable(root, name='data_containers', record=None)[source]

Bases: _abcoll.MutableMapping

A proxy class to an HDF5 group node with serialised DataContainers.

The class implements the Mutable-Mapping api where each DataContainer instance is mapped to uuid.

append(data)[source]

Append the data to the end of the table.

Parameters:data (DataContainer) – The DataContainer instance to save.
Returns:uid – The index of the saved row.
Return type:uuid.UUID
itersequence(sequence)[source]

Iterate over a sequence of row ids.

valid

A PyTables table is opened/created and the object is valid.

class simphony.io.indexed_data_container_table.IndexedDataContainerTable(root, name='data_containers', record=None, expected_number=None)[source]

Bases: _abcoll.Sequence

A proxy class to an HDF5 group node with serialised DataContainers.

The class implements the Sequence api where each DataContainer instance is mapped to the row. In addition the class implements update (i.e. __setitem__) and append.

append(data)[source]

Append the data to the end of the table.

Parameters:data (DataContainer) – The DataContainer instance to save.
Returns:index – The index of the saved row.
Return type:int
valid