ovito.modifiers

This module contains all modifiers available in OVITO. See this introduction page to learn more about modifiers and the data pipeline system of OVITO.

The abstract base class of all modifier types is Modifier. Typically, you create a modifier instance, configure its parameters and insert it into a data Pipeline as follows:

mod = AssignColorModifier()
mod.color = (0.2, 1.0, 0.9)
pipeline.modifiers.append(mod)

The following modifier types are available. Please consult the OVITO user manual for a more in-depth description of what these modifiers do.

Python class name User interface name
AffineTransformationModifier Affine transformation
AmbientOcclusionModifier Ambient occlusion
AssignColorModifier Assign color
AtomicStrainModifier Atomic strain
BinAndReduceModifier Bin and reduce
BondAngleAnalysisModifier Bond-angle analysis
CalculateDisplacementsModifier Displacement vectors
CentroSymmetryModifier Centrosymmetry parameter
ClearSelectionModifier Clear selection
ClusterAnalysisModifier Cluster analysis
ColorCodingModifier Color coding
CombineParticleSetsModifier Combine particle sets
CommonNeighborAnalysisModifier Common neighbor analysis
ComputeBondLengthsModifier Compute bond lengths
ComputePropertyModifier Compute property
ConstructSurfaceModifier Construct surface mesh
CoordinationNumberModifier Coordination analysis
CoordinationPolyhedraModifier Coordination polyhedra
CreateBondsModifier Create bonds
CreateIsosurfaceModifier Create isosurface
DeleteSelectedModifier Delete selected
DislocationAnalysisModifier Dislocation analysis (DXA)
ElasticStrainModifier Elastic strain calculation
ExpandSelectionModifier Expand selection
ExpressionSelectionModifier Expression selection
FreezePropertyModifier Freeze property
HistogramModifier Histogram
IdentifyDiamondModifier Identify diamond structure
InvertSelectionModifier Invert selection
LoadTrajectoryModifier Load trajectory
ManualSelectionModifier Manual selection
PolyhedralTemplateMatchingModifier Polyhedral template matching
PythonScriptModifier Python script
ReplicateModifier Replicate
ScatterPlotModifier Scatter plot
SelectTypeModifier Select type
SliceModifier Slice
VoronoiAnalysisModifier Voronoi analysis
VoroTopModifier VoroTop analysis
WignerSeitzAnalysisModifier Wigner-Seitz defect analysis
WrapPeriodicImagesModifier Wrap at periodic boundaries

Note that some analysis modifiers of the graphical version of OVITO are missing in the list above and are not accessible from Python. That is because they perform computations that can be achieved equally well using the Numpy module in a more straightforward manner.

class ovito.modifiers.PythonScriptModifier
Base class:ovito.pipeline.Modifier

A modifier that allows to plug a custom Python script function into a data pipeline.

This class makes it possible to implement new modifier types in the Python language which can participate in OVITO’s data pipeline system and which may be used like OVITO’s built-in modifiers. You can learn more about the usage of this class in the Writing new modifiers section.

Example:

from ovito.io import import_file
from ovito.modifiers import PythonScriptModifier

# Load some input data:
pipeline = import_file("simulation.dump")

# Define our custom modifier function, which assigns a uniform color 
# to all particles, similar to the built-in AssignColorModifier. 
def assign_color(frame, input, output):
    color_property = output.particle_properties.create('Color')
    with color_property.modify() as colors:
        colors[:] = (0.2, 0.5, 1.0)

# Insert custom modifier into the data pipeline.
pipeline.modifiers.append(PythonScriptModifier(function = assign_color))

# Evaluate data pipeline. This will result in a call to assign_color() from above.
data = pipeline.compute()
print(data.particle_properties['Color'][...])
function

The Python function to be called each time the data pipeline is evaluated by the system.

The function must have a signature as shown in the example above. The frame parameter specifies the current animation frame number at which the data pipeline is being evaluated. The DataCollection input holds the input data objects of the modifier, which were produced by the upstream part of the data pipeline. output is the DataCollection where the function should store its output.

By default, the output data collection already contains all data objects from the input data collection. Thus, without any further action, all data gets passed through the modifier unmodified.

Default:None
class ovito.modifiers.SliceModifier
Base class:ovito.pipeline.Modifier

Deletes or selects data elements in a semi-infinite region bounded by a plane or in a slab bounded by a pair of parallel planes. The modifier can operate on several kinds of data elements:

The modifier will act on all of them by default. Restriction to a subset is possible by setting the operate_on field.

distance

The distance of the slicing plane from the origin (along its normal vector).

Default:0.0
inverse

Reverses the sense of the slicing plane.

Default:False
normal

The normal vector of the slicing plane. Does not have to be a unit vector.

Default:(1,0,0)
only_selected

Controls whether the modifier should act only on currently selected data elements (e.g. selected particles).

Default:False
operate_on

A set of strings specifying the kinds of data elements this modifier should operate on. By default the set contains all data element types supported by the modifier.

Default:{'particles', 'surfaces', 'dislocations'}
select

If True, the modifier selects data elements instead of deleting them.

Default:False
slice_width

The width of the slab to cut. If zero, the modifier cuts away everything on one side of the slicing plane.

Default:0.0
class ovito.modifiers.AffineTransformationModifier
Base class:ovito.pipeline.Modifier

Applies an affine transformation to data elements in order to move, rotate, shear or scale them.The modifier can operate on several kinds of data elements:

  • Particle positions
  • Particle vector properties ('Velocity', 'Force', 'Displacement')
  • Simulation cells (SimulationCell)
  • Surfaces (SurfaceMesh)

The modifier will act on all of them by default. Restriction to a subset is possible by setting the operate_on field. Example:

xy_shear = 0.05
mod = AffineTransformationModifier(
          operate_on = {'particles'},  # Transform particles but not simulation box
          transformation = [[1,xy_shear,0,0],
                            [0,       1,0,0],
                            [0,       0,1,0]])
only_selected

Controls whether the modifier should affect only on currently selected elements (e.g. selected particles).

Default:False
operate_on

A set of strings specifying the kinds of data elements this modifier should operate on. By default the set contains all data element types supported by the modifier.

Default:{'particles', 'vector_properties', 'cell', 'surfaces'}
relative_mode

Selects the operation mode of the modifier.

If relative_mode==True, the modifier transforms elements by applying the matrix given by the transformation parameter.

If relative_mode==False, the modifier transforms elements such that the old simulation cell will have the shape given by the the target_cell parameter after the transformation.

Default:True
target_cell

This 3x4 matrix specifies the target cell shape. It is used when relative_mode == False.

The first three columns of the matrix specify the three edge vectors of the target cell. The fourth column defines the origin vector of the target cell.

transformation

The 3x4 transformation matrix being applied to input elements. The first three matrix columns define the linear part of the transformation, while the fourth column specifies the translation vector.

This matrix describes a relative transformation and is used only if relative_mode == True.

Default:[[ 1.  0.  0.  0.] [ 0.  1.  0.  0.] [ 0.  0.  1.  0.]]
class ovito.modifiers.ClearSelectionModifier
Base class:ovito.pipeline.Modifier

This modifier clears the current selection. It can operate on several kinds of data elements:

The modifier will act on particles only by default. This can be changed by setting the operate_on field.

operate_on

Selects the kind of data elements this modifier operate on. Supported values are: 'particles', 'bonds', 'voxels'.

Default:'particles'
class ovito.modifiers.InvertSelectionModifier
Base class:ovito.pipeline.Modifier

This modifier inverts the current selection. It can operate on several kinds of data elements:

The modifier will act on particles only by default. This can be changed by setting the operate_on field.

operate_on

Selects the kind of data elements this modifier operate on. Supported values are: 'particles', 'bonds', 'voxels'.

Default:'particles'
class ovito.modifiers.ColorCodingModifier
Base class:ovito.pipeline.Modifier

Assigns colors to elements based on some scalar input property to visualize the property values. The modifier can operate on several kinds of data elements:

The modifier will act on particles by default. You can change this by setting the modifier’s operate_on field.

Usage example:

pipeline.modifiers.append(ColorCodingModifier(
    property = 'Potential Energy',
    gradient = ColorCodingModifier.Hot()
))

If the start_value and end_value parameters are not explicitly specified during modifier construction, then the modifier will automatically adjust them to the minimum and maximum values of the input property at the time it is inserted into a data pipeline.

The ColorLegendOverlay may be used in conjunction with a ColorCodingModifier to insert a color legend into rendered images.

Modifier outputs:

end_value

This parameter defines, together with the start_value parameter, the normalization range for mapping the input property values to colors.

