ovito.modifiers

This module contains all modifiers of OVITO.

The abstract base class of all modifier types is the Modifier class. Typically you create a modifier instance, set its parameters, and finally insert it into a modification pipeline, e.g.:

from ovito.modifiers import *
m = AssignColorModifier()
m.color = (0.2, 1.0, 0.9)
node.modifiers.append(m)

The following modifier types are available:

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
CommonNeighborAnalysisModifier Common neighbor analysis
ConstructSurfaceModifier Construct surface mesh
CoordinationNumberModifier Coordination analysis
CreateBondsModifier Create bonds
ComputePropertyModifier Compute property
DeleteSelectedParticlesModifier Delete selected particles
DislocationAnalysisModifier Dislocation analysis (DXA)
ElasticStrainModifier Elastic strain calculation
ExpandSelectionModifier Expand selection
FreezePropertyModifier Freeze property
HistogramModifier Histogram
IdentifyDiamondModifier Identify diamond structure
InvertSelectionModifier Invert selection
ManualSelectionModifier Manual selection
PythonScriptModifier Python script
ScatterPlotModifier Scatter plot
SelectExpressionModifier Expression select
SelectParticleTypeModifier Select particle type
ShowPeriodicImagesModifier Show periodic images
SliceModifier Slice
VoronoiAnalysisModifier Voronoi analysis
WignerSeitzAnalysisModifier Wigner-Seitz defect analysis
WrapPeriodicImagesModifier Wrap at periodic boundaries

Note that some analysis modifiers are not accssible from Python. In most cases this is because they do things that can be directly achieved using the Numpy python module.

class ovito.modifiers.AffineTransformationModifier
Base class:ovito.modifiers.Modifier

Applies an affine transformation to particles and/or the simulation cell.

Example:

from ovito.modifiers import *

xy_shear = 0.05
mod = AffineTransformationModifier(
          transform_particles = True,
          transform_box = True,
          transformation = [[1,xy_shear,0,0],
                            [0,       1,0,0],
                            [0,       0,1,0]])
only_selected

If True, the modifier acts only on selected particles; if False, the modifier acts on all particles.

Default:False
relative_mode

Selects the operation mode of the modifier.

If relative_mode==True, the modifier transforms the particles and/or the simulation cell by applying the matrix given by the transformation parameter.

If relative_mode==False, the modifier transforms the particles and/or the simulation cell 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.

transform_box

If True, the modifier transforms the simulation cell.

Default:False
transform_particles

If True, the modifier transforms the particle positions.

Default:True
transform_surface

If True, the modifier transforms the surface mesh (if any) that has previously been generated by a ConstructSurfaceModifier.

Default:True
transformation

The 3x4 transformation matrix being applied to particle positions and/or the simulation cell. 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.AmbientOcclusionModifier
Base class:ovito.modifiers.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. When the number of particles is large, a larger buffer resolution should be used.

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

A number controlling the strength of the applied 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.AssignColorModifier
Base class:ovito.modifiers.Modifier

Assigns a uniform color to all selected particles. If no particle selection is defined (i.e. the "Selection" particle property does not exist), the modifier assigns the color to all particles.

color

The color that will be assigned to particles.

Default:(0.3,0.3,1.0)
class ovito.modifiers.AtomicStrainModifier
Base class:ovito.modifiers.Modifier

Computes the atomic strain tensors of particles based on a separate reference configuration. The modifier requires you to load a reference configuration from an external file:

from ovito.modifiers import *

modifier = AtomicStrainModifier()
modifier.reference.load("frame0000.dump")

The modifier stores the computed per-particle strain tensors in the "Strain Tensor" particle property (only if output_strain_tensors == True). The computed deformation gradient tensors are output in the "Deformation Gradient" particle property (only if output_deformation_gradients == True). The von Mises shear strain invariants are stored in the "Shear Strain" property. The hydrostatic component of the strain tensors gets stored in the "Volumetric Strain" property.

assume_unwrapped_coordinates

If True, the particle coordinates of the reference and of the current configuration are taken as is. If False, the minimum image convention is used to deal with particles that have crossed a periodic boundary.

