ovito.modifiers
¶
This module contains all modifiers available in OVITO. See the introduction page to learn more about modifiers and their role in the data pipeline system.
This is a table of all modifiers with their Python class name and their name in the graphical user interface of OVITO. Please consult the OVITO user manual for a more in-depth description of what each of these modifiers does.
Python class name |
User interface name |
---|---|
Ackland-Jones analysis |
|
Affine transformation |
|
Ambient occlusion |
|
Assign color |
|
Atomic strain |
|
Displacement vectors |
|
Centrosymmetry parameter |
|
Chill+ |
|
Clear selection |
|
Cluster analysis |
|
Color coding |
|
Combine datasets |
|
Common neighbor analysis |
|
Compute property |
|
Construct surface mesh |
|
Coordination analysis |
|
Coordination polyhedra |
|
Create bonds |
|
Create isosurface |
|
Delete selected |
|
Dislocation analysis (DXA) |
|
Elastic strain calculation |
|
Expand selection |
|
Expression selection |
|
Freeze property |
|
Generate trajectory lines |
|
Histogram |
|
Identify diamond structure |
|
Interpolate trajectory |
|
Invert selection |
|
Load trajectory |
|
Polyhedral template matching |
|
Python script |
|
Replicate |
|
Select type |
|
Slice |
|
Spatial binning |
|
Spatial correlation function |
|
Voronoi analysis |
|
VoroTop analysis |
|
Wigner-Seitz defect analysis |
|
Wrap at periodic boundaries |
Note that some modifiers of the graphical version of OVITO are missing from this list and are not accessible from Python scripts. That is because they perform simple operations that can be accomplished equally well or even easier using other means in Python.
-
class
ovito.modifiers.
PythonScriptModifier
¶ - Base class
Allows you to insert a user-defined Python function into a data pipeline.
This class makes it possible to implement new modifier functions in the Python language which can participate in OVITO’s data pipeline system and which can be used just like OVITO’s built-in modifiers. You can learn more about the usage of this class in the User-defined modifiers section.
Example:
from ovito.io import import_file # Load some input data: pipeline = import_file("input/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, data): color_property = data.particles_.create_property('Color') color_property[:] = (0.2, 0.5, 1.0) # Insert the user-defined modifier function into the data pipeline. pipeline.modifiers.append(assign_color) # Note that appending the Python function to the pipeline is equivalent to # creating a PythonScriptModifier instance and appending it: # # pipeline.modifiers.append(PythonScriptModifier(function = assign_color)) # Evaluate data pipeline. This will make the system invoke assign_color(). data = pipeline.compute() print(data.particles.colors[...])
-
property
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
data initially holds the input data objects of the modifier, which were produced by the upstream part of the data pipeline. The user-defined modifier function is free modify the data collection and the data objects stored in it.- Default
None
-
class
ovito.modifiers.
SliceModifier
¶ - Base class
Deletes or selects data elements located within a semi-infinite region bounded by a plane or within a slab bounded by a pair of parallel planes. See also the corresponding user manual page for more information.
Inputs:
The modifier can operate on any combination of the following data elements:
Data element
particles
Deletes (or selects) particles.
surfaces
Cuts the mesh geometry of a
SurfaceMesh
.dislocations
Cuts dislocation lines of a
DislocationNetwork
.By default the modifier will act on all of these. You can restrict it to a subset by setting the
operate_on
field. Furthermore, you can restrict the operation to only selected particles by setting theonly_selected
option.The
select
option lets you select all elements on one side of the plane instead of deleting them. Currently, the selection mode only works for particles, which get selected by setting theirSelection
particle property to 1.-
property
distance
¶ The distance of the slicing plane from the origin (along its normal vector).
- Default
0.0
-
property
inverse
¶ Reverses the sense of the slicing plane.
- Default
False
-
property
normal
¶ The normal vector of the slicing plane. Does not have to be a unit vector.
- Default
(1,0,0)
-
property
only_selected
¶ Controls whether the modifier should act only on currently selected data elements (e.g. selected particles).
- Default
False
-
property
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'}
-
property
plane_vis
¶ A
TriMeshVis
object controlling the visual appearance of the cutting plane in rendered images. It is only used whenrender_plane
has been set toTrue
.
-
property
render_plane
¶ Controls whether the modifier should produce renderable geometry to visualize the cutting plane. The visual appearance of the plane can be adjusted through the
plane_vis
element.- Default
False
-
property
select
¶ If
True
, the modifier selects data elements instead of deleting them.- Default
False
-
property
slab_width
¶ The thicknes of the slab to cut. If zero, the modifier cuts away everything on one side of the cutting plane.
- Default
0.0
-
class
ovito.modifiers.
AffineTransformationModifier
¶ - Base class
This modifier applies an affine transformation to data elements in order to move, rotate, shear or scale them. See also the corresponding user manual page for more information.
Inputs:
The modifier can operate on any combination of the following data elements:
Data element
particles
Transforms the
Position
particle property.vector_properties
Transforms the vectorial particle properties (
Velocity
,Force
,Displacement
).cell
Transforms the
SimulationCell
.surfaces
Transforms
SurfaceMesh
objects.dislocations
Transforms a
DislocationNetwork
.By default the modifier will act on all of these. You can restrict it to a subset by setting the
operate_on
field.Example:
xy_shear = 0.05 mod = AffineTransformationModifier( operate_on = {'particles'}, # Transform particles but not the box transformation = [[1, xy_shear, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0]])
-
property
only_selected
¶ Controls whether the modifier should affect only on currently selected elements (e.g. selected particles).
- Default
False
-
property
operate_on
¶ A set of strings specifying the kinds of data elements this modifier should act on. By default the set includes all types of data elements supported by the modifier.
- Default
{'particles', 'vector_properties', 'cell', 'surfaces', 'dislocations'}
-
property
relative_mode
¶ Selects the operation mode of the modifier.
If
relative_mode
==True
, the modifier transforms data elements by applying the specifiedtransformation
matrix.If
relative_mode
==False
, the modifier determines the transformation dynamically from the current shape of theSimulationCell
and the specifiedtarget_cell
matrix. The former will be mapped to the latter by the transformation.- Default
True
-
property
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 specifies the origin vector of the target cell.
The following code shows how to scale the simulation box, whose shape may vary with simulation time, back to the initial shape at frame 0, including the cell’s contents. As a result, the output dataset generated by the modifier will have a constant simulation cell size.
pipeline = import_file("input/simulation.*.dump") modifier = AffineTransformationModifier( relative_mode = False, target_cell = pipeline.compute(0).cell[...] ) pipeline.modifiers.append(modifier)
-
property
transformation
¶ The 3x4 transformation matrix to apply to input elements. The first three matrix columns define the linear part of the transformation. 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
This modifier clears the current selection by removing the
Selection
property from aPropertyContainer
such that subsequent modifiers in the pipeline won’t see it. See also the corresponding user manual page for more information. The modifier can operate on different kinds of data elements:Data element
particles
Removes the
Selection
property of particles.bonds
Removes the
Selection
property of bonds.voxels
Removes the
Selection
property of voxel grid cells.By default the modifier will act on particles. You can change this by setting the
operate_on
field.-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'voxels'
.- Default
'particles'
-
class
ovito.modifiers.
InvertSelectionModifier
¶ - Base class
This modifier inverts the current data element selection. See also the corresponding user manual page for more information. The modifier can operate on different kinds of data elements:
Data element
particles
Inverts the values of the
Selection
particle property.bonds
Inverts the values of the
Selection
bond property.voxels
Inverts the values of the
Selection
voxel grid property.By default the modifier will act on particles. You can change this by setting the
operate_on
field.-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'voxels'
.- Default
'particles'
-
class
ovito.modifiers.
ColorCodingModifier
¶ - Base class
Colors elements to visualize one of their properties. See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Sets the
Color
property of particles.vectors
Sets the
Vector Color
property of particles.bonds
Sets the
Color
property of bonds.voxels
Sets the
Color
property of voxel grid cells.By default the modifier will act on particles. You can change this by setting the
operate_on
field.Example:
pipeline.modifiers.append(ColorCodingModifier( property = 'Potential Energy', gradient = ColorCodingModifier.Hot() ))
If the
start_value
andend_value
parameters are not explicitly specified during modifier construction, the modifier will automatically set them to the minimum and maximum of the input property (at time of insertion into the data pipeline).The
ColorLegendOverlay
may be used in conjunction with aColorCodingModifier
to insert a color legend into rendered images.-
property
end_value
¶ This parameter defines, together with the
start_value
parameter, the normalization range for mapping the input property values to colors.
-
property
gradient
¶ The color gradient used to map 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.Gradient(Nx3 array)
ColorCodingModifier.Image("<image file path>")
The
Gradient
constructor lets you define your own coloring scheme and takes an array of dimensions N x 3 containing a table of colors (RGB values in the range [0-1]). The color coding modifier will linearly interpolate between the N colors of the table. TheImage
constructor expects the path to an image file on disk, which will be used to create a custom color gradient from the first row of pixels in the image.Code example:
color_table = [ (1.0, 0.0, 0.0), # red (1.0, 1.0, 0.0), # yellow (1.0, 1.0, 1.0) # white ] modifier = ColorCodingModifier( property = 'Position.X', gradient = ColorCodingModifier.Gradient(color_table) )
-
property
only_selected
¶ If
True
, only selected elements will be affected by the modifier and the existing colors of unselected elements will be preserved; ifFalse
, all elements will be colored.- Default
False
-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'vectors'
,'voxels'
.- Default
'particles'
-
property
property
¶ The name of the input property that should be used to color elements.
When the input property has multiple components, then a component name must be appended to the property base name, e.g.
"Velocity.X"
.
-
class
ovito.modifiers.
AssignColorModifier
¶ - Base class
This modifier assigns a uniform color to all selected data elements. See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Sets the
Color
property of selected particles.vectors
Sets the
Vector Color
property of selected particles.bonds
Sets the
Color
property of selected bonds.By default the modifier will act on particles. You can change this by setting the
operate_on
field.Inputs:
Selection
The selection state of particles. If not present in the input, the modifier will assign the color to all particles.
-
property
color
¶ The RGB color that will be assigned to all selected elements by the modifier.
- Default
(0.3, 0.3, 1.0)
-
property
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
This modifier deletes the currently selected elements. See also the corresponding user manual page for more information.
Inputs:
The modifier can operate on any combination of the following data elements:
Data element
particles
Deletes all particles with a non-zero value of the
Selection
property.bonds
Deletes all bonds with a non-zero value of the
Selection
property.By default the modifier will act on all data element types simultaneously. You can restrict it to a subset by setting the
operate_on
field.-
property
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
Selects data elements of a certain type or types (e.g. all atoms of a chemical species). See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Selects all particles of a certain type.
bonds
Selects all bonds of a certain type.
By default the modifier will act on particles. You can change this by setting the
operate_on
field.Outputs:
SelectType.num_selected
The number of data elements (particles/bonds) that have been selected by the modifier.
Example:
from ovito.io import import_file from ovito.modifiers import SelectTypeModifier, CommonNeighborAnalysisModifier pipeline = import_file("input/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'])
-
property
operate_on
¶ Selects the kind of data elements this modifier should select. Supported values are:
'particles'
,'bonds'
.- Default
'particles'
-
property
property
¶ The name of the property to use as input; must be an integer property.
For selecting particles, possible input properties are
'Particle Type'
and'Structure Type'
, for example. For selecting bonds,'Bond Type'
is a typical input property.- Default
'Particle Type'
-
property
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 usingParticleProperty.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
Generates a histogram of a property, i.e. the distribution of its per-element values. See also the corresponding user manual page for more information. The modifier can operate on different types of data elements:
Data element
particles
Computes the histogram for a particle property.
bonds
Computes the histogram for a bond property.
voxels
Computes the histogram for a voxel grid property.
By default the modifier will operate on a particle property. You can change this by setting the
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 toTrue
. In this case the range of the histogram is controlled by thexrange_start
andxrange_end
parameters.Example:
from ovito.modifiers import HistogramModifier from ovito.io import import_file, export_file pipeline = import_file("input/simulation.dump") modifier = HistogramModifier(bin_count=100, property='peatom') pipeline.modifiers.append(modifier) export_file(pipeline, "output/histogram.txt", "txt/series", key="histogram[peatom]")
-
property
bin_count
¶ The number of histogram bins.
- Default
200
-
property
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
andxrange_end
attributes.- Default
False
-
property
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
-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'voxels'
.- Default
'particles'
-
property
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"
.- Default
''
-
property
xrange_end
¶ If
fix_xrange
is true, then this specifies the upper end of the value range covered by the histogram.- Default
0.0
-
property
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
This modifier replicates all particles, bonds and other elements of a system to visualize periodic images. See also the corresponding user manual page for more information.
Inputs:
The modifier can operate on any combination of the following data elements:
Data element
particles
surfaces
Duplicates the mesh geometry of
SurfaceMesh
objects.voxels
Duplicates the voxel elements of
VoxelGrid
objects.dislocations
Duplicates dislocation lines in a
DislocationNetwork
.By default the modifier will operate on all of these. You can restrict it to a subset by setting the
operate_on
field.-
property
adjust_box
¶ Controls whether the simulation cell is resized. If
True
, the simulation cell is accordingly extended to fit the replicated data. IfFalse
, the original simulation cell size (containing only the primary image of the system) is maintained.- Default
True
-
property
num_x
¶ A positive integer specifying the number of copies to generate in the x direction (including the existing primary image).
- Default
1
-
property
num_y
¶ A positive integer specifying the number of copies to generate in the y direction (including the existing primary image).
- Default
1
-
property
num_z
¶ A positive integer specifying the number of copies to generate in the z direction (including the existing primary image).
- Default
1
-
property
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', 'voxels', 'surfaces', 'dislocations'}
-
property
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
-
class
ovito.modifiers.
ExpressionSelectionModifier
¶ - Base class
Selects data elements based on a user-defined Boolean expression. See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Selects particles according to a user-defined criterion.
bonds
Selects bonds according to a user-defined criterion.
By default the modifier will act on particles. You can change this by setting the
operate_on
field.Outputs:
ExpressionSelection.count
The number of data elements (particles/bonds) that have been selected by the modifier.
Example:
# Select all atoms with potential energy above -3.6 eV: pipeline.modifiers.append(ExpressionSelectionModifier(expression = 'PotentialEnergy > -3.6')) data = pipeline.compute() # Demonstrating two ways to get the number of selected atoms: print(data.attributes['SelectExpression.num_selected']) print(numpy.count_nonzero(data.particles.selection))
-
property
expression
¶ A string containing the Boolean expression to be evaluated for every element. The expression syntax is documented in OVITO’s user manual.
-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
.- Default
'particles'
-
class
ovito.modifiers.
FreezePropertyModifier
¶ - Base class
This modifier copies the values of a source property from some reference animation frame (frame 0 by default) to the current animation frame. It allows preserving a particle or bond property that would otherwise change with time. See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Freezes a particle property.
bonds
Freezes a bond property.
voxels
Freezes a voxel grid property.
By default the modifier will operate on a particle property. You can change this by setting the
operate_on
field.Example:
from ovito.io import import_file, export_file from ovito.modifiers import (CoordinationAnalysisModifier, FreezePropertyModifier, ExpressionSelectionModifier) # Load a input simulation sequence. pl = import_file("input/simulation.*.dump") # Add modifier for computing the coordination numbers of particles. pl.modifiers.append(CoordinationAnalysisModifier(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/changes.txt', 'txt', columns = ['Timestep', 'SelectExpression.num_selected'], multiple_frames = True)
-
property
destination_property
¶ The name of the output property that should be created by the modifier. It may be the same as
source_property
. If the destination property already exists in the modifier’s input, the values are overwritten.
-
property
freeze_at
¶ The animation frame number at which to freeze the input property’s values.
- Default
0
-
property
operate_on
¶ Selects the kind of properties this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'voxels'
.- Default
'particles'
-
class
ovito.modifiers.
ComputePropertyModifier
¶ - Base class
Evaluates a user-defined math expression for every input element and stores the results in an output property. See also the corresponding user manual page for more information. The modifier can operate on different data elements:
Data element
particles
Computes a particle property.
bonds
Computes a bond property.
voxels
Computes a voxel grid property.
By default the modifier will act on particles. You can change this by setting the
operate_on
field.Example:
pipeline.modifiers.append(ComputePropertyModifier( output_property = 'Color', expressions = ['Position.X / CellSize.X', '0.0', '0.5'] ))
Note that a
PythonScriptModifier
may sometimes be a better choice than this modifier to set properties, in particular when the computation involves complex element indexing or conditions.-
property
cutoff_radius
¶ The cutoff radius up to which neighboring particles are visited to compute
neighbor_expressions
. This parameter is only used ifoperate_on
is set to'particles'
and theneighbor_expressions
field has been set.- Default
3.0
-
property
expressions
¶ A list of strings containing the math expressions to compute, one for each vector component of the selected output property. If the output property is scalar, the list must comprise one expression string.
See the corresponding user manual page for a description of the expression syntax.
- Default
["0"]
-
property
neighbor_expressions
¶ The list of strings containing the math expressions for the per-neighbor terms, one for each vector component of the output particle property. If the output property is scalar, the list must comprise one string only.
The neighbor expressions are only evaluated for each neighbor particle and the value is added to the output property of the central particle. Neighbor expressions are only evaluated if
operate_on
is set to'particles'
.- Default
[""]
-
property
only_selected
¶ If
True
, the property is only computed for currently selected elements. In this case, the property values of unselected elements will be preserved if the output property already exists.- Default
False
-
property
operate_on
¶ Selects the kind of data elements this modifier should operate on. Supported values are:
'particles'
,'bonds'
,'voxels'
.- Default
'particles'
-
property
output_property
¶ The output property that will be assigned the computed values.
- Default
"My property"
-
class
ovito.modifiers.
CombineDatasetsModifier
¶ - Base class
This modifier loads a set of particles from a separate simulation file and merges them into the primary dataset. See also the corresponding user manual page for more information.
Example:
from ovito.io import import_file, export_file from ovito.modifiers import CombineDatasetsModifier # Load a first set of particles. pipeline = import_file('input/first_file.dump') # Insert the particles from a second file into the dataset. modifier = CombineDatasetsModifier() modifier.source.load('input/second_file.dump') pipeline.modifiers.append(modifier) # Export combined dataset to a new file. export_file(pipeline, 'output/combined.dump', 'lammps/dump', columns = ['Position.X', 'Position.Y', 'Position.Z'])
-
property
source
¶ A
FileSource
that provides the set of particles to be merged. You can call itsload()
function to load a data file as shown in the code example above.
-
class
ovito.modifiers.
CreateIsosurfaceModifier
¶ - Base class
Generates an isosurface of a scalar field defined on a three-dimensional
VoxelGrid
. See the corresponding user manual page for more information.Outputs:
isosurface
The isosurface mesh constructed by the modifier. You can access it through the
surfaces
dictionary of the outputDataCollection
under the lookup key"isosurface"
.isosurface-histogram
A histogram of the input field values. You can access it through the
series
dictionary of the outputDataCollection
under the lookup key"isosurface-histogram"
.-
property
isolevel
¶ The value at which to create the isosurface.
- Default
0.0
-
property
operate_on
¶ Specifies the voxel grid this modifier should operate on.
- Default
'voxels:'
-
property
property
¶ The name of the voxel property from which the isosurface should be constructed.
-
property
vis
¶ The
SurfaceMeshVis
controlling the visual appearance of the generated isosurface in rendered images.
-
class
ovito.modifiers.
AmbientOcclusionModifier
¶ - Base class
Performs a quick lighting calculation to shade particles according to the degree of occlusion by other particles. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Color
The original per-particle colors (optional).
Outputs:
Color
The new per-particle colors, which have been modulated by the occlusion factor computed by the modifier for each particle.
-
property
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 particles is small compared to the simulation dimensions, a higher buffer resolution should be used.
- Valid range
[1, 4]
- Default
3
-
property
intensity
¶ Controls the strength of the shading effect.
- Valid range
[0.0, 1.0]
- Default
0.7
-
property
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
This modifier maps particles located outside of the simulation cell back into the cell by “wrapping” their coordinates around at the periodic boundaries of the
SimulationCell
. This modifier has no parameters.See also the corresponding user manual page for this modifier.
-
class
ovito.modifiers.
ExpandSelectionModifier
¶ - Base class
Expands the current particle selection by selecting particles that are neighbors of already selected particles. See the corresponding user manual page for more information.
Inputs:
Selection
The selection state of the input particles.
Position
The coordinates of the input particles (only used if
mode
isCutoff
orNearest
).Topology
The list of bonds (only used if
mode
isBonded
).Outputs:
Selection
The output particle selection.
-
property
cutoff
¶ The maximum distance up to which particles are selected around already selected particles. This parameter is only used if
mode
is set toExpansionMode.Cutoff
.- Default
3.2
-
property
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
-
property
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
-
class
ovito.modifiers.
CommonNeighborAnalysisModifier
¶ - Base class
Analyzes the local neighborhood of each particle to identify simple crystalline structures. The structure identification is performed using the common neighbor analysis (CNA) method. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles. They are not used if
mode
is set toBondBased
.Selection
The selection state of the input particles. Only needed if
only_selected
is set toTrue
.Topology
The input bond topology, which is required only if
mode
is set toBondBased
.Outputs:
Structure Type
The structure type computed by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
CommonNeighborAnalysisModifier.Type.OTHER
1
CommonNeighborAnalysisModifier.Type.FCC
2
CommonNeighborAnalysisModifier.Type.HCP
3
CommonNeighborAnalysisModifier.Type.BCC
4
CommonNeighborAnalysisModifier.Type.ICO
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).CommonNeighborAnalysis.counts.OTHER
Number of particles not matching any of the known structure types.
CommonNeighborAnalysis.counts.FCC
Number of particles identified as face-centered cubic.
CommonNeighborAnalysis.counts.HCP
Number of particles identified as hexagonal close packed.
CommonNeighborAnalysis.counts.BCC
Number of particles identified as body-centered cubic.
CommonNeighborAnalysis.counts.ICO
Number of particles identified as icosahedral.
structures
A histogram table listing the particle counts for each structure type supported by the modifier. You can retrieve this
DataSeries
object through theseries
dictionary of the outputDataCollection
under the lookup key"structures"
-
property
color_by_type
¶ Controls whether the modifier also assigns a color to each particle representing the identified structure type. The color value associated with a structure type can be changed through the
structures
field.- Default
True
-
property
cutoff
¶ The cutoff radius used for the conventional common neighbor analysis. This parameter is only used if
mode
==CommonNeighborAnalysisModifier.Mode.FixedCutoff
.- Default
3.2
-
property
mode
¶ Selects the mode of operation. Valid values are:
CommonNeighborAnalysisModifier.Mode.FixedCutoff
CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
CommonNeighborAnalysisModifier.Mode.BondBased
- Default
CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
-
property
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
-
property
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type supported by the algorithm. The particle color representing a structural type can be changed as follows:modifier = CommonNeighborAnalysisModifier() modifier.structures[CommonNeighborAnalysisModifier.Type.FCC].color = (0, 0, 1)
.
-
class
ovito.modifiers.
AcklandJonesModifier
¶ - Base class
Analyzes the local neighborhood of each particle to identify simple crystalline structures. The structure identification is performed using the bond-angle method proposed by Ackland and Jones. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Structure Type
The structure type computed by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
AcklandJonesModifier.Type.OTHER
1
AcklandJonesModifier.Type.FCC
2
AcklandJonesModifier.Type.HCP
3
AcklandJonesModifier.Type.BCC
4
AcklandJonesModifier.Type.ICO
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).AcklandJones.counts.OTHER
Number of particles not matching any of the known structure types.
AcklandJones.counts.FCC
Number of particles identified as face-centered cubic.
AcklandJones.counts.HCP
Number of particles identified as hexagonal close packed.
AcklandJones.counts.BCC
Number of particles identified as body-centered cubic.
AcklandJones.counts.ICO
Number of particles identified as icosahedral.
structures
A histogram table listing the particle counts for each structure type supported by the modifier. You can retrieve this
DataSeries
object through theseries
dictionary of the outputDataCollection
under the lookup key"structures"
-
property
color_by_type
¶ Controls whether the modifier also assigns a color to each particle representing the identified structure type. The color value associated with a structure type can be changed through the
structures
field.- Default
True
-
property
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type supported by the algorithm. The particle color representing a structural type can be changed as follows:modifier = AcklandJonesModifier() modifier.structures[AcklandJonesModifier.Type.FCC].color = (0.0, 0.0, 1.0)
.
-
class
ovito.modifiers.
CreateBondsModifier
¶ - Base class
Creates bonds between nearby particles. See the corresponding user manual page for more information.
Inputs:
Position
The xyz coordinates of the input particles.
Particle Type
The particle type information, which is used only if
mode
is set toPairwise
.Molecule Identifier
The assignment of atoms to molecules, which is used only if
intra_molecule_only
is set toTrue
.Outputs:
Topology
The modifier will create new bond topology entries and append them to the property arrays in an existing
Bonds
object; or it creates a newBonds
instance if necessary.Periodic Image
Stores the transitions of each bond through the faces of a periodic simulation cell if the bond connects two particles from different periodic images of the system.
Bond Type
The type ID information that is assigned to newly created bonds according to the modifier’s
bond_type
field.CreateBonds.num_bonds
The number of bonds that exists after the modifier’s operation.
-
property
bond_type
¶ The
BondType
that will be assigned to the newly created bonds. This lets you control the display color of the new bonds.
-
property
cutoff
¶ The upper cutoff distance for the creation of bonds between particles. This parameter is only used if
mode
is set toUniform
.- Default
3.2
-
get_pairwise_cutoff
(type_a, type_b) → float¶ Returns the pair-wise cutoff distance that was previously set for a specific pair of particle types using the
set_pairwise_cutoff()
method.
-
property
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
-
property
lower_cutoff
¶ The minimum bond length. No bonds will be created between particles whose distance is below this threshold.
- Default
0.0
-
property
mode
¶ Selects the mode of operation. Valid modes are:
CreateBondsModifier.Mode.Uniform
CreateBondsModifier.Mode.Pairwise
In
Uniform
mode one globalcutoff
is used irrespective of the particle types. InPairwise
mode a separate cutoff distance must be specified for all pairs of particle types between which bonds are to be created.- Default
CreateBondsModifier.Mode.Uniform
-
set_pairwise_cutoff
(type_a, type_b, cutoff)¶ Sets the cutoff range for creating bonds between a specific pair of particle types. This information is only used if
mode
is set toPairwise
.- Parameters
If you want no bonds to be created between a pair of types, set the corresponding cutoff radius to zero (which is the default).
-
class
ovito.modifiers.
CentroSymmetryModifier
¶ - Base class
Computes the centro-symmetry parameter (CSP) of each particle, which is a measure of the local lattice disorder around a particle in centrosymmetric crystal lattices. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Outputs:
Centrosymmetry
The non-negative CSP value computed for each particle. Values close to zero mean neighboring particles are in a perfect centrosymmetric arrangement.
-
property
num_neighbors
¶ The number of nearest neighbors to take into account for the computation, e.g.
12 for FCC crystals
8 for BCC crystals
- Default
12
-
class
ovito.modifiers.
ClusterAnalysisModifier
¶ - Base class
This modifier groups particles into disconnected clusters based on a selectable neighboring criterion. See the corresponding user manual page for more information.
Outputs:
Cluster
Stores for each particle the ID it has been assigned to.
ClusterAnalysis.cluster_count
Total number of clusters produced by the modifier. Cluster IDs range from 1 to this number.
ClusterAnalysis.largest_size
Number of particles in the largest cluster (cluster ID 1). Only computed if
sort_by_size
is set toTrue
.Example:
The following script demonstrates the use of the numpy.bincount() function to determine the size (=number of particles) of each cluster. The function is employed to count how often each cluster ID occurs in the
Cluster
particle property output by the modifier.from ovito.io import import_file from ovito.modifiers import ClusterAnalysisModifier import numpy pipeline = import_file("input/simulation.dump") pipeline.modifiers.append(ClusterAnalysisModifier(cutoff=2.8, sort_by_size=True)) data = pipeline.compute() cluster_sizes = numpy.bincount(data.particles['Cluster']) numpy.savetxt("output/cluster_sizes.txt", cluster_sizes)
-
property
cutoff
¶ The cutoff distance used by the algorithm to form clusters of connected particles. This parameter is only used when
neighbor_mode
is set toCutoffRange
; otherwise it is ignored.- Default
3.2
-
property
neighbor_mode
¶ Selects the neighboring criterion for the clustering algorithm. Valid values are:
ClusterAnalysisModifier.NeighborMode.CutoffRange
ClusterAnalysisModifier.NeighborMode.Bonding
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 parametercutoff
.In the second mode (
Bonding
), 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 theCreateBondsModifier
or theVoronoiAnalysisModifier
.- Default
ClusterAnalysisModifier.NeighborMode.CutoffRange
-
property
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
-
property
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.
CoordinationAnalysisModifier
¶ - Base class
Computes coordination number of each particle and the radial distribution function (RDF) for the entire system. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Particle Type
Required if
partial
is set toTrue
.Outputs:
Coordination
The number of neighbors of each particle.
coordination-rdf
The RDF computed by the modifier. You can retrieve the RDF data through the
series
dictionary of the outputDataCollection
under the lookup key"coordination-rdf"
, see the code examples below.Examples:
The following batch script demonstrates how to load a particle configuration, compute the RDF using the modifier and export the data to a text file:
from ovito.io import import_file from ovito.modifiers import CoordinationAnalysisModifier import numpy # Load a particle dataset, apply the modifier, and evaluate pipeline. pipeline = import_file("input/simulation.dump") modifier = CoordinationAnalysisModifier(cutoff = 5.0, number_of_bins = 200) pipeline.modifiers.append(modifier) data = pipeline.compute() # Export the computed RDF data to a text file. numpy.savetxt("output/rdf.txt", data.series['coordination-rdf'].as_table())
The next script demonstrates how to compute the RDF for every frame of a simulation sequence and build a time-averaged RDF histogram from the data:
from ovito.io import import_file from ovito.modifiers import CoordinationAnalysisModifier import numpy # Load a simulation trajectory consisting of several frames: pipeline = import_file("input/simulation.dump") # Insert the modifier into the pipeline: modifier = CoordinationAnalysisModifier(cutoff = 5.0, number_of_bins = 200) pipeline.modifiers.append(modifier) # Initialize array for accumulated RDF histogram to zero: total_rdf = numpy.zeros((modifier.number_of_bins, 2)) # Iterate over all frames of the sequence. for frame in range(pipeline.source.num_frames): # Evaluate pipeline to let the modifier compute the RDF of the current frame: data = pipeline.compute(frame) # Accumulate RDF histograms: total_rdf += data.series['coordination-rdf'].as_table() # Averaging: total_rdf /= pipeline.source.num_frames # Export the average RDF to a text file: numpy.savetxt("output/rdf.txt", total_rdf)
-
property
cutoff
¶ Specifies the cutoff distance for the coordination number calculation and also the range up to which the modifier calculates the RDF.
- Default
3.2
-
property
number_of_bins
¶ The number of histogram bins to use when computing the RDF.
- Default
200
-
property
partial
¶ Setting this flag to true requests calculation of element-specific (partial) RDFs.
- Default
False
-
class
ovito.modifiers.
CalculateDisplacementsModifier
¶ -
Computes the displacement vectors of particles with respect to a reference configuration. See the corresponding user manual page for more information.
The modifier is a subclass of
ReferenceConfigurationModifier
, which provides the programming interface for specifying the reference configuration and how particle displacements get calculated. By default, frame 0 of the processed simulation sequence is used as static reference configuration.Outputs:
Displacement
The computed displacement vectors.
Displacement Magnitude
The length of the computed displacement vectors.
-
property
vis
¶ A
VectorVis
element controlling the visual representation of the computed displacement vectors. Note that the computed displacement vectors are hidden by default. You can enable the visualization of arrows as follows:modifier = CalculateDisplacementsModifier() modifier.vis.enabled = True modifier.vis.color = (0.8, 0.0, 0.5)
-
property
-
class
ovito.modifiers.
AtomicStrainModifier
¶ -
Computes the atomic-level deformation with respect to a reference configuration. See the corresponding user manual page for more information.
The modifier is a subclass of
ReferenceConfigurationModifier
, which provides the programming interface for specifying the reference configuration and how particle displacements get calculated. By default, frame 0 of the processed simulation sequence is used as static reference configuration.Outputs:
Shear Strain
The von Mises shear strain invariant of the computed atomic Green-Lagrangian strain tensor.
Volumetric Strain
One third of the trace of the computed atomic Green-Lagrangian strain tensor.
Strain Tensor
The six components of the symmetric Green-Lagrangian strain tensor. Only if
output_strain_tensors
was set toTrue
.Deformation Gradient
The nine components of the atomic deformation gradient tensor. Only if
output_deformation_gradients
was set toTrue
.Stretch Tensor
The six components of the symmetric right stretch tensor U in the polar decomposition F=RU. Only if
output_stretch_tensors
was set toTrue
.Rotation
The atomic microrotation obtained from the polar decomposition F=RU as a 4-component quaternion. Only if
output_rotations
was set toTrue
.Nonaffine Squared Displacement
The D2min measure of Falk & Langer, which describes the non-affine part of the local deformation. Only if
output_nonaffine_squared_displacements
was set toTrue
.Selection
Set to a non-zero value for particles for which the modifier failed to determine a local deformation tensor, because they do not have enough neighbors within the specified
cutoff
distance. Only ifselect_invalid_particles
was set toTrue
. The selected particles without valid deformation values can subsequently be removed using aDeleteSelectedModifier
.AtomicStrain.invalid_particle_count
Number of particles for which the modifier could not compute a deformation tensor, because they do not have enough neighbors within the specified
cutoff
distance. You typically should increase the cutoff distance if this value is non-zero.-
property
cutoff
¶ The spatial range up to which neighboring atoms will be taken into account to calculate the local strain measure.
- Default
3.0
-
property
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
-
property
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
-
property
output_rotations
¶ Controls the calculation of the per-particle rotations.
- Default
False
-
property
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
-
property
output_stretch_tensors
¶ Controls the calculation of the per-particle stretch tensors.
- Default
False
-
property
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
-
property
-
class
ovito.modifiers.
WignerSeitzAnalysisModifier
¶ -
Performs the Wigner-Seitz cell analysis to identify point defects in a crystal. See the corresponding user manual page for more information.
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.Outputs:
Occupancy
The computed site occupation numbers, one for each particle in the reference configuration.
WignerSeitz.vacancy_count
The total number of vacant sites (having
Occupancy
== 0).WignerSeitz.interstitial_count
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.
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 theExpressionSelectionModifier
to pick sites having a certain occupancy. The following script exemplarily demonstrates the use of a customPythonScriptModifier
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("input/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, data): # Retrieve the two-dimensional array with the site occupancy numbers. # Use [...] to cast it to a Numpy array. occupancies = data.particles['Occupancy'] # Get the site types as additional input: site_type = data.particles['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 = data.particles_.create_property('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. selection[...] = (site_type == 1) & (occupancies[:,1] == 1) & (total_occupancy == 1) # Additionally output the total number of antisites as a global attribute: data.attributes['Antisite_count'] = np.count_nonzero(selection) # Insert Python modifier into the data pipeline. pipeline.modifiers.append(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, "output/antisites.txt", "txt/attr", 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(DeleteSelectedModifier()) export_file(pipeline, "output/antisites.xyz", "xyz", columns = ['Position.X', 'Position.Y', 'Position.Z'], multiple_frames = True)
-
property
output_displaced
¶ Specifies whether the modifier should output the atoms of the current configuration or replace them with the sites from the reference configuration.
By default, the modifier throws away all atoms of the current configuration and outputs the atomic sites from the reference configuration instead. Thus, in this default mode, you will obtain information about how many atoms occupy each site from the reference configuration. If, however, you are more insterested in visualizing the physical atoms that are currently occupying the sites (instead of the sites being occupied), then you should activate this modifier option. If set to true, the modifier will maintain the input atoms from the current configuration. The
Occupancy
property generated by the modifier will now pertain to the atoms instead of the sites, with the following new meaning: The occupancy number now counts how many atoms in total are occupying the same site as the atom the property refers to does. Furthermore, the modifier will in this mode output another property namedSite Type
, which reports for each atom the type of the reference site it was assigned to by the W-S algorithm.- Default
False
-
property
per_type_occupancies
¶ A flag controlling whether the modifier should compute occupancy numbers on a per-particle-type basis.
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 N components, where N is the number of particle types defined in the system. Each component of theOccupancy
property counts the number of particles of the corresponding type that occupy the site. For example, the property componentOccupancy.1
contains the number of particles of type 1 that occupy a site.- Default
False
-
property
-
class
ovito.modifiers.
VoronoiAnalysisModifier
¶ - Base class
Computes the atomic volumes and coordination numbers using a Voronoi tessellation of the particle system. See the corresponding user manual page for more information. See Example B1: Computing Voronoi indices for a code example demonstrating the use of this modifier.
Inputs:
Position
The coordinates of the input particles.
Radius
Per-particle radii are used if
use_radii
is set toTrue
.Particle Type
Per-type radii are used if
use_radii
is set toTrue
andRadius
property is not present.Selection
The selection state of the input particles. Only needed if
only_selected
is set toTrue
.Outputs:
Atomic Volume
The computed volume of each particle’s Voronoi polyhedron.
Coordination
The number of faces of each particle’s Voronoi polyhedron.
Voronoi Index
The index vector of each Voronoi polyhedron. Only computed if
compute_indices
is set toTrue
.Max Face Order
The maximum number of edges in any face of a particle’s Voronoi polyhedron. Only if
compute_indices
is set toTrue
.Voronoi.max_face_order
Indicates the maximum number of edges of any face in the computed Voronoi tessellation (ignoring edges and faces that fall below the area/length thresholds).
Topology
The connectivity information of newly created
Bonds
(one bond for each Voronoi face). Only ifgenerate_bonds
is set toTrue
.-
property
compute_indices
¶ If
True
, the modifier calculates the Voronoi indices of particles. The modifier stores the computed indices in a vector particle property namedVoronoi 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
-
property
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
-
property
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
-
property
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 theedge_threshold
.- Default
False
-
property
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
-
property
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
-
property
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
Analyzes the local neighborhood of each particle to identify cubic or hexagonal diamond lattices. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Structure Type
The structure type computed by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
IdentifyDiamondModifier.Type.OTHER
1
IdentifyDiamondModifier.Type.CUBIC_DIAMOND
2
IdentifyDiamondModifier.Type.CUBIC_DIAMOND_FIRST_NEIGHBOR
3
IdentifyDiamondModifier.Type.CUBIC_DIAMOND_SECOND_NEIGHBOR
4
IdentifyDiamondModifier.Type.HEX_DIAMOND
5
IdentifyDiamondModifier.Type.HEX_DIAMOND_FIRST_NEIGHBOR
6
IdentifyDiamondModifier.Type.HEX_DIAMOND_SECOND_NEIGHBOR
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).IdentifyDiamond.counts.OTHER
Number of particles not matching any of the known structure types.
IdentifyDiamond.counts.CUBIC_DIAMOND
Number of particles identified as fully coordinated cubic diamond.
IdentifyDiamond.counts.CUBIC_DIAMOND_FIRST_NEIGHBOR
Number of particles identified as partially coordinated cubic diamond.
IdentifyDiamond.counts.CUBIC_DIAMOND_SECOND_NEIGHBOR
Number of particles identified as partially coordinated cubic diamond.
IdentifyDiamond.counts.HEX_DIAMOND
Number of particles identified as fully coordinated hexagonal diamond.
IdentifyDiamond.counts.HEX_DIAMOND_FIRST_NEIGHBOR
Number of particles identified as partially coordinated hexagonal diamond.
IdentifyDiamond.counts.HEX_DIAMOND_SECOND_NEIGHBOR
Number of particles identified as partially coordinated hexagonal diamond.
structures
A histogram table listing the particle counts for each structure type supported by the modifier. You can retrieve this
DataSeries
object through theseries
dictionary of the outputDataCollection
under the lookup key"structures"
-
property
color_by_type
¶ Controls whether the modifier also assigns a color to each particle representing the identified structure type. The color value associated with a structure type can be changed through the
structures
field.- Default
True
-
property
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
-
property
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type supported by the algorithm. The particle color representing a structural type can be changed as follows:modifier = IdentifyDiamondModifier() modifier.structures[IdentifyDiamondModifier.Type.HEX_DIAMOND].color = (0, 0, 1)
.
-
class
ovito.modifiers.
LoadTrajectoryModifier
¶ - Base class
This modifier loads trajectories of particles from a separate simulation file. See also the corresponding user manual page for this modifier.
The typical use case 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 theLoadTrajectoryModifier
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/input.data', atom_style='bond') # Load atom trajectories from separate LAMMPS dump file. traj_mod = LoadTrajectoryModifier() traj_mod.source.load('input/trajectory.dump') print("Number of frames: ", traj_mod.source.num_frames) # Insert modifier into data pipeline. pipeline.modifiers.append(traj_mod)
-
property
source
¶ A
FileSource
that provides the trajectories of particles. You can call itsload()
function to load a simulation trajectory file as shown in the code example above.
-
class
ovito.modifiers.
PolyhedralTemplateMatchingModifier
¶ - Base class
Analyzes the local neighborhood of each particle to identify simple crystalline structures and other structural motives. The structure identification is performed using the Polyhedral Template Matching (PTM) algorithm. Additionally, the modifier can compute local orientations, elastic lattice strains and identify local chemical orderings. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Particle Type
The chemical types of the input particles (optional).
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Structure Type
The structure type computed by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
PolyhedralTemplateMatchingModifier.Type.OTHER
1
PolyhedralTemplateMatchingModifier.Type.FCC
2
PolyhedralTemplateMatchingModifier.Type.HCP
3
PolyhedralTemplateMatchingModifier.Type.BCC
4
PolyhedralTemplateMatchingModifier.Type.ICO
5
PolyhedralTemplateMatchingModifier.Type.SC
6
PolyhedralTemplateMatchingModifier.Type.CUBIC_DIAMOND
7
PolyhedralTemplateMatchingModifier.Type.HEX_DIAMOND
RMSD
The per-particle RMSD values computed by the PTM algorithm. Only if
output_rmsd
is set.Interatomic Distance
The per-particle local atomic distances computed by the PTM algorithm. Only if
output_interatomic_distance
is set.Orientation
The local lattice orientations computed by the PTM algorithm, encoded as quaternions. Only if
output_orientation
is set.Elastic Deformation Gradient
The per-particle elastic deformation gradient tensors computed by the PTM algorithm (3x3 components). Only if
output_deformation_gradient
is set.Ordering Type
The local chemical ordering type determined by the PTM algorithm, encoded as an integer value. Only if
output_ordering
is set.Value
Python constant
0
PolyhedralTemplateMatchingModifier.OrderingType.OTHER
1
PolyhedralTemplateMatchingModifier.OrderingType.PURE
2
PolyhedralTemplateMatchingModifier.OrderingType.L10
3
PolyhedralTemplateMatchingModifier.OrderingType.L12_A
4
PolyhedralTemplateMatchingModifier.OrderingType.L12_B
5
PolyhedralTemplateMatchingModifier.OrderingType.B2
6
PolyhedralTemplateMatchingModifier.OrderingType.ZINCBLENDE_WURTZITE
7
PolyhedralTemplateMatchingModifier.OrderingType.BORON_NITRIDE
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).PolyhedralTemplateMatching.counts.OTHER
Number of particles not matching any of the known structural types.
PolyhedralTemplateMatching.counts.FCC
Number of particles identified as face-centered cubic structure.
PolyhedralTemplateMatching.counts.HCP
Number of particles identified as hexagonal close packed structure.
PolyhedralTemplateMatching.counts.BCC
Number of particles identified as body-centered cubic structure.
PolyhedralTemplateMatching.counts.ICO
Number of particles identified as icosahedral structure.
PolyhedralTemplateMatching.counts.SC
Number of particles identified as simple cubic structure.
PolyhedralTemplateMatching.counts.CUBIC_DIAMOND
Number of particles identified as cubic diamond structure.
PolyhedralTemplateMatching.counts.HEX_DIAMOND
Number of particles identified as hexagonal diamond structure.
structures
A histogram table listing the particle counts for each structure type supported by the modifier. You can retrieve this
DataSeries
object through theseries
dictionary of the outputDataCollection
under the lookup key"structures"
-
property
color_by_type
¶ Controls whether the modifier also assigns a color to each particle representing the identified structure type. The color value associated with a structure type can be changed through the
structures
field.- Default
True
-
property
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 and will all be assigned to the “Other” structure category.
- Default
False
-
property
output_deformation_gradient
¶ Boolean flag that controls whether the modifier outputs the computed per-particle elastic deformation gradients as a new particle property named
Elastic Deformation Gradient
.The elastic deformation gradient describes the local deformation and rigid-body rotation of the crystal with repect to an ideal reference lattice configuration. See the OVITO user manual for details.- Default
False
-
property
output_interatomic_distance
¶ Boolean flag that controls whether the modifier outputs the computed per-particle interatomic distance as a new particle property named
Interatomic Distance
.- Default
False
-
property
output_ordering
¶ Boolean flag that controls whether the modifier should identify local ordering types and output them as a new particle property named
Ordering Type
.- Default
False
-
property
output_orientation
¶ Boolean flag that controls whether the modifier outputs the computed per-particle lattice orientations as a new particle property named
Orientation
. The lattice orientation is specified in terms of a quaternion that describes the rotation of the crystal with repect to a reference lattice orientation. See the OVITO user manual for details.- Default
False
-
property
output_rmsd
¶ Boolean flag that controls whether the modifier outputs the computed per-particle RMSD values as a new particle property named
RMSD
.- Default
False
-
property
rmsd_cutoff
¶ The maximum allowed root mean square deviation for positive structure matches. If the this threshold value 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).
- Default
0.1
-
property
structures
¶ This list contains one
ParticleType
instance each for structural type the modifier can identify. You can adjust the particle color for a structural type or turn its identification on or off:modifier = PolyhedralTemplateMatchingModifier() # Enable the identification of cubic and hexagonal diamond structures: modifier.structures[PolyhedralTemplateMatchingModifier.Type.CUBIC_DIAMOND].enabled = True modifier.structures[PolyhedralTemplateMatchingModifier.Type.HEX_DIAMOND].enabled = True # Give all cubic diamond atoms a blue color and hexagonal atoms a red color: modifier.structures[PolyhedralTemplateMatchingModifier.Type.CUBIC_DIAMOND].color = (0.0, 0.0, 1.0) modifier.structures[PolyhedralTemplateMatchingModifier.Type.HEX_DIAMOND].color = (1.0, 0.0, 0.0)
-
class
ovito.modifiers.
CoordinationPolyhedraModifier
¶ - Base class
Constructs coordination polyhedra around selected particles. See the corresponding user manual page for more information.
Inputs:
Selection
Determines around which central particles coordination polyhedra should be constructed. You can select all particles of certain chemical type(s) by first inserting a
SelectTypeModifier
into the pipeline.Topology
The input bond topology. It is used to determine the set of neighbors of a selected particle around which a coordination polyhedron should be constructued. You can create the bond topology if needed by inserting a
CreateBondsModifier
into the pipeline first.Outputs:
coord-polyhedra
The polyhedral mesh generated by the modifier. You can access it through the
surfaces
dictionary of the outputDataCollection
under the lookup key"coord-polyhedra"
.-
property
vis
¶ A
SurfaceMeshVis
element controlling the visual appearance of the generated polyhedra in rendered images and animations.
-
class
ovito.modifiers.
InterpolateTrajectoryModifier
¶ - Base class
This modifier interpolates the particle positions in between successive snapshots of a simulation trajectory. It can be used to create smoothly looking animations from relatively coarse sequences of simulation snapshots. See also the corresponding user manual page for this modifier.
-
property
minimum_image_convention
¶ If this option is set, the modifier will automatically detect when particles cross a simulation box boundary in between two successive simulation frames and computes the unwrapped displacements correctly. You should leave this option activated unless the particle coordinates loaded from the input data file(s) are already in unwrapped form.
- Default
True
-
class
ovito.modifiers.
GenerateTrajectoryLinesModifier
¶ - Base class
This modifier periodically samples the time-dependent positions of particles to produce a
TrajectoryLines
object. The modifier is typically used to visualize the trajectories of particles as static lines. See the corresponding user manual page for more information.The generation of trajectory lines must be explicitly triggered by a call to
generate()
as shown in the following example:from ovito.io import import_file from ovito.modifiers import GenerateTrajectoryLinesModifier from ovito.vis import TrajectoryVis # Load a particle simulation sequence: pipeline = import_file('input/simulation.*.dump') # Insert the modifier into the pipeline for creating the trajectory lines. modifier = GenerateTrajectoryLinesModifier(only_selected = False) pipeline.modifiers.append(modifier) # Now let the modifier generate the trajectory lines by sampling the # particle positions over the entire animation interval. modifier.generate() # Configure trajectory line visualization: modifier.vis.width = 0.4 modifier.vis.color = (1,0,0) modifier.vis.shading = TrajectoryVis.Shading.Flat # Insert pipeline into the scene to make the particles and # the trajectory lines visible in rendered images. pipeline.add_to_scene()
-
property
frame_interval
¶ The animation frame interval over which the particle positions are sampled to generate the trajectory lines. Set this to a tuple of two integers to specify the first and the last animation frame; or use
None
to generate trajectory lines over the entire animation sequence.- Default
None
-
generate
()¶ Generates the trajectory lines by sampling the positions of the particles from the upstream pipeline in regular animation time intervals. Make sure you call this method after the modifier has been inserted into the pipeline.
-
property
only_selected
¶ Controls whether trajectory lines should only by generated for currently selected particles.
- Default
True
-
property
sampling_frequency
¶ Length of the animation frame intervals at which the particle positions should be sampled.
- Default
1
-
property
unwrap_trajectories
¶ Controls whether trajectory lines should be automatically unwrapped at the box boundaries when the particles cross a periodic boundary.
- Default
True
-
property
vis
¶ The
TrajectoryVis
element controlling the visual appearance of the trajectory lines created by this modifier.
-
class
ovito.modifiers.
UnwrapTrajectoriesModifier
¶ - Base class
This modifier determines when particles cross through the periodic boundaries of the simulation cell and unwraps the particle coordinates in order to make the trajectories continuous. As a result of this operation, particle trajectories will no longer fold back into the simulation cell and instead lead outside the cell.
For unwrapping the particle coordinates, the modifier must load all frames of the input simulation trajectory to detect crossings of the periodic cell boundaries. In the current version of OVITO, this initialization step must be explicitly triggered by calling the
update()
method as shown in the following example.from ovito.io import import_file from ovito.modifiers import UnwrapTrajectoriesModifier # Load a simulation trajectory: pipeline = import_file('input/simulation.*.dump') # Insert the unwrap modifier into the pipeline. modifier = UnwrapTrajectoriesModifier() pipeline.modifiers.append(modifier) # Let the modifier determine crossings of the periodic cell boundaries. modifier.update() # Request last frame of the trajectory with unwrapped particle positions: data = pipeline.compute(pipeline.source.num_frames - 1)
-
update
()¶ This method detects crossings of the particles through of the periodic cell boundaries. The list of crossing events will subsequently be used by the modifier to unwrap the particle coordinates and produce continuous particle trajectories. The method loads and steps through all animation frames of the input trajectory, which can take some time. Make sure you call this method right after the modifier has been inserted into the pipeline and before the pipeline is evaluated for the first time.
-
class
ovito.modifiers.
ChillPlusModifier
¶ - Base class
Analyzes the local neighborhood of each particle to identify different structural arrangements of water molecules. The structure identification is performed using the CHILL+ algorithm. See the corresponding user manual page for more information.
Inputs:
Position
The input coordinates of the particles.
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Structure Type
The structure type computed by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
ChillPlusModifier.Type.OTHER
1
ChillPlusModifier.Type.HEXAGONAL_ICE
2
ChillPlusModifier.Type.CUBIC_ICE
3
ChillPlusModifier.Type.INTERFACIAL_ICE
4
ChillPlusModifier.Type.HYDRATE
5
ChillPlusModifier.Type.INTERFACIAL_HYDRATE
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).ChillPlus.counts.OTHER
Number of particles not matching any of the known structure types.
ChillPlus.counts.HEXAGONAL_ICE
Number of particles identified as hexgonal ice.
ChillPlus.counts.CUBIC_ICE
Number of particles identified as cubic ice.
ChillPlus.counts.INTERFACIAL_ICE
Number of particles identified as interfacial ice.
ChillPlus.counts.HYDRATE
Number of particles identified as hydrate.
ChillPlus.counts.INTERFACIAL_HYDRATE
Number of particles identified as interfacial hydrate.
structures
A histogram table listing the particle counts for each structure type supported by the modifier. You can retrieve this
DataSeries
object through theseries
dictionary of the outputDataCollection
under the lookup key"structures"
-
property
color_by_type
¶ Controls whether the modifier also assigns a color to each particle representing the identified structure type. The color value associated with a structure type can be changed through the
structures
field.- Default
True
-
property
cutoff
¶ The cutoff distance for bonds between water molecules.
- Default
3.5
-
property
only_selected
¶ Lets the modifier perform the analysis only on currently selected particles. Particles that are not selected will be treated as if they did not exist.
- Default
False
-
property
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type supported by the algorithm. The particle color representing a structural type can be changed as follows:modifier = ChillPlusModifier() # Give all hexagonal ice particles a blue color: modifier.structures[ChillPlusModifier.Type.HEXAGONAL_ICE].color = (0.0, 0.0, 1.0)
.
-
class
ovito.modifiers.
ConstructSurfaceModifier
¶ - Base class
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. See the corresponding user manual page for more information.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.
Outputs:
Surface
The surface mesh computed by the modifier. You can access it through the
surfaces
dictionary in the outputDataCollection
under the lookup key"surface"
, see the code example below.ConstructSurfaceMesh.surface_area
The area of the surface mesh (in simulation length units squared).
ConstructSurfaceMesh.solid_volume
The volume of the solid region bounded by the surface mesh (in simulation length units cubed).
Selection
The property is set to a non-zero value for particles that form the surface. Only if
select_surface_particles
is set toTrue
.Example:
from ovito.io import import_file, export_file from ovito.data import SurfaceMesh, SimulationCell from ovito.modifiers import ConstructSurfaceModifier # Load a particle structure and reconstruct its geometric surface: pipeline = import_file("input/simulation.dump") pipeline.modifiers.append(ConstructSurfaceModifier(radius = 2.9)) data = pipeline.compute() mesh = data.surfaces['surface'] # 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'] / data.cell.volume print("Solid volume fraction: %f" % fraction) # Export the surface triangle mesh to a VTK file. export_file(mesh, "output/surface.vtk", "vtk/trimesh")
-
property
only_selected
¶ If
True
, the modifier acts only on selected particles and ignores other particles; ifFalse
, the modifier constructs the surface around all particles.- Default
False
-
property
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
-
property
select_surface_particles
¶ This option activates the selection of particles that form the constructed surface. When set to
True
, the modifier will generate theSelection
output particle property.- Default
False
-
property
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
-
property
vis
¶ The
SurfaceMeshVis
element controlling the visual representation of the generated surface in rendered images and animations.
-
class
ovito.modifiers.
SpatialBinningModifier
¶ - Base class
This modifier applies a reduction operation to a property of all the particles located within a spatial bin. The output of the modifier is a one-, two- or three-dimensional grid of bin values. See also the corresponding user manual page for this modifier.
-
property
bin_count_x
¶ This attribute sets the number of bins to generate along the first binning axis.
- Default
200
-
property
bin_count_y
¶ This attribute sets the number of bins to generate along the second binning axis (only used when generating a two- or three-dimensional grid).
- Default
200
-
property
bin_count_z
¶ This attribute sets the number of bins to generate along the third binning axis (only used when generting a three-dimensional grid).
- Default
200
-
property
direction
¶ Selects the alignment of the bins. Possible values:
SpatialBinningModifier.Direction.X
SpatialBinningModifier.Direction.Y
SpatialBinningModifier.Direction.Z
SpatialBinningModifier.Direction.XY
SpatialBinningModifier.Direction.XZ
SpatialBinningModifier.Direction.YZ
SpatialBinningModifier.Direction.XYZ
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
SpatialBinningModifier.Direction.X
-
property
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
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
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"
.
-
property
reduction_operation
¶ Selects the reduction operation to be carried out. Possible values are:
SpatialBinningModifier.Operation.Mean
SpatialBinningModifier.Operation.Sum
SpatialBinningModifier.Operation.SumVol
SpatialBinningModifier.Operation.Min
SpatialBinningModifier.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
SpatialBinningModifier.Operation.Mean
-
class
ovito.modifiers.
SpatialCorrelationFunctionModifier
¶ - Base class
This modifier calculates the spatial correlation function between two particle properties. See also the corresponding user manual page for this modifier.
The algorithm uses the FFT to compute the convolution. It then computes a radial average in reciprocal and real space. This gives the correlation function up to half of the cell size. The modifier can additionally compute the short-ranged part of the correlation function from a direct summation over neighbors.
Usage example:
from ovito.modifiers import SpatialCorrelationFunctionModifier from ovito.io import import_file, export_file pipeline = import_file("input/simulation.dump") mod = SpatialCorrelationFunctionModifier(property1='Position.X', property2='peatom') pipeline.modifiers.append(mod) data = pipeline.compute() # Export RDF and correlation functions to text files: C = data.series['correlation-real-space'] rdf = data.series['correlation-real-space-rdf'] export_file(C, 'output/real_correlation_function.txt', 'txt/series') export_file(rdf, 'output/rdf.txt', 'txt/series') # Compute normalized correlation function (by co-variance): C_norm = C.as_table() mean1 = data.attributes['CorrelationFunction.mean1'] mean2 = data.attributes['CorrelationFunction.mean2'] covariance = data.attributes['CorrelationFunction.covariance'] C_norm[:,1] = (C_norm[:,1] - mean1*mean2) / (covariance - mean1*mean2) import numpy numpy.savetxt('output/normalized_real_correlation_function.txt', C_norm)
-
property
apply_window
¶ This flag controls whether nonperiodic directions have a Hann window applied to them. Applying a window function is necessary to remove spurios oscillations and power-law scaling of the (implicit) rectangular window of the nonperiodic domain.
- Default
True
-
property
direct_summation
¶ Flag controlling whether the real-space correlation plot will show the result of a direct calculation of the correlation function, obtained by summing over neighbors.
- Default
False
-
property
grid_spacing
¶ Controls the approximate size of the FFT grid cell. The actual size is determined by the distance of the simulation cell faces which must contain an integer number of grid cells.
- Default
3.0
-
property
neighbor_bins
¶ This integer value controls the number of bins for the direct calculation of the real-space correlation function.
- Default
50
-
property
neighbor_cutoff
¶ This parameter determines the cutoff of the direct calculation of the real-space correlation function.
- Default
5.0
-
property
property1
¶ The name of the first input particle property for which to compute the correlation, P1. For vector properties a component name must be appended in the string, e.g.
"Velocity.X"
.- Default
''
-
class
ovito.modifiers.
DislocationAnalysisModifier
¶ - Base class
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]. See also the corresponding user manual page for this modifier.
The extracted dislocation lines are output as a
DislocationNetwork
object by the modifier and can be accessed through theDataCollection.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 on this page of the OVITO user manual.Inputs:
Position
The coordinates of the input particles.
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Dislocations
The dislocation lines found by the modifier. You can access this data object through the
dislocations
field of the outputDataCollection
, see the code example below.DislocationAnalysis.total_line_length
Total length of all dislocation lines found by the DXA (in simulation units).
DislocationAnalysis.length.1/n<ijk>
A set of attributes indicating the length of dislocations broken down by Burgers vector type. For example, the attribute
DislocationAnalysis.length.1/6<112>
specifies the total line length of Shockley partials found by the DXA.DislocationAnalysis.length.other
Total length of dislocation lines with an unusual Burgers vector that do not belong to any of the predefined standard dislocation types.
DislocationAnalysis.cell_volume
The volume of the input simulation cell. You can use it to calculate the dislocation density from the line length.
DislocationAnalysis.counts.OTHER
Number of particles not matching any of the known structural types.
DislocationAnalysis.counts.FCC
Number of particles identified as face-centered cubic structure.
DislocationAnalysis.counts.HCP
Number of particles identified as hexagonal close packed structure.
DislocationAnalysis.counts.BCC
Number of particles identified as body-centered cubic structure.
DislocationAnalysis.counts.CubicDiamond
Number of particles identified as cubic diamond structure.
DislocationAnalysis.counts.HexagonalDiamond
Number of particles identified as hexagonal diamond structure.
Structure Type
The structure type assigned to each particle by the CNA sub-algorithm, encoded as an integer value:
Value
Python constant
0
DislocationAnalysisModifier.Lattice.OTHER
1
DislocationAnalysisModifier.Lattice.FCC
2
DislocationAnalysisModifier.Lattice.HCP
3
DislocationAnalysisModifier.Lattice.BCC
4
DislocationAnalysisModifier.Lattice.CubicDiamond
5
DislocationAnalysisModifier.Lattice.HexagonalDiamond
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).Cluster
The ID of the cluster each atom has been assigned to. A “cluster” is a contiguous group of atoms, all being of the same crystalline structure type. Non-crystalline atoms are assigned to cluster ID 0.
Example:
from ovito.io import import_file, export_file from ovito.modifiers import DislocationAnalysisModifier from ovito.data import DislocationNetwork pipeline = import_file("input/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: print("Found %i dislocation segments" % len(data.dislocations.segments)) for segment in data.dislocations.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, "output/dislocations.ca", "ca") # Or export dislocations to a ParaView VTK file: export_file(pipeline, "output/dislocations.vtk", "vtk/disloc")
-
property
circuit_stretchability
¶ The number of steps by which a Burgers circuit can stretch while it is being advanced along a dislocation line.
- Default
9
-
property
color_by_type
¶ Controls whether the modifier assigns a color to each particle based on the identified structure type.
- Default
True
-
property
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
-
property
defect_vis
¶ The
SurfaceMeshVis
element controlling the visual representation of the generated defect mesh.
-
property
disloc_vis
¶ The
DislocationVis
element controlling the visual representation of the generated dislocation lines.
-
property
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
-
property
line_coarsening_enabled
¶ Flag that enables the coarsening of extracted dislocation lines, which reduces the number of sample points along the lines.
- Default
True
-
property
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
-
property
line_smoothing_enabled
¶ Flag that enables the smoothing of extracted dislocation lines after they have been coarsened.
- Default
True
-
property
line_smoothing_level
¶ The number of iterations of the line smoothing algorithm to perform.
- Default
1
-
property
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
-
property
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
-
property
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
This modifier computes the atomic-level elastic strain and deformation gradient tensors in crystalline systems. See also the corresponding user manual page for this modifier.
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 theinput_crystal_structure
property. Atoms that do not form a crystalline structure or which are part of defects are assigned the special typeOTHER
(=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 namedElastic 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 asOTHER
) will be assigned the null tensor.If
calculate_strain_tensors
is set to true, the modifier outputs a new particle property namedElastic 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 asOTHER
) 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 asOTHER
) will be assigned a value of zero.Inputs:
Position
The coordinates of the input particles.
Selection
The selection state of the input particles. Only needed if
only_selected
isTrue
.Outputs:
Elastic Deformation Gradient
The computed per-atom elastic deformation gradient tensors. Each tensor consists of 9 components stored in column-major order. All components will be set to zero for atoms for which no elastic deformation tensor could be determined (because they were classified as
OTHER
). This output property is only generated ifcalculate_deformation_gradients
is set toTrue
.Elastic Strain
The computed per-atom elastic strain tensor. Each symmetric strain tensor has six components stored in the order XX, YY, ZZ, XY, XZ, YZ. All components will be set to zero for atoms for which no elastic strain tensor could be determined (because they were classified as
OTHER
). This output property is only generated ifcalculate_strain_tensors
is set toTrue
.Volumetric Strain
Scalar particle property which is set to one third of the trace of the computed local elastic strain tensor. Atoms for which no elastic strain tensor could be determined (because they were classified as
OTHER
) will have a volumetric strain value of zero.Structure Type
The structure type determined by the algorithm for each particle, encoded as an integer value:
Value
Python constant
0
ElasticStrainModifier.Lattice.OTHER
1
ElasticStrainModifier.Lattice.FCC
2
ElasticStrainModifier.Lattice.HCP
3
ElasticStrainModifier.Lattice.BCC
4
ElasticStrainModifier.Lattice.CubicDiamond
5
ElasticStrainModifier.Lattice.HexagonalDiamond
Color
A per-particle color representing the identified structure type (only if
color_by_type
isTrue
).Cluster
The ID of the cluster each atom has been assigned to. A “cluster” is a contiguous group of atoms, all being of the same crystalline structure type. Non-crystalline atoms are assigned the invalid cluster ID 0.
-
property
axial_ratio
¶ The c/a ratio of the ideal unit cell for crystals with hexagonal symmetry.
- Default
sqrt(8/3)
-
property
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
-
property
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
-
property
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
-
property
lattice_constant
¶ Lattice constant (a0) of the ideal unit cell.
- Default
1.0
-
property
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.
VoroTopModifier
¶ - Base class
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 theSelectTypeModifier
.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.
See also the corresponding user manual page for this modifier.
-
property
filter_file
¶ Path to the filter definition file used by the modifier. Filters files are available from the VoroTop website.
- Default
''
-
property
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
-
property
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type loaded from thefilter_file
.
-
property
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