CUDS

Abstract CUDS interfaces

Containers

abstractmesh.ABCMesh
abstractparticles.ABCParticles
abstractlattice.ABCLattice

Description

class simphony.cuds.abc_mesh.ABCMesh[source]

Abstract base class for mesh.

name

str – name of mesh

add_cells(cell)[source]

Adds a set of new cells to the mesh.

Parameters: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(edge)[source]

Adds a set of new edges to the mesh.

Parameters: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(face)[source]

Adds a set of new faces to the mesh.

Parameters: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)[source]

Adds a set of new points to the mesh.

Parameters: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)[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.
get_cell(uid)[source]

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 identified by uid

Return type:

Cell

Raises:
  • KeyError : – If the cell identified by uuid was not found
  • TypeError : – When uid is not uuid.UUID
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 an exception is raised.

Parameters:

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

Returns:

edge – Edge identified by uid

Return type:

Edge

Raises:
  • KeyError : – If the edge identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
get_face(uid)[source]

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 identified by uid

Return type:

Face

Raises:
  • KeyError : – If the face identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
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.UUID) – uid of the desired point.

Returns:

point – Mesh point identified by uuid

Return type:

Point

Raises:
  • KeyError : – If the point identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
has_cells()[source]

Check if the mesh has cells

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

Check if the mesh has edges

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

Check if the mesh has faces

Returns:result – 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.
Yields:cell (Cell)
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.
Yields:edge (Edge)
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.
Yields:face (Face)
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.
Yields:point (Point)
update_cells(cell)[source]

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.

Parameters:cells (iterable of Cell) – Cell to be updated
Raises:ValueError : – If the any cell was not found in the mesh
update_edges(edge)[source]

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.

Parameters:edges (iterable of Edge) – Edge to be updated
Raises:ValueError : – If the any edge was not found in the mesh
update_faces(face)[source]

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.

Parameters:faces (iterable of Face) – Face to be updated
Raises:ValueError : – If the any face was not found in the mesh
update_points(point)[source]

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.

Parameters:points (iterable of Point) – Point to be updated
Raises:ValueError : – If the any point was not found in the mesh
class simphony.cuds.abc_particles.ABCParticles[source]

Abstract base class for a container of particles items.

name

str – name of particles item.

data

DataContainer – The data associated with the container

add_bonds(iterable)[source]

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.

Parameters:iterable (iterable of Bond objects) – the new bond that will be included in the container.
Returns:uuid – The uuids of the added bonds.
Return type:list of uuid.UUID
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)[source]

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.

Parameters:iterable (iterable of Particle objects) – the new set of particles that will be included in the container.
Returns:uids – The uids of the added particles.
Return type:list of uuid.UUID
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)
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.
get_bond(uid)[source]

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 – A copy of the internally stored bond info.
Return type:Bond
get_particle(uid)[source]

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 – A copy of the internally stored particle info.
Return type:Particle
has_bond(uid)[source]

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

has_particle(uid)[source]

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

iter_bonds(uids=None)[source]

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.

Parameters: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 interable 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)[source]

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.

Parameters: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 interable 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
remove_bonds(uids)[source]

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.

Parameters:uids (uuid.UUID) – the uid of the bond to be removed.

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)[source]

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.

Parameters:uid (uuid.UUID) – the uid of the particle 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])
update_bonds(iterable)[source]

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.

Parameters: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)[source]

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.

Parameters: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.cuds.abc_lattice.ABCLattice[source]

Abstract base class for a lattice.

name

str – name of lattice

primitive_cell

PrimitiveCell – primitive cell specifying the 3D Bravais lattice

size

int[3] – lattice dimensions

origin

float[3] – lattice origin

data

DataContainer – high level CUBA data assigned to lattice

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.
get_coordinate(ind)[source]

Get coordinate of the given index coordinate.

Parameters:ind (int[3]) – node index coordinate
Returns:coordinates
Return type:float[3]
get_node(index)[source]

Get the lattice node corresponding to the given index.

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

Get an iterator over the LatticeNodes described by the indices.

Parameters: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 the nodes that are returned.
Returns:An iterator over LatticeNode objects
Return type:iterator
primitive_cell
update_nodes(nodes)[source]

Update the corresponding lattice nodes.

Parameters:nodes (iterator of LatticeNodes) –

Pure Python implementation

Classes

PrimitiveCell(p1, p2, p3, bravais_lattice) A primitive cell of a Bravais lattice.
BravaisLattice The 3D Bravais lattices
Lattice(name, primitive_cell, size, origin) A Bravais lattice.
LatticeNode(index[, data]) A single node of a lattice.
Particles(name) Class that represents a container of particles and bonds.
Bond(particles[, uid, data]) Class representing a bond.
Particle([coordinates, uid, data]) Class representing a particle.
Mesh(name) Mesh object to store points and elements.
Point(coordinates[, uid, data]) Coordinates describing a point in the space
Edge(points[, uid, data]) Edge element
Face(points[, uid, data]) Face element
Cell(points[, uid, data]) Cell element