Default:False
cutoff

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

Default:3.0
eliminate_cell_deformation

Boolean flag that controls the elimination of the affine cell deformation prior to calculating the local strain.

Default:False
frame_offset

The relative frame offset when using a sliding reference configuration (use_frame_offset==True).

Default:-1
invalid_particle_count

After the modifier has computed the atomic strain tensors this field contains the number of particles for which the strain calculation failed. Note that accessing this value is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

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_strain_tensors

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

Default:False
reference

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

reference_frame

The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if use_frame_offset==False.

Default:0
select_invalid_particles

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

Default:True
use_frame_offset

Determines whether a sliding reference configuration is taken at a constant time offset (specified by frame_offset) relative to the current frame. If False, a constant reference configuration is used (set by the reference_frame parameter) irrespective of the current frame.

Default:False
class ovito.modifiers.BinAndReduceModifier
Base class:ovito.modifiers.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 ovito.ObjectNode.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 ovito.ObjectNode.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 ovito.ObjectNode.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
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.BondAngleAnalysisModifier
Base class:ovito.modifiers.Modifier

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

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

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

For example, to count the number of FCC atoms in a system:

from ovito.modifiers import *

modifier = BondAngleAnalysisModifier()
node.modifiers.append(modifier)
node.compute()
print("Number of FCC atoms: %i" % modifier.counts[BondAngleAnalysisModifier.Type.FCC])

Furthermore, the modifier assigns a color to particles based on their structural types. You can change the color of a structural type as shown in the following example:

modifier = BondAngleAnalysisModifier()
node.modifiers.append(modifier)

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

# Select all disordered atoms:
node.modifiers.append(SelectParticleTypeModifier(
    property = ParticleProperty.Type.StructureType,
    types = { BondAngleAnalysisModifier.Type.OTHER }
))
counts

A list of integers indicating the number of particles found for each structure type. Note that accessing this output field is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

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.CalculateDisplacementsModifier
Base class:ovito.modifiers.Modifier

Computes the displacement vectors of particles based on a separate reference configuration. The modifier requires you to load a reference configuration from an external file:

from ovito.modifiers import *

modifier = CalculateDisplacementsModifier()
modifier.reference.load("frame0000.dump")

The modifier stores the computed displacement vectors in the "Displacement" particle property. The displacement magnitudes are stored in the "Displacement Magnitude" property.

assume_unwrapped_coordinates

If True, the particle coordinates of the reference and of the current configuration are taken as is. If False, the minimum image convention is used to deal with particles that have crossed a periodic boundary.

Default:False
eliminate_cell_deformation

Boolean flag that controls the elimination of the affine cell deformation prior to calculating the displacement vectors.

Default:False
frame_offset

The relative frame offset when using a sliding reference configuration (use_frame_offset==True).

Default:-1
reference

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

reference_frame

The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if use_frame_offset==False.

Default:0
use_frame_offset

Determines whether a sliding reference configuration is taken at a constant time offset (specified by frame_offset) relative to the current frame. If False, a constant reference configuration is used (set by the reference_frame parameter) irrespective of the current frame.

Default:False
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:

modifier = CalculateDisplacementsModifier()
modifier.vector_display.enabled = True
modifier.vector_display.color = (0,0,0)
class ovito.modifiers.CentroSymmetryModifier
Base class:ovito.modifiers.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.ClearSelectionModifier
Base class:ovito.modifiers.Modifier

This modifier clears the particle selection by deleting the "Selection" particle property. It has no parameters.

class ovito.modifiers.ClusterAnalysisModifier
Base class:ovito.modifiers.Modifier

Groups particles into clusters.

The modifier stores the assigned cluster IDs in the "Cluster" particle property.

count

This output field contains the number of clusters found. Note that accessing this value is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

cutoff

The cutoff radius used when forming clusters.

Default:3.2
class ovito.modifiers.ColorCodingModifier
Base class:ovito.modifiers.Modifier

Colors particles based on the values of an arbitrary particle property.

Usage example:

from ovito.modifiers import *

