Cuds module

A module containing tvtk dataset wrappers to simphony CUDS containers.

Classes

VTKParticles(name[, data, data_set, mappings])	Constructor.
VTKMesh(name[, data, data_set, mappings])	Constructor.
VTKLattice(name, primitive_cell, data_set[, ...])	Constructor.

Description

class simphony_mayavi.cuds.vtk_particles.VTKParticles(name, data=None, data_set=None, mappings=None)

Bases: simphony.cuds.abc_particles.ABCParticles

Constructor.

Parameters:

• name (string) – The name of the container.
• data (DataContainer) – The data attribute to attach to the container. Default is None.
• data_set (tvtk.DataSet) – The dataset to wrap in the CUDS api. Default is None which will create a tvtk.PolyData
• mappings (dict) – A dictionary of mappings for the particle2index, index2particle, bond2index and bond2element. Should be provided if the particles and bonds described in data_set are already assigned uids. Default is None and will result in the uid <-> index mappings being generated at construction.

add_bonds(iterable)

Adds a set of bonds to the container.

Also like with particles, if any bond has a defined uid, it won’t add the bond if a bond with the same uid already exists, and if the bond has no uid the particle container will generate an uid. If the user wants to replace an existing bond in the container there is an ‘update_bonds’ method for that purpose.

iterable : iterable of Bond objects

the new bond that will be included in the container.

Returns:

uuid : list of uuid.UUID

The uuids of the added bonds.

Raises:ValueError – when there is a bond with an uuid that already exists in the container.

Examples

Add a set of bonds to a Particles container.

>>> bonds_list = [Bond(), Bond()]
>>> particles = Particles(name="foo")
>>> particles.add_bonds(bonds_list)

add_particles(iterable)

Adds a set of particles from the provided iterable to the container.

If any particle have no uids, the container will generate a new uids for it. If the particle has already an uids, it won’t add the particle if a particle with the same uid already exists. If the user wants to replace an existing particle in the container there is an ‘update_particles’ method for that purpose.

iterable : iterable of Particle objects

the new set of particles that will be included in the container.

Returns:

uids : list of uuid.UUID

The uids of the added particles.

Raises:ValueError – when there is a particle with an uids that already exists in the container.

Examples

Add a set of particles to a Particles container.

>>> particle_list = [Particle(), Particle()]
>>> particles = Particles(name="foo")
>>> uids = particles.add_particles(particle_list)

bond2index = None

The mapping from uid to bond index

count_of(item_type)

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 (int) – The number of items of item_type in the container. Raises:ValueError – If the type of the item is not supported in the current container.

data

Easy access to the vtk CellData structure

data_set = None

The vtk.PolyData dataset

classmethod from_dataset(name, data_set, data=None)

Wrap a plain dataset into a new VTKParticles.

The constructor makes some sanity checks to make sure that the tvtk.DataSet is compatible and all the information can be properly used.

Parameters:

• name (str) – The name of the container.
• data_set (tvtk.DataSet) – The dataset to wrap in the CUDS api. Default is None which will create a tvtk.PolyData
• data (DataContainer) – The data attribute to attach to the container. Default is None.

Raises:

TypeError – When the sanity checks fail.

classmethod from_particles(particles, particle_keys=None, bond_keys=None)

Create a new VTKParticles copy from a CUDS particles instance.

Parameters:

• particles (ABCParticles) – CUDS Particles dataset
• particle_keys (list) – A list of point CUBA keys that we want to copy, and only those. If None, all available and compatible keys will be copied.
• bond_keys (list) – A list of cell CUBA keys that we want to copy, and only those. If None, all available and compatible keys will be copied.

get_bond(uid)

Returns a copy of the bond with the ‘bond_id’ id.

Parameters:uid (uuid.UUID) – the uid of the bond Raises:KeyError – when the bond is not in the container. Returns:bond (Bond) – A copy of the internally stored bond info.

get_particle(uid)

Returns a copy of the particle with the ‘particle_id’ id.

Parameters:uid (uuid.UUID) – the uid of the particle Raises:KeyError – when the particle is not in the container. Returns:particle (Particle) – A copy of the internally stored particle info.

has_bond(uid)

Checks if a bond with the given uid already exists in the container.

has_particle(uid)

Checks if a particle with the given uid already exists in the container.

index2bond = None

The reverse mapping from index to bond uid

index2particle = None

The reverse mapping from index to point uid

is_connected(bond)

Test if the connectivity described in bonds is valid i.e. the particles are part of the container