Functions

make_cubic_lattice(name, h, size[, origin]) Create and return a 3D cubic lattice.
make_body_centered_cubic_lattice(name, h, size) Create and return a 3D body-centered cubic lattice.
make_face_centered_cubic_lattice(name, h, size) Create and return a 3D face-centered cubic lattice.
make_rhombohedral_lattice(name, h, angle, size) Create and return a 3D rhombohedral lattice.
make_tetragonal_lattice(name, hxy, hz, size) Create and return a 3D tetragonal lattice.
make_body_centered_tetragonal_lattice(name, ...) Create and return a 3D body-centered tetragonal lattice.
make_hexagonal_lattice(name, hxy, hz, size) Create and return a 3D hexagonal lattice.
make_orthorhombic_lattice(name, hs, size[, ...]) Create and return a 3D orthorhombic lattice.
make_body_centered_orthorhombic_lattice(...) Create and return a 3D body-centered orthorhombic lattice.
make_face_centered_orthorhombic_lattice(...) Create and return a 3D face-centered orthorhombic lattice.
make_base_centered_orthorhombic_lattice(...) Create and return a 3D base-centered orthorhombic lattice.
make_monoclinic_lattice(name, hs, beta, size) Create and return a 3D monoclinic lattice.
make_base_centered_monoclinic_lattice(name, ...) Create and return a 3D base-centered monoclinic lattice.
make_triclinic_lattice(name, hs, angles, size) Create and return a 3D triclinic lattice.

Implementation

class simphony.cuds.lattice.Lattice(name, primitive_cell, size, origin)[source]

A Bravais lattice. Stores references to data containers (node related data).

name

str – name of lattice

primitive_cell

PrimitiveCell – primitive cell specifying the 3D Bravais lattice

size

int[3] – lattice dimensions

origin

float[3] – lattice origin

data

DataContainer – high level CUBA data assigned to lattice

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_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 indices.

Parameters: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 the nodes that are returned.
Returns:
Return type:A generator for LatticeNode objects
origin
size
update_nodes(nodes)[source]

Update the corresponding lattice nodes (data copied).

Parameters:nodes (iterable of LatticeNode objects) – reference to LatticeNode objects from where the data is copied to the Lattice
class simphony.cuds.lattice.LatticeNode(index, data=None)[source]

A single node of a lattice.

index

tuple of int[3] – node index coordinate

data

DataContainer

simphony.cuds.lattice.make_base_centered_monoclinic_lattice(name, hs, beta, size, origin=(0, 0, 0))[source]

Create and return a 3D base-centered monoclinic lattice.

Parameters:
  • name (str) –
  • hs (float) – lattice spacing in each axis direction
  • beta (float) – angle between the (conventional) unit cell edges (in radians),
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_base_centered_orthorhombic_lattice(name, hs, size, origin=(0, 0, 0))[source]

Create and return a 3D base-centered orthorhombic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_body_centered_cubic_lattice(name, h, size, origin=(0, 0, 0))[source]

Create and return a 3D body-centered cubic lattice.

Parameters:
  • name (str) –
  • h (float) – lattice spacing
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_body_centered_orthorhombic_lattice(name, hs, size, origin=(0, 0, 0))[source]

Create and return a 3D body-centered orthorhombic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_body_centered_tetragonal_lattice(name, hxy, hz, size, origin=(0, 0, 0))[source]

Create and return a 3D body-centered tetragonal lattice.

Parameters:
  • name (str) –
  • hxy (float) – lattice spacing in the xy-plane
  • hz (float) – lattice spacing in the z-direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_cubic_lattice(name, h, size, origin=(0, 0, 0))[source]

Create and return a 3D cubic lattice.

Parameters:
  • name (str) –
  • h (float) – lattice spacing
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_face_centered_cubic_lattice(name, h, size, origin=(0, 0, 0))[source]

Create and return a 3D face-centered cubic lattice.

Parameters:
  • name (str) –
  • h (float) – lattice spacing
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_face_centered_orthorhombic_lattice(name, hs, size, origin=(0, 0, 0))[source]

Create and return a 3D face-centered orthorhombic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_hexagonal_lattice(name, hxy, hz, size, origin=(0, 0, 0))[source]

Create and return a 3D hexagonal lattice.

Parameters:
  • name (str) –
  • hxy (float) – lattice spacing in the xy-plane
  • hz (float) – lattice spacing in the z-direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_monoclinic_lattice(name, hs, beta, size, origin=(0, 0, 0))[source]