modifier = ColorCodingModifier(
    property = "Potential Energy",
    gradient = ColorCodingModifier.Hot()
)
node.modifiers.append(modifier)

If, as in the example above, the start_value and end_value parameters are not explicitly set, then the modifier automatically adjusts them to the minimum and maximum values of the particle property when the modifier is inserted into the modification pipeline.

end_value

This parameter defines the value range when mapping the input property to a color.

gradient
The color gradient object, which is responsible for mapping normalized property values to colors. Available gradient types are:
  • ColorCodingModifier.Rainbow() (default)
  • ColorCodingModifier.Grayscale()
  • ColorCodingModifier.Hot()
  • ColorCodingModifier.Jet()
  • ColorCodingModifier.BlueWhiteRed()
  • 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 particles will be affected by the modifier and the existing colors of unselected particles will be preserved; if False, all particles will be colored.

Default:False
property

The name of the input property that should be used to color particles. This can be one of the standard particle properties or a custom particle property. When using vector properties the component must be included in the name, e.g. "Velocity.X".

start_value

This parameter defines the value range when mapping the input property to a color.

class ovito.modifiers.CommonNeighborAnalysisModifier
Base class:ovito.modifiers.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)

For example, the following code counts the number of FCC atoms in the system:

from ovito.modifiers import *

modifier = CommonNeighborAnalysisModifier()
node.modifiers.append(modifier)
node.compute()
print("Number of FCC atoms: %i" % modifier.counts[CommonNeighborAnalysisModifier.Type.FCC])

Furthermore, the modifier assigns a color to particles based on their structural types. You can change the color of a structural type as shown in the following example:

modifier = CommonNeighborAnalysisModifier()
node.modifiers.append(modifier)

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

# Select all disordered atoms:
node.modifiers.append(SelectParticleTypeModifier(
    property = ParticleProperty.Type.StructureType,
    types = { CommonNeighborAnalysisModifier.Type.OTHER }
))
counts

A list of integers indicating the number of particles found for each structure type. Note that accessing this output field is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

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
structures

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

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

Evaluates a user-defined math expression to compute the values of a particle property.

Example:

from ovito.modifiers import *

modifier = ComputePropertyModifier()
modifier.output_property = "Color"
modifier.expressions = ["Position.X / CellSize.X", "0.0", "0.5"]
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 exactly one string.

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 exactly one string.

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.

Default:"Custom property"
class ovito.modifiers.ConstructSurfaceModifier
Base class:ovito.modifiers.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 inside a solid, for example.

See this article for a description of the surface construction algorithm.

Example:

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

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

# Query surface properties:
print("Surface area: %f" % mod.surface_area)
print("Solid volume: %f" % mod.solid_volume)
print("Solid volume fraction: %f" % (mod.solid_volume/mod.total_volume))

# Export the surface mesh to a VTK file.
mesh = node.output.surface
mesh.export_vtk('surface.vtk', node.output.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.

Default:8
solid_volume

After the modifier has computed the surface, this output field contains the volume of the solid region enclosed by the surface.

Note that this value is only available after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

surface_area

After the modifier has computed the surface, this output field contains the area of the surface.

Note that this value is only available after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

total_volume

This output field reports the volume of the input simulation cell, which can be used to calculate the solid volume fraction or porosity of a system (in conjunction with the solid_volume computed by the modifier).

class ovito.modifiers.CoordinationNumberModifier
Base class:ovito.modifiers.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.

cutoff

The neighbor cutoff distance.

Default:3.2
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) function.

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

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

Creates bonds between nearby particles. The modifier outputs its computation results as a Bonds data object.

bonds_display

A BondsDisplay instance controlling the visual appearance of the bonds created by this modifier.

cutoff

The cutoff distance for the creation of bonds between particles.

Default:3.2
intra_molecule_only

If this option is set to true, the modifier will create bonds only between atoms that belong to the same molecule.

Default:False
class ovito.modifiers.DeleteSelectedParticlesModifier
Base class:ovito.modifiers.Modifier

This modifier deletes the selected particles. It has no parameters.

class ovito.modifiers.DislocationAnalysisModifier
Base class:ovito.modifiers.Modifier

