OVITO 2.9 Migration Guide

This page describes important changes to the Python programming interface introduced with new OVITO 3.0 program releases. It is supposed to help script authors adapt their old scripts to the most recent version of the Python API.

Migrating from OVITO 2.9 to 3.0

Release 3 of OVITO introduces significant changes to the Python programming interface. Various classes and methods have been deprecated and replaced with new facilities. The old interfaces of OVITO 2 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 as far as possible. Thus, in many cases, old Python scripts written for OVITO 2 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

The ovito.ObjectNode class has been renamed to Pipeline and moved to the new ovito.pipeline module.

The StaticSource is a special type of data source for a Pipeline and can hold a set of data objects that should be processed by the pipeline. The FileSource class maintains its role as the main data source type for pipelines, reading the input data from an external file.

The 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()

Pipeline.compute() returns a new DataCollection containing the output data of the pipeline after evaluating any modifiers that are currently part of the pipeline.

The DataCollection class

The new 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()

The properties .number_of_particles, .number_of_half_bonds and .number_of_full_bonds have been deprecated. Instead, these numbers are now reported by the count attribute of the Particles and the Bonds container objects:

num_particles = data.particles.count
num_bonds = data.particles.bonds.count

Particle and bond properties

The ParticleProperty and BondProperty classes have been replaced with the generic Property class, which provides the functionality common to all property types in OVITO. The PropertyContainer class has been introduced as a generic container type for Property objects. OVITO knows several specializations of this generic container type, e.g. Particles, Bonds, VoxelGrid and DataTable, that each represent different collections of elements.

The ovito.data.Particles container behaves like a dictionary of particle properties, providing key-based access to the Property objects it manages.

The ParticleProperty.array and ParticleProperty.marray attributes for accessing property values have been deprecated. Instead, the Property class itself now behaves like a regular Numpy array:

# Read access:
pos_property = data.particles['Position']
assert(len(pos_property) == data.particles.count)
print('XYZ coordinates of first particle:', pos_property[0])

# Write access:
pos_property = data.particles_['Position_']
pos_property[0] += displacement

Simulation cells

The SimulationCell class now behaves like a Numpy matrix array of shape (3,4), providing direct access to the cell vectors and the cell origin. The old array and marray accessor attributes have been deprecated:

# Expand cell along y-direction by scaling second cell vector
data.cell_[:,1] *= 1.05


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.

The ovito.data.Bonds container class stores the bond topology as a standard Property named 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))

The Bonds.Enumerator helper class has been renamed to BondsEnumerator.

File I/O

The 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, import_file() now 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.

The ovito.io.export_file() function now accepts not only a Pipeline object which generates the data to be exported, but alternatively also any DataCollection or individual data objects.

Some of the file format names accepted by export_file() have been renamed and the new vtk/trimesh has been added, which allows you to export a SurfaceMesh to a VTK geometry file.

The FileSource.loaded_file attribute has been removed. The path of the input data file is now accessible as an attribute of the DataCollection interface, e.g.:

pipeline = import_file('input.dump')
data = pipeline.compute()

The old DataCollection.to_ase_atoms() and DataCollection.create_from_ase_atoms() methods have been refactored into the new ovito.io.ase module and are now standalone functions named ovito_to_ase() and ase_to_ovito(). The latter requires that the caller provides an existing data collection object as destination for the atoms data, e.g. a StaticSource instance.

Changes to the global DataSet class

The ovito.DataSet class has been renamed to ovito.Scene and the singleton class instance is now accessible as global variable ovito.scene.

The DataSet.selected_node and DataSet.scene_nodes fields have been renamed to Scene.selected_pipeline and Scene.pipelines respectively.

The 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

The RenderSettings class and the Viewport.render() method have been deprecated. Instead, the Viewport class now supports the new render_image() and render_anim() methods, which directly accept the required render settings as keyword function parameters.

Changes to the PythonViewportOverlay class

The signature of user-defined overlay functions has been changed. The PythonViewportOverlay now passes a single parameter of the PythonViewportOverlay.Arguments 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

The 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 DataVis base class.

SurfaceMesh data object

The SurfaceMesh class has been greatly extended. It now provides access to the periodic 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 ovito.io.export_file() function ('vtk/trimesh' output format).

Furthermore, the SurfaceMesh class now provides the locate_point() method, 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.

© 2020 OVITO GmbH.