API version changes¶
This page documents changes to the Python programming interface introduced with new OVITO program releases. It is supposed to help script authors adapt their scripts to the most recent version of the Python API.
Migrating from OVITO 2.x to 3.0¶
Release 3 of OVITO introduces significant interface changes. Various classes and methods have been deprecated and replaced with new facilities. The old interfaces of OVITO 2.x no longer show up in the Python reference documentation, however, a backward compatibility layer has been put in place to support execution of old scripts. Thus, in many cases, old Python scripts written for OVITO 2.x should still work, at least for now, but it is recommended to update them in order to use the new programming interfaces described in the following. The backward compatibility layer will be removed in a future version of OVITO.
Data pipelines and data sources¶
StaticSource is a special type of data source for a
and can hold a set of data objects that should be processed by the pipeline. The
class maintains its role as the main data source type for pipelines, reading the input data from an external file.
ObjectNode.output field has been removed. It used to provide access to the cached results of the data pipeline
after a call to
ObjectNode.compute(). Now the computation results should be requested using
compute() and stored in a local variable instead:
pipeline = import_file('simulation.dump') ... data = pipeline.compute()
objects field exposes all objects in a data collection as an unordered list.
You can insert/remove data objects using standard Python list manipulation statements, e.g.:
cell = SimulationCell() data.objects.append(cell) data.objects.remove(cell)
been deprecated. Instead, these numbers are now reported by the
Particles and the
Bonds container objects:
num_particles = data.particles.count num_bonds = data.particles.bonds.count
Particle and bond properties¶
BondProperty classes have been replaced with the generic
Property class, which provides the functionality common to all property types in OVITO.
PropertyContainer class has been introduced as a generic container type for
Property objects. OVITO knows several specializations of this generic container type,
DataSeries, that each represent different collections of elements.
for accessing property values have been deprecated. Instead, the
Property object itself now behaves like a Numpy array:
pos_property = data.particles['Position'] assert(len(pos_property) == data.particles.count) print('XYZ position of first particle:', pos_property)
Note, however, that
Property is not a true Numpy array subclass; it just mimics the Numpy array
interface to some extent. You can turn it into true Numpy array if needed in two ways:
pos_array = numpy.asarray(pos_property) pos_array = pos_property[...]
In both cases no data copy is made. The Numpy array will be a view of the internal memory of the
To modify the data stored in a
Property, write access must be explicitly requested using a Python
with pos_property: pos_property = (0,0,0)
ParticleProperty.marray accessor attribute and a
call to the removed
ParticleProperty.changed() method to finalize the write transaction are no longer needed.
SimulationCell class now behaves like a read-only Numpy array of shape (3,4), providing direct
access to the cell vectors and the cell origin. The old
marray accessor attributes have been deprecated.
Write access to the cell matrix now requires a
cell = data.cell_ with cell: cell[:,1] *= 1.1 # Expand cell along y-direction by scaling second cell vector
OVITO 3.x no longer works with a half-bond representation. Older program versions represented each full bond A<–>B as two individual half-bonds A–>B and B–>A. Now, only a single record per bond is maintained by OVITO.
ovito.data.Bonds container class stores the bond topology as a standard
Topology, which is a N x 2 array of integer indices into the particles list:
topology = data.particles.bonds['Topology'] assert(topology.shape == (data.particles.bonds.count, 2))
Bonds.Enumerator helper class has been renamed to
ovito.io.import_file() function no longer requires the
multiple_frames flag to load simulation files
containing more than one frame. Detection of multi-timestep files happens automatically now. Furthermore,
supports loading file sequences that are specified as an explicit list of file paths. This makes it possible to
load sets of files that are distributed over everal directories as single animation sequence.
FileSource.loaded_file attribute has been removed. The path of the input data file is now accessible as an attribute
DataCollection interface, e.g.:
pipeline = import_file('input.dump') data = pipeline.compute() print(data.attributes['SourceFile'])
have been refactored into the new
ovito.io.ase module and are now standalone functions named
ase_to_ovito(). The latter requires that the caller provides an existing data collection object
as destination for the atoms data, e.g. a
Changes to the global
AnimationSettings class and the
DataSet.anim attribute have been deprecated.
Because of this, scripts no longer have control over the current time slider position. To determine the number of
loaded animation frames, use the
FileSource.num_frames attribute instead.
Changes to modifiers¶
Several modifier classes have been renamed in OVITO 3.0:
Old modifier name:
New modifier name:
The following modifier classes have been generalized and gained a new
operate_on field that controls what kind(s) of data elements (e.g. particles,
bonds, voxel data, etc.) the modifier should act on:
Changes to rendering functions¶
RenderSettings class and the
Viewport.render() method have been deprecated.
Viewport class now supports the new
render_anim() methods, which directly accept the required render settings as keyword function
Changes to the PythonViewportOverlay class¶
The signature of user-defined overlay functions has been changed. The
now passes a single parameter of the
type to the user function, which contains all necessary information. This helper class also provides additional utility methods for
projecting points from 3d space to 2d screen space, which may be used by the user-defined overlay function.
Changes to display objects¶
Display base class has been renamed to
DataVis. Instead of display objects, the documentation now uses the term
visual elements. The
ovito.vis module provides various visual element types, each derived from the common
SurfaceMesh data object¶
SurfaceMesh class has been greatly extended. It now provides access to
domain the surface mesh is embedded in as well as the vertices and faces
of the mesh. Export of the triangle mesh to a VTK file is now performed using the standard
'vtk/trimesh' output format).
SurfaceMesh class now provides the
which can be used to determine whether a spatial point is located on the surface manifold, inside the region enclosed by the surface, or outside.