This analysis modifier extracts all dislocations in a crystal and converts them to continuous line segments. The method behind this is called Dislocation Extraction Algorithm (DXA).

The extracted dislocation lines are returned as a DislocationNetwork object, which will be present in the output DataCollection of the node after the modification pipeline has been evaluated.

Usage example:

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

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

# Print list of dislocation lines:
network = node.output.dislocations
print("Found %i dislocation segments" % len(network.segments))
for segment in network.segments:
    print("Segment %i: length=%f, Burgers vector=%s" % (segment.id, segment.length, segment.true_burgers_vector))
    print(segment.points)
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
reconstruct_edge_vectors

Flag that enables the reconstruction of ideal lattice vectors in highly distorted crystal regions. This algorithm step is supposed to improve the identification of dislocations in some situations, but it may have undesirable side effect. Use with care, only for experts!

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.modifiers.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.ExpandSelectionModifier
Base class:ovito.modifiers.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.HistogramModifier
Base class:ovito.modifiers.Modifier

Generates a histogram from the values of a particle property.

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.

Example:

from ovito.modifiers import *
modifier = HistogramModifier(bin_count=100, property="Potential Energy")
node.modifiers.append(modifier)
node.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 particle property 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 ovito.ObjectNode.compute() first to ensure that the histogram was generated.

property

The name of the input particle property for which to compute the histogram. This can be one of the standard particle properties or a custom particle property. For vector properties a specific component name must be included in the string, e.g. "Velocity.X".

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.IdentifyDiamondModifier
Base class:ovito.modifiers.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 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)

For example, to count the number of cubic diamond atoms in a system:

from ovito.modifiers import *

modifier = IdentifyDiamondModifier()
node.modifiers.append(modifier)
node.compute()
print("Number of cubic diamond atoms:")
print(modifier.counts[IdentifyDiamondModifier.Type.CUBIC_DIAMOND])
counts

A list of integers indicating the number of particles found for each structure type. Note that accessing this output field is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

structures

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

class ovito.modifiers.InvertSelectionModifier
Base class:ovito.modifiers.Modifier

This modifier inverts the particle selection. It has no parameters.

class ovito.modifiers.Modifier

This is the base class for all modifiers in OVITO.

enabled

Controls whether the modifier is applied to the input data. Modifiers which are not enabled are skipped even if they are part of a modification pipeline.

Default:True
class ovito.modifiers.PythonScriptModifier
Base class:ovito.modifiers.Modifier

A modifier that executes a Python script function which computes the output of the modifier.

This class makes it possible to implement new modifier types in Python which can participate in OVITO’s data pipeline system and which may be used like OVITO’s standard 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
from ovito.data import ParticleProperty

# Load input data and create an ObjectNode with a modification pipeline.
node = import_file("simulation.dump")

# Define our custom modifier function, which assigns a uniform color 
# to all particles, just like the built-in Assign Color modifier. 
def assign_color(frame, input, output):
    color_property = output.create_particle_property(ParticleProperty.Type.Color)
    color_property.marray[:] = (0.0, 0.5, 1.0)

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

The Python function to be called every time the modification pipeline is evaluated by the system.

The function must have a signature as shown in the example above. The frame parameter contains 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 modification pipeline. output is the DataCollection where the modifier function should store the modified or newly generated data objects. This data objects in this collection flow down the modification pipeline and are eventually rendered in the viewports.

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

Default:None
script

The source code of the user-defined Python script, which is executed by the modifier and which defines the modify() function. Note that this property returns the source code entered by the user through the graphical user interface, not the callable Python function.

If you want to set the modification script function from an already running Python script, you should set the function property instead as demonstrated in the example above.

class ovito.modifiers.SelectExpressionModifier
Base class:ovito.modifiers.Modifier

This modifier selects particles based on a user-defined Boolean expression.

Example:

from ovito.modifiers import SelectExpressionModifier

mod = SelectExpressionModifier(expression = 'PotentialEnergy > 3.6')
node.modifiers.append(mod)
expression

A string with a Boolean expression. The syntax is documented in OVITO’s user manual.

