ovito.data

This module contains data container classes that are used by OVITO’s modification pipeline system.

Data collection:

Data objects:

Auxiliary classes:

class ovito.data.BondProperty
Base class:ovito.data.DataObject

A data object that stores the values of a bond property.

array

This attribute returns a NumPy array, which provides read access to the per-bond data stored in this bond property object.

The returned array is one-dimensional for scalar bond properties (components == 1), or two-dimensional for vector properties (components > 1). The outer length of the array is equal to the number of half-bonds in both cases.

Note that the returned NumPy array is read-only and provides a view of the internal data. No copy of the data, which may be shared by multiple objects, is made. If you want to modify the data stored in this bond property, use marray instead.

changed()

Informs the bond property object that its internal data has changed. This function must be called after each direct modification of the per-bond data through the marray attribute.

Calling this method on an input bond property is necessary to invalidate data caches down the modification pipeline. Forgetting to call this method may result in an incomplete re-evaluation of the modification pipeline. See marray for more information.

components

The number of vector components (if this is a vector bond property); otherwise 1 (= scalar property).

marray

This attribute returns a mutable NumPy array providing read/write access to the internal per-bond data.

The returned array is one-dimensional for scalar bond properties (components == 1), or two-dimensional for vector properties (components > 1). The outer length of the array is equal to the number of half-bonds in both cases.

Note

After you are done modifying the data in the returned NumPy array, you must call changed()! Calling this method is necessary to inform the data pipeline system that the input bond data has changed and the modification pipeline needs to be re-evaluated. The reason is that OVITO cannot automatically detect modifications made by the script to the returned NumPy array. Therefore, an explicit call to changed() is necessary.

name

The human-readable name of the bond property.

size

The number of stored values, which is equal to the number of half-bonds.

type

The type of the bon property (user-defined or one of the standard types). One of the following constants:

Type constant Property name Data type
BondProperty.Type.User (a user-defined property with a non-standard name) int/float
BondProperty.Type.BondType Bond Type int
BondProperty.Type.Selection Selection int
BondProperty.Type.Color Color float
class ovito.data.BondType

Stores the properties of a bond type.

The list of bond types is stored in the BondTypeProperty class.

color

The display color to use for bonds of this type.

id

The identifier of the bond type.

name

The display name of this bond type.

class ovito.data.BondTypeProperty
Base class:ovito.data.BondProperty

A special BondProperty that stores a list of BondType instances in addition to the per-bond values.

The bond property Bond Type is represented by an instance of this class. In addition to the regular per-bond data (consisting of an integer per half-bond, indicating its type ID), this class holds the list of defined bond types. These are BondType instances, which store the ID, name, and color of each bond type.

type_list

A mutable list of BondType instances.

class ovito.data.Bonds
Base class:ovito.data.DataObject

This data object stores a list of bonds between pairs of particles. Typically bonds are loaded from a simulation file or are created using the CreateBondsModifier in the modification pipeline.

The following example shows how to access the bond list create by a CreateBondsModifier:

from ovito.io import import_file
from ovito.modifiers import CreateBondsModifier
from ovito.vis import BondsDisplay

# Load a set of atoms and create bonds between pairs of atoms
# that are within a given cutoff distance of each other
# using the Create Bonds modifier.
node = import_file('simulation.dump')
node.modifiers.append(CreateBondsModifier(cutoff = 3.4))
node.compute()