gradient
The color gradient object, which is responsible for mapping normalized property values to colors. Available gradient types are:
  • ColorCodingModifier.BlueWhiteRed()
  • ColorCodingModifier.Grayscale()
  • ColorCodingModifier.Hot()
  • ColorCodingModifier.Jet()
  • ColorCodingModifier.Magma()
  • ColorCodingModifier.Rainbow() [default]
  • ColorCodingModifier.Viridis()
  • ColorCodingModifier.Custom("<image file>")

The last color map constructor expects the path to an image file on disk, which will be used to create a custom color gradient from a row of pixels in the image.

only_selected

If True, only selected elements will be affected by the modifier and the existing colors of unselected elements will be preserved; if False, all elements will be colored.

Default:False
operate_on

Selects the kind of data elements this modifier should operate on. Supported values are: 'particles', 'bonds', 'vectors'.

Note: Assigning a new value to this attribute resets the property field.

Default:'particles'
property

The name of the input property that should be used to color elements.

If operate_on is set to 'particles' or 'vectors', this can be one of the standard particle properties or a name of a user-defined ParticleProperty. If operate_on is set to 'bonds', this can be one of the standard bond properties or a name of a user-defined BondProperty.

When the input property has multiple components, then a component name must be appended to the property base name, e.g. "Velocity.X".

Note: Make sure that operate_on is set to the desired value before setting this attribute, because changing operate_on will implicitly reset the property attribute.

start_value

This parameter defines, together with the end_value parameter, the normalization range for mapping the input property values to colors.

class ovito.modifiers.AssignColorModifier
Base class:ovito.pipeline.Modifier

Assigns a uniform color to all selected elements. The modifier can operate on several kinds of data elements:

The modifier will act on particles by default. You can change this by setting the modifier’s operate_on field.

The modifier uses the 'Selection' property as input to decide which elements are being assigned the color. If the 'Selection' property does not exist in the modifier’s input, the color will be assigned to all elements.

color

The uniform RGB color that will be assigned to elements by the modifier.

Default:(0.3, 0.3, 1.0)
operate_on

Selects the kind of data elements this modifier should operate on. Supported values are: 'particles', 'bonds', 'vectors'.

Default:'particles'
class ovito.modifiers.DeleteSelectedModifier
Base class:ovito.pipeline.Modifier

This modifier deletes the currently selected elements of the following kinds:

  • Particles (deleting particles whose 'Selection' property is non-zero)
  • Bonds (deleting bonds whose 'Selection' property is non-zero)

The modifier will act on all of them by default. Restriction to a subset is possible by setting the operate_on field.

operate_on

A set of strings specifying the kinds of data elements this modifier should operate on. By default the set contains all data element types supported by the modifier.

Default:{'particles', 'bonds'}
class ovito.modifiers.SelectTypeModifier
Base class:ovito.pipeline.Modifier

Selects all elements of a certain type (e.g. atoms of a chemical type). The modifier can operate on different kinds of data elements:

  • Particles
  • Bonds

The modifier will act on particles by default. You can change this by setting the modifier’s operate_on field.

Usage example:

from ovito.io import import_file
from ovito.modifiers import SelectTypeModifier, CommonNeighborAnalysisModifier

pipeline = import_file("simulation.dump")

# Insert a CNA modifier to determine the structural type of each atom:
pipeline.modifiers.append(CommonNeighborAnalysisModifier())

# Apply the SelectTypeModifier to select all atoms of FCC and HCP type:
pipeline.modifiers.append(SelectTypeModifier(
    operate_on = "particles",
    property = "Structure Type",
    types = { CommonNeighborAnalysisModifier.Type.FCC,
              CommonNeighborAnalysisModifier.Type.HCP }
))

# The SelectTypeModifier reports the number of selected elements as an attribute:
data = pipeline.compute()
print("Number of FCC/HCP atoms: %i" % data.attributes['SelectType.num_selected'])

Modifier outputs:

  • Selection (ParticleProperty or BondProperty): The output property will be set to 1 for particles/bonds whose type is contained in types and 0 for others.
  • SelectType.num_selected (attribute): The number of elements that were selected by the modifier.
operate_on

Selects the kind of data elements this modifier should select. Supported values are: 'particles', 'bonds'.

Note: Assigning a new value to this attribute resets the property field.

Default:'particles'
property

The name of the property to use as input; must be an integer property.

When selecting particles, possible input properties are 'Particle Type' and 'Structure Type', for example. When selecting bonds, 'Bond Type' is a typical input property for this modifier.

Note: Make sure that operate_on is set to the desired value before setting this attribute, because changing operate_on will implicitly reset the property attribute.

Default:''
types

The set of types to select. You can add numeric type IDs or type names to this set. Type names will automatically be translated into corresponding numeric type IDs by the modifier. Thus, it is not necessary for you to look up the numeric type ID for a type name using ParticleProperty.type_by_name(). For example, to select all atoms belonging to the type named ‘Cu’:

modifier = SelectTypeModifier(property = 'Particle Type', types = {'Cu'})

When using the SelectTypeModifier to select structural types, you can directly use the predefined numeric constants for the structures, e.g.:

# Let the CNA modifier identify the structural type of each particle:
pipeline.modifiers.append(CommonNeighborAnalysisModifier())
# Select all FCC and HCP particles:
modifier = SelectTypeModifier(property = 'Structure Type')
modifier.types = { CommonNeighborAnalysisModifier.Type.FCC,
                   CommonNeighborAnalysisModifier.Type.HCP }
pipeline.modifiers.append(modifier)
Default:set([])
class ovito.modifiers.HistogramModifier
Base class:ovito.pipeline.Modifier

Generates a histogram from the values of a property. The modifier can operate on properties of different kinds of elements:

The modifier will act on particles by default. You can change this by setting the modifier’s operate_on field.

The value range of the histogram is determined automatically from the minimum and maximum values of the selected property unless fix_xrange is set to True. In this case the range of the histogram is controlled by the xrange_start and xrange_end parameters.

Usage example:

from ovito.modifiers import HistogramModifier
from ovito.io import import_file

pipeline = import_file("simulation.dump")

modifier = HistogramModifier(bin_count=100, property='peatom')
pipeline.modifiers.append(modifier)
pipeline.compute()

import numpy
numpy.savetxt("histogram.txt", modifier.histogram)
bin_count

The number of histogram bins.

Default:200
fix_xrange

Controls how the value range of the histogram is determined. If false, the range is chosen automatically by the modifier to include all input values. If true, the range is specified manually using the xrange_start and xrange_end attributes.

Default:False
histogram

Returns a NumPy array containing the histogram computed by the modifier. The returned array is two-dimensional and consists of [x, count(x)] value pairs, where x denotes the bin center and count(x) the number of particles whose property value falls into the bin.

Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call Pipeline.compute() first to ensure that the histogram was generated.

only_selected

If True, the histogram is computed only on the basis of currently selected particles or bonds. You can use this to restrict histogram calculation to a subset of particles/bonds.

Default:False
operate_on

Selects the kind of data elements this modifier operate on. Supported values are: 'particles', 'bonds', 'oxels'.

Note: Assigning a new value to this attribute resets the property field.

Default:'particles'
property

The name of the input property for which to compute the histogram. For vector properties a component name must be appended in the string, e.g. "Velocity.X".

Note: Make sure that operate_on is set to the desired value before setting this attribute, because changing operate_on will implicitly reset the property attribute.

Default:''
xrange_end

If fix_xrange is true, then this specifies the upper end of the value range covered by the histogram.

Default:0.0
xrange_start

If fix_xrange is true, then this specifies the lower end of the value range covered by the histogram.

Default:0.0
class ovito.modifiers.ReplicateModifier
Base class:ovito.pipeline.Modifier

This modifier replicates all particles and bonds to generate periodic images.

adjust_box

Controls whether the simulation cell is resized. If True, the simulation cell is accordingly extended to fit the replicated data. If False, the original simulation cell size (containing only the primary image of the system) is maintained.

Default:True
num_x

A positive integer specifying the number of copies to generate in the x direction (including the existing primary image).

Default:1
num_y

A positive integer specifying the number of copies to generate in the y direction (including the existing primary image).

Default:1
num_z

A positive integer specifying the number of copies to generate in the z direction (including the existing primary image).

Default:1
operate_on

A set of strings specifying the kinds of data elements this modifier should operate on. By default the set contains all data element types supported by the modifier.

Default:{'particles', 'vector_properties', 'cell', 'surfaces'}
unique_ids

If True, the modifier automatically generates new unique IDs for each copy of particles. Otherwise, the replica will keep the same IDs as the original particles, which is typically not what you want.

Note: This option has no effect if the input particles do not already have numeric IDs (i.e. the 'Particle Identifier' property does not exist).

Default:True
ovito.modifiers.DeleteSelectedParticlesModifier

alias of DeleteSelectedModifier

ovito.modifiers.SelectParticleTypeModifier