class ovito.modifiers.SelectParticleTypeModifier
Base class:ovito.modifiers.Modifier

Selects all particles of a certain type (or types).

Example:

from ovito.modifiers import *

modifier = SelectParticleTypeModifier()
modifier.property = "Structure Type"
modifier.types = { CommonNeighborAnalysisModifier.Type.FCC,
                   CommonNeighborAnalysisModifier.Type.HCP }
property

The name of the integer particle property to be used as input, which contains the particle types. This can be a standard particle property such as "Particle Type" or "Structure Type", or a custom particle property.

Default:"Particle Type"
types

A Python set of integers, which specifies the particle types to select.

Default:set([])
class ovito.modifiers.ShowPeriodicImagesModifier
Base class:ovito.modifiers.Modifier

This modifier replicates all particles to display periodic images of the system.

adjust_box

A boolean flag controlling the modification of the simulation cell geometry. If True, the simulation cell is extended to fit the multiplied system. If False, the original simulation cell (containing only the primary image of the system) is kept.

Default:False
num_x

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

Default:3
num_y

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

Default:3
num_z

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

Default:3
replicate_x

Enables replication of particles along x.

Default:False
replicate_y

Enables replication of particles along y.

Default:False
replicate_z

Enables replication of particles along z.

Default:False
unique_ids

If True, the modifier automatically generates a new unique ID for each copy of a particle. This option has no effect if the input system does not contain particle IDs.

Default:True
class ovito.modifiers.SliceModifier
Base class:ovito.modifiers.Modifier

Deletes or selects particles based on a plane in three-dimensional space.

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

If True, the modifier acts only on selected particles; if False, the modifier acts on all particles.

Default:False
select

If True, the modifier selects particles instead of deleting them.

Default:False
slice_width

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

Default:0.0
class ovito.modifiers.VoronoiAnalysisModifier
Base class:ovito.modifiers.Modifier

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

The modifier stores the computed per-particle volumes in the "Atomic Volume" particle property and the number of neighbors of each particle in the "Coordination" property.

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 max_face_order output property 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.

Default:0.0
face_threshold

Specifies a minimum area for faces of a Voronoi cell. The modifier will ignore any Voronoi cell faces with an area smaller than this threshold when computing the coordination number and the Voronoi index of particles.

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
max_face_order

This is an output value computed by the modifier, which 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 accessing this property is only possible after the modifier has computed the Voronoi tessellation, i.e. after the modification pipeline has been evaluated. That means you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

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.

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
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.WignerSeitzAnalysisModifier
Base class:ovito.modifiers.Modifier

Performs the Wigner-Seitz cell analysis to identify point defects in crystals. The modifier requires you to load a reference configuration from an external file:

from ovito.modifiers import *

mod = WignerSeitzAnalysisModifier()
mod.reference.load("frame0000.dump")
node.modifiers.append(mod)
node.compute()
print("Number of vacant sites: %i" % mod.vacancy_count)

The modifier stores the computed occupation numbers in the "Occupancy" particle property. The number of vacancies and the number of interstitial sites found by the modifier are reported in the vacancy_count and interstitial_count output fields.

eliminate_cell_deformation

Boolean flag that controls the elimination of the affine cell deformation prior to performing the analysis.

Default:False
frame_offset

The relative frame offset when using a sliding reference configuration (use_frame_offset==True).

Default:-1
interstitial_count

After the modifier has performed the analysis, this field contains the number of interstitial atoms. Note that accessing this value is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

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
reference

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

reference_frame

The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if use_frame_offset==False.

Default:0
use_frame_offset

Determines whether a sliding reference configuration is taken at a constant time offset (specified by frame_offset) relative to the current frame. If False, a constant reference configuration is used (set by the reference_frame parameter) irrespective of the current frame.

Default:False
vacancy_count

After the modifier has performed the analysis, this field contains the number of vacant sites. Note that accessing this value is only possible after the modifier has computed its results. Thus, you have to call ovito.ObjectNode.compute() first to ensure that this information is up to date.

class ovito.modifiers.WrapPeriodicImagesModifier
Base class:ovito.modifiers.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.