Create and return a 3D monoclinic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • beta (float) – angle between the (conventional) unit cell edges (in radians),
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_orthorhombic_lattice(name, hs, size, origin=(0, 0, 0))[source]

Create and return a 3D orthorhombic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_rhombohedral_lattice(name, h, angle, size, origin=(0, 0, 0))[source]

Create and return a 3D rhombohedral lattice.

Parameters:
  • name (str) –
  • h (float) – lattice spacing
  • angle (float) – angle between the (conventional) unit cell edges (in radians)
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_tetragonal_lattice(name, hxy, hz, size, origin=(0, 0, 0))[source]

Create and return a 3D tetragonal lattice.

Parameters:
  • name (str) –
  • hxy (float) – lattice spacing in the xy-plane
  • hz (float) – lattice spacing in the z-direction
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

simphony.cuds.lattice.make_triclinic_lattice(name, hs, angles, size, origin=(0, 0, 0))[source]

Create and return a 3D triclinic lattice.

Parameters:
  • name (str) –
  • hs (float[3]) – lattice spacings in each axis direction
  • angles (float[3]) – angles between the (conventional) unit cell edges (in radians)
  • size (int[3]) – Number of lattice nodes in each axis direction.
  • origin (float[3], default value = (0, 0, 0)) – lattice origin
Returns:

lattice – A reference to a Lattice object.

Return type:

Lattice

Mesh module

This module contains the implementation to store, access, and modify a mesh

class simphony.cuds.mesh.Cell(points, uid=None, data=None)[source]

Cell element

Element for storing 3D geometrical objects

Parameters:
  • points (list of uid) – list of points uids defining the cell.
  • uid (uuid.UUID) – uid of the cell.
  • data (DataContainer) – object to store data relative to the cell
classmethod from_cell(cell)[source]
class simphony.cuds.mesh.Edge(points, uid=None, data=None)[source]

Edge element

Element for storing 1D geometrical objects

Parameters:
  • points (list of uid) – list of points uids defining the edge.
  • uid (uuid.UUID) – uid of the edge.
  • data (DataContainer) – object to store data relative to the edge
classmethod from_edge(edge)[source]
class simphony.cuds.mesh.Element(points, uid=None, data=None)[source]

Element base class

Element for storing geometrical objects

Parameters:
  • uid – uid of the edge.
  • points (list of uid) – list of points uids defining the edge.
  • data (DataContainer) – object to store data relative to the element
points

list of uid – list of points uids defining the element.

uid

uuid.UUID – uid of the element

data

DataContainer – Element data

class simphony.cuds.mesh.Face(points, uid=None, data=None)[source]

Face element

Element for storing 2D geometrical objects

Parameters:
  • points (list of uid) – list of points uids defining the face.
  • uid (uuid.UUID) – uid of the face.
  • data (DataContainer) – object to store data relative to the face
classmethod from_face(face)[source]
class simphony.cuds.mesh.Mesh(name)[source]

Mesh object to store points and elements.

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 different 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.
Parameters:name (str) – name of mesh
name

str – name of mesh

data

Data – Data relative to the mesh.

points

dictionary of Point – Points of the mesh.

edges

dictionary of Edge – Edges of the mesh.

faces

dictionary of Face – Faces of the mesh.

cells

dictionary of Cell – Cells of the mesh.

add_cells(cells)[source]

Adds a set of new cells to the mesh.

Parameters: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)[source]

Adds a set of new edges to the mesh.

Parameters: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)[source]

Adds a set of new faces to the mesh.

Parameters: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)[source]

Adds a set of new points to the mesh.

Parameters: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)[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 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 identified by uid

Return type:

Cell

Raises:
  • KeyError : – If the cell identified by uuid was not found
  • TypeError : – When uid is not uuid.UUID
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 an exception is raised.

Parameters:

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

Returns:

edge – Edge identified by uid

Return type:

Edge

Raises:
  • KeyError : – If the edge identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
get_face(uid)[source]

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 identified by uid

Return type:

Face

Raises:
  • KeyError : – If the face identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
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.UUID) – uid of the desired point.

Returns:

point – Mesh point identified by uuid

Return type:

Point

Raises:
  • KeyError : – If the point identified by uid was not found
  • TypeError : – When uid is not uuid.UUID
has_cells()[source]

Check if the mesh has cells

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

Check if the mesh has edges

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

Check if the mesh has faces

Returns:result – 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.
Yields:cell (Cell)
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.
Yields:edge (Edge)
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.
Yields:face (Face)
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.
Yields:cell (Cell)
update_cells(cells)[source]

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.