alias of SelectTypeModifier

ovito.modifiers.ShowPeriodicImagesModifier

alias of ReplicateModifier

class ovito.modifiers.AmbientOcclusionModifier
Base class:ovito.pipeline.Modifier

Performs a quick lighting calculation to shade particles according to the degree of occlusion by other particles.

buffer_resolution

A positive integer controlling the resolution of the internal render buffer, which is used to compute how much light each particle receives. For large datasets, where the size of a particle is small compared to the simulation dimensions, a highezr buffer resolution should be used.

Valid range:[1, 4]
Default:3
intensity

Controls the strength of the shading effect.

Valid range:[0.0, 1.0]
Default:0.7
sample_count

The number of light exposure samples to compute. More samples give a more even light distribution but take longer to compute.

Default:40
class ovito.modifiers.WrapPeriodicImagesModifier
Base class:ovito.pipeline.Modifier

This modifier maps particles located outside the simulation cell back into the box by “wrapping” their coordinates around at the periodic boundaries of the simulation cell. This modifier has no parameters.

class ovito.modifiers.ComputePropertyModifier
Base class:ovito.pipeline.Modifier

Evaluates a user-defined math expression for every particle and assigns the values to a particle property.

Usage example:

pipeline.modifiers.append(ComputePropertyModifier(
    output_property = 'Color',
    expressions = ['Position.X / CellSize.X', '0.0', '0.5']
))

Note that, in many cases, the PythonScriptModifier is the better choice to perform computations on particle properties, unless you need the advanced capabaility of the ComputePropertyModifier to evaluate expressions over the neighbors of a particle.

cutoff_radius

The cutoff radius up to which neighboring particles are visited. This parameter is only used if neighbor_mode is enabled.

Default:3.0
expressions

A list of strings containing the math expressions to compute, one for each vector component of the output property. If the output property is a scalar property, the list should comprise one string only.

Default:["0"]
neighbor_expressions

A list of strings containing the math expressions for the per-neighbor terms, one for each vector component of the output property. If the output property is a scalar property, the list should comprise one string only.

The neighbor expressions are only evaluated if neighbor_mode is enabled.

Default:["0"]
neighbor_mode

Boolean flag that enabled the neighbor computation mode, where contributions from neighbor particles within the cutoff radius are taken into account.

Default:False
only_selected

If True, the property is only computed for selected particles and existing property values are preserved for unselected particles.

Default:False
output_property

The output particle property in which the modifier should store the computed values. This can be one of the standard property names defined by OVITO or a user-defined property name. Note that the modifier can only generate scalar custom properties, but standard properties may be vector properties.

Default:"Custom property"
class ovito.modifiers.FreezePropertyModifier
Base class:ovito.pipeline.Modifier

This modifier obtains the value of a particle property by evaluating the data pipeline at a fixed animation time (frame 0 by default), and injects it back into the pipeline, optionally under a different name than the original property. Thus, the FreezePropertyModifier allows to freeze a dynamically changing property and overwrite its values with those from a fixed point in time.

Example:

from ovito.io import import_file, export_file
from ovito.modifiers import (CoordinationNumberModifier, FreezePropertyModifier,
                            ExpressionSelectionModifier)

# Load a input simulation sequence. 
pl = import_file("simulation.*.dump")

# Add modifier for computing the coordination numbers of particles.
pl.modifiers.append(CoordinationNumberModifier(cutoff = 2.9))

# Save the initial coordination numbers from frame 0 under a new name.
modifier = FreezePropertyModifier(source_property = 'Coordination', 
                                  destination_property = 'Coord0',
                                  freeze_at = 0)
pl.modifiers.append(modifier)

# Select all particles whose coordination number has changed since frame 0
# by comapring the dynamically computed coordination numbers with the frozen ones.
pl.modifiers.append(ExpressionSelectionModifier(expression='Coordination != Coord0'))

# Write out number of particles exhibiting a change in coordination number.
export_file(pl, 'output.txt', 'txt', 
            columns = ['Timestep', 'SelectExpression.num_selected'], 
            multiple_frames = True)
destination_property

The name of the output particle property that should be created by the modifier. It can be one of the standard particle properties or a custom particle property. It may be the same as the source_property. If the destination property already exists in the input, its values are overwritten.

freeze_at

The animation frame number at which to freeze the input property’s values.

Default:0
source_property

The name of the input particle property that should be evaluated by the modifier at the animation frame give by freeze_at. It can be one of the standard particle properties or a custom particle property.

class ovito.modifiers.ExpandSelectionModifier
Base class:ovito.pipeline.Modifier

Expands the current particle selection by selecting particles that are neighbors of already selected particles.

cutoff

The maximum distance up to which particles are selected around already selected particles. This parameter is only used if mode is set to ExpansionMode.Cutoff.

Default:3.2
iterations

Controls how many iterations of the modifier are executed. This can be used to select neighbors of neighbors up to a certain recursive depth.

Default:1
mode

Selects the mode of operation, i.e., how the modifier extends the selection around already selected particles. Valid values are:

  • ExpandSelectionModifier.ExpansionMode.Cutoff
  • ExpandSelectionModifier.ExpansionMode.Nearest
  • ExpandSelectionModifier.ExpansionMode.Bonded
Default:ExpandSelectionModifier.ExpansionMode.Cutoff
num_neighbors

The number of nearest neighbors to select around each already selected particle. This parameter is only used if mode is set to ExpansionMode.Nearest.

Default:1
class ovito.modifiers.ExpressionSelectionModifier
Base class:ovito.pipeline.Modifier

This modifier selects particles based on a user-defined Boolean expression. Those particles will be selected for which the expression yields a non-zero value.

Modifier outputs:

  • Selection (ParticleProperty): This particle property is set to 1 for selected particles and 0 for others.
  • SelectExpression.num_selected (attribute): The number of particles selected by the modifier.

Example:

# Select all atoms with potential energy above -3.6 eV: 
node.modifiers.append(ExpressionSelectionModifier(expression = 'PotentialEnergy > -3.6'))
node.compute()
# Demonstrating two ways to get the number of selected atoms:
print(node.output.attributes['SelectExpression.num_selected'])
print(numpy.count_nonzero(node.output.particle_properties['Selection']))
expression

A string containing the Boolean expression to be evaluated for every particle. The expression syntax is documented in OVITO’s user manual.

class ovito.modifiers.BinAndReduceModifier
Base class:ovito.pipeline.Modifier

This modifier applies a reduction operation to a property of the particles within a spatial bin. The output of the modifier is a one or two-dimensional grid of bin values.

axis_range_x

A 2-tuple containing the range of the generated bin grid along the first binning axis. Note that this is an output attribute which is only valid after the modifier has performed the bin and reduce operation. That means you have to call Pipeline.compute() first to evaluate the data pipeline.

axis_range_y

A 2-tuple containing the range of the generated bin grid along the second binning axis. Note that this is an output attribute which is only valid after the modifier has performed the bin and reduce operation. That means you have to call Pipeline.compute() first to evaluate the data pipeline.

bin_count_x

This attribute sets the number of bins to generate along the first binning axis.

Default:200
bin_count_y

This attribute sets the number of bins to generate along the second binning axis (only used when working with a two-dimensional grid).

Default:200
bin_data

Returns a NumPy array containing the reduced bin values computed by the modifier. Depending on the selected binning direction the returned array is either one or two-dimensional. In the two-dimensional case the outer index of the returned array runs over the bins along the second binning axis.

Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call Pipeline.compute() first to ensure that the binning and reduction operation was performed.

direction

Selects the alignment of the bins. Possible values:

  • BinAndReduceModifier.Direction.Vector_1
  • BinAndReduceModifier.Direction.Vector_2
  • BinAndReduceModifier.Direction.Vector_3
  • BinAndReduceModifier.Direction.Vectors_1_2
  • BinAndReduceModifier.Direction.Vectors_1_3
  • BinAndReduceModifier.Direction.Vectors_2_3

In the first three cases the modifier generates a one-dimensional grid with bins aligned perpendicular to the selected simulation cell vector. In the last three cases the modifier generates a two-dimensional grid with bins aligned perpendicular to both selected simulation cell vectors (i.e. parallel to the third vector).

Default:BinAndReduceModifier.Direction.Vector_3
first_derivative

If true, the modifier numerically computes the first derivative of the binned data using a finite differences approximation. This works only for one-dimensional bin grids.

Default:False
only_selected

If True, the computation takes into account only the currently selected particles. You can use this to restrict the calculation to a subset of particles.

Default:False
property

The name of the input particle property to which the reduction operation should be applied. This can be one of the standard particle properties or a custom particle property. For vector properties the selected component must be appended to the name, e.g. "Velocity.X".

reduction_operation