Parameters:bond (Bond) – Returns:valid (bool)

iter_bonds(uids=None)

Generator method for iterating over the bonds of the container.

It can receive any kind of sequence of bond ids to iterate over those concrete bond. If nothing is passed as parameter, it will iterate over all the bonds.

uids : iterable of uuid.UUID, optional

sequence containing the id’s of the bond that will be iterated. When the uids are provided, then the bonds are returned in the same order the uids are returned by the iterable. If uids is None, then all bonds are returned by the iterable and there is no restriction on the order that they are returned.

Yields:bond (Bond) – The next Bond item Raises:KeyError – if any of the ids passed as parameters are not in the container.

Examples

It can be used with a sequence as parameter or without it:

>>> particles = Particles(name="foo")
>>> ...
>>> for bond in particles.iter_bonds([id1, id2, id3]):
        ...  #do stuff

>>> for bond in particles.iter_bond():
        ...  #do stuff; it will iterate over all the bond

iter_particles(uids=None)

Generator method for iterating over the particles of the container.

It can receive any kind of sequence of particle uids to iterate over those concrete particles. If nothing is passed as parameter, it will iterate over all the particles.

uids : iterable of uuid.UUID, optional

sequence containing the uids of the particles that will be iterated. When the uids are provided, then the particles are returned in the same order the uids are returned by the iterable. If uids is None, then all particles are returned by the iterable and there is no restriction on the order that they are returned.

Yields:particle (Particle) – The Particle item. Raises:KeyError – if any of the ids passed as parameters are not in the container.

Examples

It can be used with a sequence as parameter or without it:

>>> particles = Particles(name="foo")
>>> ...
>>> for particle in particles.iter_particles([uid1, uid2, uid3]):
    ...  #do stuff
>>> for particle in particles.iter_particles():
    ...  #do stuff

particle2index = None

The mapping from uid to point index

remove_bonds(uids)

Remove the bonds with the provided uids.

The uids passed as parameter should exists in the container. If any uid doesn’t exist, an exception will be raised.

uids : iterable of uuid.UUID

the uids of the bond to be removed.

Raises:KeyError – If any bond doesn’t exist.

Examples

Having a set of uids of existing bonds, pass it to the method.

>>> particles = Particles(name="foo")
>>> ...
>>> particles.remove_bonds([uid1, uid2])

remove_particles(uids)

Remove the particles with the provided uids from the container.

The uids inside the iterable should exists in the container. Otherwise an exception will be raised.

uids : iterable of uuid.UUID

the uids of the particles to be removed.

Raises:KeyError – If any particle doesn’t exist.

Examples

Having a set of uids of existing particles, pass it to the method.

>>> particles = Particles(name="foo")
>>> ...
>>> particles.remove_particles([uid1, uid2])

supported_cuba = None

The currently supported and stored CUBA keywords.

update_bonds(iterable)

Updates a set of bonds from the provided iterable.

Takes the uids of the bonds and searches inside the container for those bond. If the bonds exists, they are replaced in the container. If any bond doesn’t exist, it will raise an exception.

iterable : iterable of Bond objects

the bonds that will be replaced.

Raises:ValueError – If any bond doesn’t exist.

Examples

Given a set of Bond objects that already exists in the container (taken with the ‘get_bond’ method for example) just call the function passing the set of Bond as parameter.

>>> particles = Particles(name="foo")
>>> ...
>>> bond1 = particles.get_bond(uid1)
>>> bond2 = particles.get_bond(uid2)
>>> ... #do whatever you want with the bonds
>>> particles.update_bonds([bond1, bond2])

update_particles(iterable)

Updates a set of particles from the provided iterable.

Takes the uids of the particles and searches inside the container for those particles. If the particles exists, they are replaced in the container. If any particle doesn’t exist, it will raise an exception.

iterable : iterable of Particle objects

the particles that will be replaced.

Raises:ValueError – If any particle inside the iterable does not exist.

Examples

Given a set of Particle objects that already exists in the container (taken with the ‘get_particle’ method for example), just call the function passing the Particle items as parameter.

>>> part_container = Particles(name="foo")
>>> ... #do whatever you want with the particles
>>> part_container.update_particles([part1, part2])

class simphony_mayavi.cuds.vtk_mesh.VTKMesh(name, data=None, data_set=None, mappings=None)

Bases: simphony.cuds.abc_mesh.ABCMesh

Constructor.

Parameters:

• name (string) – The name of the container
• data (DataContainer) – The data attribute to attach to the container. Default is None.
• data_set (tvtk.DataSet) – The dataset to wrap in the CUDS api. Default is None which will create a tvtk.UnstructuredGrid.
• mappings (dict) – A dictionary of mappings for the point2index, index2point, element2index and index2element. Should be provided if the points and elements described in data_set are already assigned uids. Default is None and will result in the uid <-> index mappings being generated at construction.

add_cells(cells)

Adds a set of new cells to the mesh.

cells : iterable of Cell

Cell to be added to the mesh

Raises:ValueError – If other cell with a duplicated uid was already in the mesh

add_edges(edges)

Adds a set of new edges to the mesh.

edges : iterable of Edge

Edge to be added to the mesh

Raises:ValueError – If other edge with a duplicated uid was already in the mesh

add_faces(faces)

Adds a set of new faces to the mesh.

faces : iterable of Face

Face to be added to the mesh

Raises:ValueError – If other face with a duplicated uid was already in the mesh

add_points(points)

Adds a set of new points to the mesh.

points : iterable of Point

Points to be added to the mesh

Raises:ValueError – If other point with a duplicated uid was already in the mesh.

count_of(item_type)

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 (int) – The number of items of item_type in the container. Raises:ValueError – If the type of the item is not supported in the current container.

data

Easy access to the vtk PointData structure

data_set = None

The vtk.PolyData dataset

element2index = None

The mapping from uid to bond index

element_data = None

Easy access to the vtk CellData structure

classmethod from_dataset(name, data_set, data=None)

Wrap a plain dataset into a new VTKMesh.

The constructor makes some sanity checks to make sure that the tvtk.DataSet is compatible and all the information can be properly used.

Parameters:

• name (string) – The name of the container
• data_set (tvtk.DataSet) – The dataset to wrap in the CUDS api. Default is None which will create a tvtk.UnstructuredGrid.
• data (DataContainer) – The data attribute to attach to the container. Default is None.

Raises:

TypeError – When the sanity checks fail.

classmethod from_mesh(mesh, point_keys=None, cell_keys=None)

Create a new VTKMesh copy from a CUDS mesh instance.

Parameters:

• mesh (ABCMesh) – The original mesh to create the new one.
• point_keys (list) – A list of point CUBA keys that we want to copy, and only those. If None, all available and compatible keys will be copied.
• cell_keys (list) – A list of cell CUBA keys that we want to copy, and only those. If None, all available and compatible keys will be copied.

get_cell(uid)

Returns a cell with a given uid.

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

Parameters:

uid (uuid.UUID) – uid of the desired cell.

Returns:

cell (Cell) – Cell identified by uid

Raises:

• KeyError – If the cell identified by uuid was not found
• TypeError – When uid is not uuid.UUID

get_edge(uid)

Returns an edge with a given uid.

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

Parameters:

uid (uuid.UUID) – uid of the desired edge.

Returns:

edge (Edge) – Edge identified by uid

Raises:

• KeyError – If the edge identified by uid was not found
• TypeError – When uid is not uuid.UUID

get_face(uid)

Returns a face with a given uid.

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

Parameters:

uid (uuid.UUID) – uid of the desired face.

Returns:

face (Face) – Face identified by uid

Raises:

• KeyError – If the face identified by uid was not found
• TypeError – When uid is not uuid.UUID

get_point(uid)

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.UUID) – uid of the desired point.

Returns:

point (Point) – Mesh point identified by uuid

Raises:

• KeyError – If the point identified by uid was not found
• TypeError – When uid is not uuid.UUID

has_cells()

Check if the mesh has cells

Returns:result (bool) – True of there are cells inside the mesh, False otherwise

has_edges()

Check if the mesh has edges

Returns:result (bool) – True of there are edges inside the mesh, False otherwise

has_faces()

Check if the mesh has faces

Returns:result (bool) – True of there are faces inside the mesh, False otherwise

index2element = None

The reverse mapping from index to bond uid

index2point = None

The reverse mapping from index to point uid

iter_cells(uids=None)

Returns an iterator over cells.

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 iterable and there is no restriction on the order that they are returned.

Yields:cell (Cell)

iter_edges(uids=None)

Returns an iterator over edges.

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 iterable and there is no restriction on the order that they are returned.

Yields:edge (Edge)

iter_faces(uids=None)

Returns an iterator over faces.

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 iterable and there is no restriction on the order that they are returned.

Yields:face (Face)

iter_points(uids=None)

Returns an iterator over points.

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 iterable and there is no restriction on the order that they are returned.

Yields:point (Point)