Parameters:cells (iterable of Cell) – Cell to be updated
Raises:ValueError : – If the any cell was not found in the mesh
update_edges(edges)[source]

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.

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

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.

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

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.

Parameters:points (iterable of Point) – Point to be updated
Raises:ValueError : – If the any point was not found in the mesh
class simphony.cuds.mesh.Point(coordinates, uid=None, data=None)[source]

Coordinates describing a point in the space

Set of coordinates (x,y,z) describing a point in the space and data about that point

Parameters:
  • uid (uuid.UUID) – uid of the point.
  • coordinates (list of double) – set of coordinates (x,y,z) describing the point position.
  • data (DataContainer) – object to store point data
uid

uuid.UUID – uid of the point.

data

DataContainer – object to store point data

coordinates

list of double – set of coordinates (x,y,z) describing the point position.

classmethod from_point(point)[source]
class simphony.cuds.particles.Bond(particles, uid=None, data=None)[source]

Class representing a bond.

uid

uuid.UUID – the uid of the bond

particles

tuple – tuple of uids of the particles that are participating in the bond.

data

DataContainer – DataContainer to store the attributes of the bond

classmethod from_bond(bond)[source]
class simphony.cuds.particles.Particle(coordinates=(0.0, 0.0, 0.0), uid=None, data=None)[source]

Class representing a particle.

uid

uuid.UUID – the uid of the particle

coordinates

list / tuple – x,y,z coordinates of the particle

data

DataContainer – DataContainer to store the attributes of the particle

classmethod from_particle(particle)[source]
class simphony.cuds.particles.Particles(name)[source]

Class that represents a container of particles and bonds.

Class provides methods to add particles and bonds, remove them and update them.

name

str – name of the particle container

_particles

dict – data structure for particles storage

_bonds

dict – data structure for bonds storage

data

DataContainer – data attributes of the element

add_bonds(iterable)[source]

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.

Parameters:iterable (iterable of Bond objects) – the new bond that will be included in the container.
Returns:uuid – The uuids of the added bonds.
Return type:list of uuid.UUID
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_bond(bonds_list)
add_particles(iterable)[source]

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.

Parameters:iterable (iterable of Particle objects) – the new set of particles that will be included in the container.
Returns:uids – The uids of the added particles.
Return type:list of uuid.UUID
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)
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]

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 – A copy of the internally stored bond info.
Return type:Bond
get_particle(uid)[source]

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 – A copy of the internally stored particle info.
Return type:Particle
has_bond(uid)[source]

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

has_particle(uid)[source]

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

iter_bonds(uids=None)[source]

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.

Parameters: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 interable 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:

>>> part_container = Particles(name="foo")
>>> ...
>>> for bond in part_container.iter_bonds([id1, id2, id3]):
        ...  #do stuff
        #take the bond back to the container so it will be updated
        #in case we need it
        part_container.update_bond(bond)
>>> for bond in part_container.iter_bond():
        ...  #do stuff; it will iterate over all the bond
        #take the bond back to the container so it will be updated
        #in case we need it
        part_container.update_bond(bond)
iter_particles(uids=None)[source]

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.

Parameters: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 interable 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:

>>> part_container = Particles(name="foo")
>>> ...
>>> for particle in part_container.iter_particles([uid1, uid2, uid3]):
        ...  #do stuff
        #take the particle back to the container so it will be updated
        #in case we need it
        part_container.update_particle(particle)
>>> for particle in part_container.iter_particles():
        ...  #do stuff; it will iterate over all the particles
        #take the particle back to the container so it will be updated
        #in case we need it
        part_container.update_particle(particle)
remove_bonds(uids)[source]

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.

Parameters:uids (uuid.UUID) – the uid of the bond to be removed.

Examples

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

>>> particles = Particles(name="foo")
>>> ...
>>> bond1 = particles.get_bond(uid1)
>>> bond2 = particles.get_bond(uid2)
>>> ...
>>> particles.remove_bonds([bond1.uid, bond2.uid])
or
>>> particles.remove_bond([uid1, uid2])
remove_particles(uids)[source]

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.

Parameters:uid (uuid.UUID) – the uid of the particle 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")
>>> ...
>>> particle1 = particles.get_particle(uid1)
>>> particle2 = particles.get_particle(uid2)
>>> ...
>>> particles.remove_particle([part1.uid, part2.uid)
or directly
>>> particles.remove_particle([uid1, uid2])
update_bonds(iterable)[source]

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.

Parameters: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_bond([bond1, bond2])
update_particles(iterable)[source]

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.

Parameters: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")
>>> ...
>>> part1 = part_container.get_particle(uid1)
>>> part2 = part_container.get_particle(uid2)
>>> ... #do whatever you want with the particles
>>> part_container.update_particle([part1, part2])