Selects the reduction operation to be carried out. Possible values are:

  • BinAndReduceModifier.Operation.Mean
  • BinAndReduceModifier.Operation.Sum
  • BinAndReduceModifier.Operation.SumVol
  • BinAndReduceModifier.Operation.Min
  • BinAndReduceModifier.Operation.Max

The operation SumVol first computes the sum and then divides the result by the volume of the respective bin. It is intended to compute pressure (or stress) within each bin from the per-atom virial.

Default:BinAndReduceModifier.Operation.Mean
class ovito.modifiers.CommonNeighborAnalysisModifier
Base class:ovito.pipeline.Modifier

Performs the common neighbor analysis (CNA) to classify the structure of the local neighborhood of each particle.

The modifier stores its results as integer values in the "Structure Type" particle property. The following constants are defined:

  • CommonNeighborAnalysisModifier.Type.OTHER (0)
  • CommonNeighborAnalysisModifier.Type.FCC (1)
  • CommonNeighborAnalysisModifier.Type.HCP (2)
  • CommonNeighborAnalysisModifier.Type.BCC (3)
  • CommonNeighborAnalysisModifier.Type.ICO (4)

Modifier outputs:

  • CommonNeighborAnalysis.counts.OTHER (attribute): The number of particles not matching any of the known structure types.
  • CommonNeighborAnalysis.counts.FCC (attribute): The number of FCC particles found.
  • CommonNeighborAnalysis.counts.HCP (attribute): The number of HCP particles found.
  • CommonNeighborAnalysis.counts.BCC (attribute): The number of BCC particles found.
  • CommonNeighborAnalysis.counts.ICO (attribute): The number of icosahedral particles found.
  • Structure Type (ParticleProperty): This output particle property contains the per-particle structure types assigned by the modifier.
  • Color (ParticleProperty): The modifier assigns a color to each particle according to its identified structure type.
cutoff

The cutoff radius used for the conventional common neighbor analysis. This parameter is only used if mode == CommonNeighborAnalysisModifier.Mode.FixedCutoff.

Default:3.2
mode

Selects the mode of operation. Valid values are:

  • CommonNeighborAnalysisModifier.Mode.FixedCutoff
  • CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
  • CommonNeighborAnalysisModifier.Mode.BondBased
Default:CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
only_selected

Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be treated as if they did not exist.

Default:False
structures

A list of ParticleType instances managed by this modifier, one for each supported structure type. The display color of a structure type can be changed as follows:

modifier = CommonNeighborAnalysisModifier()
# Give all FCC atoms a blue color:
modifier.structures[CommonNeighborAnalysisModifier.Type.FCC].color = (0, 0, 1)

.

class ovito.modifiers.BondAngleAnalysisModifier
Base class:ovito.pipeline.Modifier

Performs the bond-angle analysis described by Ackland & Jones to classify the local crystal structure around each particle.

The modifier stores the results as integer values in the "Structure Type" particle property. The following structure type constants are defined:

  • BondAngleAnalysisModifier.Type.OTHER (0)
  • BondAngleAnalysisModifier.Type.FCC (1)
  • BondAngleAnalysisModifier.Type.HCP (2)
  • BondAngleAnalysisModifier.Type.BCC (3)
  • BondAngleAnalysisModifier.Type.ICO (4)

Modifier outputs:

  • BondAngleAnalysis.counts.OTHER (attribute): The number of particles not matching any of the known structure types.
  • BondAngleAnalysis.counts.FCC (attribute): The number of FCC particles found.
  • BondAngleAnalysis.counts.HCP (attribute): The number of HCP particles found.
  • BondAngleAnalysis.counts.BCC (attribute): The number of BCC particles found.
  • BondAngleAnalysis.counts.ICO (attribute): The number of icosahedral found.
  • Structure Type (ParticleProperty): This particle property will contain the per-particle structure type assigned by the modifier.
  • Color (ParticleProperty): The modifier assigns a color to each particle according to its identified structure type.
structures

A list of ParticleType instances managed by this modifier, one for each supported structure type. The display color of a structure type can be changed as follows:

modifier = BondAngleAnalysisModifier()
# Give all FCC atoms a blue color:
modifier.structures[BondAngleAnalysisModifier.Type.FCC].color = (0, 0, 1)

.

class ovito.modifiers.CreateBondsModifier
Base class:ovito.pipeline.Modifier

Creates bonds between nearby particles. The modifier outputs its results as a Bonds data object, which can be accessed through the DataCollection.bonds attribute of the pipeline output data collection.

Modifier outputs:

  • CreateBonds.num_bonds (attribute): The number of full bonds created by the modifier.
  • Bonds object (DataCollection.bonds): Contains the list of bonds created by the modifier.
bonds_display

The BondsDisplay object controlling the visual appearance of the bonds created by this modifier.

cutoff

The maximum cutoff distance for the creation of bonds between particles. This parameter is only used if mode is Uniform.

Default:3.2
get_pairwise_cutoff(type_a, type_b) → float

Returns the pair-wise cutoff distance set for a pair of atom types.

Parameters:
  • type_a (str) – The name of the first atom type
  • type_b (str) – The name of the second atom type (order doesn’t matter)
Returns:

The cutoff distance set for the type pair. Returns zero if no cutoff has been set for the pair.

intra_molecule_only

If this option is set to true, the modifier will create bonds only between atoms that belong to the same molecule (i.e. which have the same molecule ID assigned to them).

Default:False
lower_cutoff

The minimum bond length. No bonds will be created between atoms whose distance is below this threshold.

Default:0.0
mode

Selects the mode of operation. Valid modes are:

  • CreateBondsModifier.Mode.Uniform
  • CreateBondsModifier.Mode.Pairwise

In Uniform mode one global cutoff is used irrespective of the atom types. In Pairwise mode a separate cutoff distance must be specified for all pairs of atom types between which bonds are to be created.

Default:CreateBondsModifier.Mode.Uniform
set_pairwise_cutoff(type_a, type_b, cutoff)

Sets the pair-wise cutoff distance for a pair of atom types. This information is only used if mode is Pairwise.

Parameters:
  • type_a (str) – The name of the first atom type
  • type_b (str) – The name of the second atom type (order doesn’t matter)
  • cutoff (float) – The cutoff distance to be set for the type pair

If you do not want to create any bonds between a pair of types, set the corresponding cutoff radius to zero (which is the default).

class ovito.modifiers.CentroSymmetryModifier
Base class:ovito.pipeline.Modifier

Computes the centro-symmetry parameter (CSP) of each particle.

The modifier outputs the computed values in the "Centrosymmetry" particle property.

num_neighbors

The number of neighbors to take into account (12 for FCC crystals, 8 for BCC crystals).

Default:12
class ovito.modifiers.ClusterAnalysisModifier
Base class:ovito.pipeline.Modifier

This modifier groups particles into clusters on the basis of a neighboring criterion.

Modifier outputs:

  • Cluster (ParticleProperty): This output particle property stores the IDs of the clusters the particles have been assigned to.
  • ClusterAnalysis.cluster_count (attribute): The total number of clusters produced by the modifier. Cluster IDs range from 1 to this number.
  • ClusterAnalysis.largest_size (attribute): The number of particles belonging to the largest cluster (cluster ID 1). This attribute is only computed by the modifier when sort_by_size is set.

Example:

The following script demonstrates how to apply the numpy.bincount() function to the Cluster particle property generated by the ClusterAnalysisModifier to determine the size (=number of particles) of each cluster.

from ovito.io import import_file
from ovito.modifiers import ClusterAnalysisModifier
import numpy

pipeline = import_file("simulation.dump")
pipeline.modifiers.append(ClusterAnalysisModifier(cutoff = 2.8, sort_by_size = True))
data = pipeline.compute()

cluster_sizes = numpy.bincount(data.particle_properties['Cluster'])
numpy.savetxt("cluster_sizes.txt", cluster_sizes)
cutoff

The cutoff distance used by the algorithm to form clusters of connected particles. This parameter is only used when neighbor_mode is set to CutoffRange; otherwise it is ignored.

Default:3.2
neighbor_mode

Selects the neighboring criterion for the clustering algorithm. Valid values are:

  • ClusterAnalysisModifier.NeighborMode.CutoffRange
  • ClusterAnalysisModifier.NeighborMode.Bonded

In the first mode (CutoffRange), the clustering algorithm treats pairs of particles as neighbors which are within a certain range of each other given by the parameter cutoff.

In the second mode (Bonded), particles which are connected by bonds are combined into clusters. Bonds between particles can either be loaded from the input simulation file or dynamically created using for example the CreateBondsModifier or the VoronoiAnalysisModifier.

Default:ClusterAnalysisModifier.NeighborMode.CutoffRange
only_selected