point2index = None

The mapping from uid to point index

supported_cuba = None

The currently supported and stored CUBA keywords.

update_cells(cells)

Updates the information of a set of cells.

Gets the mesh cell identified by the same uid as the provided cell and updates its information with the one provided with the new cell.

cells : iterable of Cell

Cell to be updated

Raises:ValueError – If the any cell was not found in the mesh

update_edges(edges)

Updates the information of a set of edges.

Gets the mesh edge identified by the same uid as the provided edge and updates its information with the one provided with the new edge.

edges : iterable of Edge

Edge to be updated

Raises:ValueError – If the any edge was not found in the mesh

update_faces(faces)

Updates the information of a set of faces.

Gets the mesh face identified by the same uid as the provided face and updates its information with the one provided with the new face.

faces : iterable of Face

Face to be updated

Raises:ValueError – If the any face was not found in the mesh

update_points(points)

Updates the information of a set of points.

Gets the mesh point identified by the same uid as the provided point and updates its information with the one provided with the new point.

points : iterable of Point

Point to be updated

Raises:ValueError – If the any point was not found in the mesh

class simphony_mayavi.cuds.vtk_lattice.VTKLattice(name, primitive_cell, data_set, data=None)

Bases: simphony.cuds.abc_lattice.ABCLattice

Constructor.

Parameters:

• name (string) – The name of the container.
• primitive_cell (PrimitiveCell) – primitive cell specifying the 3D Bravais lattice
• data_set (tvtk.DataSet) – The dataset to wrap in the CUDS api. If it is a tvtk.PolyData, the points are assumed to be arranged in C-contiguous order so that the first point is the origin and the last point is furthest away from the origin
• data (DataContainer) – The data attribute to attach to the container. Default is None.

count_of(item_type)

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 (int) – The number of items of item_type in the container. Raises:ValueError – If the type of the item is not supported in the current container.

data

The container data

classmethod empty(name, primitive_cell, size, origin, data=None)

Create a new empty Lattice.

Parameters:

• name (string) – The name of the container.
• primitive_cell (PrimitiveCell) – Primitive cell specifying the 3D Bravais lattice
• size (tuple) – lattice dimensions (nx, ny, nz)
• origin (tuple) – lattice origin (x, y, z)
• data (DataContainer) – The data attribute to attach to the container. Default is None.

Returns:

lattice (VTKLattice)

classmethod from_dataset(name, data_set, data=None)

Create a new Lattice and try to guess the primitive_cell

Parameters:

• name (str) –
• data_set (tvtk.ImageData or tvtk.PolyData) – The dataset to wrap in the CUDS api. If it is a PolyData, the points are assumed to be arranged in C-contiguous order
• data (DataContainer) – The data attribute to attach to the container. Default is None.

Returns:

lattice (VTKLattice)

Raises:

TypeError – If data_set is not either tvtk.ImageData or tvtk.PolyData

IndexError:

If the lattice nodes are not arranged in C-contiguous order

classmethod from_lattice(lattice, node_keys=None)

Create a new Lattice from the provided one.

Parameters:

• lattice (simphony.cuds.lattice.Lattice) –
• node_keys (list) – A list of point CUBA keys that we want to copy, and only those. If None, all available and compatible keys will be copied.

Returns:

lattice (VTKLattice)

Raises:

ValueError

• if bravais_lattice attribute of the primitive cell indicates a cubic/tetragonal/orthorhombic lattice but the primitive vectors are inconsistent with this attribute
• if bravais_lattice is not a member of BravaisLattice

get_coordinate(ind)

Get coordinate of the given index coordinate.

ind : int[3]

node index coordinate

Returns:

coordinates : float[3]

get_node(index)

Get the lattice node corresponding to the given index.

index : int[3]

node index coordinate

Returns:node (LatticeNode)

iter_nodes(indices=None)

Get an iterator over the LatticeNodes described by the indices.

indices : iterable set of int[3], optional

When indices (i.e. node index coordinates) are provided, then nodes are returned in the same order of the provided indices. If indices is None, there is no restriction on the order of the returned nodes.

Returns:

iterator:

An iterator over LatticeNode objects

origin

lattice origin (x, y, z)

point_data = None

Easy access to the vtk PointData structure

primitive_cell

Primitive cell specifying the 3D Bravais lattice

size

lattice dimensions (nx, ny, nz)

supported_cuba = None

The currently supported and stored CUBA keywords.

update_nodes(nodes)

Update the corresponding lattice nodes.

nodes : iterator of LatticeNodes