ovito.modifiers
¶
This module contains all modifiers of OVITO.
The abstract base class of all modifier types is the Modifier
class.
Typically you create a modifier instance, set its parameters, and finally insert it into the
modification pipeline of an ObjectNode
, e.g.:
from ovito.modifiers import *
m = AssignColorModifier()
m.color = (0.2, 1.0, 0.9)
node.modifiers.append(m)
The following modifier types are available:
Note that some analysis modifiers are not accessible from Python. That is because they do things that can be achieved equally well using the Numpy python module.
-
class
ovito.modifiers.
AffineTransformationModifier
¶ Base class: ovito.modifiers.Modifier
Applies an affine transformation to particles and/or the simulation cell.
Example:
from ovito.modifiers import * xy_shear = 0.05 mod = AffineTransformationModifier( transform_particles = True, transform_box = True, transformation = [[1,xy_shear,0,0], [0, 1,0,0], [0, 0,1,0]])
-
only_selected
¶ If
True
, the modifier acts only on selected particles; ifFalse
, the modifier acts on all particles.Default: False
-
relative_mode
¶ Selects the operation mode of the modifier.
If
relative_mode==True
, the modifier transforms the particles and/or the simulation cell by applying the matrix given by thetransformation
parameter.If
relative_mode==False
, the modifier transforms the particles and/or the simulation cell such that the old simulation cell will have the shape given by the thetarget_cell
parameter after the transformation.Default: True
-
target_cell
¶ This 3x4 matrix specifies the target cell shape. It is used when
relative_mode
==False
.The first three columns of the matrix specify the three edge vectors of the target cell. The fourth column defines the origin vector of the target cell.
-
transform_box
¶ If
True
, the modifier transforms the simulation cell.Default: False
-
transform_particles
¶ If
True
, the modifier transforms the particle positions.Default: True
-
transform_surface
¶ If
True
, the modifier transforms the surface mesh (if any) that has previously been generated by aConstructSurfaceModifier
.Default: True
-
transformation
¶ The 3x4 transformation matrix being applied to particle positions and/or the simulation cell. The first three matrix columns define the linear part of the transformation, while the fourth column specifies the translation vector.
This matrix describes a relative transformation and is used only if
relative_mode
==True
.Default: [[ 1. 0. 0. 0.] [ 0. 1. 0. 0.] [ 0. 0. 1. 0.]]
-
-
class
ovito.modifiers.
AmbientOcclusionModifier
¶ Base class: ovito.modifiers.Modifier
Performs a quick lighting calculation to shade particles according to the degree of occlusion by other particles.
-
buffer_resolution
¶ A positive integer controlling the resolution of the internal render buffer, which is used to compute how much light each particle receives. When the number of particles is large, a larger buffer resolution should be used.
Valid range: [1, 4] Default: 3
-
intensity
¶ A number controlling the strength of the applied shading effect.
Valid range: [0.0, 1.0] Default: 0.7
-
sample_count
¶ The number of light exposure samples to compute. More samples give a more even light distribution but take longer to compute.
Default: 40
-
-
class
ovito.modifiers.
AssignColorModifier
¶ Base class: ovito.modifiers.Modifier
Assigns a uniform color to all selected particles. If no particle selection is defined (i.e. the
"Selection"
particle property does not exist), the modifier assigns the color to all particles.-
color
¶ The color that will be assigned to particles.
Default: (0.3,0.3,1.0)
-
-
class
ovito.modifiers.
AtomicStrainModifier
¶ Base class: ovito.modifiers.Modifier
Computes the atomic-level deformation with respect to a reference configuration. The reference configuration required for the calculation must be explicitly loaded from an external simulation file:
from ovito.modifiers import * modifier = AtomicStrainModifier() modifier.reference.load("initial_config.dump")
Modifier outputs:
Shear Strain
(ParticleProperty
): The von Mises shear strain invariant of the atomic Green-Lagrangian strain tensor.Volumetric Strain
(ParticleProperty
): One third of the trace of the atomic Green-Lagrangian strain tensor.Strain Tensor
(ParticleProperty
): The six components of the symmetric Green-Lagrangian strain tensor. Output of this property must be explicitly enabled with theoutput_strain_tensors
flag.Deformation Gradient
(ParticleProperty
): The nine components of the atomic deformation gradient tensor. Output of this property must be explicitly enabled with theoutput_deformation_gradients
flag.Stretch Tensor
(ParticleProperty
): The six components of the symmetric right stretch tensor U in the polar decomposition F=RU. Output of this property must be explicitly enabled with theoutput_stretch_tensors
flag.Rotation
(ParticleProperty
): The atomic microrotation obtained from the polar decomposition F=RU as a quaternion. Output of this property must be explicitly enabled with theoutput_rotations
flag.Nonaffine Squared Displacement
(ParticleProperty
): The D2min measure of Falk & Langer, which describes the non-affine part of the local deformation. Output of this property must be explicitly enabled with theoutput_nonaffine_squared_displacements
flag.Selection
(ParticleProperty
): The modifier can select those particles for which a local deformation could not be computed because there were not enough neighbors within thecutoff
range. Those particles with invalid deformation values can subsequently be removed using theDeleteSelectedParticlesModifier
, for example. Selection of invalid particles is controlled by theselect_invalid_particles
flag.AtomicStrain.invalid_particle_count
(attribute
): The number of particles for which the local strain calculation failed because they had not enough neighbors within thecutoff
range.
-
assume_unwrapped_coordinates
¶ If
True
, the particle coordinates of the reference and of the current configuration are taken as is. IfFalse
, the minimum image convention is used to deal with particles that have crossed a periodic boundary.Default: False
-
cutoff
¶ Sets the distance up to which neighbor atoms are taken into account in the local strain calculation.
Default: 3.0
-
eliminate_cell_deformation
¶ Boolean flag that controls the elimination of the affine cell deformation prior to calculating the local strain.
Default: False
-
frame_offset
¶ The relative frame offset when using a sliding reference configuration (
use_frame_offset==True
).Default: -1
-
output_deformation_gradients
¶ Controls the output of the per-particle deformation gradient tensors. If
False
, the computed tensors are not output as a particle property to save memory.Default: False
-
output_nonaffine_squared_displacements
¶ Enables the computation of the squared magnitude of the non-affine part of the atomic displacements. The computed values are output in the
"Nonaffine Squared Displacement"
particle property.Default: False
-
output_rotations
¶ Flag that controls the calculation of the per-particle rotations.
Default: False
-
output_strain_tensors
¶ Controls the output of the per-particle strain tensors. If
False
, the computed strain tensors are not output as a particle property to save memory.Default: False
-
output_stretch_tensors
¶ Flag that controls the calculation of the per-particle stretch tensors.
Default: False
-
reference
¶ A
FileSource
that provides the reference positions of particles. You can call itsload()
function to load a reference simulation file as shown in the code example above.
-
reference_frame
¶ The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if
use_frame_offset==False
.Default: 0
-
select_invalid_particles
¶ If
True
, the modifier selects the particle for which the local strain tensor could not be computed (because of an insufficient number of neighbors within the cutoff).Default: True
-
use_frame_offset
¶ Determines whether a sliding reference configuration is taken at a constant time offset (specified by
frame_offset
) relative to the current frame. IfFalse
, a constant reference configuration is used (set by thereference_frame
parameter) irrespective of the current frame.Default: False
-
class
ovito.modifiers.
BinAndReduceModifier
¶ Base class: ovito.modifiers.Modifier
This modifier applies a reduction operation to a property of the particles within a spatial bin. The output of the modifier is a one or two-dimensional grid of bin values.
-
axis_range_x
¶ A 2-tuple containing the range of the generated bin grid along the first binning axis. Note that this is an output attribute which is only valid after the modifier has performed the bin and reduce operation. That means you have to call
ovito.ObjectNode.compute()
first to evaluate the data pipeline.
-
axis_range_y
¶ A 2-tuple containing the range of the generated bin grid along the second binning axis. Note that this is an output attribute which is only valid after the modifier has performed the bin and reduce operation. That means you have to call
ovito.ObjectNode.compute()
first to evaluate the data pipeline.
-
bin_count_x
¶ This attribute sets the number of bins to generate along the first binning axis.
Default: 200
-
bin_count_y
¶ This attribute sets the number of bins to generate along the second binning axis (only used when working with a two-dimensional grid).
Default: 200
-
bin_data
¶ Returns a NumPy array containing the reduced bin values computed by the modifier. Depending on the selected binning
direction
the returned array is either one or two-dimensional. In the two-dimensional case the outer index of the returned array runs over the bins along the second binning axis.Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call
ovito.ObjectNode.compute()
first to ensure that the binning and reduction operation was performed.
-
direction
¶ Selects the alignment of the bins. Possible values:
BinAndReduceModifier.Direction.Vector_1
BinAndReduceModifier.Direction.Vector_2
BinAndReduceModifier.Direction.Vector_3
BinAndReduceModifier.Direction.Vectors_1_2
BinAndReduceModifier.Direction.Vectors_1_3
BinAndReduceModifier.Direction.Vectors_2_3
In the first three cases the modifier generates a one-dimensional grid with bins aligned perpendicular to the selected simulation cell vector. In the last three cases the modifier generates a two-dimensional grid with bins aligned perpendicular to both selected simulation cell vectors (i.e. parallel to the third vector).
Default: BinAndReduceModifier.Direction.Vector_3
-
first_derivative
¶ If true, the modifier numerically computes the first derivative of the binned data using a finite differences approximation. This works only for one-dimensional bin grids.
Default: False
-
only_selected
¶ If
True
, the computation takes into account only the currently selected particles. You can use this to restrict the calculation to a subset of particles.Default: False
-
property
¶ The name of the input particle property to which the reduction operation should be applied. This can be one of the standard particle properties or a custom particle property. For vector properties the selected component must be appended to the name, e.g.
"Velocity.X"
.
-
reduction_operation
¶ Selects the reduction operation to be carried out. Possible values are:
BinAndReduceModifier.Operation.Mean
BinAndReduceModifier.Operation.Sum
BinAndReduceModifier.Operation.SumVol
BinAndReduceModifier.Operation.Min
BinAndReduceModifier.Operation.Max
The operation
SumVol
first computes the sum and then divides the result by the volume of the respective bin. It is intended to compute pressure (or stress) within each bin from the per-atom virial.Default: BinAndReduceModifier.Operation.Mean
-
-
class
ovito.modifiers.
BondAngleAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
Performs the bond-angle analysis described by Ackland & Jones to classify the local crystal structure around each particle.
The modifier stores the results as integer values in the
"Structure Type"
particle property. The following structure type constants are defined:BondAngleAnalysisModifier.Type.OTHER
(0)BondAngleAnalysisModifier.Type.FCC
(1)BondAngleAnalysisModifier.Type.HCP
(2)BondAngleAnalysisModifier.Type.BCC
(3)BondAngleAnalysisModifier.Type.ICO
(4)
Modifier outputs:
BondAngleAnalysis.counts.OTHER
(attribute
): The number of particles not matching any of the known structure types.BondAngleAnalysis.counts.FCC
(attribute
): The number of FCC particles found.BondAngleAnalysis.counts.HCP
(attribute
): The number of HCP particles found.BondAngleAnalysis.counts.BCC
(attribute
): The number of BCC particles found.BondAngleAnalysis.counts.ICO
(attribute
): The number of icosahedral found.Structure Type
(ParticleProperty
): This particle property will contain the per-particle structure type assigned by the modifier.Color
(ParticleProperty
): The modifier assigns a color to each particle based on its identified structure type. You can change the color representing a structural type as follows:modifier = BondAngleAnalysisModifier() # Give all FCC atoms a blue color: modifier.structures[BondAngleAnalysisModifier.Type.FCC].color = (0.0, 0.0, 1.0)
-
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type. You can adjust the color of structural types as shown in the code example above.
-
class
ovito.modifiers.
CalculateDisplacementsModifier
¶ Base class: ovito.modifiers.Modifier
Computes the displacement vectors of particles based on a separate reference configuration. The modifier requires you to load a reference configuration from an external file:
from ovito.modifiers import * modifier = CalculateDisplacementsModifier() modifier.reference.load("frame0000.dump")
The modifier stores the computed displacement vectors in the
"Displacement"
particle property. The displacement magnitudes are stored in the"Displacement Magnitude"
property.-
assume_unwrapped_coordinates
¶ If
True
, the particle coordinates of the reference and of the current configuration are taken as is. IfFalse
, the minimum image convention is used to deal with particles that have crossed a periodic boundary.Default: False
-
eliminate_cell_deformation
¶ Boolean flag that controls the elimination of the affine cell deformation prior to calculating the displacement vectors.
Default: False
-
frame_offset
¶ The relative frame offset when using a sliding reference configuration (
use_frame_offset==True
).Default: -1
-
reference
¶ A
FileSource
that provides the reference positions of particles. You can call itsload()
function to load a reference simulation file as shown in the code example above.
-
reference_frame
¶ The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if
use_frame_offset==False
.Default: 0
-
use_frame_offset
¶ Determines whether a sliding reference configuration is taken at a constant time offset (specified by
frame_offset
) relative to the current frame. IfFalse
, a constant reference configuration is used (set by thereference_frame
parameter) irrespective of the current frame.Default: False
-
vector_display
¶ A
VectorDisplay
instance controlling the visual representation of the computed displacement vectors. Note that the computed displacement vectors are not shown by default. You can enable the arrow display as follows:modifier = CalculateDisplacementsModifier() modifier.vector_display.enabled = True modifier.vector_display.color = (0,0,0)
-
-
class
ovito.modifiers.
CentroSymmetryModifier
¶ Base class: ovito.modifiers.Modifier
Computes the centro-symmetry parameter (CSP) of each particle.
The modifier outputs the computed values in the
"Centrosymmetry"
particle property.-
num_neighbors
¶ The number of neighbors to take into account (12 for FCC crystals, 8 for BCC crystals).
Default: 12
-
-
class
ovito.modifiers.
ClearSelectionModifier
¶ Base class: ovito.modifiers.Modifier
This modifier clears the particle selection by deleting the
"Selection"
particle property. The modifier has no input parameters.
-
class
ovito.modifiers.
ClusterAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
Groups particles into clusters using a distance cutoff criterion.
Modifier outputs:
Cluster
(ParticleProperty
): This output particle property stores the IDs of the clusters the particles have been assigned to.ClusterAnalysis.cluster_count
(attribute
): The total number of clusters produced by the modifier. Cluster IDs range from 1 to this number.ClusterAnalysis.largest_size
(attribute
): The number of particles belonging to the largest cluster (cluster ID 1). This attribute is only computed by the modifier whensort_by_size
is set.
Example:
The following script demonstrates how to apply the numpy.bincount() function to the generated
Cluster
particle property to determine the size (=number of particles) of each cluster found by the modifier.from ovito.io import import_file from ovito.modifiers import ClusterAnalysisModifier import numpy node = import_file("simulation.dump") node.modifiers.append(ClusterAnalysisModifier(cutoff = 2.8, sort_by_size = True)) node.compute() cluster_sizes = numpy.bincount(node.output.particle_properties['Cluster'].array) numpy.savetxt("cluster_sizes.txt", cluster_sizes)
-
cutoff
¶ The cutoff distance used by the algorithm to form clusters of connected particles.
Default: 3.2
-
only_selected
¶ Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be assigned cluster ID 0 and treated as if they did not exist.
Default: False
-
sort_by_size
¶ Enables the sorting of clusters by size (in descending order). Cluster 1 will be the largest cluster, cluster 2 the second largest, and so on.
Default: False
-
class
ovito.modifiers.
ColorCodingModifier
¶ Base class: ovito.modifiers.Modifier
Colors particles, bonds, or vectors based on the value of a property.
Usage example:
from ovito.modifiers import * modifier = ColorCodingModifier( particle_property = "Potential Energy", gradient = ColorCodingModifier.Hot() ) node.modifiers.append(modifier)
If, as in the example above, the
start_value
andend_value
parameters are not explicitly set, then the modifier automatically adjusts them to the minimum and maximum values of the property when the modifier is inserted into the modification pipeline.-
assign_to
¶ - Determines what the modifier assigns the colors to. This must be one of the following constants:
ColorCodingModifier.AssignmentMode.Particles
ColorCodingModifier.AssignmentMode.Bonds
ColorCodingModifier.AssignmentMode.Vectors
If this attribute is set to
Bonds
, then the bond property selected bybond_property
is used to color bonds. Otherwise the particle property selected byparticle_property
is used to color particles or vectors.Default: ColorCodingModifier.AssignmentMode.Particles
-
bond_property
¶ The name of the input bond property that should be used to color bonds. This can be one of the standard bond properties or a custom bond property.
This field is only used if
assign_to
is set toBonds
.
-
end_value
¶ This parameter defines the value range when mapping the input property to a color.
-
gradient
¶ - The color gradient object, which is responsible for mapping normalized property values to colors. Available gradient types are:
ColorCodingModifier.BlueWhiteRed()
ColorCodingModifier.Grayscale()
ColorCodingModifier.Hot()
ColorCodingModifier.Jet()
ColorCodingModifier.Magma()
ColorCodingModifier.Rainbow()
[default]ColorCodingModifier.Viridis()
ColorCodingModifier.Custom("<image file>")
The last color map constructor expects the path to an image file on disk, which will be used to create a custom color gradient from a row of pixels in the image.
-
only_selected
¶ If
True
, only selected particles or bonds will be affected by the modifier and the existing colors of unselected particles or bonds will be preserved; ifFalse
, all particles/bonds will be colored.Default: False
-
particle_property
¶ The name of the input particle property that should be used to color particles. This can be one of the standard particle properties or a custom particle property. When using vector properties the component must be included in the name, e.g.
"Velocity.X"
.This field is only used if
bond_mode
is not set toBonds
.
-
start_value
¶ This parameter defines the value range when mapping the input property to a color.
-
-
class
ovito.modifiers.
CombineParticleSetsModifier
¶ Base class: ovito.modifiers.Modifier
This modifier loads a set of particles from a separate simulation file and merges them into the current dataset.
Example:
from ovito.io import * from ovito.modifiers import CombineParticleSetsModifier # Load a first set of particles. node = import_file('first_file.dump') # Insert the particles from a second file into the dataset. modifier = CombineParticleSetsModifier() modifier.source.load('second_file.dump') node.modifiers.append(modifier) # Export combined dataset to a new file. export_file(node, 'output.dump', 'lammps_dump', columns = ['Position.X', 'Position.Y', 'Position.Z']) # The particle set leaving the pipeline is the union of the two inputs. assert(node.compute().number_of_particles == node.source.number_of_particles + modifier.source.number_of_particles)
-
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.
CommonNeighborAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
Performs the common neighbor analysis (CNA) to classify the structure of the local neighborhood of each particle.
The modifier stores its results as integer values in the
"Structure Type"
particle property. The following constants are defined:CommonNeighborAnalysisModifier.Type.OTHER
(0)CommonNeighborAnalysisModifier.Type.FCC
(1)CommonNeighborAnalysisModifier.Type.HCP
(2)CommonNeighborAnalysisModifier.Type.BCC
(3)CommonNeighborAnalysisModifier.Type.ICO
(4)
Modifier outputs:
CommonNeighborAnalysis.counts.OTHER
(attribute
): The number of particles not matching any of the known structure types.CommonNeighborAnalysis.counts.FCC
(attribute
): The number of FCC particles found.CommonNeighborAnalysis.counts.HCP
(attribute
): The number of HCP particles found.CommonNeighborAnalysis.counts.BCC
(attribute
): The number of BCC particles found.CommonNeighborAnalysis.counts.ICO
(attribute
): The number of icosahedral particles found.Structure Type
(ParticleProperty
): This output particle property contains the per-particle structure types assigned by the modifier.Color
(ParticleProperty
): The modifier assigns a color to each particle based on its identified structure type. You can change the color representing a structural type as follows:modifier = CommonNeighborAnalysisModifier() # Give all FCC atoms a blue color: modifier.structures[CommonNeighborAnalysisModifier.Type.FCC].color = (0.0, 0.0, 1.0)
-
cutoff
¶ The cutoff radius used for the conventional common neighbor analysis. This parameter is only used if
mode
==CommonNeighborAnalysisModifier.Mode.FixedCutoff
.Default: 3.2
-
mode
¶ Selects the mode of operation. Valid values are:
CommonNeighborAnalysisModifier.Mode.FixedCutoff
CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
CommonNeighborAnalysisModifier.Mode.BondBased
Default: CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff
-
only_selected
¶ Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be treated as if they did not exist.
Default: False
-
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type. You can adjust the color of structural types as shown in the code example above.
-
class
ovito.modifiers.
ComputeBondLengthsModifier
¶ Base class: ovito.modifiers.Modifier
Computes the length of every bond in the system and outputs the values as a new bond property named
Length
.Modifier outputs:
Length
(BondProperty
): The output bond property containing the length of each bond.
-
class
ovito.modifiers.
ComputePropertyModifier
¶ Base class: ovito.modifiers.Modifier
Evaluates a user-defined math expression to compute the values of a particle property.
Example:
from ovito.modifiers import * modifier = ComputePropertyModifier() modifier.output_property = "Color" modifier.expressions = ["Position.X / CellSize.X", "0.0", "0.5"]
-
cutoff_radius
¶ The cutoff radius up to which neighboring particles are visited. This parameter is only used if
neighbor_mode
is enabled.Default: 3.0
-
expressions
¶ A list of strings containing the math expressions to compute, one for each vector component of the output property. If the output property is a scalar property, the list should comprise exactly one string.
Default: ["0"]
-
neighbor_expressions
¶ A list of strings containing the math expressions for the per-neighbor terms, one for each vector component of the output property. If the output property is a scalar property, the list should comprise exactly one string.
The neighbor expressions are only evaluated if
neighbor_mode
is enabled.Default: ["0"]
-
neighbor_mode
¶ Boolean flag that enabled the neighbor computation mode, where contributions from neighbor particles within the cutoff radius are taken into account.
Default: False
-
only_selected
¶ If
True
, the property is only computed for selected particles and existing property values are preserved for unselected particles.Default: False
-
output_property
¶ The output particle property in which the modifier should store the computed values.
Default: "Custom property"
-
-
class
ovito.modifiers.
ConstructSurfaceModifier
¶ Base class: ovito.modifiers.Modifier
Constructs the geometric surface of a solid made of point-like particles. The modifier generates a
SurfaceMesh
, which is a closed manifold consisting of triangles. It also computes the total surface area and the volume of the region enclosed by the surface mesh.The
radius
parameter controls how many details of the solid shape are resolved during surface construction. A larger radius leads to a surface with fewer details, reflecting only coarse features of the surface topology. A small radius, on the other hand, will resolve finer surface features and small pores in the interior of a solid, for example.See [A. Stukowski, JOM 66 (2014), 399-407] for a description of the surface construction algorithm.
Modifier outputs:
DataCollection.surface
(SurfaceMesh
): This property of the output data collection provides access to the surface mesh computed by the modifier. See the example script below.ConstructSurfaceMesh.surface_area
(attribute
): The area of the surface mesh.ConstructSurfaceMesh.solid_volume
(attribute
): The volume of the solid region bounded by the surface mesh.
Example:
from ovito.io import import_file from ovito.modifiers import ConstructSurfaceModifier # Load a particle structure and construct its geometric surface: node = import_file("simulation.dump") mod = ConstructSurfaceModifier(radius = 2.9) node.modifiers.append(mod) node.compute() # Query computed surface properties: print("Surface area: %f" % node.output.attributes['ConstructSurfaceMesh.surface_area']) print("Solid volume: %f" % node.output.attributes['ConstructSurfaceMesh.solid_volume']) fraction = node.output.attributes['ConstructSurfaceMesh.solid_volume'] / node.output.cell.volume print("Solid volume fraction: %f" % fraction) # Export the surface triangle mesh to a VTK file. mesh = node.output.surface mesh.export_vtk('surface.vtk', node.output.cell)
-
mesh_display
¶ The
SurfaceMeshDisplay
controlling the visual representation of the computed surface.
-
only_selected
¶ If
True
, the modifier acts only on selected particles and ignores other particles; ifFalse
, the modifier constructs the surface around all particles.Default: False
-
radius
¶ The radius of the probe sphere used in the surface construction algorithm.
A rule of thumb is that the radius parameter should be slightly larger than the typical distance between nearest neighbor particles.
Default: 4.0
-
smoothing_level
¶ The number of iterations of the smoothing algorithm applied to the computed surface mesh.
Note that the smoothing level does only affect the computed surface area but not the solid volume. That is because the solid volume is computed before smoothing the mesh. (Smoothing is supposed to be volume preserving.)
Default: 8
-
class
ovito.modifiers.
CoordinationNumberModifier
¶ Base class: ovito.modifiers.Modifier
Computes coordination numbers of particles and the radial distribution function (RDF) of the system.
The modifier stores the computed coordination numbers in the
"Coordination"
particle property.Example showing how to export the RDF data to a text file:
from ovito.io import import_file from ovito.modifiers import CoordinationNumberModifier import numpy # Load a particle dataset, apply modifier, and evaluate data pipeline. node = import_file("simulation.dump") modifier = CoordinationNumberModifier(cutoff = 5.0, number_of_bins = 200) node.modifiers.append(modifier) node.compute() # Export the computed RDF data to a text file. numpy.savetxt("output_rdf.txt", modifier.rdf)
-
cutoff
¶ The neighbor cutoff distance.
Default: 3.2
-
number_of_bins
¶ The number of histogram bins to use when computing the RDF.
Default: 200
-
rdf
¶ Returns a NumPy array containing the radial distribution function (RDF) computed by the modifier. The returned array is two-dimensional and consists of the [r, g(r)] data points of the tabulated g(r) RDF function.
Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call
ovito.ObjectNode.compute()
first to ensure that this information is up to date, see the example above.
-
-
class
ovito.modifiers.
CreateBondsModifier
¶ Base class: ovito.modifiers.Modifier
Creates bonds between nearby particles. The modifier outputs its results as a
Bonds
data object, which can be accessed through theDataCollection.bonds
attribute of the pipeline output data collection.Modifier outputs:
CreateBonds.num_bonds
(attribute
): The number of full bonds created by the modifier.Bonds
object (DataCollection.bonds
): Contains the list of bonds created by the modifier.
-
bonds_display
¶ The
BondsDisplay
object controlling the visual appearance of the bonds created by this modifier.
-
cutoff
¶ The maximum cutoff distance for the creation of bonds between particles. This parameter is only used if
mode
isUniform
.Default: 3.2
-
get_pairwise_cutoff
()¶ Returns the pair-wise cutoff distance set for a pair of atom types.
Parameters: Returns: The cutoff distance set for the type pair. Returns zero if no cutoff has been set for the pair.
-
intra_molecule_only
¶ If this option is set to true, the modifier will create bonds only between atoms that belong to the same molecule (i.e. which have the same molecule ID assigned to them).
Default: False
-
lower_cutoff
¶ The minimum bond length. No bonds will be created between atoms whose distance is below this threshold.
Default: 0.0
-
mode
¶ Selects the mode of operation. Valid modes are:
CreateBondsModifier.Mode.Uniform
CreateBondsModifier.Mode.Pairwise
In
Uniform
mode one globalcutoff
is used irrespective of the atom types. InPairwise
mode a separate cutoff distance must be specified for all pairs of atom types between which bonds are to be created.Default: CreateBondsModifier.Mode.Uniform
-
class
ovito.modifiers.
DeleteSelectedParticlesModifier
¶ Base class: ovito.modifiers.Modifier
This modifier deletes the selected particles. It has no parameters.
-
class
ovito.modifiers.
DislocationAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
This analysis modifier extracts all dislocations in a crystal and converts them to continuous line segments. The computational method behind this is called Dislocation Extraction Algorithm (DXA) and is described in the paper [MSMSE 20 (2012), 085007].
The extracted dislocation lines are output as a
DislocationNetwork
object by the modifier and can be accessed through 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 in the documentation section of the OVITO user manual for the Dislocation Analysis modifier.Modifier outputs:
DataCollection.dislocations
(DislocationNetwork
): This property of the output data collection provides access to the dislocation lines found by the modifier. See the example script below.DislocationAnalysis.total_line_length
(attribute
): The total length of all dislocation lines found by the DXA.DislocationAnalysis.length.1/n<ijk>
(attribute
): The modifier outputs a set of attributes that indicate the length of dislocations broken down by Burgers vector type. For example, the attributeDislocationAnalysis.length.1/6<112>
specifies the total amount of Shockley partials found by the DXA.DislocationAnalysis.length.other
(attribute
): The length of dislocation lines with an unusual Burgers vector that do not belong to any of the predefined standard dislocation types.DislocationAnalysis.cell_volume
(attribute
): The volume of the simulation cell. This is output for convenience to enable the calculation of dislocation densities from the line length.DislocationAnalysis.counts.OTHER
(attribute
): The number of particles not matching any of the known structure types.DislocationAnalysis.counts.FCC
(attribute
): The number of particles with local FCC structure.DislocationAnalysis.counts.HCP
(attribute
): The number of particles with local HCP structure.DislocationAnalysis.counts.BCC
(attribute
): The number of particles with local BCC structure.DislocationAnalysis.counts.CubicDiamond
(attribute
): The number of particles with local cubic diamond structure.DislocationAnalysis.counts.HexagonalDiamond
(attribute
): The number of particles with local hexagonal diamond structure.
Example:
from ovito.io import import_file, export_file from ovito.modifiers import DislocationAnalysisModifier node = import_file("simulation.dump") # Extract dislocation lines from a crystal with diamond structure: modifier = DislocationAnalysisModifier() modifier.input_crystal_structure = DislocationAnalysisModifier.Lattice.CubicDiamond node.modifiers.append(modifier) node.compute() total_line_length = node.output.attributes['DislocationAnalysis.total_line_length'] print("Dislocation density: %f" % (total_line_length / node.output.cell.volume)) # Print list of dislocation lines: network = node.output.dislocations print("Found %i dislocation segments" % len(network.segments)) for segment in network.segments: print("Segment %i: length=%f, Burgers vector=%s" % (segment.id, segment.length, segment.true_burgers_vector)) print(segment.points) # Export dislocation lines to a CA file: export_file(node, "dislocations.ca", "ca")
-
circuit_stretchability
¶ The number of steps by which a Burgers circuit can stretch while it is being advanced along a dislocation line.
Default: 9
-
defect_mesh_smoothing_level
¶ Specifies the number of iterations of the surface smoothing algorithm to perform when post-processing the extracted defect mesh.
Default: 8
-
input_crystal_structure
¶ The type of crystal to analyze. Must be one of:
DislocationAnalysisModifier.Lattice.FCC
DislocationAnalysisModifier.Lattice.HCP
DislocationAnalysisModifier.Lattice.BCC
DislocationAnalysisModifier.Lattice.CubicDiamond
DislocationAnalysisModifier.Lattice.HexagonalDiamond
Default: DislocationAnalysisModifier.Lattice.FCC
-
line_coarsening_enabled
¶ Flag that enables the coarsening of extracted dislocation lines, which reduces the number of sample points along the lines.
Default: True
-
line_point_separation
¶ Sets the desired distance between successive sample points along the dislocation lines, measured in multiples of the interatomic spacing. This parameter controls the amount of coarsening performed during post-processing of dislocation lines.
Default: 2.5
-
line_smoothing_enabled
¶ Flag that enables the smoothing of extracted dislocation lines after they have been coarsened.
Default: True
-
line_smoothing_level
¶ The number of iterations of the line smoothing algorithm to perform.
Default: 1
-
only_perfect_dislocations
¶ This flag controls whether the algorithm should extract only perfect dislocations (and no partial dislocations, which is normally done for FCC/HCP and diamond lattices). Make sure you set the
circuit_stretchability
parameter to a high value when activating this option, because large Burgers circuits are needed to identify dissociated dislocations with a wide core.Default: False
-
trial_circuit_length
¶ The maximum length of trial Burgers circuits constructed by the DXA to discover dislocations. The length is specified in terms of the number of atom-to-atom steps.
Default: 14
-
class
ovito.modifiers.
ElasticStrainModifier
¶ Base class: ovito.modifiers.Modifier
This modifier computes the atomic-level elastic strain and deformation gradient tensors in crystalline systems.
The modifier first performs an identification of the local crystal structure and stores the results in the
Structure Type
particle property. Possible structure type values are listed under 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.-
axial_ratio
¶ The c/a ratio of the ideal unit cell for crystals with hexagonal symmetry.
Default: sqrt(8/3)
-
calculate_deformation_gradients
¶ Flag that enables the output of the calculated elastic deformation gradient tensors. The per-particle tensors will be stored in a new particle property named
Elastic Deformation Gradient
with nine components (stored in column-major order). Particles for which the local elastic deformation cannot be calculated, are assigned the null tensor.Default: False
-
calculate_strain_tensors
¶ Flag that enables the calculation and out of the elastic strain tensors. The symmetric strain tensors will be stored in a new particle property named
Elastic Strain
with six components (XX, YY, ZZ, XY, XZ, YZ).Default: True
-
input_crystal_structure
¶ The type of crystal to analyze. Must be one of:
ElasticStrainModifier.Lattice.FCC
ElasticStrainModifier.Lattice.HCP
ElasticStrainModifier.Lattice.BCC
ElasticStrainModifier.Lattice.CubicDiamond
ElasticStrainModifier.Lattice.HexagonalDiamond
Default: ElasticStrainModifier.Lattice.FCC
-
lattice_constant
¶ Lattice constant (a0) of the ideal unit cell.
Default: 1.0
-
push_strain_tensors_forward
¶ Selects the frame in which the elastic strain tensors are calculated.
If true, the Eulerian-Almansi finite strain tensor is computed, which measures the elastic strain in the global coordinate system (spatial frame).
If false, the Green-Lagrangian strain tensor is computed, which measures the elastic strain in the local lattice coordinate system (material frame).
Default: True
-
-
class
ovito.modifiers.
ExpandSelectionModifier
¶ Base class: ovito.modifiers.Modifier
Expands the current particle selection by selecting particles that are neighbors of already selected particles.
-
cutoff
¶ The maximum distance up to which particles are selected around already selected particles. This parameter is only used if
mode
is set toExpansionMode.Cutoff
.Default: 3.2
-
iterations
¶ Controls how many iterations of the modifier are executed. This can be used to select neighbors of neighbors up to a certain recursive depth.
Default: 1
-
mode
¶ Selects the mode of operation, i.e., how the modifier extends the selection around already selected particles. Valid values are:
ExpandSelectionModifier.ExpansionMode.Cutoff
ExpandSelectionModifier.ExpansionMode.Nearest
ExpandSelectionModifier.ExpansionMode.Bonded
Default: ExpandSelectionModifier.ExpansionMode.Cutoff
-
-
class
ovito.modifiers.
FreezePropertyModifier
¶ Base class: ovito.modifiers.Modifier
This modifier can store a static copy of a particle property and inject it back into the pipeline (optionally under a different name than the original property). Since the snapshot of the current particle property values is taken by the modifier at a particular animation time, the
FreezePropertyModifier
allows to freeze the property and overwrite any dynamically changing property values with the stored static copy.Example:
from ovito import * from ovito.io import * from ovito.modifiers import * # Load a simulation sequence. node = import_file("simulation.*.dump") # Add modifier for computing the coordination numbers of particles. node.modifiers.append(CoordinationNumberModifier(cutoff = 2.9)) # Save the initial coordination numbers at frame 0 under a different name. modifier = FreezePropertyModifier(source_property = 'Coordination', destination_property = 'Coord0') node.modifiers.append(modifier) # This will evaluate the modification pipeline at the current animation and up to # the FreezePropertyModifier. The current values of the 'Coordination' property are # stored and inserted back into the pipeline under the new name 'Coord0'. modifier.take_snapshot() # Select all particles whose coordination number has changed since frame 0 # by comapring the dynamically computed coordination numbers with the stored ones. node.modifiers.append(SelectExpressionModifier(expression='Coordination != Coord0')) # Write a table with the number of particles having a coordination number variation. export_file(node, 'output.txt', 'txt', columns = ['Timestep', 'SelectExpression.num_selected'], multiple_frames = True)
-
destination_property
¶ The name of the output particle property that should be written to by the modifier. It can be one of the standard particle properties or a custom particle property.
-
source_property
¶ The name of the input particle property that should be copied by the modifier. It can be one of the standard particle properties or a custom particle property.
-
take_snapshot
(frame=None)¶ Evaluates the modification pipeline up to this modifier and makes a copy of the current values of the
source_property
.Parameters: frame (int) – The animation frame at which to take the snapshot. If none
, the current animation frame is used (seeovito.anim.AnimationSettings.current_frame
).Note that
take_snapshot()
must be called after the modifier has been inserted into anObjectNode
‘s modification pipeline.
-
-
class
ovito.modifiers.
HistogramModifier
¶ Base class: ovito.modifiers.Modifier
Generates a histogram from the values of a particle property.
The value range of the histogram is determined automatically from the minimum and maximum values of the selected property unless
fix_xrange
is set toTrue
. In this case the range of the histogram is controlled by thexrange_start
andxrange_end
parameters.Example:
from ovito.modifiers import * modifier = HistogramModifier(bin_count=100, property="Potential Energy") node.modifiers.append(modifier) node.compute() import numpy numpy.savetxt("histogram.txt", modifier.histogram)
-
bin_count
¶ The number of histogram bins.
Default: 200
-
fix_xrange
¶ Controls how the value range of the histogram is determined. If false, the range is chosen automatically by the modifier to include all particle property values. If true, the range is specified manually using the
xrange_start
andxrange_end
attributes.Default: False
-
histogram
¶ Returns a NumPy array containing the histogram computed by the modifier. The returned array is two-dimensional and consists of [x, count(x)] value pairs, where x denotes the bin center and count(x) the number of particles whose property value falls into the bin.
Note that accessing this array is only possible after the modifier has computed its results. Thus, you have to call
ovito.ObjectNode.compute()
first to ensure that the histogram was generated.
-
only_selected
¶ If
True
, the histogram is computed only on the basis of currently selected particles. You can use this to restrict histogram calculation to a subset of particles.Default: False
-
property
¶ The name of the input particle property for which to compute the histogram. This can be one of the standard particle properties or a custom particle property. For vector properties a specific component name must be included in the string, e.g.
"Velocity.X"
.
-
xrange_end
¶ If
fix_xrange
is true, then this specifies the upper end of the value range covered by the histogram.Default: 0.0
-
xrange_start
¶ If
fix_xrange
is true, then this specifies the lower end of the value range covered by the histogram.Default: 0.0
-
-
class
ovito.modifiers.
IdentifyDiamondModifier
¶ Base class: ovito.modifiers.Modifier
This analysis modifier finds atoms that are arranged in a cubic or hexagonal diamond lattice.
The modifier stores its results as integer values in the
"Structure Type"
particle property. The following structure type constants are defined:IdentifyDiamondModifier.Type.OTHER
(0)IdentifyDiamondModifier.Type.CUBIC_DIAMOND
(1)IdentifyDiamondModifier.Type.CUBIC_DIAMOND_FIRST_NEIGHBOR
(2)IdentifyDiamondModifier.Type.CUBIC_DIAMOND_SECOND_NEIGHBOR
(3)IdentifyDiamondModifier.Type.HEX_DIAMOND
(4)IdentifyDiamondModifier.Type.HEX_DIAMOND_FIRST_NEIGHBOR
(5)IdentifyDiamondModifier.Type.HEX_DIAMOND_SECOND_NEIGHBOR
(6)
Modifier outputs:
IdentifyDiamond.counts.OTHER
(attribute
): The number of atoms not matching any of the known structure types.IdentifyDiamond.counts.CUBIC_DIAMOND
(attribute
): The number of cubic diamond atoms found.IdentifyDiamond.counts.CUBIC_DIAMOND_FIRST_NEIGHBOR
(attribute
): The number of atoms found that are first neighbors of a cubic diamond atom.IdentifyDiamond.counts.CUBIC_DIAMOND_SECOND_NEIGHBOR
(attribute
): The number of atoms found that are second neighbors of a cubic diamond atom.IdentifyDiamond.counts.HEX_DIAMOND
(attribute
): The number of hexagonal diamond atoms found.IdentifyDiamond.counts.HEX_DIAMOND_FIRST_NEIGHBOR
(attribute
): The number of atoms found that are first neighbors of a hexagonal diamond atom.IdentifyDiamond.counts.HEX_DIAMOND_SECOND_NEIGHBOR
(attribute
): The number of atoms found that are second neighbors of a hexagonal diamond atom.Structure Type
(ParticleProperty
): This particle property will contain the per-particle structure type assigned by the modifier.Color
(ParticleProperty
): The modifier assigns a color to each atom based on its identified structure type. You can change the color representing a structural type as follows:modifier = BondAngleAnalysisModifier() # Give all hexagonal diamond atoms a blue color: modifier.structures[IdentifyDiamondModifier.Type.HEX_DIAMOND].color = (0.0, 0.0, 1.0)
-
only_selected
¶ Lets the modifier perform the analysis only for selected particles. Particles that are not selected will be treated as if they did not exist.
Default: False
-
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type. You can adjust the color of structural types as shown in the code example above.
-
class
ovito.modifiers.
InvertSelectionModifier
¶ Base class: ovito.modifiers.Modifier
This modifier inverts the particle selection. It has no input parameters.
-
class
ovito.modifiers.
LoadTrajectoryModifier
¶ Base class: ovito.modifiers.Modifier
This modifier loads trajectories of particles from a separate simulation file.
A typical usage scenario for this modifier is when the topology of a molecular system (i.e. the definition of atom types, bonds, etc.) is stored separately from the trajectories of atoms. In this case you should load the topology file first using
import_file()
. Then create and apply 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. node = import_file('input.data', atom_style = 'bond') # Load atom trajectories from separate LAMMPS dump file. traj_mod = LoadTrajectoryModifier() traj_mod.source.load('trajectory.dump', multiple_frames = True) # Insert modifier into modification pipeline. node.modifiers.append(traj_mod)
-
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.
Modifier
¶ This is the base class for all modifiers in OVITO.
-
enabled
¶ Controls whether the modifier is applied to the input data. Modifiers which are not enabled are skipped even if they are part of a modification pipeline.
Default: True
-
-
class
ovito.modifiers.
PolyhedralTemplateMatchingModifier
¶ Base class: ovito.modifiers.Modifier
Uses the Polyhedral Template Matching (PTM) method to classify the local structural neighborhood of each particle.
The modifier stores its results as integer values in the
"Structure Type"
particle property. The following constants are defined:PolyhedralTemplateMatchingModifier.Type.OTHER
(0)PolyhedralTemplateMatchingModifier.Type.FCC
(1)PolyhedralTemplateMatchingModifier.Type.HCP
(2)PolyhedralTemplateMatchingModifier.Type.BCC
(3)PolyhedralTemplateMatchingModifier.Type.ICO
(4)PolyhedralTemplateMatchingModifier.Type.SC
(5)
Modifier outputs:
PolyhedralTemplateMatching.counts.OTHER
(attribute
): The number of particles not matching any of the known structure types.PolyhedralTemplateMatching.counts.FCC
(attribute
): The number of FCC particles found.PolyhedralTemplateMatching.counts.HCP
(attribute
): The number of HCP particles found.PolyhedralTemplateMatching.counts.BCC
(attribute
): The number of BCC particles found.PolyhedralTemplateMatching.counts.ICO
(attribute
): The number of icosahedral particles found.PolyhedralTemplateMatching.counts.SC
(attribute
): The number of simple cubic particles found.Structure Type
(ParticleProperty
): This output particle property will contain the per-particle structure types assigned by the modifier.RMSD
(ParticleProperty
): This particle property will contain the per-particle RMSD values computed by the PTM method. The modifier will output this property only if theoutput_rmsd
flag is set.Interatomic Distance
(ParticleProperty
): This particle property will contain the local interatomic distances computed by the PTM method. The modifier will output this property only if theoutput_interatomic_distance
flag is set.Orientation
(ParticleProperty
): This particle property will contain the local lattice orientations computed by the PTM method encoded as quaternions. The modifier will generate this property only if theoutput_orientation
flag is set.Elastic Deformation Gradient
(ParticleProperty
): This particle property will contain the local elastic deformation gradient tensors computed by the PTM method. The modifier will output this property only if theoutput_deformation_gradient
flag is set.Alloy Type
(ParticleProperty
): This output particle property contains the alloy type assigned to particles by the modifier. (only if theoutput_alloy_types
flag is set). The alloy types get stored as integer values in the"Alloy Type"
particle property. The following alloy type constants are defined:PolyhedralTemplateMatchingModifier.AlloyType.NONE
(0)PolyhedralTemplateMatchingModifier.AlloyType.PURE
(1)PolyhedralTemplateMatchingModifier.AlloyType.L10
(2)PolyhedralTemplateMatchingModifier.AlloyType.L12_CU
(3)PolyhedralTemplateMatchingModifier.AlloyType.L12_AU
(4)PolyhedralTemplateMatchingModifier.AlloyType.B2
(5)
Color
(ParticleProperty
): The modifier assigns a color to each particle based on its identified structure type. You can change the color representing a structural type as follows:modifier = PolyhedralTemplateMatchingModifier() # Give all FCC atoms a blue color: modifier.structures[PolyhedralTemplateMatchingModifier.Type.FCC].color = (0.0, 0.0, 1.0)
-
only_selected
¶ Lets the modifier perform the analysis only on the basis of currently selected particles. Unselected particles will be treated as if they did not exist.
Default: False
-
output_alloy_types
¶ Boolean flag that controls whether the modifier identifies localalloy types and outputs them to the pipeline.
Default: False
-
output_deformation_gradient
¶ Boolean flag that controls whether the modifier outputs the computed per-particle elastic deformation gradients to the pipeline.
Default: False
-
output_interatomic_distance
¶ Boolean flag that controls whether the modifier outputs the computed per-particle interatomic distance to the pipeline.
Default: False
-
output_orientation
¶ Boolean flag that controls whether the modifier outputs the computed per-particle lattice orientation to the pipeline.
Default: False
-
output_rmsd
¶ Boolean flag that controls whether the modifier outputs the computed per-particle RMSD values to the pipeline.
Default: False
-
rmsd_cutoff
¶ The maximum allowed root mean square deviation for positive structure matches. If the cutoff is non-zero, template matches that yield a RMSD value above the cutoff are classified as “Other”. This can be used to filter out spurious template matches (false positives).
If this parameter is zero, no cutoff is applied.
Default: 0.0
-
structures
¶ A list of
ParticleType
instances managed by this modifier, one for each structural type. You can adjust the color of structural types as shown in the code example above.
-
class
ovito.modifiers.
PythonScriptModifier
¶ Base class: ovito.modifiers.Modifier
A modifier that executes a Python script function which computes the output of the modifier.
This class makes it possible to implement new modifier types in Python which can participate in OVITO’s data pipeline system and which may be used like OVITO’s standard built-in modifiers. You can learn more about the usage of this class in the Writing new modifiers section.
Example:
from ovito.io import import_file from ovito.modifiers import PythonScriptModifier from ovito.data import ParticleProperty # Load input data and create an ObjectNode with a modification pipeline. node = import_file("simulation.dump") # Define our custom modifier function, which assigns a uniform color # to all particles, just like the built-in Assign Color modifier. def assign_color(frame, input, output): color_property = output.create_particle_property(ParticleProperty.Type.Color) color_property.marray[:] = (0.0, 0.5, 1.0) # Insert custom modifier into the data pipeline. modifier = PythonScriptModifier(function = assign_color) node.modifiers.append(modifier)
-
function
¶ The Python function to be called every time the modification pipeline is evaluated by the system.
The function must have a signature as shown in the example above. The frame parameter contains the current animation frame number at which the data pipeline is being evaluated. The
DataCollection
input holds the input data objects of the modifier, which were produced by the upstream part of the modification pipeline. output is theDataCollection
where the modifier function should store the modified or newly generated data objects. This data objects in this collection flow down the modification pipeline and are eventually rendered in the viewports.By default the output data collection contains the same data objects as the input data collection. Thus, without further action, all data gets passed through the modifier unmodified.
Default: None
-
script
¶ The source code of the user-defined Python script, which is executed by the modifier and which defines the
modify()
function. Note that this property returns the source code entered by the user through the graphical user interface, not the callable Python function.If you want to set the modification script function from an already running Python script, you should set the
function
property instead as demonstrated in the example above.
-
-
class
ovito.modifiers.
SelectExpressionModifier
¶ Base class: ovito.modifiers.Modifier
This modifier selects particles based on a user-defined Boolean expression. Those particles will be selected for which the expression yields a non-zero value.
Modifier outputs:
Selection
(ParticleProperty
): This particle property is set to 1 for selected particles and 0 for others.SelectExpression.num_selected
(attribute
): The number of particles selected by the modifier.
Example:
# Select all atoms with potential energy above -3.6 eV: node.modifiers.append(SelectExpressionModifier(expression = 'PotentialEnergy > -3.6')) node.compute() # Demonstrating two ways to get the number of selected atoms: print(node.output.attributes['SelectExpression.num_selected']) print(numpy.count_nonzero(node.output.particle_properties['Selection']))
-
expression
¶ A string containing the Boolean expression to be evaluated for every particle. The expression syntax is documented in OVITO’s user manual.
-
class
ovito.modifiers.
SelectParticleTypeModifier
¶ Base class: ovito.modifiers.Modifier
Selects all particles of a certain type (or multiple types).
Note that OVITO knows several classes of particle types, e.g. chemical types and structural types. Each of which are encoded as integer values by a different particle property. The
property
field of this modifier selects the class of types considered by the modifier, and thetypes
field determines which of the defined types get selected.Example:
modifier = SelectParticleTypeModifier(property = "Structure Type") modifier.types = { CommonNeighborAnalysisModifier.Type.FCC, CommonNeighborAnalysisModifier.Type.HCP } node.modifiers.append(modifier) node.compute() print("Number of FCC/HCP atoms: %i" % node.output.attributes['SelectParticleType.num_selected'])
Modifier outputs:
Selection
(ParticleProperty
): This particle property is set to 1 for selected particles and 0 for others.SelectParticleType.num_selected
(attribute
): The number of particles selected by the modifier.
-
property
¶ The name of the particle property storing the input particle types. This can be a standard particle property such as
"Particle Type"
or"Structure Type"
, or a custom integer particle property.Default: "Particle Type"
-
types
¶ A Python
set
of integers, which specifies the particle types to select.Default: set([])
-
class
ovito.modifiers.
ShowPeriodicImagesModifier
¶ Base class: ovito.modifiers.Modifier
This modifier replicates all particles to display periodic images of the system.
-
adjust_box
¶ A boolean flag controlling the modification of the simulation cell geometry. If
True
, the simulation cell is extended to fit the multiplied system. IfFalse
, the original simulation cell (containing only the primary image of the system) is kept.Default: False
-
num_x
¶ A positive integer specifying the number of copies to generate in the x direction (including the existing primary image).
Default: 3
-
num_y
¶ A positive integer specifying the number of copies to generate in the y direction (including the existing primary image).
Default: 3
-
num_z
¶ A positive integer specifying the number of copies to generate in the z direction (including the existing primary image).
Default: 3
-
replicate_x
¶ Enables replication of particles along x.
Default: False
-
replicate_y
¶ Enables replication of particles along y.
Default: False
-
replicate_z
¶ Enables replication of particles along z.
Default: False
-
unique_ids
¶ If
True
, the modifier automatically generates a new unique ID for each copy of a particle. This option has no effect if the input system does not contain particle IDs.Default: True
-
-
class
ovito.modifiers.
SliceModifier
¶ Base class: ovito.modifiers.Modifier
Deletes or selects particles in a region bounded by one or two parallel infinite planes in three-dimensional space.
-
distance
¶ The distance of the slicing plane from the origin (along its normal vector).
Default: 0.0
-
inverse
¶ Reverses the sense of the slicing plane.
Default: False
-
normal
¶ The normal vector of the slicing plane. Does not have to be a unit vector.
Default: (1,0,0)
-
only_selected
¶ If
True
, the modifier acts only on selected particles; ifFalse
, the modifier acts on all particles.Default: False
-
select
¶ If
True
, the modifier selects particles instead of deleting them.Default: False
-
slice_width
¶ The width of the slab to cut. If zero, the modifier cuts all particles on one side of the slicing plane.
Default: 0.0
-
-
class
ovito.modifiers.
VoronoiAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
Computes the atomic volumes and coordination numbers using a Voronoi tessellation of the particle system.
Modifier outputs:
Atomic Volume
(ParticleProperty
): Stores the computed Voronoi cell volume of each particle.Coordination
(ParticleProperty
): Stores the number of faces of each particle’s Voronoi cell.Voronoi Index
(ParticleProperty
): Stores the Voronoi indices computed from each particle’s Voronoi cell. This property is only generated whencompute_indices
is set.Bonds
(Bonds
): The list of nearest neighbor bonds, one for each Voronoi face. Bonds are only generated whengenerate_bonds
is set.Voronoi.max_face_order
(attribute
): This output attribute reports the maximum number of edges of any face in the computed Voronoi tessellation (ignoring edges and faces that are below the area and length thresholds). Note that, if calculation of Voronoi indices is enabled (compute_indices
== true), andedge_count
<max_face_order
, then the computed Voronoi index vectors will be truncated because there exists at least one Voronoi face having more edges than the maximum Voronoi vector length specified byedge_count
. In such a case you should consider increasingedge_count
(to at leastmax_face_order
) to not lose information because of truncated index vectors.
-
compute_indices
¶ If
True
, the modifier calculates the Voronoi indices of particles. The modifier stores the computed indices in a vector particle property 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
-
edge_count
¶ Integer parameter controlling the order up to which Voronoi indices are computed by the modifier. Any Voronoi face with more edges than this maximum value will not be counted! Computed Voronoi index vectors are truncated at the index specified by
edge_count
.See the
Voronoi.max_face_order
output attributes described above on how to avoid truncated Voronoi index vectors.This parameter is ignored if
compute_indices
is false.Minimum: 3 Default: 6
-
edge_threshold
¶ Specifies the minimum length an edge must have to be considered in the Voronoi index calculation. Edges that are shorter than this threshold will be ignored when counting the number of edges of a Voronoi face.
Default: 0.0
-
face_threshold
¶ Specifies a minimum area for faces of a Voronoi cell. The modifier will ignore any Voronoi cell faces with an area smaller than this threshold when computing the coordination number and the Voronoi index of particles.
Default: 0.0
-
generate_bonds
¶ Controls whether the modifier outputs the nearest neighbor bonds. The modifier will generate a bond for every pair of adjacent atoms that share a face of the Voronoi tessellation. No bond will be created if the face’s area is below the
face_threshold
or if the face has less than three edges that are longer than theedge_threshold
.Default: False
-
only_selected
¶ Lets the modifier perform the analysis only for selected particles. Particles that are currently not selected will be treated as if they did not exist.
Default: False
-
use_radii
¶ If
True
, the modifier computes the poly-disperse Voronoi tessellation, which takes into account the radii of particles. Otherwise a mono-disperse Voronoi tessellation is computed, which is independent of the particle sizes.Default: False
-
class
ovito.modifiers.
WignerSeitzAnalysisModifier
¶ Base class: ovito.modifiers.Modifier
Performs the Wigner-Seitz cell analysis to identify point defects in crystals. The modifier requires loading a reference configuration from an external file:
from ovito.modifiers import * mod = WignerSeitzAnalysisModifier() mod.reference.load("frame0000.dump") node.modifiers.append(mod) node.compute() print("Number of vacant sites: %i" % node.output.attributes['WignerSeitz.vacancy_count'])
Modifier outputs:
Occupancy
(ParticleProperty
): The computed site occupation numbers, one for each particle in the reference configuration.WignerSeitz.vacancy_count
(attribute
): The total number of vacant sites (havingOccupancy
== 0).WignerSeitz.interstitial_count
(attribute
): The total number of of interstitial atoms. This is equal to the sum of occupancy numbers of all non-empty sites minus the number of non-empty sites.
-
eliminate_cell_deformation
¶ Boolean flag that controls the elimination of the affine cell deformation prior to performing the analysis.
Default: False
-
frame_offset
¶ The relative frame offset when using a sliding reference configuration (
use_frame_offset==True
).Default: -1
-
per_type_occupancies
¶ A parameter flag that controls whether occupancy numbers are determined per particle type.
If false, only the total occupancy number is computed for each reference site, which counts the number of particles that occupy the site irrespective of their types. If true, then the
Occupancy
property computed by the modifier becomes a vector property with one component per particle type. Each property component counts the number of particles of the corresponding type that occupy a site. For example, the property componentOccupancy.1
contains the number of particles of type 1 that occupy a site.Default: False
-
reference
¶ A
FileSource
that provides the reference positions of particles. You can call itsload()
function to load a reference simulation file as shown in the code example above.
-
reference_frame
¶ The frame number to use as reference configuration if the reference data comprises multiple simulation frames. Only used if
use_frame_offset==False
.Default: 0
-
use_frame_offset
¶ Determines whether a sliding reference configuration is taken at a constant time offset (specified by
frame_offset
) relative to the current frame. IfFalse
, a constant reference configuration is used (set by thereference_frame
parameter) irrespective of the current frame.Default: False
-
class
ovito.modifiers.
WrapPeriodicImagesModifier
¶ Base class: ovito.modifiers.Modifier
This modifier maps particles located outside the simulation cell back into the box by “wrapping” their coordinates around at the periodic boundaries of the simulation cell. This modifier has no parameters.