Lets the modifier perform the analysis only for selected particles. In this case, particles which are not selected are treated as if they did not exist and will be assigned cluster ID 0.

Default:False
sort_by_size

Enables the sorting of clusters by size (in descending order). Cluster 1 will be the largest cluster, cluster 2 the second largest, and so on.

Default:False
class ovito.modifiers.CoordinationNumberModifier
Base class:ovito.pipeline.Modifier

Computes coordination numbers of particles and the radial distribution function (RDF) of the system.

The modifier stores the computed coordination numbers in the "Coordination" particle property.

Example showing how to export the RDF data to a text file:

from ovito.io import import_file
from ovito.modifiers import CoordinationNumberModifier
import numpy

# Load a particle dataset, apply the modifier, and evaluate pipeline.
pipeline = import_file("simulation.dump")
modifier = CoordinationNumberModifier(cutoff = 5.0, number_of_bins = 200)
pipeline.modifiers.append(modifier)
pipeline.compute()

# Export the computed RDF data to a text file.
numpy.savetxt("output_rdf.txt", modifier.rdf)
cutoff

The neighbor cutoff distance.

Default:3.2
number_of_bins

The number of histogram bins to use when computing the RDF.

Default:200
rdf

Returns a NumPy array containing the radial distribution function (RDF) computed by the modifier. The returned array is two-dimensional and consists of the [r, g(r)] data points of the tabulated g(r) RDF function.

Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call Pipeline.compute() first to ensure that this information is up to date, see the example above.

class ovito.modifiers.CalculateDisplacementsModifier
Base class:ovito.pipeline.ReferenceConfigurationModifier

Computes the displacement vectors of particles with respect to a reference configuration.

This modifier class inherits from ReferenceConfigurationModifier, which provides various properties that control how the reference configuration is specified and also how displacement vectors are calculated. By default, frame 0 of the current simulation sequence is used as reference configuration.

Modifier outputs:

vector_display

A VectorDisplay instance controlling the visual representation of the computed displacement vectors. Note that the computed displacement vectors are not shown by default. You can enable the arrow display as follows:

mod = CalculateDisplacementsModifier()
mod.vector_display.enabled = True
mod.vector_display.color = (0,0,0)
class ovito.modifiers.AtomicStrainModifier
Base class:ovito.pipeline.ReferenceConfigurationModifier

Computes the atomic-level deformation with respect to a reference configuration.

This modifier class inherits from ReferenceConfigurationModifier, which provides various properties that control how the reference configuration is specified and also how particle displacements are calculated. By default, frame 0 of the current simulation sequence is used as reference configuration.

Modifier outputs:

  • Shear Strain (ParticleProperty): The von Mises shear strain invariant of the atomic Green-Lagrangian strain tensor.
  • Volumetric Strain (ParticleProperty): One third of the trace of the atomic Green-Lagrangian strain tensor.
  • Strain Tensor (ParticleProperty): The six components of the symmetric Green-Lagrangian strain tensor. Output of this property must be explicitly enabled with the output_strain_tensors flag.
  • Deformation Gradient (ParticleProperty): The nine components of the atomic deformation gradient tensor. Output of this property must be explicitly enabled with the output_deformation_gradients flag.
  • Stretch Tensor (ParticleProperty): The six components of the symmetric right stretch tensor U in the polar decomposition F=RU. Output of this property must be explicitly enabled with the output_stretch_tensors flag.
  • Rotation (ParticleProperty): The atomic microrotation obtained from the polar decomposition F=RU as a quaternion. Output of this property must be explicitly enabled with the output_rotations flag.
  • Nonaffine Squared Displacement (ParticleProperty): The D2min measure of Falk & Langer, which describes the non-affine part of the local deformation. Output of this property must be explicitly enabled with the output_nonaffine_squared_displacements flag.
  • Selection (ParticleProperty): The modifier can select those particles for which a local deformation could not be computed because there were not enough neighbors within the cutoff range. Those particles with invalid deformation values can subsequently be removed using the DeleteSelectedParticlesModifier, for example. Selection of invalid particles is controlled by the select_invalid_particles flag.
  • AtomicStrain.invalid_particle_count (attribute): The number of particles for which the local strain calculation failed because they had not enough neighbors within the cutoff range.
cutoff

Sets the distance up to which neighbor atoms are taken into account in the local strain calculation.

Default:3.0
output_deformation_gradients

Controls the output of the per-particle deformation gradient tensors. If False, the computed tensors are not output as a particle property to save memory.

Default:False
output_nonaffine_squared_displacements

Enables the computation of the squared magnitude of the non-affine part of the atomic displacements. The computed values are output in the "Nonaffine Squared Displacement" particle property.

Default:False
output_rotations

Flag that controls the calculation of the per-particle rotations.

Default:False
output_strain_tensors

Controls the output of the per-particle strain tensors. If False, the computed strain tensors are not output as a particle property to save memory.

Default:False
output_stretch_tensors

Flag that controls the calculation of the per-particle stretch tensors.

Default:False
select_invalid_particles

If True, the modifier selects the particle for which the local strain tensor could not be computed (because of an insufficient number of neighbors within the cutoff).

Default:True
class ovito.modifiers.WignerSeitzAnalysisModifier
Base class:ovito.pipeline.ReferenceConfigurationModifier

Performs the Wigner-Seitz cell analysis to identify point defects in crystals.

Defects are identified with respect to a perfect reference crystal configuration. By default, frame 0 of the current simulation sequence is used as reference configuration. The modifier inherits from the ReferenceConfigurationModifier class, which provides further settings that control the definition of the reference configuration.

Modifier outputs:

  • Occupancy (ParticleProperty): The computed site occupation numbers, one for each particle in the reference configuration.
  • WignerSeitz.vacancy_count (attribute): The total number of vacant sites (having Occupancy == 0).
  • WignerSeitz.interstitial_count (attribute): The total number of of interstitial atoms. This is equal to the sum of occupancy numbers of all non-empty sites minus the number of non-empty sites.

Usage example:

The Occupancy particle property generated by the Wigner-Seitz algorithm allows to select specific types of point defects, e.g. antisites, using OVITO’s selection tools. One option is to use the ExpressionSelectionModifier to pick sites with a certain occupancy. Here we exemplarily demonstrate the alternative use of a custom PythonScriptModifier to select and count A-sites occupied by B-atoms in a binary system with two atom types (A=1 and B=2).

from ovito.io import *
from ovito.data import *
from ovito.modifiers import *
from ovito.pipeline import *
import numpy as np

pipeline = import_file("simulation.*.dump")

# Perform Wigner-Seitz analysis:
ws = WignerSeitzAnalysisModifier(
    per_type_occupancies = True, 
    affine_mapping = ReferenceConfigurationModifier.AffineMapping.ToReference)
pipeline.modifiers.append(ws)

# Define a modifier function that selects sites of type A=1 which
# are occupied by exactly one atom of type B=2.
def modify(frame, input, output):

    # Retrieve the two-dimensional array with the site occupancy numbers.
    # Use [...] to cast it to a Numpy array.
    occupancies = input.particle_properties['Occupancy'][...]
    
    # Get the site types as additional input:
    site_type = input.particle_properties['Particle Type'][...]

    # Calculate total occupancy of every site:
    total_occupancy = np.sum(occupancies, axis=1)

    # Set up a particle selection by creating the Selection property:
    selection = output.create_particle_property(ParticleProperty.Type.Selection)
    
    # Select A-sites occupied by exactly one B-atom (the second entry of the Occupancy
    # array must be 1, and all others 0). Note that the Occupancy array uses 0-based
    # indexing, while atom type IDs are typically 1-based.
    with selection.modify() as sel:
        sel[...] = (site_type == 1) & (occupancies[:,1] == 1) & (total_occupancy == 1)
    
    # Additionally output the total number of antisites as a global attribute:
    output.attributes['Antisite_count'] = np.count_nonzero(selection)

# Insert Python modifier into the data pipeline.
pipeline.modifiers.append(PythonScriptModifier(function = modify))

# Let OVITO do the computation and export the number of identified 
# antisites as a function of simulation time to a text file:
export_file(pipeline, "antisites.txt", "txt", 
    columns = ['Timestep', 'Antisite_count'],
    multiple_frames = True)

# Export the XYZ coordinates of just the antisites by removing all other atoms.
pipeline.modifiers.append(InvertSelectionModifier())
pipeline.modifiers.append(DeleteSelectedParticlesModifier())
export_file(pipeline, "antisites.xyz", "xyz", 
    columns = ['Position.X', 'Position.Y', 'Position.Z'],
    multiple_frames = True)
per_type_occupancies

A parameter flag that controls whether occupancy numbers are determined per particle type.