# Read out list of generated bonds.
bonds_list = node.output.bonds.array
print("Number of generated bonds: ", len(bonds_list)//2)

OVITO represents each bond as two half-bonds, one pointing from a particle A to a particle B, and the other half-bond pointing back from B to A. Thus, for a given number of bonds, you will find twice as many half-bonds in the Bonds object. The array attribute returns a (read-only) NumPy array that contains the list of half-bonds, which are defined by pairs of particle indices (the first one specifying the particle the half-bond is pointing away from).

Furthermore, every Bonds object is associated with a BondsDisplay instance, which controls the visual appearance of the bonds. It can be accessed through the display attribute:

# Change appearance of bonds.
node.output.bonds.display.enabled = True
node.output.bonds.display.shading = BondsDisplay.Shading.Flat
node.output.bonds.display.width = 0.3
class Enumerator(bonds)

Utility class that allows to efficiently iterate over the bonds that are adjacent to a particular particle.

The class constructor takes the Bonds object for which it will first build a lookup table. After the Enumerator has been constructed, the half-bonds of a particular particle can be found using the bonds_of_particle() method.

Warning: Do not modify the underlying Bonds object while using the Enumerator. Adding or deleting bonds would render the internal lookup table of the Enumerator invalid.

bonds_of_particle(particle_index)

Returns an iterator that yields the indices of the half-bonds connected to the given particle.

Bonds.add(p1, p2)

Creates a new half-bond from particle p1 to particle p2.

To also create a half-bond from p2 to p1, use add_full() instead.

Parameters:
  • p1 (int) – Zero-based index of the particle at which the bonds originates.
  • p2 (int) – Zero-based index of the particle the bonds leads to.
Bonds.add_full(p1, p2)

Creates two half-bonds between the particles p1 and p2.

Parameters:
  • p1 (int) – Zero-based index of the first particle.
  • p2 (int) – Zero-based index of the second particle.
Bonds.array

This attribute returns a NumPy array providing direct access to the bond list.

The returned array is two-dimensional and contains pairs of particle indices connected by a bond. The array’s shape is N x 2, where N is the number of half bonds. Each pair-wise bond occurs twice in the array, once for the connection A->B and second time for the connection B->A. Particle indices start at 0.

Note that the returned NumPy array is read-only and provides a view of the internal data. No copy of the data is made.

Bonds.clear()

Removes all stored bonds.

class ovito.data.CutoffNeighborFinder(cutoff, data_collection)

A utility class that computes particle neighbor lists.

This class allows to iterate over the neighbors of each particle within a given cutoff distance. You can use it to build neighbors lists or perform other kinds of analyses that require neighbor information.

The constructor takes a positive cutoff radius and a DataCollection containing the input particle positions and the cell geometry (including periodic boundary flags).

Once the CutoffNeighborFinder has been constructed, you can call its find() method to iterate over the neighbors of a specific particle, for example:

from ovito.io import import_file
from ovito.data import CutoffNeighborFinder

# Load input simulation file.
node = import_file("simulation.dump")
data = node.source

# Initialize neighbor finder object:
cutoff = 3.5
finder = CutoffNeighborFinder(cutoff, data)

# Loop over all input particles:
for index in range(data.number_of_particles):
    print("Neighbors of particle %i:" % index)
    # Iterate over the neighbors of the current particle:
    for neigh in finder.find(index):
        print(neigh.index, neigh.distance, neigh.delta, neigh.pbc_shift)

If you want to determine the N nearest neighbors of a particle, use the NearestNeighborFinder class instead.

find(index)

Returns an iterator over all neighbors of the given particle.

Parameters:index (int) – The index of the central particle whose neighbors should be iterated. Particle indices start at 0.
Returns:A Python iterator that visits all neighbors of the central particle within the cutoff distance. For each neighbor the iterator returns an object with the following attributes:
  • index: The index of the current neighbor particle (starting at 0).
  • distance: The distance of the current neighbor from the central particle.
  • distance_squared: The squared neighbor distance.
  • delta: The three-dimensional vector connecting the central particle with the current neighbor (taking into account periodicity).
  • pbc_shift: The periodic shift vector, which specifies how often each periodic boundary of the simulation cell is crossed when going from the central particle to the current neighbor.

Note that all periodic images of particles within the cutoff radius are visited. Thus, the same particle index may appear multiple times in the neighbor list of a central particle. In fact, the central particle may be among its own neighbors in a sufficiently small periodic simulation cell. However, the computed vector (delta) and PBC shift (pbc_shift) will be unique for each visited image of a neighboring particle.

class ovito.data.DataCollection

A data collection is a dictionary-like container that can store an arbitrary number of data objects. OVITO knows various types of data objects, e.g.

Data collections hold the data that enters or leaves an ObjectNode‘s modification pipeline. The input data collection of the pipeline can be accessed through the node’s source attribute:

>>> node = import_file(...)
>>> print(node.source)
DataCollection(['Simulation cell', 'Position'])

In this example the input data collection contains the original data that was read from the external file, consisting of the particle position property and a simulation cell.

The input data typically gets modified or extended by modifiers in the node’s modification pipeline. To access the results of the modification pipeline, we need to call ObjectNode.compute(), which returns the output data collection after evaluating the modifiers:

>>> node.modifiers.append(CommonNeighborAnalysisModifier())
>>> print(node.compute())
DataCollection(['Simulation cell', 'Position', 'Color', 'Structure Type'])

The output data collection is cached by the ObjectNode and may subsequently be accessed through the output attribute:

>>> print(node.output)
DataCollection(['Simulation cell', 'Position', 'Color', 'Structure Type'])

In our example, the CommonNeighborAnalysisModifier in the modification pipeline has added additional particle properties to the DataCollection. Particle properties, which are instances of the ParticleProperty class, are so-called data objects. Likewise, the simulation cell (SimulationCell) and bonds (Bonds) are data objects, which can all be part of a data collection.

The particle properties in a collection can be accessed through the particle_properties dictionary view. Use its keys() method to find out which particle properties are contained in the collection:

>>> data = node.compute()
>>> list(data.particle_properties.keys())
['Particle Identifier', 'Position', 
 'Potential Energy', 'Color', 'Structure Type']

Specific particle properties in the collection can be accessed using the dictionary interface:

>>> data.particle_properties['Potential Energy']
<ParticleProperty at 0x11d01d60>

Standard particle properties, however, can be directly accessed more conveniently via corresponding Python attributes, e.g.:

>>> data.particle_properties.potential_energy
<ParticleProperty at 0x11d01d60>

>>> print(data.particle_properties.position.array)
[[ 0.          0.          0.        ]
 [ 0.8397975   0.8397975   0.        ]
 ...

The SimulationCell, Bonds, and other data objects in the data collection can be accessed through its cell, bonds, surface, and dislocations property:

>>> data.cell
<SimulationCellObject at 0x24338a0>

>>> data.cell.matrix
[[ 3.35918999  0.          0.          0.        ]
 [ 0.          3.35918999  0.          0.        ]
 [ 0.          0.          3.35918999  0.        ]]
add(obj)

Inserts a DataObject into the DataCollection.

The method will do nothing if the data object is already part of the collection. A data object can be part of several data collections.

bond_properties

Returns a dictionary view that provides access to the BondProperty instances stored in this DataCollection.

bonds

Returns the Bonds object stored in this DataCollection.

Accessing this property raises an AttributeError if the data collection contains no bonds.

cell

Returns the SimulationCell stored in this DataCollection.

Accessing this property raises an AttributeError if the data collection contains no simulation cell information.

copy_if_needed(obj)

Makes a copy of a data object if it was created upstream in the data pipeline.

Typically, this method is used in implementations of a modifier function that participates in OVITO’s data pipeline system. A modifier receives a collection with input data objects from the system. However, directly modifying these input objects is not allowed because they are owned by the upstream part of the data pipeline. This is where this method comes into play: It makes a copy of a data object and replaces it with its copy in the modifier’s output. The modifier can then go ahead and modify the copy as needed, because it is now exclusively owned by the modifier.

The method first checks if obj, which must be a data object from this data collection, is owned by anybody else. If yes, it creates an exact copy of obj and replaces the original in this data collection with the copy. Now the copy is an independent object, which is referenced by nobody except this data collection. Thus, the modifier function is now free to modify the contents of the data object.

Note that the copy_if_needed() method should always be called on the output data collection of the modifier.

Parameters:obj (DataObject) – The object in the output data collection to be copied.
Returns:An exact copy of obj if obj is owned by someone else. Otherwise the original instance is returned.
classmethod create_from_ase_atoms(atoms)

Converts an ASE Atoms object to a DataCollection.

Note

The built-in Python interpreter shipping with OVITO does not contain the ASE module (Atomistic Simulation Environment). It is therefore recommended to build OVITO from source (as explained in the user manual), which will allow you to use all modules installed in the system’s Python interpreter.

Parameters:atoms

The ASE Atoms object to be converted.

Returns:A new DataCollection instance containing the converted data from the ASE object.
create_particle_property(property_type, data=None)

Adds a standard particle property to this data collection.

If the specified particle property already exists in this data collection, the existing property instance is returned. Otherwise the method creates a new property instance using ParticleProperty.create() and adds it to this data collection.

The optional parameter data allows to directly set or initialize the values of the particle property.

Parameters:
  • property_type (ParticleProperty.Type) – The standard particle property to create. See the ParticleProperty.type attribute for a list of possible values.
  • data – An optional data array (e.g. NumPy array), which contains the per-particle values used to initialize the particle property. The size of the array must match the number of particles in this data collection (see number_of_particles attribute).
Returns:

A newly created instance of the ovito.data.ParticleProperty class or one of its sub-classes if the property did not exist yet in the data collection. Otherwise, the existing particle property object is returned.

create_user_particle_property(name, data_type, num_components=1, data=None)

Adds a user-defined particle property to this data collection.

If a particle property with the given name already exists in this data collection, the existing property instance is returned. Otherwise the method creates a new property instance using ParticleProperty.create_user() and adds it to this data collection.

The optional parameter data allows to directly set or initialize the values of the particle property.

Parameters:
  • name (str) – The name of the user-defined particle property to create.
  • data_type (str) – Must be either "int" or "float".
  • num_components (int) – The number of components when creating a vector property.
  • data – An optional data array (e.g. NumPy array), which contains the per-particle values used to initialize the particle property. The size of the array must match the number of particles in this data collection (see number_of_particles attribute).
Returns:

A newly created instance of the ParticleProperty class or one of its sub-classes if the property did not exist yet in the data collection. Otherwise, the existing particle property object is returned.

dislocations

Returns the DislocationNetwork object in this DataCollection.

Accessing this property raises an AttributeError if the data collection contains no dislocations object.

number_of_bonds

The number of half-bonds stored in the data collection.

number_of_particles

The number of particles stored in the data collection.

particle_properties

Returns a dictionary view that provides access to the ParticleProperty instances stored in this DataCollection.

remove(obj)

Removes a DataObject from the DataCollection.

The method will do nothing if the data object is not part of the collection.

replace(old_obj, new_obj)

Replaces a DataObject in the DataCollection with a different one.

The method will do nothing if the data object to be replaced is not part of the collection.

surface

Returns the SurfaceMesh in this DataCollection.

Accessing this property raises an AttributeError if the data collection contains no surface mesh instance.

to_ase_atoms()

Constructs and returns an ASE Atoms object from the particles stored in this DataCollection.

Note

Calling this method raises an ImportError if ASE (Atomistic Simulation Environment) is not available. Note that the built-in Python interpreter shipping with OVITO does not contain the ASE module. It is therefore recommended to build OVITO from source (as explained in the user manual), which will allow you to use all modules installed in the system’s Python interpreter.

Returns:A new ASE Atoms object that contains the contains the converted particle data from this DataCollection.
class ovito.data.DataObject

Abstract base class for all data objects.

Some data objects are associated with a Display object, which is responsible for displaying the data in the viewports and in rendered images. The display attribute provides access to the attached display object and allows controlling the visual appearance of the data.

display

The Display object associated with this data object, which is responsible for displaying the data. If this field is None, the data is non-visual.

class ovito.data.DislocationNetwork
Base class:ovito.data.DataObject

This data object types stores the network of dislocation lines extracted by a DislocationAnalysisModifier.

Instances of this class are associated with a DislocationDisplay that controls the visual appearance of the dislocation lines. It can be accessed through the display attribute of the DataObject base class.

Example:

from ovito.io import import_file
from ovito.modifiers import DislocationAnalysisModifier

# Extract dislocation lines from the crystal:
node = import_file("simulation.dump")
modifier =  DislocationAnalysisModifier()
modifier.input_crystal_structure = DislocationAnalysisModifier.Lattice.CubicDiamond
node.modifiers.append(modifier)
node.compute()

# Print list of dislocation lines:
network = node.output.dislocations
print("Found %i dislocation segments" % len(network.segments))
for segment in network.segments:
    print("Segment %i: length=%f, Burgers vector=%s" % (segment.id, segment.length, segment.true_burgers_vector))
    print(segment.points)
segments

The list of dislocation segments in this dislocation network. This list-like object is read-only and contains DislocationSegment objects.

class ovito.data.DislocationSegment

A single dislocation line from a DislocationNetwork.

The list of dislocation segments is returned by the DislocationNetwork.segments attribute.

cluster_id

The unique identifier of the cluster of crystal atoms that contains this dislocation segment.

The Burgers vector of the segment is expressed in the local coordinate system of this atomic cluster.

id

The unique identifier of this dislocation segment.

is_infinite_line

This property indicates whether this segment is an infinite line passing through a periodic simulation box boundary. A segment is considered infinite if it is a closed loop and its start and end points do not coincide.

See also the is_loop property.

is_loop

This property indicates whether this segment forms a closed dislocation loop. Note that an infinite dislocation line passing through a periodic boundary is also considered a loop.

See also the is_infinite_line property.

length

Returns the length of this dislocation segment.

points

The list of points in space that define the shape of this dislocation segment.

true_burgers_vector

The Burgers vector of the segment, expressed in the local coordinate system of the crystal. Also known as the True Burgers vector.

class ovito.data.NearestNeighborFinder(N, data_collection)

A utility class that finds the N nearest neighbors of a particle.

The constructor takes the number of requested nearest neighbors, N, and a DataCollection containing the input particle positions and the cell geometry (including periodic boundary flags). N must be a positive integer not greater than 30 (which is the built-in maximum supported by this class).

Once the NearestNeighborFinder has been constructed, you can call its find() method to iterate over the sorted list of nearest neighbors of a specific particle, for example:

from ovito.io import import_file
from ovito.data import NearestNeighborFinder

# Load input simulation file.
node = import_file("simulation.dump")
data = node.source

# Initialize neighbor finder object.
# Visit the 12 nearest neighbors of each particle.
N = 12
finder = NearestNeighborFinder(N, data)

# Loop over all input particles:
for index in range(data.number_of_particles):
    print("Nearest neighbors of particle %i:" % index)
    # Iterate over the neighbors of the current particle, starting with the closest:
    for neigh in finder.find(index):
        print(neigh.index, neigh.distance, neigh.delta)

If you want to iterate over all neighbors within a certain cutoff radius of a central particle, use the CutoffNeighborFinder class instead.

find(index)

Returns an iterator that visits the N nearest neighbors of the given particle in order of ascending distance.

Parameters:index (int) – The index of the central particle whose neighbors should be iterated. Particle indices start at 0.
Returns:A Python iterator that visits the N nearest neighbors of the central particle in order of ascending distance. For each visited neighbor the iterator returns an object with the following attributes:
  • index: The index of the current neighbor particle (starting at 0).
  • distance: The distance of the current neighbor from the central particle.
  • distance_squared: The squared neighbor distance.
  • delta: The three-dimensional vector connecting the central particle with the current neighbor (taking into account periodicity).

Note that several periodic images of the same particle may be visited. Thus, the same particle index may appear multiple times in the neighbor list of a central particle. In fact, the central particle may be among its own neighbors in a sufficiently small periodic simulation cell. However, the computed neighbor vector (delta) will be unique for each visited image of a neighboring particle.

The number of neighbors actually visited may be smaller than the requested number, N, if the system contains too few particles and no periodic boundary conditions are used.

class ovito.data.ParticleProperty
Base class:ovito.data.DataObject

A data object that stores the values of a single particle property.

array

This attribute returns a NumPy array, which provides read access to the per-particle data stored in this particle property object.

The returned array is one-dimensional for scalar particle properties (components == 1), or two-dimensional for vector properties (components > 1). The outer length of the array is equal to the number of particles in both cases.

Note that the returned NumPy array is read-only and provides a view of the internal data. No copy of the data, which may be shared by multiple objects, is made. If you want to modify the data stored in this particle property, use marray instead.

changed()

Informs the particle property object that its internal data has changed. This function must be called after each direct modification of the per-particle data through the array attribute.

Calling this method on an input particle property is necessary to invalidate data caches down the modification pipeline. Forgetting to call this method may result in an incomplete re-evaluation of the modification pipeline. See marray for more information.

components

The number of vector components (if this is a vector particle property); otherwise 1 (= scalar property).

static create(prop_type, num_particles)

Static factory function that creates a new ParticleProperty instance for a standard particle property. To create a new user-defined property, use create_user() instead.

Note that this factory function is a low-level method. If you want to add a new particle property to an existing DataCollection, you can do so using the high-level method create_particle_property() instead.

Parameters:
  • prop_type (ParticleProperty.Type) – The standard particle property to create. See the type attribute for a list of possible values.
  • num_particles (int) – The number of particles. This determines the size of the allocated data array.
Returns:

A newly created instance of the ParticleProperty class or one of its sub-classes.

static create_user(name, data_type, num_particles, num_components=1)

Static factory function that creates a new ParticleProperty instance for a user-defined particle property. To create one of the standard properties, use create() instead.

Note that this factory function is a low-level method. If you want to add a new user-defined particle property to an existing DataCollection, you can do so using the high-level method create_user_particle_property() instead.

Parameters:
  • name (str) – The name of the user-defined particle property to create.
  • data_type (str) – Must be either "int" or "float".
  • num_particles (int) – The number of particles. This determines the size of the allocated data array.
  • num_components (int) – The number of components when creating a vector property.
Returns:

A newly created instance of the ParticleProperty class.

marray

This attribute returns a mutable NumPy array providing read/write access to the internal per-particle data.

The returned array is one-dimensional for scalar particle properties (components == 1), or two-dimensional for vector properties (components > 1). The outer length of the array is equal to the number of particles in both cases.

Note

After you are done modifying the data in the returned NumPy array, you must call changed()! Calling this method is necessary to inform the data pipeline system that the input particle data has changed and the modification pipeline needs to be re-evaluated. The reason is that OVITO cannot automatically detect modifications made by the script to the returned NumPy array. Therefore, an explicit call to changed() is necessary.

Example

from ovito.io import import_file
from ovito.modifiers import *

# Load a simulation file.
node = import_file('simulation.dump')
# Set up modification pipeline, which selects and deletes all particle of type 2.
node.modifiers.append(SelectParticleTypeModifier(property='Particle Type', types={2}))
node.modifiers.append(DeleteSelectedParticlesModifier())

# Evaluate modification pipeline the first time.
output1 = node.compute()
print('Number of remaining particles: ', output1.number_of_particles)

# Modify pipeline input by changing the type of the first particle to 2.
node.source.particle_properties.particle_type.marray[0] = 2

# Inform pipeline that input has changed.
# Failing to do so would lead to incorrect results below. OVITO would assume the 
# cached pipeline output is  still valid and wouldn't re-evaluate the modifiers.
node.source.particle_properties.particle_type.changed()

# Evaluate modification pipeline a second time.
# Note that compute() may return cached results if it thinks the 
# pipeline's input hasn't changed since the last call.
output2 = node.compute()
print('Number of remaining particles: ', output2.number_of_particles)
assert(output2.number_of_particles == output1.number_of_particles - 1)
name

The human-readable name of the particle property.

size

The number of particles.

type

The type of the particle property (user-defined or one of the standard types). One of the following constants:

Type constant Property name Data type
ParticleProperty.Type.User (a user-defined property with a non-standard name) int/float
ParticleProperty.Type.ParticleType Particle Type int
ParticleProperty.Type.Position Position float
ParticleProperty.Type.Selection Selection int
ParticleProperty.Type.Color Color float
ParticleProperty.Type.Displacement Displacement float
ParticleProperty.Type.DisplacementMagnitude Displacement Magnitude float
ParticleProperty.Type.PotentialEnergy Potential Energy float
ParticleProperty.Type.KineticEnergy Kinetic Energy float
ParticleProperty.Type.TotalEnergy Total Energy float
ParticleProperty.Type.Velocity Velocity float
ParticleProperty.Type.Radius Radius float
ParticleProperty.Type.Cluster Cluster int
ParticleProperty.Type.Coordination Coordination int
ParticleProperty.Type.StructureType Structure Type int
ParticleProperty.Type.Identifier Particle Identifier int
ParticleProperty.Type.StressTensor Stress Tensor float
ParticleProperty.Type.StrainTensor Strain Tensor float
ParticleProperty.Type.DeformationGradient Deformation Gradient float
ParticleProperty.Type.Orientation Orientation float
ParticleProperty.Type.Force Force float
ParticleProperty.Type.Mass Mass float
ParticleProperty.Type.Charge Charge float
ParticleProperty.Type.PeriodicImage Periodic Image int
ParticleProperty.Type.Transparency Transparency float
ParticleProperty.Type.DipoleOrientation Dipole Orientation float
ParticleProperty.Type.DipoleMagnitude Dipole Magnitude float
ParticleProperty.Type.AngularVelocity Angular Velocity float
ParticleProperty.Type.AngularMomentum Angular Momentum float
ParticleProperty.Type.Torque Torque float
ParticleProperty.Type.Spin Spin float
ParticleProperty.Type.CentroSymmetry Centrosymmetry float
ParticleProperty.Type.VelocityMagnitude Velocity Magnitude float
ParticleProperty.Type.NonaffineSquaredDisplacement Nonaffine Squared Displacement float
ParticleProperty.Type.Molecule Molecule Identifier int
ParticleProperty.Type.AsphericalShape Aspherical Shape float
class ovito.data.ParticleType

Stores the properties of a particle type or atom type.

The list of particle types is stored in the ParticleTypeProperty class.

color

The display color to use for particles of this type.

id

The identifier of the particle type.

name

The display name of this particle type.

radius

The display radius to use for particles of this type.

class ovito.data.ParticleTypeProperty
Base class:ovito.data.ParticleProperty

A special ParticleProperty that stores a list of ParticleType instances in addition to the per-particle values.

The particle properties Particle Type and Structure Type are represented by instances of this class. In addition to the regular per-particle data (consisting of an integer per particle, indicating its type ID), this class holds the list of defined particle types. These are ParticleType instances, which store the ID, name, color, and radius of each particle type.

type_list

A mutable list of ParticleType instances.

class ovito.data.SimulationCell
Base class:ovito.data.DataObject

Stores the geometry and the boundary conditions of the simulation cell.

Instances of this class are associated with a SimulationCellDisplay that controls the visual appearance of the simulation cell. It can be accessed through the display attribute of the DataObject base class.

matrix

A 3x4 matrix containing the three edge vectors of the cell (matrix columns 0-2) and the cell origin (matrix column 3).

pbc

A tuple containing three boolean values, which specify periodic boundary flags of the simulation cell in each of the spatial directions.

class ovito.data.SurfaceMesh
Base class:ovito.data.DataObject

This data object stores the surface mesh computed by a ConstructSurfaceModifier.

Currently, no direct script access to the vertices and faces of the mesh is possible. But you can export the mesh to a VTK text file, which can be further processed by external tools such as ParaView.

The visual appearance of the surface mesh within Ovito is controlled by its attached SurfaceMeshDisplay instance, which is accessible through the display attribute of the DataObject base class or through the mesh_display attribute of the ConstructSurfaceModifier that created the surface mesh.

Example:

from ovito.io import import_file
from ovito.modifiers import ConstructSurfaceModifier

# Load a particle structure and construct its surface mesh:
node = import_file("simulation.dump")
node.modifiers.append(ConstructSurfaceModifier(radius = 2.8))
node.compute()

# Access the computed surface mesh and export it to VTK files for 
# visualization with ParaView.
mesh = node.output.surface
mesh.export_vtk('surface.vtk', node.output.cell)
mesh.export_cap_vtk('surface_cap.vtk', node.output.cell)
export_cap_vtk(filename, cell)

If the surface mesh has been generated from a SimulationCell with periodic boundary conditions, then this method computes the cap polygons from the intersection of the surface mesh with the periodic cell boundaries. The cap polygons are written to a VTK file, which is a simple text-based format and which can be opened with the software ParaView.

export_vtk(filename, cell)

Writes the surface mesh to a VTK file, which is a simple text-based format and which can be opened with the software ParaView. The method takes the output filename and a SimulationCell object as input. The simulation cell information is needed by the method to generate a non-periodic version of the mesh, which is truncated at the periodic boundaries of the simulation cell (if it has any).