If false, only the total occupancy number is computed for each reference site, which counts the number of particles that occupy the site irrespective of their types. If true, then the Occupancy property computed by the modifier becomes a vector property with one component per particle type. Each property component counts the number of particles of the corresponding type that occupy a site. For example, the property component Occupancy.1 contains the number of particles of type 1 that occupy a site.

Default:False
class ovito.modifiers.VoronoiAnalysisModifier
Base class:ovito.pipeline.Modifier

Computes the atomic volumes and coordination numbers using a Voronoi tessellation of the particle system.

Modifier outputs:

  • Atomic Volume (ParticleProperty): Stores the computed Voronoi cell volume of each particle.
  • Coordination (ParticleProperty): Stores the number of faces of each particle’s Voronoi cell.
  • Voronoi Index (ParticleProperty): Stores the Voronoi indices computed from each particle’s Voronoi cell. This property is only generated when compute_indices is set.
  • Bonds (Bonds): The list of nearest neighbor bonds, one for each Voronoi face. Bonds are only generated when generate_bonds is set.
  • Voronoi.max_face_order (attribute): This output attribute reports the maximum number of edges of any face in the computed Voronoi tessellation (ignoring edges and faces that are below the area and length thresholds). Note that, if calculation of Voronoi indices is enabled (compute_indices == true), and edge_count < max_face_order, then the computed Voronoi index vectors will be truncated because there exists at least one Voronoi face having more edges than the maximum Voronoi vector length specified by edge_count. In such a case you should consider increasing edge_count (to at least max_face_order) to not lose information because of truncated index vectors.
compute_indices

If True, the modifier calculates the Voronoi indices of particles. The modifier stores the computed indices in a vector particle property named Voronoi Index. The i-th component of this property will contain the number of faces of the Voronoi cell that have i edges. Thus, the first two components of the per-particle vector will always be zero, because the minimum number of edges a polygon can have is three.

Default:False
edge_count

Integer parameter controlling the order up to which Voronoi indices are computed by the modifier. Any Voronoi face with more edges than this maximum value will not be counted! Computed Voronoi index vectors are truncated at the index specified by edge_count.

See the Voronoi.max_face_order output attributes described above on how to avoid truncated Voronoi index vectors.

This parameter is ignored if compute_indices is false.

Minimum:3
Default:6
edge_threshold

Specifies the minimum length an edge must have to be considered in the Voronoi index calculation. Edges that are shorter than this threshold will be ignored when counting the number of edges of a Voronoi face. The threshold parameter is an absolute value in units of length of your input data.

Default:0.0
face_threshold

Specifies a minimum area for individual Voronoi faces in terms of an absolute area. The algorithm will ignore any face of a Voronoi polyhedron with an area smaller than this threshold when computing the coordination number and the Voronoi index of a particle. The threshold parameter is an absolute area given in units of length squared (in whatever units your input data is given).

Note that this absolute area threshold and the relative_face_threshold are applied simultaneously.

Default:0.0
generate_bonds

Controls whether the modifier outputs the nearest neighbor bonds. The modifier will generate a bond for every pair of adjacent atoms that share a face of the Voronoi tessellation. No bond will be created if the face’s area is below the face_threshold or if the face has less than three edges that are longer than the edge_threshold.

Default:False
only_selected

Lets the modifier perform the analysis only for selected particles. Particles that are currently not selected will be treated as if they did not exist.

Default:False
relative_face_threshold

Specifies a minimum area for Voronoi faces in terms of a fraction of total area of the Voronoi polyhedron surface. The algorithm will ignore any face of a Voronoi polyhedron with an area smaller than this threshold when computing the coordination number and the Voronoi index of particles. The threshold parameter is specified as a fraction of the total surface area of the Voronoi polyhedron the faces belong to. For example, a threshold value of 0.01 would remove those faces from the analysis with an area less than 1% of the total area of the polyhedron surface.

Note that this relative threshold and the absolute face_threshold are applied simultaneously.

Default:0.0
use_radii

If True, the modifier computes the poly-disperse Voronoi tessellation, which takes into account the radii of particles. Otherwise a mono-disperse Voronoi tessellation is computed, which is independent of the particle sizes.

Default:False
class ovito.modifiers.IdentifyDiamondModifier
Base class:ovito.pipeline.Modifier

This analysis modifier finds atoms that are arranged in a cubic or hexagonal diamond lattice.

The modifier stores its results as integer values in the "Structure Type" particle property. The following structure type constants are defined:

  • IdentifyDiamondModifier.Type.OTHER (0)
  • IdentifyDiamondModifier.Type.CUBIC_DIAMOND (1)
  • IdentifyDiamondModifier.Type.CUBIC_DIAMOND_FIRST_NEIGHBOR (2)
  • IdentifyDiamondModifier.Type.CUBIC_DIAMOND_SECOND_NEIGHBOR (3)
  • IdentifyDiamondModifier.Type.HEX_DIAMOND (4)
  • IdentifyDiamondModifier.Type.HEX_DIAMOND_FIRST_NEIGHBOR (5)
  • IdentifyDiamondModifier.Type.HEX_DIAMOND_SECOND_NEIGHBOR (6)

Modifier outputs:

  • IdentifyDiamond.counts.OTHER (attribute): The number of atoms not matching any of the known structure types.
  • IdentifyDiamond.counts.CUBIC_DIAMOND (attribute): The number of cubic diamond atoms found.
  • IdentifyDiamond.counts.CUBIC_DIAMOND_FIRST_NEIGHBOR (attribute): The number of atoms found that are first neighbors of a cubic diamond atom.
  • IdentifyDiamond.counts.CUBIC_DIAMOND_SECOND_NEIGHBOR (attribute): The number of atoms found that are second neighbors of a cubic diamond atom.
  • IdentifyDiamond.counts.HEX_DIAMOND (attribute): The number of hexagonal diamond atoms found.
  • IdentifyDiamond.counts.HEX_DIAMOND_FIRST_NEIGHBOR (attribute): The number of atoms found that are first neighbors of a hexagonal diamond atom.
  • IdentifyDiamond.counts.HEX_DIAMOND_SECOND_NEIGHBOR (attribute): The number of atoms found that are second neighbors of a hexagonal diamond atom.
  • Structure Type (ParticleProperty): This particle property will contain the per-particle structure type assigned by the modifier.
  • Color (ParticleProperty): The modifier assigns a color to each atom according to its identified structure type.
only_selected

Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be treated as if they did not exist.

Default:False
structures

A list of ParticleType instances managed by this modifier, one for each supported structure type. The display color of a structure type can be changed as follows:

modifier = BondAngleAnalysisModifier()
# Give all hexagonal diamond atoms a blue color:
modifier.structures[IdentifyDiamondModifier.Type.HEX_DIAMOND].color = (0, 0, 1)

.

class ovito.modifiers.LoadTrajectoryModifier
Base class:ovito.pipeline.Modifier

This modifier loads trajectories of particles from a separate simulation file.

A typical usage scenario for this modifier is when the topology of a molecular system (i.e. the definition of atom types, bonds, etc.) is stored separately from the trajectories of atoms. In this case you should load the topology file first using import_file(). Then create and apply the LoadTrajectoryModifier to the topology dataset, which loads the trajectory file. The modifier will replace the static atom positions from the topology dataset with the time-dependent positions from the trajectory file.

Example:

from ovito.io import import_file
from ovito.modifiers import LoadTrajectoryModifier

# Load static topology data from a LAMMPS data file.
pipeline = import_file('input.data', atom_style = 'bond')

# Load atom trajectories from separate LAMMPS dump file.
traj_mod = LoadTrajectoryModifier()
traj_mod.source.load('trajectory.dump', multiple_frames = True)

# Insert modifier into data pipeline.
pipeline.modifiers.append(traj_mod)
source

A FileSource that provides the trajectories of particles. You can call its load() function to load a simulation trajectory file as shown in the code example above.

class ovito.modifiers.CombineParticleSetsModifier
Base class:ovito.pipeline.Modifier

This modifier loads a set of particles from a separate simulation file and merges them into the current dataset.

Example:

from ovito.io import import_file, export_file
from ovito.modifiers import CombineParticleSetsModifier

# Load a first set of particles.
pipeline = import_file('first_file.dump')

# Insert the particles from a second file into the dataset. 
modifier = CombineParticleSetsModifier()
modifier.source.load('second_file.dump')
pipeline.modifiers.append(modifier)

# Export combined dataset to a new file.
export_file(pipeline, 'output.dump', 'lammps/dump',
            columns = ['Position.X', 'Position.Y', 'Position.Z'])
source

A FileSource that provides the set of particles to be merged. You can call its load() function to load a data file as shown in the code example above.

class ovito.modifiers.ComputeBondLengthsModifier
Base class:ovito.pipeline.Modifier

Computes the length of every bond in the system and outputs the values as a new bond property named Length.

Modifier outputs:

  • Length (BondProperty): The output bond property containing the length of each bond.
class ovito.modifiers.PolyhedralTemplateMatchingModifier
Base class:ovito.pipeline.Modifier

Uses the Polyhedral Template Matching (PTM) method to classify the local structural neighborhood of each particle.

The modifier stores its results as integer values in the "Structure Type" particle property. The following constants are defined:

  • PolyhedralTemplateMatchingModifier.Type.OTHER (0)
  • PolyhedralTemplateMatchingModifier.Type.FCC (1)
  • PolyhedralTemplateMatchingModifier.Type.HCP (2)
  • PolyhedralTemplateMatchingModifier.Type.BCC (3)
  • PolyhedralTemplateMatchingModifier.Type.ICO (4)
  • PolyhedralTemplateMatchingModifier.Type.SC (5)

Modifier outputs:

  • PolyhedralTemplateMatching.counts.OTHER (attribute): The number of particles not matching any of the known structure types.

  • PolyhedralTemplateMatching.counts.FCC (attribute): The number of FCC particles found.

  • PolyhedralTemplateMatching.counts.HCP (attribute): The number of HCP particles found.

  • PolyhedralTemplateMatching.counts.BCC (attribute): The number of BCC particles found.

  • PolyhedralTemplateMatching.counts.ICO (attribute): The number of icosahedral particles found.

  • PolyhedralTemplateMatching.counts.SC (attribute): The number of simple cubic particles found.

  • Structure Type (ParticleProperty): This output particle property will contain the per-particle structure types assigned by the modifier.

  • RMSD (ParticleProperty): This particle property will contain the per-particle RMSD values computed by the PTM method. The modifier will output this property only if the output_rmsd flag is set.

  • Interatomic Distance (ParticleProperty): This particle property will contain the local interatomic distances computed by the PTM method. The modifier will output this property only if the output_interatomic_distance flag is set.

  • Orientation (ParticleProperty): This particle property will contain the local lattice orientations computed by the PTM method encoded as quaternions. The modifier will generate this property only if the output_orientation flag is set.

  • Elastic Deformation Gradient (ParticleProperty): This particle property will contain the local elastic deformation gradient tensors computed by the PTM method. The modifier will output this property only if the output_deformation_gradient flag is set.

  • Alloy Type (ParticleProperty): This output particle property contains the alloy type assigned to particles by the modifier. (only if the output_alloy_types flag is set). The alloy types get stored as integer values in the "Alloy Type" particle property. The following alloy type constants are defined:

    • PolyhedralTemplateMatchingModifier.AlloyType.NONE (0)
    • PolyhedralTemplateMatchingModifier.AlloyType.PURE (1)
    • PolyhedralTemplateMatchingModifier.AlloyType.L10 (2)
    • PolyhedralTemplateMatchingModifier.AlloyType.L12_CU (3)
    • PolyhedralTemplateMatchingModifier.AlloyType.L12_AU (4)
    • PolyhedralTemplateMatchingModifier.AlloyType.B2 (5)
  • Color (ParticleProperty): The modifier assigns a color to each particle based on its identified structure type. You can change the color representing a structural type as follows:

    modifier = PolyhedralTemplateMatchingModifier()
    # Give all FCC atoms a blue color:
    modifier.structures[PolyhedralTemplateMatchingModifier.Type.FCC].color = (0.0, 0.0, 1.0)
    
only_selected

Lets the modifier perform the analysis only on the basis of currently selected particles. Unselected particles will be treated as if they did not exist.

Default:False
output_alloy_types

Boolean flag that controls whether the modifier identifies localalloy types and outputs them to the pipeline.

Default:False
output_deformation_gradient

Boolean flag that controls whether the modifier outputs the computed per-particle elastic deformation gradients to the pipeline.

Default:False
output_interatomic_distance

Boolean flag that controls whether the modifier outputs the computed per-particle interatomic distance to the pipeline.

Default:False
output_orientation

Boolean flag that controls whether the modifier outputs the computed per-particle lattice orientation to the pipeline.

Default:False
output_rmsd

Boolean flag that controls whether the modifier outputs the computed per-particle RMSD values to the pipeline.

Default:False
rmsd_cutoff

The maximum allowed root mean square deviation for positive structure matches. If the cutoff is non-zero, template matches that yield a RMSD value above the cutoff are classified as “Other”. This can be used to filter out spurious template matches (false positives).

If this parameter is zero, no cutoff is applied.

Default:0.0
structures

A list of ParticleType instances managed by this modifier, one for each structural type. You can adjust the color of structural types as shown in the code example above.

class ovito.modifiers.CoordinationPolyhedraModifier
Base class:ovito.pipeline.Modifier

Constructs coordination polyhedra around currently selected particles. A coordination polyhedron is the convex hull spanned by the bonded neighbors of a particle.

polyhedra_display

A SurfaceMeshDisplay instance controlling the visual representation of the generated polyhedra.

ovito.modifiers.SelectExpressionModifier

alias of ExpressionSelectionModifier

class ovito.modifiers.ConstructSurfaceModifier
Base class:ovito.pipeline.Modifier

Constructs the geometric surface of a solid made of point-like particles. The modifier generates a SurfaceMesh, which is a closed manifold consisting of triangles. It also computes the total surface area and the volume of the region enclosed by the surface mesh.

The radius parameter controls how many details of the solid shape are resolved during surface construction. A larger radius leads to a surface with fewer details, reflecting only coarse features of the surface topology. A small radius, on the other hand, will resolve finer surface features and small pores in the interior of a solid, for example.

See [A. Stukowski, JOM 66 (2014), 399-407] for a description of the surface construction algorithm.

Modifier outputs:

  • SurfaceMesh: The surface mesh computed by the modifier.
  • ConstructSurfaceMesh.surface_area (attribute): The area of the surface mesh.
  • ConstructSurfaceMesh.solid_volume (attribute): The volume of the solid region bounded by the surface mesh.

Example:

from ovito.io import import_file
from ovito.data import SurfaceMesh, SimulationCell
from ovito.modifiers import ConstructSurfaceModifier

# Load a particle structure and reconstruct its geometric surface:
pipeline = import_file("simulation.dump")
pipeline.modifiers.append(ConstructSurfaceModifier(radius = 2.9))
data = pipeline.compute()
mesh = data.expect(SurfaceMesh)
cell = data.expect(SimulationCell)

# Query computed surface properties:
print("Surface area: %f" % data.attributes['ConstructSurfaceMesh.surface_area'])
print("Solid volume: %f" % data.attributes['ConstructSurfaceMesh.solid_volume'])
fraction = data.attributes['ConstructSurfaceMesh.solid_volume'] / cell.volume
print("Solid volume fraction: %f" % fraction)

# Export the surface triangle mesh to a VTK file.
mesh.export_vtk('surface.vtk', cell)
mesh_display

The SurfaceMeshDisplay controlling the visual representation of the computed surface.

only_selected

If True, the modifier acts only on selected particles and ignores other particles; if False, the modifier constructs the surface around all particles.

Default:False
radius

The radius of the probe sphere used in the surface construction algorithm.

A rule of thumb is that the radius parameter should be slightly larger than the typical distance between nearest neighbor particles.

Default:4.0
smoothing_level

The number of iterations of the smoothing algorithm applied to the computed surface mesh.

Note that the smoothing level does only affect the computed surface area but not the solid volume. That is because the solid volume is computed before smoothing the mesh. (Smoothing is supposed to be volume preserving.)

Default:8
class ovito.modifiers.DislocationAnalysisModifier
Base class:ovito.pipeline.Modifier

This analysis modifier extracts all dislocations in a crystal and converts them to continuous line segments. The computational method behind this is called Dislocation Extraction Algorithm (DXA) and is described in the paper [MSMSE 20 (2012), 085007].

The extracted dislocation lines are output as a DislocationNetwork object by the modifier and can be accessed through the DataCollection.dislocations field after the modification pipeline has been evaluated. This is demonstrated in the example script below.

Furthermore, you can use the export_file() function to write the dislocation lines to a so-called CA file. The CA file format is described in the documentation section of the OVITO user manual for the Dislocation Analysis modifier.

Modifier outputs:

  • DataCollection.dislocations (DislocationNetwork): This property of the output data collection provides access to the dislocation lines found by the modifier. See the example script below.
  • DislocationAnalysis.total_line_length (attribute): The total length of all dislocation lines found by the DXA.
  • DislocationAnalysis.length.1/n<ijk> (attribute): The modifier outputs a set of attributes that indicate the length of dislocations broken down by Burgers vector type. For example, the attribute DislocationAnalysis.length.1/6<112> specifies the total amount of Shockley partials found by the DXA.
  • DislocationAnalysis.length.other (attribute): The length of dislocation lines with an unusual Burgers vector that do not belong to any of the predefined standard dislocation types.
  • DislocationAnalysis.cell_volume (attribute): The volume of the simulation cell. This is output for convenience to enable the calculation of dislocation densities from the line length.
  • DislocationAnalysis.counts.OTHER (attribute): The number of particles not matching any of the known structure types.
  • DislocationAnalysis.counts.FCC (attribute): The number of particles with local FCC structure.
  • DislocationAnalysis.counts.HCP (attribute): The number of particles with local HCP structure.
  • DislocationAnalysis.counts.BCC (attribute): The number of particles with local BCC structure.
  • DislocationAnalysis.counts.CubicDiamond (attribute): The number of particles with local cubic diamond structure.
  • DislocationAnalysis.counts.HexagonalDiamond (attribute): The number of particles with local hexagonal diamond structure.

Example:

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

pipeline = import_file("simulation.dump")

# Extract dislocation lines from a crystal with diamond structure:
modifier = DislocationAnalysisModifier()
modifier.input_crystal_structure = DislocationAnalysisModifier.Lattice.CubicDiamond
pipeline.modifiers.append(modifier)
data = pipeline.compute()

total_line_length = data.attributes['DislocationAnalysis.total_line_length']
cell_volume = data.attributes['DislocationAnalysis.cell_volume']
print("Dislocation density: %f" % (total_line_length / cell_volume))

# Print list of dislocation lines:
network = data.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)

# Export dislocation lines to a CA file:
export_file(pipeline, "dislocations.ca", "ca")

# Or export dislocations to a ParaView file:
export_file(pipeline, "dislocations.vtk", "vtk/disloc")
circuit_stretchability

The number of steps by which a Burgers circuit can stretch while it is being advanced along a dislocation line.

Default:9
defect_mesh_smoothing_level

Specifies the number of iterations of the surface smoothing algorithm to perform when post-processing the extracted defect mesh.

Default:8
input_crystal_structure

The type of crystal to analyze. Must be one of:

  • DislocationAnalysisModifier.Lattice.FCC
  • DislocationAnalysisModifier.Lattice.HCP
  • DislocationAnalysisModifier.Lattice.BCC
  • DislocationAnalysisModifier.Lattice.CubicDiamond
  • DislocationAnalysisModifier.Lattice.HexagonalDiamond
Default:DislocationAnalysisModifier.Lattice.FCC
line_coarsening_enabled

Flag that enables the coarsening of extracted dislocation lines, which reduces the number of sample points along the lines.

Default:True
line_point_separation

Sets the desired distance between successive sample points along the dislocation lines, measured in multiples of the interatomic spacing. This parameter controls the amount of coarsening performed during post-processing of dislocation lines.

Default:2.5
line_smoothing_enabled

Flag that enables the smoothing of extracted dislocation lines after they have been coarsened.

Default:True
line_smoothing_level

The number of iterations of the line smoothing algorithm to perform.

Default:1
only_perfect_dislocations

This flag controls whether the algorithm should extract only perfect dislocations (and no partial dislocations, which is normally done for FCC/HCP and diamond lattices). Make sure you set the circuit_stretchability parameter to a high value when activating this option, because large Burgers circuits are needed to identify dissociated dislocations with a wide core.

Default:False
trial_circuit_length

The maximum length of trial Burgers circuits constructed by the DXA to discover dislocations. The length is specified in terms of the number of atom-to-atom steps.

Default:14
class ovito.modifiers.ElasticStrainModifier
Base class:ovito.pipeline.Modifier

This modifier computes the atomic-level elastic strain and deformation gradient tensors in crystalline systems.

The modifier first performs an identification of the local crystal structure and stores the results in the Structure Type particle property. Possible structure type values are listed under the input_crystal_structure property. Atoms that do not form a crystalline structure or which are part of defects are assigned the special type OTHER (=0). For these atoms the local elastic deformation cannot be computed.

If calculate_deformation_gradients is set to true, the modifier outputs a new particle property named Elastic Deformation Gradient, which contains the per-atom elastic deformation gradient tensors. Each tensor has nine components stored in column-major order. Atoms for which the elastic deformation gradient could not be determined (i.e. which are classified as OTHER) will be assigned the null tensor.

If calculate_strain_tensors is set to true, the modifier outputs a new particle property named Elastic Strain, which contains the per-atom elastic strain tensors. Each symmetric strain tensor has six components stored in the order XX, YY, ZZ, XY, XZ, YZ. Atoms for which the elastic strain tensor could not be determined (i.e. which are classified as OTHER) will be assigned the null tensor.

Furthermore, the modifier generates a particle property Volumetric Strain, which stores the trace divided by three of the local elastic strain tensor. Atoms for which the elastic strain tensor could not be determined (i.e. which are classified as OTHER) will be assigned a value of zero.

axial_ratio

The c/a ratio of the ideal unit cell for crystals with hexagonal symmetry.

Default:sqrt(8/3)
calculate_deformation_gradients

Flag that enables the output of the calculated elastic deformation gradient tensors. The per-particle tensors will be stored in a new particle property named Elastic Deformation Gradient with nine components (stored in column-major order). Particles for which the local elastic deformation cannot be calculated, are assigned the null tensor.

Default:False
calculate_strain_tensors

Flag that enables the calculation and out of the elastic strain tensors. The symmetric strain tensors will be stored in a new particle property named Elastic Strain with six components (XX, YY, ZZ, XY, XZ, YZ).

Default:True
input_crystal_structure

The type of crystal to analyze. Must be one of:

  • ElasticStrainModifier.Lattice.FCC
  • ElasticStrainModifier.Lattice.HCP
  • ElasticStrainModifier.Lattice.BCC
  • ElasticStrainModifier.Lattice.CubicDiamond
  • ElasticStrainModifier.Lattice.HexagonalDiamond
Default:ElasticStrainModifier.Lattice.FCC
lattice_constant

Lattice constant (a0) of the ideal unit cell.

Default:1.0
push_strain_tensors_forward

Selects the frame in which the elastic strain tensors are calculated.

If true, the Eulerian-Almansi finite strain tensor is computed, which measures the elastic strain in the global coordinate system (spatial frame).

If false, the Green-Lagrangian strain tensor is computed, which measures the elastic strain in the local lattice coordinate system (material frame).

Default:True
class ovito.modifiers.CreateIsosurfaceModifier
Base class:ovito.pipeline.Modifier

Generates an isosurface from a field defined on a structured data grid (voxel data).

Modifier outputs:

  • SurfaceMesh: The isosurface mesh generted by the modifier.
isolevel

The value at which to create the isosurface.

Default:0.0
mesh_display

The SurfaceMeshDisplay controlling the visual representation of the generated isosurface.

property

The name of the voxel property from which the isosurface should be constructed.

class ovito.modifiers.VoroTopModifier
Base class:ovito.pipeline.Modifier

This modifier uses the Voronoi cell topology of particles to characterize their local environments [Lazar, Han, Srolovitz, PNAS 112:43 (2015)].

The Voronoi cell of a particle is the region of space closer to it than to any other particle. The topology of the Voronoi cell is the manner in which its faces are connected, and describes the manner in which a particle’s neighbors are arranged. The topology of a Voronoi cell can be completely described in a vector of integers called a Weinberg vector [Weinberg, IEEE Trans. Circuit Theory 13:2 (1966)].

This modifier requires loading a filter, which specifies structure types and associated Weinberg vectors. Filters for several common structures can be obtained from the VoroTop website. The modifier calculates the Voronoi cell topology of each particle, uses the provided filter to determine the structure type, and stores the results in the Structure Type particle property. This allows the user to subsequently select particles of a certain structural type, e.g. by using the SelectParticleTypeModifier.

This method is well-suited for analyzing finite-temperature systems, including those heated to their bulk melting temperatures. This robust behavior relieves the need to quench a sample (such as by energy minimization) prior to analysis. Further information about the Voronoi topology approach for local structure analysis, as well as additional filters, can be found on the VoroTop webpage.

Modifier outputs:

  • Structure Type (ParticleProperty): This output particle property contains the integer structure type computed by the modifier for each particle.
  • Color (ParticleProperty): The modifier assigns a color to each particle to indicate its identified structure type.
filter_file

Path to the filter definition file used by the modifier. Filters files are available from the VoroTop website.

Default:''
only_selected

Lets the modifier take into account only selected particles. Particles that are currently not selected will be treated as if they did not exist.

Default:False
structures

A list of ParticleType instances managed by this modifier, one for each structural type loaded from the filter_file.

use_radii

If True, the modifier computes the poly-disperse Voronoi tessellation, which takes into account the radii of particles. Otherwise a mono-disperse Voronoi tessellation is computed, which is independent of the particle sizes.

Default:False