ovito.modifiers — OVITO Python Reference 3.16.0 documentation

# `ovito.modifiers`

This module contains all modifiers available in OVITO. See the introduction to learn more about modifiers and their role in the data pipeline system. The following table lists the Python names of all modifier types that can be instantiated. 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
--- | ---
`AcklandJonesModifier` | Ackland-Jones analysis
`AffineTransformationModifier` | Affine transformation
`AmbientOcclusionModifier` | Ambient occlusion
`AssignColorModifier` | Assign color
`AtomicStrainModifier` | Atomic strain
`BaderChargeIntegrationModifier` | Bader charge integration
`BondAngleDistributionModifier` | Bond angle distribution
`BondLengthDistributionModifier` | Bond length distribution
`BondOrderModifier` | Bond order
`CalculateDisplacementsModifier` | Displacement vectors
`CentroSymmetryModifier` | Centrosymmetry parameter
`ChillPlusModifier` | Chill+
`ClearSelectionModifier` | Clear selection
`ClusterAnalysisModifier` | Cluster analysis
`ColorByTypeModifier` | Color by type
`ColorCodingModifier` | Color coding
`CombineDatasetsModifier` | Combine datasets
`CommonNeighborAnalysisModifier` | Common neighbor analysis
`ComputePropertyModifier` | Compute property
`ConstructSurfaceModifier` | Construct surface mesh
`CoordinationPolyhedraModifier` | Coordination polyhedra
`CreateBondsModifier` | Create bonds
`CreateIsosurfaceModifier` | Create isosurface
`DeleteSelectedModifier` | Delete selected
`DifferenceBetweenFramesModifier` | Difference between frames
`DislocationAnalysisModifier` | Dislocation analysis (DXA)
`EditSimulationCellModifier` | Edit simulation cell
`EditTypesModifier` | Edit types
`ElasticStrainModifier` | Elastic strain calculation
`ExpandSelectionModifier` | Expand selection
`ExpressionSelectionModifier` | Expression selection
`FindRingsModifier` | Find rings
`FindOverlappingParticlesModifier` | Find overlapping particles
`FreezePropertyModifier` | Freeze property
`GenerateTrajectoryLinesModifier` | Generate trajectory lines
`GrainSegmentationModifier` | Grain segmentation
`HistogramModifier` | Histogram
`IdentifyFCCPlanarFaultsModifier` | Identify fcc planar faults
`IdentifyDiamondModifier` | Identify diamond structure
`InvertSelectionModifier` | Invert selection
`LoadTrajectoryModifier` | Load trajectory
`PolyhedralTemplateMatchingModifier` | Polyhedral template matching
`PythonModifier` | Python script
`RadialDistributionFunctionModifier` | Radial distribution function (RDF)
`ReducePropertyModifier` | Reduce property
`RemovePropertyModifier` | Remove property
`RenderLAMMPSRegionsModifier` | Render LAMMPS regions
`ReplicateModifier` | Replicate
`SelectTypeModifier` | Select type
`SliceModifier` | Slice
`SmoothTrajectoryModifier` | Smooth trajectory
`SpatialBinningModifier` | Spatial binning
`SpatialCorrelationFunctionModifier` | Spatial correlation function
`StructureFactorModifier` | Structure factor
`TextLabelsModifier` | Add text labels
`TimeAveragingModifier` | Time averaging
`TimeSeriesModifier` | Time series
`UnwrapTrajectoriesModifier` | Unwrap trajectories
`VoronoiAnalysisModifier` | Voronoi analysis
`VoroTopModifier` | VoroTop analysis
`WignerSeitzAnalysisModifier` | Wigner-Seitz defect analysis
`WrapPeriodicImagesModifier` | 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.AcklandJonesModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  This modifier analyzes the local neighborhood of each particle to identify simple crystalline structures. The structure identification is performed using the bond-angle classification method proposed by Ackland and Jones. See the corresponding user manual page for more information on this modifier.

  Note that this class inherits several important parameter fields from its `StructureIdentificationModifier` base class.

  Modifier inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is `True`.

  Modifier outputs:

  Particle properties |
  --- | ---
  `Structure Type` | The structure type computed by the algorithm for each particle, encoded as an integer value:
  Numeric id | Python constant
  --- | ---
  0 | `AcklandJonesModifier.Type.OTHER`
  1 | `AcklandJonesModifier.Type.FCC`
  2 | `AcklandJonesModifier.Type.HCP`
  3 | `AcklandJonesModifier.Type.BCC`
  4 | `AcklandJonesModifier.Type.ICO`
  `Color` | Particle coloring to indicate the identified structure type for each particle; only if `color_by_type` is `True`. See the `structures` array on how to customize the colors.

  Global attributes |
  --- | ---
  `AcklandJones.counts.OTHER` | Number of particles not matching any of the recognized 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.

  Data tables |
  --- | ---
  `structures` | A bar chart with the particle counts for each structure type identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.

class ovito.modifiers.AffineTransformationModifier

  Base: `ovito.pipeline.Modifier`

  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 specifier | Description
  --- | ---
  `particles` | Transforms the `Position` particle property.
  `vector_properties` | Transforms all vectorial properties having 3 components and an attached `VectorVis` element, e.g. the particle properties `Velocity`, `Force`, and `Displacement`.
  `cell` | Transforms the `SimulationCell`.
  `lines` | Transforms the vertices of all `Lines` objects.
  `surfaces` | Transforms the vertices of all `SurfaceMesh` objects.
  `dislocations` | Transforms all dislocation lines in a `DislocationNetwork`.
  `vectors` | Transforms the base points and directions of all `Vectors` objects.
  `voxels` | Transforms the spatial `domain` of all `VoxelGrid` objects.
  `triangle_meshes` | Transforms the vertices of all `TriangleMesh` objects.

  The modifier will act on all of these by default. You can restrict the transform to a subset of data objects by setting the `operate_on` field.

  Examples:

  The following code applies a simple shear transformation to all particle coordinates. The shear transformation is specified as a 3x3 matrix with ones on the matrix diagonal and an off-diagonal element that is non-zero. No translation is applied to the particles. Thus all elements in the fourth column of the extended 3x4 affine transformation matrix are set to zero:

      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]])

  Note that the modifier itself only supports static transformations, which remain constant over the entire trajectory. However, it is possible to employ the `AffineTransformationModifier` in a user-defined modifier function, which calculates the transformation matrix dynamically at each animation frame:

      import numpy as np

      def rotate(frame, data):
          theta = np.deg2rad(frame * 5.0)  # time-dependent angle of rotation
          tm = [[np.cos(theta), -np.sin(theta), 0, 0],
                [np.sin(theta),  np.cos(theta), 0, 0],
                [            0,              0, 1, 0]]
          # Execute AffineTransformationModifier as a sub-operation:
          data.apply(AffineTransformationModifier(transformation = tm))

      pipeline.modifiers.append(rotate)

  property only_selected: bool

    Controls whether the modifier should transform only the subset of currently selected elements (e.g. selected particles). For data object types that do not support selections, e.g. the simulation cell, this option has no effect.

    Default:

      `False`

  property operate_on: MutableSet[str]

    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', 'lines', 'triangle_meshes', 'vectors', 'voxels'}`

  property reduced_coords: bool

    Controls whether the translation vector (fourth column of the `transformation` matrix) is specified in reduced cell coordinates or in absolute Cartesian coordinates.

    If set to `False`, the modifier applies the transformation \(\mathbf{x}' = \mathbf{M} \cdot \mathbf{x} + \mathbf{t}\) to Cartesian input points \(\mathbf{x}\). Here, \(\mathbf{M}\) refers to the 3x3 linear part of the affine `transformation` matrix and \(\mathbf{t}\) to the translational part (fourth matrix column).

    If set to `True`, the modifier applies the transformation \(\mathbf{x}' = \mathbf{M} \cdot (\mathbf{x} + \mathbf{H} \cdot \mathbf{t})\). Here, \(\mathbf{H}\) refers to the 3x3 cell matrix formed by the three edge vectors of the simulation cell.

    Note that this option only applies if `relative_mode` is active.

    Default:

      `False`

  property relative_mode: bool

    Selects the operation mode of the modifier.

    If set to `True`, the modifier transforms data elements by applying the specified `transformation` matrix.

    If set to `False`, the modifier determines the effective transformation dynamically based on the current shape of the `SimulationCell` and the specified `target_cell` matrix. The old cell will be mapped to the new shape using an appropriate affine transformation.

    Default:

      `True`

  property target_cell

    This 3x4 matrix specifies the target cell shape. It is only used if `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.

    Note that this matrix describes a relative transformation and is used only if `relative_mode` == `True`. See the `reduced_coords` field for a definition of the precise coordinate transformation that is specified by this matrix.

    Default:

      `[[1,0,0,0], [0,1,0,0], [0,0,1,0]]`

class ovito.modifiers.AmbientOcclusionModifier

  Base: `ovito.pipeline.Modifier`

  Performs a quick lighting calculation to modulate the brightness of particles according to the degree of occlusion by other particles. See the corresponding user manual page for more information.

  This modifier should always be inserted at the end of a data pipeline, after particle filtering and coloring is done. It can help to improve the visual appearance of complex particle structures which are rendered with the default `StandardRenderer`. It is not needed when using the `TachyonRenderer` or `OSPRayRenderer`, which both perform the ambient occlusion calculation on the fly as part of the rendering process.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Color` | The original per-particle colors.

  Outputs:

  Particle properties |
  --- | ---
  `Color` | The new per-particle colors, which have been modulated by the occlusion factor computed by the modifier for each particle.

  property buffer_resolution: int

    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: float

    Controls the strength of the shading effect.

    Valid range:

      [0.0, 1.0]

    Default:

      `0.7`

  property sample_count: int

    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: `ovito.pipeline.Modifier`

  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.
  `lines` | Sets the `Color` property of selected line segments.
  `surface_vertices` | Sets the `Color` property of selected vertices of a `SurfaceMesh` structure.
  `surface_faces` | Sets the `Color` property of selected faces of a `SurfaceMesh` structure.
  `surface_regions` | Sets the `Color` property of selected spatial regions of a `SurfaceMesh` structure.

  By default the modifier will act on particles. You can change this by setting the `operate_on` field. The modifier uses the input `Property` named `Selection` to determine which subset of data elements should be assigned the specified `color`. Data elements whose `Selection` property is zero, keep their current color. In case the `Selection` property does not exist at all, the modifier assigns the color to every data element.

  OVITO provides various modifiers for creating selections: `SelectTypeModifier`, `ExpressionSelectionModifier`, `SliceModifier`, `InvertSelectionModifier`.

  Examples

  Select some particles with the `SelectTypeModifier` and give them a new color:

  >     pipeline.modifiers.append(SelectTypeModifier(types={1,3}))
  >     pipeline.modifiers.append(AssignColorModifier(color=(1.0, 0.3, 0.3)))

  Use the `CalculateDisplacementsModifier` to calculate the atomic displacement vectors and visualize them as arrows in rendered images. Particularly large displacement arrows can be highlighted using the `AssignColorModifier`:

  >     # Calculate and visualize atomic displacement vectors:
  >     modifier = CalculateDisplacementsModifier()
  >     modifier.vis.enabled = True
  >     pipeline.modifiers.append(modifier)

  >     # Select particles with large displacement magnitudes:
  >     pipeline.modifiers.append(ExpressionSelectionModifier(expression='DisplacementMagnitude > 1.2'))
  >     # Highlight large displacement vectors using a special color:
  >     pipeline.modifiers.append(AssignColorModifier(operate_on='vectors', color=(0.0, 0.9, 1.0)))

  property color: tuple[float, float, float]

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

    Default:

      `(0.3, 0.3, 1.0)`

  property operate_on: str

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

    Default:

      `'particles'`

class ovito.modifiers.AtomicStrainModifier

  Base: `ovito.pipeline.ReferenceConfigurationModifier`

  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:

  Particle properties |
  --- | ---
  `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 to `True`.
  `Deformation Gradient` | The nine components of the atomic deformation gradient tensor. Only if `output_deformation_gradients` was set to `True`.
  `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 to `True`.
  `Rotation` | The atomic microrotation obtained from the polar decomposition F=RU as a 4-component quaternion. Only if `output_rotations` was set to `True`.
  `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 to `True`.
  `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 if `select_invalid_particles` was set to `True`. The selected particles without valid deformation values can subsequently be removed using a `DeleteSelectedModifier`.

  Global attributes |
  --- | ---
  `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: float

    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: bool

    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: bool

    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: bool

    Controls the calculation of the per-particle rotations.

    Default:

      `False`

  property output_strain_tensors: bool

    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: bool

    Controls the calculation of the per-particle stretch tensors.

    Default:

      `False`

  property select_invalid_particles: bool

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

    Default:

      `True`

class ovito.modifiers.BaderChargeIntegrationModifier

  Base: `ovito.pipeline.Modifier`

  Performs Bader charge integration on a voxel grid, partitioning space into Bader volumes (basins of attraction) and integrating a scalar field quantity over each volume. See the corresponding user manual page for more information on this modifier. The implementation uses the weight method by Yu and Trinkle. Please cite their work when you use this modifier.

  The modifier requires a `VoxelGrid` as input from the upstream pipeline. The grid is typically loaded from a DFT output file (e.g., a VASP CHGCAR file). A scalar property on the grid (the `density`) defines the gradient field whose local maxima determine the Bader regions. A second scalar property (the `integrand`) is integrated over each Bader volume; by default, this is the same as the density property.

  If the data from the upstream pipeline also contains `Particles`, the modifier maps each Bader region to the nearest particle and outputs the integrated quantities as new per-particle properties. Multiple Bader regions can map to the same atom; their integrated values are summed to produce the per-particle output properties.

  Added in version 3.16.0.

  Inputs:

  `VoxelGrid` properties | Description
  --- | ---
  `density` | A scalar floating-point property on the voxel grid whose gradient field defines the Bader volume partitioning.
  `integrand` | A scalar (or multi-component) floating-point property on the voxel grid to be integrated over each Bader volume. May be the same as the `density` property. In that case the modifier will only compute results for the `density`.

  Particle properties (optional) | Description
  --- | ---
  `Position` | The coordinates of the input particles, used to map Bader regions to particles.

  Outputs:

  Particle properties (optional) | Description
  --- | ---
  `Integrated Density` | The total integrated density over all Bader volumes (regions) mapped to each particle.
  `Integrated Volume` | The total Bader volume associated with each particle.
  `Integrated <Integrand>` | The total integrated value of the `integrand` property for each particle.

  `VoxelGrid` properties |
  --- | ---
  `Region` | Integer index identifying the Bader region each voxel is assigned to (based on maximum weight).
  `Maximum Region Weight` | The fractional weight of the dominant Bader region at each voxel (between 0 and 1).
  `Mapped Particle Index` | The 0-based index of the atom to which each voxel’s Bader region is mapped (Only when particles are present).

  `DataTable` | Description
  --- | ---
  `Integrated Density` | The integral of the density property over the Bader volume.
  `Integrated Volume` | The integrated volume of the Bader region.
  `Position` | The Cartesian coordinates of the density maximum (local grid maximum) that defines this Bader region.
  `Integrated <Integrand>` | The integral of the integrand property over the Bader volume (only present when the integrand property differs from the density property). If the integrand is a multi-component property, all components are integrated separately and stored as vector components.
  `Mapped Particle Distance` | The spatial distance from the density maximum of this Bader region to its nearest atom (only present when particles exist in the input).
  `Mapped Particle Index` | The 0-based index of the nearest atom to which this Bader region is mapped. (only present when particles exist in the input).

  Example:

  The following Python script demonstrates how to load a VASP CHGCAR file containing a voxel grid with charge density data and perform Bader charge integration:

      from ovito.io import *
      from ovito.modifiers import *

      # Load the CHGCAR file containing the charge density
      pipeline = import_file("input/CHGCAR.nospin.gz")

      # Show what has been loaded from the CHGCAR file:
      print("Available voxel grids and their properties:")
      data = pipeline.compute()
      for id, grid in data.grids.items():
          print(f"  - {id}:")
          for prop_name in grid:
              print(f"      - {prop_name}")

      # Set up Bader charge integration:
      pipeline.modifiers.append(
          BaderChargeIntegrationModifier(
              operate_on="charge-density",
              density="Charge Density",
              integrand="Charge Density",
          )
      )

      # Evaluate full data pipeline:
      data = pipeline.compute()
      bader_regions = data.tables["bader-charge-integration"]
      print("Identified Bader regions:")
      for i in range(bader_regions.count):
          position = bader_regions["Position"][i]
          integrated_density = bader_regions["Integrated Density"][i]
          print(f"  - Region {i}: Position={position}, Integrated Density={integrated_density}")

      # Print the atomic charges computed by the modifier:
      print("Computed atomic charges:")
      for i in range(data.particles.count):
          charge = data.particles["Integrated Density"][i]
          print(f"  - Atom {i}: Charge={charge}")

  property density: str

    The name of the `Property` in the input `VoxelGrid` selected by `operate_on` that will be used as basis for the Bader charge integration. Note that this must be a scalar property. If the property is a vector property, you need to explicitly specify which vector component to use, e.g. `'Field.Z'`.

  property integrand: str

    The name of the `Property` in the selected input `VoxelGrid` that will be integrated based on the regions determined from the `density`. If set to `None`, the density field itself is used as the integrand.

  property operate_on: str

    Specifies the `VoxelGrid` this modifier should operate on. Set this to unique `identifier` of the grid to process.

    Note: You can use the Python statement `print(pipeline.compute().grids)` to find out which voxel `grids` are present in your data pipeline.

    Default:

      `''`

class ovito.modifiers.BondAngleDistributionModifier

  Base: `ovito.pipeline.Modifier`

  Computes the bond angle distribution for the particle system with bonds. See the corresponding user manual page for more information on this modifier.

  The input for this modifier must contain a `Bonds` data object with the bond topology information, which may either be loaded from the simulation file or by first inserting the `CreateBondsModifier` into the pipeline.

  The modifier outputs the computed bond angle histogram as `DataTable` objects, which may be exported to an output text file using the `export_file()` function or retrieved from the pipeline’s output data collection, see the `DataCollection.tables` dictionary and the code examples following below.

  This modifier partially replaces the functionality of the “Bond Analysis” modifier in OVITO 3.14 and earlier. See `BondLengthDistributionModifier` for bond length analysis.

  Added in version 3.15.0.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Particle Type` | Required if `partition` is set to `ByParticleType`.
  `Selection` | Required if `partition` is set to `ByParticleSelection`.

  Bond properties |
  --- | ---
  `Topology` | The input bonds list.
  `Bond Type` | Required if `partition` is set to `ByBondType`.
  `Selection` | Required if `partition` is set to `ByBondSelection`.

  Outputs:

  `DataTable` |
  --- | ---
  `bond-angle-distr` | The bond angle distribution histogram computed by the modifier.

  Examples:

  The following Python script demonstrates how to load a particle system (without bond topology) from a file, create the bond topology using OVITO’s `CreateBondsModifier`, and then compute the bond angle distribution. Finally, the histogram is written to an output text file using the `export_file()` function.

      from ovito.io import import_file, export_file
      from ovito.modifiers import BondAngleDistributionModifier, CreateBondsModifier

      # Set up data pipeline:
      pipeline = import_file("input/simulation.dump")
      pipeline.modifiers.append(CreateBondsModifier(cutoff=3.2))
      pipeline.modifiers.append(BondAngleDistributionModifier(bins=180))

      # Export bond angle distribution to an output text file.
      export_file(pipeline, "output/bond_angles.txt", "txt/table", key="bond-angle-distr")

      # Convert bond angle histogram to a NumPy array and print it to the terminal.
      data = pipeline.compute()
      print(data.tables["bond-angle-distr"].xy())

  The script above computes the instantaneous distribution for the initial frame in the simulation file only. To compute an average bond angle distribution for the entire MD trajectory, you can make use of the `TimeAveragingModifier`:

      from ovito.io import *
      from ovito.modifiers import *

      # Load a LAMMPS topology data file containing bond information:
      pipeline = import_file('input/input.data', atom_style='bond')

      # Load trajectory data from separate LAMMPS dump file.
      traj = LoadTrajectoryModifier()
      traj.source.load('input/trajectory.dump')
      pipeline.modifiers.append(traj)

      # Calculate instantaneous bond angle distribution.
      pipeline.modifiers.append(BondAngleDistributionModifier())

      # Perform time averaging of the DataTable 'bond-angle-distr'.
      pipeline.modifiers.append(TimeAveragingModifier(operate_on='table:bond-angle-distr'))

      # Compute and export the time-averaged histogram to a text file.
      export_file(pipeline, "output/avg_bond_angles.txt", 'txt/table', key='bond-angle-distr[average]')

  property bins: int

    The number of bins in the length and angle histograms generated by the modifier.

    Default:

      `180`

  property cosine_mode: bool

    If set to `True`, the modifier will calculate the distribution of the cosines of the bond angles instead of the angles themselves, and the bond angle histogram output by the modifier will then extend over the value interval [-1, +1] instead of [0, 180] degrees.

    Default:

      `False`

  property partition: BondAngleDistributionModifier.Partition

    This mode parameter instructs the modifier to split the bond length and bond angle distributions into partial distributions, one for each particle or bond type combination. Available partitioning modes are:

    > - `BondAngleDistributionModifier.Partition.Off`

    > - `BondAngleDistributionModifier.Partition.ByBondType`

    > - `BondAngleDistributionModifier.Partition.ByBondSelection`

    > - `BondAngleDistributionModifier.Partition.ByParticleType`

    > - `BondAngleDistributionModifier.Partition.ByParticleSelection`

    If partitioning is turned on, the `y` property array of the two `DataTable` histograms computed by the modifier will have multiple vector components, one for each partial distribution. The following code example shows how to access the partial histograms:

        from ovito.io import import_file
        from ovito.modifiers import BondAngleDistributionModifier

        # Load LAMMPS data file with bonds and compute bond angle distribution partitioned by bond type:
        pipeline = import_file("input/input.data", atom_style="bond")
        pipeline.modifiers.append(
            BondAngleDistributionModifier(
                partition=BondAngleDistributionModifier.Partition.ByBondType
            )
        )
        data = pipeline.compute()

        # Retrieve y-property array from output DataTable:
        histogram = data.tables["bond-angle-distr"].y

        # Print the individual columns of the vector-valued property array:
        for column, name in enumerate(histogram.component_names):
            print("Angle distribution for bond types:", name)
            print(histogram[:, column])

    Default:

      `BondAngleDistributionModifier.Partition.Off`

class ovito.modifiers.BondLengthDistributionModifier

  Base: `ovito.pipeline.Modifier`

  Computes the bond length distribution for the particle system with bonds. See the corresponding user manual page for more information on this modifier.

  The input for this modifier must contain a `Bonds` data object with the bond topology information, which may either be loaded from the simulation file or by first inserting the `CreateBondsModifier` into the pipeline.

  The modifier outputs the computed bond length histogram as `DataTable` object, which may be exported to an output text file using the `export_file()` function or retrieved from the pipeline’s output data collection, see the `DataCollection.tables` dictionary and the code examples following below.

  This modifier partially replaces the functionality of the “Bond Analysis” modifier in OVITO 3.14 and earlier. See `BondAngleDistributionModifier` for bond angle analysis.

  Added in version 3.15.0.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Particle Type` | Required if `partition` is set to `ByParticleType`.
  `Selection` | Required if `partition` is set to `ByParticleSelection`.

  Bond properties |
  --- | ---
  `Topology` | The input bonds list.
  `Bond Type` | Required if `partition` is set to `ByBondType`.
  `Selection` | Required if `partition` is set to `ByBondSelection`.

  Outputs:

  `DataTable` |
  --- | ---
  `bond-length-distr` | The bond length distribution histogram computed by the modifier.

  Examples:

  The following Python script demonstrates how to load a particle system (without bond topology) from a file, create the bond topology using OVITO’s `CreateBondsModifier`, and then compute the bond length distribution. Finally, the histogram is written to an output text file using the `export_file()` function.

      from ovito.io import import_file, export_file
      from ovito.modifiers import BondLengthDistributionModifier, CreateBondsModifier

      # Set up data pipeline:
      pipeline = import_file("input/simulation.dump")
      pipeline.modifiers.append(CreateBondsModifier(cutoff=3.2))
      pipeline.modifiers.append(BondLengthDistributionModifier(bins=100))

      # Export bond length distribution to an output text file.
      export_file(pipeline, "output/bond_length.txt", "txt/table", key="bond-length-distr")

      # Convert bond length histogram to a NumPy array and print it to the terminal.
      data = pipeline.compute()
      print(data.tables["bond-length-distr"].xy())

  The script above computes the instantaneous distribution for the initial frame in the simulation file only. To compute an average bond length distribution for the entire MD trajectory, you can make use of the `TimeAveragingModifier`:

      from ovito.io import *
      from ovito.modifiers import *

      # Load a LAMMPS topology data file containing bond information:
      pipeline = import_file('input/input.data', atom_style='bond')

      # Load trajectory data from separate LAMMPS dump file.
      traj = LoadTrajectoryModifier()
      traj.source.load('input/trajectory.dump')
      pipeline.modifiers.append(traj)

      # Calculate instantaneous bond length distribution.
      pipeline.modifiers.append(BondLengthDistributionModifier())

      # Perform time averaging of the DataTable 'bond-length-distr'.
      pipeline.modifiers.append(TimeAveragingModifier(operate_on='table:bond-length-distr'))

      # Compute and export the time-averaged histogram to a text file.
      export_file(pipeline, "output/avg_bond_lengths.txt", 'txt/table', key='bond-length-distr[average]')

  property bins: int

    The number of bins in the length and angle histograms generated by the modifier.

    Default:

      `100`

  property length_cutoff: float

    Maximum bond length at which the bond length distribution gets truncated. Together with the `bins` parameter, this value determines the bin size of the bond length histogram output by the modifier.

    Note that this parameter does not affect the computation of the bond angle distribution. All bonds are included in the angle distribution, even if their length exceeds the cutoff.

    Default:

      `4.0`

  property partition: BondLengthDistributionModifier.Partition

    This mode parameter instructs the modifier to split the bond length and bond angle distributions into partial distributions, one for each particle or bond type combination. Available partitioning modes are:

    > - `BondLengthDistributionModifier.Partition.Off`

    > - `BondLengthDistributionModifier.Partition.ByBondType`

    > - `BondLengthDistributionModifier.Partition.ByBondSelection`

    > - `BondLengthDistributionModifier.Partition.ByParticleType`

    > - `BondLengthDistributionModifier.Partition.ByParticleSelection`

    If partitioning is turned on, the `y` property array of the two `DataTable` histograms computed by the modifier will have multiple vector components, one for each partial distribution. The following code example shows how to access the partial histograms:

        from ovito.io import import_file
        from ovito.modifiers import BondLengthDistributionModifier

        # Load LAMMPS data file with bonds and compute bond length distribution partitioned by bond type:
        pipeline = import_file("input/input.data", atom_style="bond")
        pipeline.modifiers.append(
            BondLengthDistributionModifier(
                partition=BondLengthDistributionModifier.Partition.ByBondType
            )
        )
        data = pipeline.compute()

        # Retrieve y-property array from output DataTable:
        histogram = data.tables["bond-length-distr"].y

        # Print the individual columns of the vector-valued property array:
        for column, name in enumerate(histogram.component_names):
            print("Length distribution for bond types:", name)
            print(histogram[:, column])

    Default:

      `BondLengthDistributionModifier.Partition.Off`

class ovito.modifiers.BondOrderModifier

  Base: `ovito.pipeline.Modifier`

  Computes the bond order for the particle system with bonds. See the corresponding user manual page for more information on this modifier.

  The input for this modifier must contain a `Bonds` data object with the bond topology information, which may either be loaded from the simulation file or by first inserting the `CreateBondsModifier` into the pipeline. Note that this modifier is originally designed to work with bonds created by the `CreateBondsModifier` using the `Covalent Radii` mode.

  Added in version 3.15.0.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Particle Type` | Particle type information; Type names need to exactly match chemical element symbols.

  Bond properties |
  --- | ---
  `Topology` | The input bonds list.

  Outputs:

  Particle properties |
  --- | ---
  `Functional Group` | The functional group an atom belongs to.
  Numeric id | Functional group
  --- | ---
  0 | No known functional group
  1 | Amide
  2 | Aromatic
  3 | Carboxylate
  4 | Nitro
  5 | Amine

  Bond properties |
  --- | ---
  `Bond Order` | The computed bond order. Can be fractional if `redistribute_bond_orders` is set to `True`, otherwise it is an integer value.
  `Functional Group` | The functional group a bond belongs to.
  Numeric id | Functional group
  --- | ---
  0 | No known functional group
  1 | Amide
  2 | Aromatic
  3 | Carboxylate
  4 | Nitro
  5 | Amine

  property fragment_size_limit: int

    Larger molecules are split into smaller chunks or fragments for bond order optimization. This parameter controls the maximum size of these fragments. Larger values can lead to better results at the cost of increased computation time. For performance reasons, optimization always starts at a fragment size of 3. During optimization, the fragment size may increase up to `fragment_size_limit` or until the optimization converges.

    Default:

      `5`

  property redistribute_bond_orders: bool

    When set to `True`, the modifier will redistribute the initial integer bond orders within known functional groups into fractional bond orders. By default, the redistribution is set to `False`, which means that bonds in aromatic rings will be assigned an alternating bond order of either 1 or 2. By setting `redistribute_bond_orders` to `True`, the bond orders will become 1.5 for all bonds in aromatic rings.

    Default:

      `False`

class ovito.modifiers.CalculateDisplacementsModifier

  Base: `ovito.pipeline.ReferenceConfigurationModifier`

  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:

  Particle properties |
  --- | ---
  `Displacement` | The computed displacement vectors.
  `Displacement Magnitude` | The length of the computed displacement vectors.

  property vis: VectorVis

    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)

class ovito.modifiers.CentroSymmetryModifier

  Base: `ovito.pipeline.Modifier`

  Computes the centrosymmetry 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:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.

  Outputs:

  Particle properties |
  --- | ---
  `Centrosymmetry` | The non-negative CSP value computed for each particle. Values close to zero mean neighboring particles are in a perfect centrosymmetric arrangement.

  property mode: CentroSymmetryModifier.Mode

    Selects how pair-wise opposite neighbors should be picked during the CSP calculation. Valid modes are:

    > - `CentroSymmetryModifier.Mode.Conventional`

    > - `CentroSymmetryModifier.Mode.Matching`

    See the user manual for more information on these two modes.

    Default:

      `CentroSymmetryModifier.Mode.Conventional`

  property num_neighbors: int

    The number of nearest neighbors to take into account for the computation, e.g.

    > - 12 for FCC crystals

    > - 8 for BCC crystals

    Default:

      `12`

  property only_selected: bool

    Set this to `True` to perform the analysis only on the sub-set of currently selected particles. Particles that are not selected will be treated as if they did not exist. That means they won’t be considered in the centrosymmetry calculation of the surrounding particles and their own centrosymmetry value will be zero. Use a `SelectTypeModifier` in your pipeline, for example, to restrict the centrosymmetry analysis to a sub-lattice formed by one species of particles in a multi-component system.

    Default:

      `False`

class ovito.modifiers.ChillPlusModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  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.

  Note that this class inherits several important parameter fields from its `StructureIdentificationModifier` base class.

  Modifier inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is `True`.

  Modifier outputs:

  Particle properties |
  --- | ---
  `Structure Type` | The structure type computed by the algorithm for each particle, encoded as an integer value:
  Numeric id | 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` | Particle coloring to indicate the identified structure type for each particle; only if `color_by_type` is `True`. See the `structures` array on how to customize the colors.

  Global attributes |
  --- | ---
  `ChillPlus.counts.OTHER` | Number of particles not matching any of the known structure types.
  `ChillPlus.counts.HEXAGONAL_ICE` | Number of particles identified as hexagonal 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.

  Data tables |
  --- | ---
  `structures` | A bar chart with the particle counts for each structure type identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.

  property cutoff: float

    The cutoff distance for bonds between water molecules.

    Default:

      `3.5`

class ovito.modifiers.ClearSelectionModifier

  Base: `ovito.pipeline.Modifier`

  This modifier clears the current selection by removing the `Selection` property from a `PropertyContainer` 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: str

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

    Default:

      `'particles'`

class ovito.modifiers.ClusterAnalysisModifier

  Base: `ovito.pipeline.Modifier`

  This modifier groups particles into disconnected clusters based on the chosen connectivity criterion. See the corresponding user manual page for more information.

  Outputs:

  Particle properties |
  --- | ---
  `Cluster` | The 1-based numeric ID of the cluster each particle was assigned to by the modifier.

  Global attributes |
  --- | ---
  `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 to `True`.

  `DataTable` |
  --- | ---
  `clusters` | The list of clusters identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary. It consists of several data columns, each being a separate `Property` object: `Cluster Identifier`: The numeric ID of each identified cluster (1-based). `Cluster Size`: The number of particles in each identified cluster. `Center of Mass`: The XYZ coordinates of the center of mass of each cluster (only if `compute_com` is set). `Radius of Gyration`: The radius of gyration of each cluster (only if `compute_gyration` is set) in simulation units of length. `Gyration Tensor`: The gyration tensor of each cluster (only if `compute_gyration` is set) in simulation units of length squared. The tensors are stored as vectors with six components [XX, YY, ZZ, XY, XZ, YZ].

  Example:

  The following example code demonstrates how to export the data table generated by the modifier to a text file and how to access the information from Python.

      from ovito.io import import_file, export_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,
          compute_com=True))

      # Export results of the clustering algorithm to a text file:
      export_file(pipeline, 'output/clusters.txt', 'txt/table', key='clusters')

      # Directly access information stored in the DataTable:
      data = pipeline.compute()
      cluster_table = data.tables['clusters']
      print("Centers of mass:")
      print(cluster_table['Center of Mass'][...])

  property cluster_coloring: bool

    Enables the coloring of particles based on their assignment to clusters. Each cluster is represented by a unique random color.

    Default:

      `False`

  property compute_com: bool

    Enables the computation of the center of mass of each cluster. The center coordinates will be output as an extra column named `Center of Mass` in the `clusters` data table.

    Default:

      `False`

  property compute_gyration: bool

    Enables the computation of the radius of gyration and the gyration tensor of each cluster. Both quantities will be output as auxiliary properties to the `clusters` data table, see above.

    Default:

      `False`

  property cutoff: float

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

    Default:

      `3.2`

  property neighbor_mode: ClusterAnalysisModifier.NeighborMode

    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 parameter `cutoff`.

    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 the `CreateBondsModifier` or the `VoronoiAnalysisModifier`.

    Default:

      `ClusterAnalysisModifier.NeighborMode.CutoffRange`

  property only_selected: bool

    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: bool

    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`

  property unwrap_particles: bool

    Enables the “unwrapping” of particle coordinates in order to make clusters contiguous that are cut by a periodic simulation cell boundary.

    Default:

      `False`

class ovito.modifiers.ColorByTypeModifier

  Base: `ovito.pipeline.Modifier`

  Assigns colors to data elements to visualize the discrete per-element values of a typed property, e.g. the residue type or structural type of particles. See also the corresponding user manual page for more information. The modifier can operate on different data elements:

  Data elements |
  --- | ---
  `particles` | Colors `Particles` according to a typed particle property.
  `bonds` | Colors `Bonds` according to a typed bond property.
  `voxels` | Colors `VoxelGrid` cells according to a typed property.

  By default the modifier will act on particles. You can change this by setting the `operate_on` field.

  The modifier’s `property` field names the input property according to which the data elements will be colored. It must be a so-called typed property, which means the `Property` object has a list of `ElementType` instances attached in its `types` field, defining the mapping of integer values in the property array to element type colors. Each `ElementType` instance associates one numeric `id` with a corresponding `color`.

  Output:

  The modifier sets the `Color` property of the data elements it operates on. When rendering a picture, this property determines the visual color of the individual objects.

  Examples:

      from ovito.io import import_file
      from ovito.modifiers import ColorByTypeModifier

      # Load a GROMACS file, which contains the 'Residue Type' particle property.
      pipeline = import_file("input/1AKI.gro")
      pipeline.add_to_scene()

      # Print a table of all residue types defined in the dataset:
      for residue_type in pipeline.compute().particles['Residue Type'].types:
          print(residue_type.id, residue_type.name, residue_type.color)

      # Apply the ColorByTypeModifier, giving particles a color based on
      # the value of their 'Residue Type' property:
      pipeline.modifiers.append(ColorByTypeModifier(
          operate_on='particles',
          property='Residue Type'))

  One way to change the colors of the element types is to prepend the `ColorByTypeModifier` in the pipeline with a user-defined modifier function configuring the `ElementType` instances that are attached to the typed `Property`:

      def setup_residue_colors(frame, data):
          residues = data.particles_['Residue Type_']
          residues.type_by_name_('LYS').color = (1.0, 0.0, 1.0)
          residues.type_by_name_('GLU').color = (0.0, 0.5, 1.0)
      pipeline.modifiers.insert(0, setup_residue_colors)

  Implementation:

  The `ColorByTypeModifier` is functionally equivalent to (but more efficient than) the following user-defined modifier function:

      def color_by_type(frame, data, property_name='Residue Type'):
          input_property = data.particles[property_name]
          output_colors = data.particles_.create_property('Color')
          for index, type_id in enumerate(input_property):
              element_type = input_property.type_by_id(type_id)
              output_colors[index] = element_type.color

  property clear_selection: bool

    Controls whether the current element selection is cleared to reveal the assigned colors in the interactive viewports of OVITO, which may otherwise be masked by the highlighting of selected elements. This option only has an effect if the `only_selected` option is also turned on. Otherwise the modifier never clears the current element selection.

    Default:

      `True`

  property only_selected: bool

    If `True`, only selected data elements will be assigned a color by the modifier and the colors of unselected elements will be preserved; if `False`, all data elements will be colored.

    Default:

      `False`

  property operate_on: str

    Controls the kind of data elements that are being colored by this modifier. Supported values are: `'particles'`, `'bonds'`, `'voxels'`.

    Default:

      `'particles'`

  property property: str

    The name of the typed property to use as input; must be an integer property with attached `ElementType` instances.

    For particles, typical input properties are `'Particle Type'`, `'Residue Type'` or `'Structure Type'`. When coloring bonds, the `'Bond Type'` property is an example for a typed property.

    Default:

      `'Particle Type'`

class ovito.modifiers.ColorCodingModifier

  Base: `ovito.pipeline.Modifier`

  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` | Assigns a local color to particles by setting their `Color` property.
  `vectors` | Colors the vector arrows associated with particles by setting their `Vector Color` property.
  `bonds` | Assigns a local color to bonds by setting their `Color` property.
  `voxels` | Colors the cells of a `VoxelGrid`.
  `surface_vertices` | Colors the vertices of a `SurfaceMesh` object.
  `surface_faces` | Colors the faces of a `SurfaceMesh` object.
  `surface_regions` | Colors the volumetric regions of a `SurfaceMesh` object.
  `lines` | Assigns colors to the vertices of a `Lines` object to visualize a local property.

  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, as in the example above, the `start_value` and `end_value` parameters are not explicitly specified, then the modifier will automatically adjust the mapping interval to fully cover the range of input property values (dynamically for each trajectory frame).

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

  property auto_adjust_range: bool

    Controls the automatic adjustment of the modifier’s mapping interval to always cover the full range of input values. If turned on (the default), the modifier adaptively adjusts the value-to-color mapping to the current min/max range of input values (at the current timestep). If turned off, the mapping is fixed and is determined by the `start_value` and `end_value` parameters of the modifier.

    Setting the `start_value` or `end_value` parameters to some value implicitly changes `auto_adjust_range` to `False`. Furthermore, note that the automatic range is always determined over the complete set of input elements irrespective of the `only_selected` option.

    Default:

      `True`

  property discretize_color_map: bool

    Enables the use of a discrete color map for color coding. When active, the color `gradient` is discretized into integer steps within the value interval given by `start_value` and `end_value`. This is useful for visualizing categorical data or properties with discrete integer values.

    Default:

      `False`

    Added in version 3.14.0.

  property end_value: float

    This parameter determines, together with `start_value`, the linear mapping of input property values to colors. It is only used if `auto_adjust_range` is turned off, which happens automatically as soon as you assign some value to this modifier parameter.

    Default:

      `0.0`

  property gradient

    The color gradient used to map normalized property values to colors. Available gradient types are:

    > - `ColorCodingModifier.BlueWhiteRed()`

    > - `ColorCodingModifier.CyclicRainbow()`

    > - `ColorCodingModifier.Grayscale()`

    > - `ColorCodingModifier.Hot()`

    > - `ColorCodingModifier.Jet()`

    > - `ColorCodingModifier.Magma()`

    > - `ColorCodingModifier.Rainbow()` (default)

    > - `ColorCodingModifier.Viridis()`

    > - `ColorCodingModifier.Fast()`

    > - `ColorCodingModifier.Gradient(<(N,3) 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. The `Image` 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: bool

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

    Default:

      `False`

  property operate_on: str

    Selects the kind of data elements this modifier should operate on. Supported values are: `'particles'`, `'bonds'`, `'vectors'`, `'voxels'`, `'surface_vertices'`, `'surface_faces'`, `'surface_regions'`, `'lines'`.

    Default:

      `'particles'`

  property property: str

    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"`.

  property start_value: float

    This parameter determines, together with `end_value`, the linear mapping of input property values to colors. It is only used if `auto_adjust_range` is turned off, which happens automatically as soon as you assign some value to this modifier parameter.

    Default:

      `0.0`

  property symmetric_range: bool

    When this option is enabled, the modifier will automatically adjust the value range to be symmetric around 0. Manually setting the maximum value will also adjust the minimum value to match.

    Default:

      `False`

class ovito.modifiers.CombineDatasetsModifier

  Base: `ovito.pipeline.Modifier`

  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: FileSource

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

class ovito.modifiers.CommonNeighborAnalysisModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  This modifier 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 on this modifier and the structure identification algorithm it implements.

  Note that this class inherits several important parameter fields from its `StructureIdentificationModifier` base class.

  Modifier inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles. They are not used if `mode` is set to `BondBased`.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is set to `True`.

  Bond properties |
  --- | ---
  `Topology` | The input bond topology; required only if `mode` is set to `BondBased`.

  Modifier outputs:

  Particle properties |
  --- | ---
  `Structure Type` | The structure type computed by the algorithm for each particle, encoded as an integer value:
  Numeric id | Python constant
  --- | ---
  0 | `CommonNeighborAnalysisModifier.Type.OTHER`
  1 | `CommonNeighborAnalysisModifier.Type.FCC`
  2 | `CommonNeighborAnalysisModifier.Type.HCP`
  3 | `CommonNeighborAnalysisModifier.Type.BCC`
  4 | `CommonNeighborAnalysisModifier.Type.ICO`
  `Color` | Particle coloring to indicate the identified structure type for each particle; only if `color_by_type` is `True`. See the `structures` array on how to customize the colors.

  Global attributes |
  --- | ---
  `CommonNeighborAnalysis.counts.OTHER` | Number of particles not matching any of the recognized 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.

  Data tables |
  --- | ---
  `structures` | A bar chart with the particle counts for each structure type identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.

  property cutoff: float

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

    Default:

      `3.2`

  property mode: CommonNeighborAnalysisModifier.Mode

    Selects the algorithm type. One of the following constants:

    > - `CommonNeighborAnalysisModifier.Mode.FixedCutoff`

    > - `CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff`

    > - `CommonNeighborAnalysisModifier.Mode.IntervalCutoff`

    > - `CommonNeighborAnalysisModifier.Mode.BondBased`

    Default:

      `CommonNeighborAnalysisModifier.Mode.AdaptiveCutoff`

class ovito.modifiers.ComputePropertyModifier

  Base: `ovito.pipeline.Modifier`

  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 kinds of data elements, such as particles, bonds, or voxels, which is controlled by the `operate_on` field.

  Example:

      from ovito.modifiers import ComputePropertyModifier

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

  Note

  In many cases you can replace the use of a `ComputePropertyModifier` in a pipeline with an equivalent Python modifier function performing the same task. The latter may be the better choice if the computation involves complex indexing operations or conditions, which can be accomplished more easily in the Python language or using NumPy array computations.

  For example, the `ComputePropertyModifier` creating the `Color` particle property in the code snippet above can be replaced by the following equivalent user-defined modifier function:

  >     def compute_particle_colors(frame, data):
  >         colors = data.particles_.create_property('Color')
  >         colors[:,0] = data.particles.positions[:,0] / data.cell[0,0]
  >         colors[:,1] = 0.0
  >         colors[:,2] = 0.5
  >     pipeline.modifiers.append(compute_particle_colors)

  See also

  To change the attributes of element types – the color, radius or name of a particle or bond type, for example – use the `EditTypesModifier` instead. Overwriting the `Color` property of individual elements with a `ComputePropertyModifier` achieves a similar visual result, but it does not update the type definitions themselves, so color legends, the data inspector and the GUI still show the original type colors.

  property cutoff_radius: float

    The cutoff radius up to which neighboring particles are visited to compute `neighbor_expressions`. This parameter is only used if `operate_on` is set to `'particles'`, `neighbor_mode` is set to `Cutoff`, and `neighbor_expressions` has been specified.

    Default:

      3.0

  property expressions: str | Sequence[str] | dict[str, str]

    The math expression(s) to compute for each element, one for each vector component of the output property.

    If the computed `output_property` is scalar, the expression should be a single Python string:

        ComputePropertyModifier(
            output_property = 'MyScalarProperty',
            expressions = 'sqrt(Position.X^2 + Position.Y^2)'
        )

    If the output property is one of the standard vector properties, which have predefined components, a sequence of expression strings should be specified, one for each component:

        ComputePropertyModifier(
            output_property = 'Color',
            expressions = ('ParticleIndex/N', '0', '0.5') # R, G, B
        )

    When creating a user-defined vector property, a dictionary of key-value pairs should be specified to set the property’s `component_names`:

        ComputePropertyModifier(
            output_property = 'MyVectorProperty',
            expressions = {
                'X': 'Position.X - Initial.X',
                'Y': 'Position.Y - Initial.Y',
                'Z': 'Position.Z - Initial.Z'
            }
        )

    For a description of the math expression syntax, see the corresponding user manual page.

    Attention

    The internal math expression parser can only handle variable identifiers made of alphanumeric characters and underscores. OVITO property and attribute names, however, can contain arbitrary characters (except dots). Within a math expression, properties and attributes must thus be referenced by their mangled names, with all spaces removed and other invalid characters replaced by underscores. For example, if the real name of an input property is “c_abc[1] Average”, then it must be referenced in the math expression as `c_abc_1_Average`. Furthermore, if the first character of a name happens to be a digit, an extra underscore is prepended to the mangled name.

    The modifier automatically creates a `VectorVis` visual element for a user-defined particle property if it has 3 components that are named `'X'`, `'Y'`, `'Z'`. This `VectorVis` element, which is attached to the generated `Property` object, is disabled by default and must be enabled and configured as follows if an arrow glyph visualization is desired:

        pipeline.modifiers.append(ComputePropertyModifier(
            output_property = 'InPlaneDir',
            expressions = {'X': 'cos(Angle)', 'Y': 'sin(Angle)', 'Z': '0'}
        ))
        vis = pipeline.compute().particles['InPlaneDir'].vis
        vis.enabled = True
        vis.color = (1,0,0)
        vis.width = 0.2

    Default:

      `'0'`

    Added in version 3.12.1: Support for user-defined vector properties and automatic creation of a `VectorVis` visual element.

  property neighbor_expressions: str | Sequence[str]

    The math expression(s) for the per-neighbor term(s), one for each vector component of the output particle property. The number of expressions in the list must match the number of vector components of the output property. If the output property is a scalar, only one expression string is required; otherwise, a list of strings.

    The neighbor expressions are evaluated for every neighboring particle and the obtained values are added to the output value of the central particle. Which neighboring particles are considered depends on the `neighbor_mode` and `cutoff_radius`. See Performing computations over neighbors and bonded particles for more information.

    Neighbor expressions are only used if `operate_on` is set to `'particles'`.

    Example: Compute mean velocity vector, averaged over all neighbors of a particle within a 3.8 Angstrom radius:

        ComputePropertyModifier(
            output_property = 'Averaged Velocity',
            expressions = {
                'X': 'Velocity.X / (NumNeighbors+1)',
                'Y': 'Velocity.Y / (NumNeighbors+1)',
                'Z': 'Velocity.Z / (NumNeighbors+1)'
            },
            neighbor_expressions = (
                'Velocity.X / (NumNeighbors+1)',
                'Velocity.Y / (NumNeighbors+1)',
                'Velocity.Z / (NumNeighbors+1)'
            ),
            cutoff_radius = 3.8
        )

    Default:

      `()`

  property neighbor_mode: NeighborMode

    Selects the criterion for visiting neighboring particles. Supported modes are:

    > - `ComputePropertyModifier.NeighborMode.Cutoff`

    > - `ComputePropertyModifier.NeighborMode.Bonded`

    Default:

      `ComputePropertyModifier.NeighborMode.Cutoff`

  property only_selected: bool

    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: str

    Selects the kind of data elements this modifier will operate on. Valid values are:

    > - `'particles'` - to add a property to the `Particles` container

    > - `'bonds'` - to add a property to the `Bonds` container

    > - `'voxels:<ID>'` - to add a property to the `VoxelGrid` container with the given `identifier`

    > - `'lines:<ID>'` - to add a property to a `Lines` container with the given `identifier`

    > - `'vectors:<ID>'` - to add a property to a `Vectors` container with the given `identifier`

    Default:

      `'particles'`

  property output_property: str

    The name of the output property which the computed values will be assigned to. If the property already exists in the input data, its values will be overwritten. If the name matches one of the predefined standard properties of OVITO, it will use the prescribed data type and component names. Otherwise, a new user-defined property with data type `float64` is created.

    - List of standard particle properties

    - List of standard bond properties

    - List of standard voxel properties

    - List of standard lines properties

    - List of standard vectors properties

    Default:

      `'My property'`

class ovito.modifiers.ConstructSurfaceModifier

  Base: `ovito.pipeline.Modifier`

  Constructs the geometric surface of the solid region formed by point-like particles. The modifier generates a `SurfaceMesh`, which is a closed manifold consisting of triangular elements. It furthermore can compute the surface area and the volume of individual regions enclosed by the surface mesh as well as empty pores in the interior of a structure. See the corresponding user manual page for more information.

  Basic usage example:

      pipeline.modifiers.append(ConstructSurfaceModifier(radius = 2.9))
      data = pipeline.compute()
      surface_mesh = data.surfaces['surface']

  See the `SurfaceMesh` class for further information on how to access the mesh’s vertices, faces, and spatial regions.

  Construction methods:

  The modifier supports two different surface construction methods, which are selected via the `method` parameter. The `AlphaShape` method uses a Delaunay tessellation constructed on the basis of the input particle centers to identify regions of space that cannot fully accommodate a virtual probe sphere. These Delaunay elements are classified as being part of the filled (or solid) region.

  The `radius` parameter controls the size of the virtual probe sphere and determines how much detail of the morphology is resolved during the surface construction. A larger radius leads to a surface with fewer details, reflecting only coarse features of the surface morphology. A small radius, on the other hand, will resolve finer surface features and small pores in the interior of a solid, for example.

  The second surface construction method supported by the modifier, `GaussianDensity`, is based on the smeared-out representation of the point-like particles as overlapping Gaussian distribution functions centered on each particle site. The surface mesh is constructed as an isosurface of the Gaussian density field, with the threshold `isolevel` chosen such that the resulting manifold roughly represents the input particle spheres. This code demonstrates how to use this second construction method:

      pipeline.modifiers.append(ConstructSurfaceModifier(
          method = ConstructSurfaceModifier.Method.GaussianDensity,
          radius_scaling = 1.2,
          isolevel = 0.5))

  Keep in mind that the result will depend on the current display radii of the particles when using the `GaussianDensity` method. The effective radii can generally depend on the standard radius set in the `ParticlesVis` element, the `radius` set for each `ParticleType`, or the per-particle property `Radius` if it is defined.

  Volumetric region analysis:

  Both methods provide the option to compute volumes and surface areas of the volumetric regions. This allows for the identification – and quantitative characterization – of individual cavities or clusters formed by particles. To enable this extra calculation step, set `identify_regions` to `True`. The modifier will also output various aggregate values for the entire system such as the total surface area and the porosity as global attributes, see the table below.

  Attention

  For simulation cells with one or more non-periodic boundaries, the volume of exterior regions is not well defined. Therefore, OVITO will report the volumes of these regions as infinity (inf). Global attributes derived from these volumes will also be reported as either infinity or not a number (nan).

      pipeline.modifiers.append(ConstructSurfaceModifier(
          method = ConstructSurfaceModifier.Method.AlphaShape,
          radius = 2.9,
          identify_regions = True))

      data = pipeline.compute()

      print("Aggregate quantities:")
      print(f"Surface area: {data.attributes['ConstructSurfaceMesh.surface_area']}")
      print(f"Solid volume: {data.attributes['ConstructSurfaceMesh.filled_volume']}")

      print("Volumetric regions:")
      regions = data.surfaces['surface'].regions
      for vol, area, filled, exterior in zip(regions['Volume'], regions['Surface Area'], regions['Filled'], regions['Exterior']):
          print(f"  volume={vol}, surface area={area}, filled={filled}, exterior={exterior}")

  The `AlphaShape` method furthermore provides the option to determine for each input particle which spatial region(s) it belongs to. For more information, see the `map_particles_to_regions` parameter.

  Outputs:

  Surface |
  --- | ---
  `SurfaceMesh` | The surface mesh computed by the modifier. You can access it through the `surfaces` dictionary in the output `DataCollection` under the lookup key `"surface"`, see the code example below.

  The following output attributes are computed only if `identify_regions` is turned on:

  Global attributes |
  --- | ---
  `ConstructSurfaceMesh.surface_area` | The total surface area in squared simulation units of length. Includes only interfaces between empty and filled regions if the modifier identifies internal boundaries (i.e. filled-filled interfaces).
  `ConstructSurfaceMesh.specific_surface_area` | The total surface area divided by the simulation cell volume (in reciprocal units of length).
  `ConstructSurfaceMesh.filled_volume` | The total volume of the filled region(s) bounded by the surface in cubic simulation units of length.
  `ConstructSurfaceMesh.empty_volume` | The total volume of the empty regions in cubic simulation units of length. Includes interior pores as well as the overlap of the infinite exterior region with the simulation box volume in case of a finite system with open boundary conditions.
  `ConstructSurfaceMesh.void_volume` | The total volume of the internal empty regions in cubic simulation units of length. Only includes interior pores that are not adjacent to an open simulation boundary.
  `ConstructSurfaceMesh.filled_fraction` | Total volume of filled regions divided by the simulation box volume (unitless).
  `ConstructSurfaceMesh.empty_fraction` | Total volume of empty regions divided by the simulation box volume (unitless).
  `ConstructSurfaceMesh.filled_region_count` | Integer number of disconnected volumetric regions filled with particles.
  `ConstructSurfaceMesh.empty_region_count` | Integer number of disconnected empty regions (any).
  `ConstructSurfaceMesh.void_region_count` | Integer number of internal disconnected empty regions, which are not adjacent to an open simulation box boundary.
  `ConstructSurfaceMesh.cell_volume` | The total volume of the simulation box in cubic simulation units of length. Equal to `SimulationCell.volume`.
  `ConstructSurfaceMesh.region_memberships` | A list of arrays, specifying for each spatial region which input particles belong to it. This attribute is only generated if the `map_particles_to_regions` option has been enabled.

  The following particle properties may be computed by the modifier:

  Particle properties |
  --- | ---
  `Selection` | Will be set to 1 by the modifier for particles right at the surface of a filled region, and 0 for interior particles or isolated particles not forming any solid. Computed only if the `select_surface_particles` option is turned on.
  `Surface Distance` | The computed distance of each particle from the closest point on the geometric surface. This property is only computed if the `compute_distances` option is turned on.
  `Region` | Index of the spatial region (see `SurfaceMesh.regions`) each particle is located in. This property is only computed if the `map_particles_to_regions` option is turned on.

  property compute_distances: bool

    This option activates the calculation of distances of the particles from the constructed surface. The computed distance of each particle is measured to the closest point on the surface mesh. The modifier will output the computed distance values as a new particle property named `Surface Distance`.

    Note that the computation of distances for all particles is a very expensive operation, which can take a long time for systems with many particles or a complex surface. To select surface particles, i.e. those particles which are located exactly on the surface, it may be more efficient to use the modifier’s `select_surface_particles` option instead.

    Default:

      `False`

  property grid_resolution: int

    Specifies the number of grid cells along the longest dimension of the simulation cell when generating the Gaussian density grid. This parameter thus also controls the level of detail of the of the final surface mesh, which is constructed as an isosurface from the density grid data.

    The parameter is only used if `GaussianDensity` is selected as construction `method`.

    Default:

      `50`

  property identify_regions: bool

    This option lets the modifier identify individual volumetric regions (filled with particles or empty) and compute their volumes and surface areas.

    See also

    Identification of volumetric regions and pores

    Default:

      `False`

  property isolevel: float

    The threshold value used for constructing the isosurface from the Gaussian density field. This parameter is only used if the selected construction `method` is set to `GaussianDensity`.

    Default:

      `0.6`

  property map_particles_to_regions: bool

    This option lets the modifier determine for each input particles which spatial region(s) of the output `SurfaceMesh` it is part of. The `AlphaShape` surface construction `method` must be selected and the `identify_regions` option turned on for this to work; otherwise the `map_particles_to_regions` option is ignored.

    Two outputs are produced by this option:

    1. A per-particle property named `Region` is generated, which specifies for each particle which spatial region it is located in (0-based region index). If a particle is located exactly on the boundary between a filled and an empty region, it will always be attributed to the filled region. However, a particle located fully within an empty region will be attributed to the empty region (which can happen for solitary particles that do not constitute a filled region).

           # Construct surface mesh around the subset of currently selected particles.
           pipeline.modifiers.append(ConstructSurfaceModifier(radius = 5.0, smoothing_level = 0,
               only_selected = True, identify_regions = True, map_particles_to_regions = True))
           data = pipeline.compute()

           # Count particles located inside solid regions of the surface mesh (region property "Filled" is 1).
           particle_regions = data.particles['Region']
           regions_table = data.surfaces['surface'].regions
           n = numpy.count_nonzero(regions_table['Filled'][particle_regions])

    2. In general, a particle can belong to several regions simultaneously if it is located right on the boundary between two adjacent regions. It may even be affiliated with more than one filled region if the surface mesh contains internal interfaces because it was constructed from a subdivided input structure (see `GrainSegmentationModifier`).

       In such cases, the per-particle property `Region` described above is insufficient to represent the multiple region affiliations a particle can have. Therefore, the modifier also generates a membership list for each spatial region, which lists the 0-based indices of all particles affiliated with that region. This list of lists is stored in the output data collection as the global attribute `ConstructSurfaceMesh.region_memberships`:

           # Print the list of particles affiliated with each region:
           memberships = data.attributes['ConstructSurfaceMesh.region_memberships']
           for idx, plist in enumerate(memberships):
               print(f"Region {idx} contains {len(plist)} particles: {plist[...]}")

       Note that empty regions will typically not have an empty particle membership list, because the surface particles at the interface between a filled and an empty spatial region get affiliated with both of these regions.

       You can select all particles that belong to a particular spatial region as follows:

           region_index_to_select = 0
           selection = data.particles_.create_property('Selection', data=0)
           selection[memberships[region_index_to_select]] = 1

       Added in version 3.11.0.

    Note

    The mapping of particles to regions happens before the surface smoothing stage of the alpha-shape construction algorithm, which means particles may appear slightly outside of the region they were attributed to, because the vertices of the final surface mesh are displaced by the smoothing procedure. You can turn off surface smoothing by setting `smoothing_level` to 0.

    Note

    The modifier assigns all particles to some spatial region(s) - even the unselected particles if the `only_selected` option is turned on and the surface is being constructed only from a subset of the input particles.

    Default:

      `False`

  property method: ConstructSurfaceModifier.Method

    Selects the algorithm for constructing the surface from the input particles. The following methods are available:

    > - `ConstructSurfaceModifier.Method.AlphaShape`

    > - `ConstructSurfaceModifier.Method.GaussianDensity`

    See also Comparison of alpha-shape and Gaussian density methods.

    If the alpha-shape method is selected, you should also set the `radius` parameter to specify the size of the virtual probe sphere, which determines the level of detail of the resulting surface.

    Default:

      `ConstructSurfaceModifier.Method.AlphaShape`

  property only_selected: bool

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

    Default:

      `False`

  property radius: float

    The radius of the virtual probe sphere used in the alpha-shape surface construction algorithm. This parameter is only used by the modifier if `method` is set to the default mode `AlphaShape`.

    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 radius_scaling: float

    Scaling factor applied to the input particle radii when constructing the Gaussian density field for surface generation. This parameter is only used if the selected construction `method` is set to `GaussianDensity`. The optional scaling serves as a way to increase the spatial extent of the Gaussian function centered on each particle site and to increase the overlap between the Gaussians, yielding a more connected isosurface.

    Default:

      `1.0`

  property select_surface_particles: bool

    This option lets the modifier select those particles that are part of the constructed geometric surface. This provides a simple way of identifying surface atoms or particles. If the flag is set to `True`, the modifier will create the `Selection` particle property, assigning a value of 1 to surface particles and 0 to bulk particles. This particle selection may then be used in subsequent operations in the data pipeline.

    Selecting surface particles is only supported by the `AlphaShape` construction `method`. For other construction methods, the setting is ignored and the modifier does not create a particle selection.

    An alternative way of selecting particles that are located near the surface is to use the `compute_distances` option of the modifier. While the `select_surface_particles` option lets you identify particles located exactly on the geometric surface, the `compute_distances` option lets you define a distance threshold, selecting also particles slightly away from the surface.

    Default:

      `False`

  property smoothing_level: int

    The number of times the smoothing procedure is applied to the generated surface mesh. This parameter is only used by the modifier if `method` is set to the default mode `AlphaShape`.

    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 transfer_properties: bool

    This option lets the modifier copy the property values of the particles over to the vertices of the generated surface mesh.

    Note: If the Gaussian density method is used, only particle properties of data type `Float` will be transferred to the surface. Integer properties will be skipped, because the algorithm has to blend the property values of several particles in order to compute the value at each surface vertex. In case of the alpha-shape method, all properties are transferred, including integer properties, because there is a one-to-one mapping between input particles and output mesh vertices.

    Default:

      `False`

  property vis: SurfaceMeshVis

    The `SurfaceMeshVis` element controlling the visual appearance of the generated surface in rendered images and animations.

class ovito.modifiers.CoordinationPolyhedraModifier

  Base: `ovito.pipeline.Modifier`

  Constructs coordination polyhedra around selected particles for visualization purposes. See the corresponding user manual page for more information. A coordination polyhedron is the convex hull constructed from the neighbor atoms of some central atom.

  In order to tell the modifier which input particles should be surrounded by a coordination polyhedron, the central particles must be selected first. The particle selection can be created by inserting a `SelectTypeModifier` into the data pipeline prior to this modifier.

  The modifier furthermore requires input bonds connecting a central particle with its neighbors to define which atoms the algorithm should use in the construction of the convex hulls. You can insert the `CreateBondsModifier` prior to this modifier to let OVITO dynamically generate neighbor bonds between particles.

  Example:

      # Import simulation dataset and add it to the scene:
      pipeline = import_file("input/simulation.0.dump")
      pipeline.add_to_scene()

      # Select all atoms of species type 1. They will form the centers of the polyhedra.
      pipeline.modifiers.append(SelectTypeModifier(types={1}))
      # Create bonds between nearby atoms.
      pipeline.modifiers.append(CreateBondsModifier(cutoff=3.0))
      # Let the modifier construct the coordination polyhedra around selected atoms.
      modifier = CoordinationPolyhedraModifier()
      pipeline.modifiers.append(modifier)

      # Optional: Configure visual appearance of the polyhedra and make them semi-transparent.
      modifier.vis.surface_transparency = 0.4
      modifier.vis.highlight_edges = True

  Modifier inputs:

  Particle properties |
  --- | ---
  `Selection` | Determines the subset of particles for which coordination polyhedra should be constructed. You can select all particles of certain chemical type(s) by first inserting a `SelectTypeModifier` into the pipeline.

  Bond properties |
  --- | ---
  `Topology` | The bonds list, which is used to determine the set of bonded neighbor particles serving as vertices for the construction of a coordination polyhedron around some central particle. You can let OVITO create the bond topology by inserting a `CreateBondsModifier` into the pipeline first.

  Modifier outputs:

  Polyhedral mesh |
  --- | ---
  `coord-polyhedra` | The polyhedral `SurfaceMesh` generated by the modifier. You can retrieve it from the `surfaces` dictionary of the `DataCollection`.

  property vis: SurfaceMeshVis

    The `SurfaceMeshVis` element controlling the visual appearance of the generated polyhedra in rendered images and animations.

class ovito.modifiers.CreateBondsModifier

  Base: `ovito.pipeline.Modifier`

  Creates bonds between nearby particles. See the corresponding user manual page for more information.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The xyz coordinates of the input particles.
  `Particle Type` | The particle type information, which is used only if `mode` is set to `VdWRadius`, `Pairwise`, or `CovalentRadius`.
  `Molecule Identifier` | The assignment of atoms to molecules, which is used only if `intra_molecule_only` is set to `True`.

  Outputs:

  Bond properties |
  --- | ---
  `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 new `Bonds` instance if necessary. If `discard_existing_bonds` is set, any bonds already present in the input are deleted first.
  `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.

  Global attributes |
  --- | ---
  `CreateBonds.num_bonds` | The number of bonds that exist after the modifier’s operation.

  property bond_type: BondType

    The `BondType` that will be assigned to the newly created bonds. This lets you control the display color of the new bonds.

  property cutoff: float

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

    Default:

      `3.2`

  property discard_existing_bonds: bool

    Controls whether the modifier discards all bonds that already exist in its input before creating the new bonds. By default, the modifier adds the newly created bonds to the existing bond topology, for example the bonds that were loaded from a simulation file. Set this option to `True` to let the modifier compute the bond topology of the structure from scratch. Note that all bond properties and the `BondsVis` element of the existing `Bonds` object are preserved.

    Default:

      `False`

  get_pairwise_cutoff(type_a: str | int, type_b: str | int) → float

    Returns the pair-wise cutoff distance that was previously set for a specific pair of particle types using the `set_pairwise_cutoff()` method.

    Parameters:

      - type_a – The `name` or numeric `id` of the first particle type

      - type_b – The `name` or numeric `id` of the second particle type

    Returns:

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

  property intra_molecule_only: bool

    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: float

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

    Default:

      `0.0`

  property mode: CreateBondsModifier.Mode

    Controls the cutoff criterion for creating bonds. Valid cutoff modes are:

    > - `CreateBondsModifier.Mode.Uniform`

    > - `CreateBondsModifier.Mode.VdWRadius`

    > - `CreateBondsModifier.Mode.Pairwise`

    > - `CreateBondsModifier.Mode.CovalentRadius`

    Mode `Uniform` uses a single uniform `cutoff` distance for creating bonds, which is independent of the types of the particles. Mode `VdWRadius` uses a distance cutoff that is derived from the `vdw_radius` (Van der Waals radius) of the `ParticleType` of the two particles involved. Mode `Pairwise` lets you specify a separate cutoff distance for each pairwise combination of particle types using the `set_pairwise_cutoff()` method. Mode `CovalentRadius` uses tabulated covalent radii and maximum coordination numbers to determine the bond connectivity.

    Default:

      `CreateBondsModifier.Mode.Uniform`

  property prevent_hh_bonds: bool

    Controls whether the modifier should not generate bonds between pairs of hydrogen atoms. This flag only applies if `mode` is set to `VdWRadius` and the van der Waals radii of the atom types are used for generating pair-wise bonds. A particle is considered a hydrogen atom if its `ParticleType`’s name is `'H'`.

    Default:

      `True`

  set_pairwise_cutoff(type_a: str | int, type_b: str | int, cutoff: float)

    Sets the cutoff range for creating bonds between a specific pair of particle types. This information is only used if `mode` is set to `Pairwise`.

    Parameters:

      - type_a – The `name` or numeric `id` of the first particle type

      - type_b – The `name` or numeric `id` of the second particle type

      - cutoff – The cutoff distance to be used by the modifier for the type pair

    If you want no bonds to be created between a pair of types, set the corresponding cutoff radius to zero (which is the default).

  property vis: BondsVis

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

class ovito.modifiers.CreateIsosurfaceModifier

  Base: `ovito.pipeline.Modifier`

  Constructs an isosurface for a scalar field defined on a three-dimensional `VoxelGrid`. See the corresponding user manual page for more information on this modifier.

  The modifier takes an existing `VoxelGrid` as input, for example a charge density field loaded from a simulation file or a three-dimensional voxel grid dynamically computed by the `SpatialBinningModifier`. The input voxel grid to be used in isosurface computation must be selected by setting the `operate_on` field to the string `'voxels:'` followed by the `identifier` of the input voxel grid. Furthermore, you need to specify the name of the field `Property` for which to construct the isosurface, because multiple fields may be defined on the same voxel grid.

  >     # Import a charge density field from a VASP calculation:
  >     pipeline = import_file("input/CHGCAR.nospin.gz")
  >     pipeline.add_to_scene()

  >     # The identifier of the imported VoxelGrid is 'charge-density',
  >     # and the field property defined on the grid is named 'Charge Density'.
  >     print(pipeline.compute().grids['charge-density'])

  >     # Set up the isosurface modifier:
  >     modifier = CreateIsosurfaceModifier(
  >         operate_on = 'voxels:charge-density',
  >         property = 'Charge Density',
  >         isolevel = 0.00014)
  >     pipeline.modifiers.append(modifier)

  >     # Adjust visual appearance of the isosurface in rendered images:
  >     modifier.vis.show_cap = False
  >     modifier.vis.surface_transparency = 0.4

  The following example demonstrates how to construct an isosurface for a field dynamically computed by the `SpatialBinningModifier`:

  >     pipeline.modifiers.append(SpatialBinningModifier(
  >         property = 'Particle Type',
  >         direction = SpatialBinningModifier.Direction.XYZ,
  >         bin_count = (30, 30, 30),
  >         reduction_operation = SpatialBinningModifier.Operation.Mean
  >     ))
  >     pipeline.modifiers.append(CreateIsosurfaceModifier(
  >         operate_on = 'voxels:binning',
  >         property = 'Particle Type',
  >         isolevel = 1.5
  >     ))

  Modifier outputs:

  `SurfaceMesh` |
  --- | ---
  `isosurface` | The `SurfaceMesh` constructed by the modifier. You can retrieve it from the `surfaces` dictionary of the pipeline’s output `DataCollection`.

  `DataTable` |
  --- | ---
  `isosurface-histogram` | A histogram of the input field values. You can retrieve this `DataTable` from the `tables` dictionary of the pipeline’s output `DataCollection`.

  property identify_regions: bool

    This option lets the modifier identify volumetric regions, i.e. regions of space where the field value is either below or above the iso-level, and compute their individual volumes and surface areas. These properties are calculated individually for each disconnected spatial region bounded by the isosurface.

    See also

    Identification of volumetric regions and pores

    Default:

      `False`

    Added in version 3.10.4.

  property isolevel: float

    The value at which to create the isosurface.

    Default:

      `0.0`

  property operate_on: str

    Specifies the `VoxelGrid` this modifier should operate on. Set this to the unique `identifier` of the grid.

    Note: You can use the Python statement `print(pipeline.compute().grids)` to find out what the identifiers of the voxel `grids` in your data pipeline are.

    Default:

      `''`

  property property: str

    The name of the `Property` in the selected input `VoxelGrid` for which to construct the isosurface. Note that this must be a scalar property. If the input grid property is a vector property, you need to explicitly specify which vector component to use, e.g. `'Dipole Orientation.Z'`.

  property smoothing_level: int

    The number of times the mesh smoothing procedure is applied to the generated isosurface to even out surface steps resulting from the discrete nature of the input voxel grid.

    Default:

      `0`

    Added in version 3.10.4.

  property transfer_values: bool

    This option lets the modifier copy auxiliary properties of the voxel field (aside from the primary field quantity for which the isosurface is being constructed) over to the vertices of the generated isosurface mesh. The local field value at each isosurface vertex will be computed from the voxel values using trilinear interpolation. Subsequently, the pseudo-coloring capability of the `vis` element can be used to color the generated isosurface based on a secondary field quantity.

    Default:

      `False`

  property vis: SurfaceMeshVis

    The `SurfaceMeshVis` element controlling the visual appearance of the generated isosurface in rendered images.

class ovito.modifiers.DeleteSelectedModifier

  Base: `ovito.pipeline.Modifier`

  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.
  `surface_regions` | Deletes all selected spatial regions (including the corresponding mesh faces) from a `SurfaceMesh`.
  `lines` | Deletes all vertices of a `Lines` object having a non-zero `Selection` property value.
  `vectors` | Deletes all vector glyphs of a `Vectors` object having a non-zero `Selection` property value.

  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: MutableSet[str]

    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', 'surface_regions', 'lines', 'vectors'}`

class ovito.modifiers.DifferenceBetweenFramesModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.14.0.

  This modifier computes the numeric difference (delta) between a property or attribute in the current frame and a reference frame. The reference frame can be defined either as a fixed frame or as a relative offset, enabling sliding-window difference calculations. See the user manual for more details.

  The following kinds of input quantities are currently supported by the modifier:

  > - global attributes,

  > - element-wise property values stored in `Particles` or `VoxelGrid` containers,

  > - `DataTable` objects, e.g. histograms or distribution functions computed by other analysis modifiers in the pipeline.

  Multiple such input quantities can be processed simultaneously by one modifier instance.

  If the input property is named `<property>`, the output is stored in a new property named `<property> (Difference)`. The result has the same data type and number of components as the input.

  Caution

  This modifier does not account for periodic boundary conditions. When computing differences of particle coordinates or other spatial properties, this may lead to incorrect results. Use the `CalculateDisplacementsModifier` instead for proper calculation of displacement vectors.

  Usage examples:

  Particles: A `RadialDistributionFunctionModifier` in the pipeline computes the per-particle coordination number (particle property `Coordination`) at the current time. The `DifferenceBetweenFramesModifier` can then be used to compute how the coordination of each atom changes between the current frame and a reference configuration, e.g. the first trajectory frame:

      pipeline = import_file("input/trajectory.dump")
      pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff=6.0))
      pipeline.modifiers.append(DifferenceBetweenFramesModifier(operate_on="particles:particles/Coordination"))
      data = pipeline.compute(4)
      print(data.particles["Coordination (Difference)"][...])
      assert numpy.all(data.particles["Coordination (Difference)"] == data.particles["Coordination"] - pipeline.compute(0).particles["Coordination"])

  Voxel grids: In this example we use the `SpatialBinningModifier` to generate a `VoxelGrid` with local particle densities. This grid is then processed by a `DifferenceBetweenFramesModifier` to compute density changes:

      pipeline = import_file("input/trajectory.dump")
      pipeline.modifiers.append(SpatialBinningModifier(
          direction = SpatialBinningModifier.Direction.XYZ,
          bin_count = (20, 20, 20),
          reduction_operation = SpatialBinningModifier.Operation.SumVol))
      pipeline.modifiers.append(DifferenceBetweenFramesModifier(operate_on="voxels:binning/Density"))
      data = pipeline.compute(4)
      print(data.grids["binning"]["Density (Difference)"][...])

  Data tables: The `RadialDistributionFunctionModifier` computes the radial pair distribution function (RDF) of a particle system for the current simulation time and outputs it as a `DataTable` named `coordination-rdf`. This table can be used as input to the `DifferenceBetweenFramesModifier`, which produces a new table named `coordination-rdf[diff]`:

      pipeline = import_file("input/trajectory.dump")
      pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff=6.0, number_of_bins=50))
      pipeline.modifiers.append(DifferenceBetweenFramesModifier(operate_on="table:coordination-rdf"))
      data = pipeline.compute(4)
      print(data.tables["coordination-rdf[diff]"]["g(r) (Difference)"][...])

  Global attributes: This example shows how to compute the incremental changes (deltas) for two attributes `SourceFrame` and `Timestep` simultaneously:

      pipeline = import_file("input/trajectory.dump")
      pipeline.modifiers.append(DifferenceBetweenFramesModifier(
          operate_on=("attribute:SourceFrame", "attribute:Timestep"),
          use_frame_offset=True))
      data = pipeline.compute(4)
      print(data.attributes["SourceFrame (Difference)"])
      print(data.attributes["Timestep (Difference)"])

  property frame_offset: int

    The relative frame offset when using a sliding reference configuration (if `use_frame_offset` == `True`). Negative frame offsets correspond to reference configurations that precede the current configuration in time.

    Default:

      `-1`

  property operate_on: str | Sequence[str]

    Selects the input quantity to be processed by this modifier. Supported values for this field are:

    > - `'attribute:<NAME>'`

    > - `'table:<ID>'`

    > - `'voxels:<CONTAINER>/<PROPERTY>'`

    > - `'particles:particles/<PROPERTY>'`

    Here, `<NAME>` refers to the name of a global attribute. `<ID>` is the `identifier` of a `DataTable`, `<CONTAINER>` is the `identifier` of a `Particles` object or `VoxelGrid`, and `<PROPERTY>` the `name` of the `Property` in that container. Please see the code examples given in the class documentation above.

    Furthermore, it is possible to let the modifier operate on multiple input quantities in one pass by specifying a sequence of input reference strings.

    Default:

      `''`

  property reference_frame: int

    The zero-based animation frame to use as constant reference configuration. Only used if `use_frame_offset` is set to false.

    Default:

      `0`

  property select_new: bool

    If set to `True`, the modifier will select any newly appearing particles at the current timestep that were not present in the reference configuration.

    This option is useful in conjunction with the `tolerate_new` option, which tells the modifier to accept the appearance of elements with new identities. It is typically employed for non-conservative simulations, where particles are created or deleted during the simulation.

    Default:

      `False`

  property tolerate_new: bool

    Determines whether newly appearing particles in the current configuration that were not yet present in the reference configuration are acceptable or not.

    If set to `False`, the modifier will throw an error if the current timestep contains previously unknown particles that were not present in the reference configuration. This is the default behavior, which prevents situations where some of the particles do not have counterparts in the reference configuration and their property changes cannot be computed.

    If set to `True`, the modifier will ignore the appearance of new particles compared to the reference configuration. Newly appearing particles will then receive a default difference value of 0.

    You can additionally activate `select_new` to let the modifier select any newly appearing particles. This gives you the option to visualize the newly created particles in a different way, e.g. by coloring them differently.

    Default:

      `False`

  property use_frame_offset: bool

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

    Default:

      `False`

class ovito.modifiers.DislocationAnalysisModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  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 the `DataCollection.dislocations` field after the modification pipeline has been evaluated. This is demonstrated in the example script below.

  Furthermore, you can use the `export_file()` function to write the dislocation lines to a so-called CA file. The CA file format is described on this page of the OVITO user manual.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is `True`.

  Outputs:

  Dislocations |
  --- | ---
  `DislocationNetwork` | The dislocation lines found by the modifier. You can access this data object through the `dislocations` field of the output `DataCollection`, see the code example below.

  Global attributes |
  --- | ---
  `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.

  Particle properties |
  --- | ---
  `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` is `True`).
  `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.
  `Dislocation` | Only if `mark_dislocation_core_atoms` is enabled. This particle property indicates the zero-based ID of the dislocation line each atom has been associated with. Atoms that are not part of a dislocation core are assigned the value -1.

  Example:

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

      import ovito
      ovito.enable_logging()

      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 lines" % len(data.dislocations.lines))
      for line in data.dislocations.lines:
          print("Dislocation %i: length=%f, Burgers vector=%s" % (line.id, line.length, line.true_burgers_vector))
          print(line.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: int

    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: bool

    Controls whether the modifier assigns a color to each particle based on the identified structure type.

    Default:

      `True`

  property defect_mesh_smoothing_level: int

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

    Default:

      `8`

  property defect_vis: SurfaceMeshVis

    The `SurfaceMeshVis` element controlling the visual representation of the generated defect mesh.

  property disloc_vis: DislocationVis

    The `DislocationVis` element controlling the visual representation of the generated dislocation lines.

  property input_crystal_structure: DislocationAnalysisModifier.Lattice

    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: bool

    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: float

    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: bool

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

    Default:

      `True`

  property line_smoothing_level: int

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

    Default:

      `1`

  property low_ca_ratio: bool

    Set this to `True` to enable special treatment of hexagonal close-packed (HCP) structures with a low c/a ratio, e.g., tungsten carbide. In such crystals, the common neighbor analysis (CNA) method fails to identify the correct structure type, so the DXA needs to stretch the crystal lattice in the c-direction to compensate for the low c/a ratio. Enabling this option should increase the recognition rate of HCP atoms in such structures (higher `DislocationAnalysis.counts.HCP` output attribute) and thus improve the dislocation identification.

    This option only has an effect if `input_crystal_structure` is set to `DislocationAnalysisModifier.Lattice.HCP`.

    Default:

      `False`

    Added in version 3.15.0.

  property mark_dislocation_core_atoms: bool

    Lets the algorithm identify and mark atoms belonging to the individual dislocation cores. A new particle property `Dislocation` will be created containing a zero-based dislocation identifier if the atom belongs to a dislocation’s core region. Atoms not belonging to any dislocation core are assigned the special value -1.

    Default:

      `False`

  property only_perfect_dislocations: bool

    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 higher value when activating this option, because larger Burgers circuits are needed to identify dissociated dislocations with wide cores.

    Default:

      `False`

  property only_selected: bool

    Set this to `True` to perform the analysis on selected particles only. Particles that are not selected will be treated as if they did not exist. Use the `SelectTypeModifier`, for example, to restrict the crystal structure identification to a sub-lattice formed by one species of particles in a multi-component system.

    Default:

      `False`

  property trial_circuit_length: int

    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.EditSimulationCellModifier

  Base: `ovito.pipeline.Modifier`

  Modifies the geometry and the boundary conditions of the `SimulationCell`. Use it to switch periodic boundary conditions on or off, to declare a system two-dimensional, or to override the cell vectors and the cell origin loaded from the input file. See also the corresponding user manual page for more information.

      from ovito.io import import_file
      from ovito.modifiers import EditSimulationCellModifier

      pipeline = import_file("input/simulation.dump")

      # Turn off the periodic boundary condition in the z-direction. The x- and y-flags and the
      # dimensionality are inherited from the input cell, because they are not set here.
      pipeline.modifiers.append(EditSimulationCellModifier(pbc_z=False))

      # All three flags can also be set at once, using the same tuple notation as SimulationCell.pbc:
      modifier = EditSimulationCellModifier(pbc=(True, True, False))
      pipeline.modifiers.append(modifier)

      # Override the cell geometry with an axis-aligned box of edge length 100, centered at the origin.
      # The first three columns are the cell vectors a, b and c, the fourth column is the cell origin.
      modifier.replace_cell = True
      modifier.cell_matrix = [[100, 0, 0, -50], [0, 100, 0, -50], [0, 0, 100, -50]]

  Parameters you do not set explicitly are adopted from the modifier’s input cell at the time the modifier is inserted into the pipeline. In the example above, only the z direction is made non-periodic; the x and y flags and the dimensionality keep the values of the input cell. Note that all changes take effect only at the position in the pipeline where the modifier is inserted, i.e., only downstream modifiers and the visualization see the modified cell.

  The cell geometry is left untouched unless you turn on `replace_cell`, in which case the input cell matrix is replaced with `cell_matrix`.

  When to use this modifier:

  In a standalone Python script it is often more direct to assign to `SimulationCell.pbc` from a user-defined modifier function, or to set up the cell at the data source. Reach for `EditSimulationCellModifier` when the pipeline you are building is meant to remain editable in the graphical user interface of OVITO Pro: it appears there as a regular Edit simulation cell entry in the pipeline editor, with a full editor panel.

  See also

  - `SimulationCell`

  - `AffineTransformationModifier`

  - `ReplicateModifier`

  Added in version 3.15.0.

  property cell_matrix

    The 3x4 matrix specifying the replacement cell geometry: the first three columns are the cell vectors a, b and c, the fourth column is the cell origin. It is applied to the data only if `replace_cell` is turned on.

    Default:

      the matrix of the input simulation cell

  property is2D: bool

    Controls whether the simulation cell is flagged as two-dimensional. In 2D mode, the periodic boundary condition in the z-direction is always turned off, irrespective of `pbc_z`.

    Default:

      the dimensionality of the input simulation cell

  property pbc: tuple[bool, bool, bool]

    A tuple of three Boolean flags specifying whether the modifier turns periodic boundary conditions on or off along the cell’s three spatial directions.

    Directions you never assign a value to are inherited from the modifier’s input cell at the time the modifier is inserted into the pipeline. Note that the third flag has no effect while `is2D` is turned on.

    Default:

      the PBC flags of the input simulation cell

  property pbc_x: bool

    Controls the periodic boundary condition in the x-direction. See also `pbc`.

    Default:

      the flag of the input simulation cell

  property pbc_y: bool

    Controls the periodic boundary condition in the y-direction. See also `pbc`.

    Default:

      the flag of the input simulation cell

  property pbc_z: bool

    Controls the periodic boundary condition in the z-direction. Has no effect while `is2D` is turned on. See also `pbc`.

    Default:

      the flag of the input simulation cell

  property replace_cell: bool

    Controls whether the modifier overrides the geometry of the input simulation cell with `cell_matrix`. If `False`, the modifier only changes the boundary conditions and the dimensionality and leaves the cell vectors and the cell origin as they are.

    Default:

      `False`

class ovito.modifiers.EditTypesModifier

  Base: `ovito.pipeline.Modifier`

  Inspects and modifies the list of element types associated with a typed property, for example the `Particle Type` or `Bond Type` property. Use it to change the display color, radius, name or physical attributes of individual types, to define additional types, or to remove type definitions. See also the corresponding user manual page for more information.

  The `property` field selects which typed property is being edited. When you insert the modifier into a pipeline, it automatically picks the `Particle Type` property if the input data contains one.

  The recommended way of configuring the modifier is through its `edit_type()`, `add_type()` and `delete_type()` methods, which look up the existing type definitions in the modifier’s input data for you:

      from ovito.io import import_file
      from ovito.modifiers import EditTypesModifier

      pipeline = import_file("input/simulation.dump")

      # Insert the modifier. It automatically selects the 'Particle Type' property of the input data.
      modifier = EditTypesModifier()
      pipeline.modifiers.append(modifier)

      # Change the appearance and the name of the existing type with numeric ID 1. Type attributes
      # that are not specified here keep the values they have in the modifier's input data.
      modifier.edit_type(1, name="Cu", color=(0.9, 0.5, 0.2), radius=1.28)

      # Attributes may also be set one by one on the type object returned by the method:
      type2 = modifier.edit_type(2)
      type2.color = (0.2, 0.4, 1.0)

      # Define an additional particle type. Its numeric ID is picked automatically, and its color,
      # radius and mass are preset from OVITO's internal database of chemical elements.
      new_type = modifier.add_type(name="Ni")
      print(new_type.id, new_type.name, new_type.color)

      # Remove a type definition again. Note that particles keep their numeric type ID.
      modifier.delete_type("Cu")

  Note that all changes take effect only at the position in the pipeline where the modifier is inserted, i.e., only downstream modifiers and the visualization see the modified type list.

  Modifier state:

  The modifier records the changes you make as a list of replacement type definitions in the `edited_types` field and a set of numeric IDs in the `deleted_type_ids` field. During pipeline evaluation, the types listed in `deleted_type_ids` are dropped from the input property’s `types` list, and every entry of `edited_types` then replaces the input type having the same numeric `id` – or is appended to the list if no such type exists.

  Because an entry replaces the original definition as a whole, appending a freshly constructed `ElementType` to `edited_types` yourself would discard all attributes of the original type that you do not set explicitly. `edit_type()` avoids this by starting from a copy of the original definition, which is why it should be preferred over direct manipulation of the list.

  When to use this modifier:

  In a standalone Python script that just needs different type colors or radii, it is often more direct to manipulate the `ElementType` objects of the typed property from a user-defined modifier function. Reach for `EditTypesModifier` when the pipeline you are building is meant to remain editable in the graphical user interface of OVITO Pro: it appears there as a regular Edit types entry in the pipeline editor, with a full editor panel for the type list.

  See also

  - `ColorByTypeModifier`

  - `SelectTypeModifier`

  - `ovito.data.Property.types`

  Added in version 3.15.0.

  add_type(id=None, *, name='', data=None, **params)

    Adds a new element type definition to the selected typed property.

    Note that this only defines the new type; it does not assign it to any elements. Use the `ComputePropertyModifier` or a user-defined modifier function downstream of this modifier to give elements the new type’s numeric ID.

        # Define an additional particle type. Its numeric ID is picked automatically, and its color,
        # radius and mass are preset from OVITO's internal database of chemical elements.
        new_type = modifier.add_type(name="Ni")
        print(new_type.id, new_type.name, new_type.color)

    Parameters:

      - id (int | None) – The numeric ID of the new type. If `None`, the smallest ID not yet in use is picked.

      - name (str) – The human-readable name of the new type. If it matches a chemical element symbol, the type’s color, radius and mass are preset from OVITO’s internal database of chemical elements.

      - data (DataCollection | None) – The modifier’s input data collection. Only needed if the modifier is not part of a pipeline yet or is shared by several pipelines. Otherwise it is determined automatically.

      - params (Any) – Additional type attributes to set, e.g. `color=(1.0, 0.0, 0.0)`.

    Returns:

      The mutable `ElementType` object stored in the `edited_types` list.

    Return type:

      ElementType

  delete_type(type, *, data=None)

    Removes an element type definition from the selected typed property.

    Note that this deletes the type definition only. Elements still carrying the deleted numeric type ID keep it, they just no longer have a type descriptor providing a name and display color. Typically you want to delete those elements too, e.g. with the `ExpressionSelectionModifier` followed by the `DeleteSelectedModifier`, inserted upstream of this modifier.

        # Remove a type definition again. Note that particles keep their numeric type ID.
        modifier.delete_type("Cu")

    Parameters:

      - type (int | str) – The numeric `id` or the `name` of the type to delete.

      - data (DataCollection | None) – The modifier’s input data collection. Only needed if the modifier is not part of a pipeline yet or is shared by several pipelines. Otherwise it is determined automatically.

    Return type:

      None

  property deleted_type_ids: set[int]

    The set of numeric type IDs to be removed from the selected `property`’s list of element types.

    Use the `delete_type()` and `restore_type()` methods to manipulate this set, which also let you refer to a type by name. Note that deleting a type removes its definition only; data elements still carrying the numeric ID are left untouched.

    Default:

      `set()`

  edit_type(type, *, data=None, **params)

    Modifies the attributes of an existing element type. This is the standard way of changing the display color, radius, or name of a particle or bond type from a Python script.

    The method looks up the type in the modifier’s input data, adds a copy of its definition to the `edited_types` list, and applies the given keyword arguments to that copy. All attributes you do not specify keep the values they have in the upstream data. Calling the method again for the same type returns the same object, so edits accumulate:

        # Change the appearance and the name of the existing type with numeric ID 1. Type attributes
        # that are not specified here keep the values they have in the modifier's input data.
        modifier.edit_type(1, name="Cu", color=(0.9, 0.5, 0.2), radius=1.28)

        # Attributes may also be set one by one on the type object returned by the method:
        type2 = modifier.edit_type(2)
        type2.color = (0.2, 0.4, 1.0)

    Parameters:

      - type (int | str) – The numeric `id` or the `name` of the type to edit.

      - data (DataCollection | None) – The modifier’s input data collection. Only needed if the modifier is not part of a pipeline yet or is shared by several pipelines. Otherwise it is determined automatically.

      - params (Any) – The type attributes to change, e.g. `color=(1.0, 0.0, 0.0)` or `radius=1.2`. See `ElementType` and its sub-classes for the available attributes.

    Returns:

      The mutable `ElementType` object stored in the `edited_types` list.

    Return type:

      ElementType

  property edited_types: MutableSequence[ElementType]

    The list of replacement type definitions the modifier applies to the selected `property`.

    During pipeline evaluation, each `ElementType` in this list replaces the input type having the same numeric `id`, or is appended to the type list if the input data has no such type. Since an entry replaces the original definition as a whole, all attributes of the original type that are not set on the replacement would be lost.

    That is why you should normally not append `ElementType` instances to this list yourself. Use `edit_type()` and `add_type()` instead, which start from a copy of the original type definition and also instantiate the right `ElementType` sub-class (e.g. `ParticleType`) for you.

    Default:

      `[]`

  property property: str

    The typed property whose list of element types is being edited, specified as a data object path: the identifiers of the property and of all its parent objects, joined by forward slashes. Typical values are `'particles/Particle Type'`, `'particles/Structure Type'` and `'bonds/Bond Type'`.

    The property must be a typed property, i.e. a scalar integer property with a list of `ElementType` descriptors attached to it. When the modifier is inserted into a pipeline, this field is automatically initialized to the `Particle Type` property if the input data contains one.

    Assigning a new value resets the `edited_types` and `deleted_type_ids` fields, because type IDs are only meaningful within one particular property.

    Default:

      `''`

  restore_type(type, *, data=None)

    Reverts the modifications this modifier makes to the given element type.

    If the type is currently marked for deletion, the deletion is undone. Otherwise the type’s edited attributes are discarded, so that it is passed through from the upstream data unchanged again.

    Parameters:

      - type (int | str) – The numeric `id` or the `name` of the type to restore.

      - data (DataCollection | None) – The modifier’s input data collection. Only needed if the modifier is not part of a pipeline yet or is shared by several pipelines. Otherwise it is determined automatically.

    Return type:

      None

class ovito.modifiers.ElasticStrainModifier

  Base: `ovito.pipeline.Modifier`

  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 the `input_crystal_structure` property. Atoms that do not form a crystalline structure or which are part of defects are assigned the special type `OTHER` (=0). For these atoms the local elastic deformation cannot be computed.

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

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

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

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is `True`.

  Outputs:

  Particle properties |
  --- | ---
  `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 if `calculate_deformation_gradients` is set to `True`.
  `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 if `calculate_strain_tensors` is set to `True`.
  `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` is `True`).
  `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: float

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

    Default:

      `sqrt(8/3)`

  property calculate_deformation_gradients: bool

    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: bool

    Flag that enables the calculation and output 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: ElasticStrainModifier.Lattice

    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: float

    Lattice constant (a0) of the ideal unit cell.

    Default:

      `1.0`

  property push_strain_tensors_forward: bool

    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: `ovito.pipeline.Modifier`

  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:

  Particle properties |
  --- | ---
  `Selection` | The selection state of the input particles.
  `Position` | The coordinates of the input particles (only used if `mode` is `Cutoff` or `Nearest`).

  Bond properties |
  --- | ---
  `Topology` | The list of bonds (only used if `mode` is `Bonded`).

  Outputs:

  Particle properties |
  --- | ---
  `Selection` | The output particle selection.

  Global attributes |
  --- | ---
  `ExpandSelection.num_added` | The number of particles that got newly selected by the modifier.

  property cutoff: float

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

    Default:

      `3.2`

  property iterations: int

    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: ExpandSelectionModifier.ExpansionMode

    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`

    > - `ExpandSelectionModifier.ExpansionMode.Molecule`

    Default:

      `ExpandSelectionModifier.ExpansionMode.Cutoff`

  property num_neighbors: int

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

    Default:

      `1`

class ovito.modifiers.ExpressionSelectionModifier

  Base: `ovito.pipeline.Modifier`

  Selects data elements, e.g. particles, based on a user-defined Boolean expression. This modifier can be inserted into a `Pipeline` to create a selection set, which subsequent modifiers in the pipeline can operate on.

  See also the corresponding user manual page for more information on this modifier. The modifier can select different kinds of data elements depending on the value of its `operate_on` property:

  Operate on | Description
  --- | ---
  `particles` (default) | Selects particles based on a user-defined criterion.
  `bonds` | Selects bonds based on a user-defined criterion.
  `surface_regions` | Selects volumetric regions of a `SurfaceMesh` based on a user-defined criterion.
  `lines` | Selects line vertices of a `Lines` object based on a user-defined criterion.
  `vectors` | Selects vector glyphs of a `Vectors` object based on a user-defined criterion.

  Outputs:

  The modifier sets or updates the value of the `Selection` property of each data element: 1 if the expression evaluates to true for an element; 0 otherwise.

  Global attributes |
  --- | ---
  `ExpressionSelection.count` | The number of data elements (particles/bonds) that have been selected by the modifier.

  Usage example:

  The following code example demonstrates how to select all atoms whose potential energy exceeds a threshold value of -3.6 eV. After executing the pipeline, the number of atoms that got selected may be queried by inspecting the global attribute `ExpressionSelection.count`, which was created by the modifier as summarized output:

      pipeline.modifiers.append(ExpressionSelectionModifier(expression = 'PotentialEnergy > -3.6'))
      data = pipeline.compute()
      print(data.attributes['ExpressionSelection.count'])

  Note that, in many cases, the `ExpressionSelectionModifier` class can be replaced with an equivalent Python modifier function, which creates the selection directly. The example above can be reimplemented without a `ExpressionSelectionModifier` as follows:

      def select_high_energy_atoms(frame, data):
          selection = data.particles['Potential Energy'] > -3.6
          data.particles_.create_property('Selection', data=selection)
      pipeline.modifiers.append(select_high_energy_atoms)

  In this second version, the selection criterion is specified in terms of a native Python expression operating on a NumPy array containing particle property values, which means you are no longer limited to the simple language supported by `ExpressionSelectionModifier`. NumPy expressions allow you to directly and efficiently compute the `Selection` array and thereby create the output selection set. See User-defined modifiers for more information.

  Furthermore, if you just want to count the number of particles that fulfill a certain criterion, it may not even be necessary to create a selection. You can directly use NumPy’s count_nonzero() function to determine the number of particles for which some Boolean expression evaluates to true:

      data = pipeline.compute()
      print(numpy.count_nonzero(data.particles['Potential Energy'] > -3.6))

  property expression: str

    The Boolean expression to be evaluated by the modifier for each data element, formatted as a Python string. The expression syntax is documented in OVITO’s user manual; it is not regular Python syntax. The string’s contents will be parsed by OVITO’s integrated math expression interpreter (muparser).

    Attention

    Keep in mind that the Boolean expression is subject to special syntax rules. The internal expression parser can only handle variable names consisting of alphanumeric characters and underscores. OVITO’s property and attribute names, however, can contain arbitrary characters (except dots). Within a Boolean expression, properties and attributes must thus be referenced by their mangled names, with all spaces removed and other invalid characters replaced by underscores. For example, if the original name of an input property is “c_abc[1] Average”, then it must be referenced as `c_abc_1_Average` in the Boolean expression. Furthermore, if the first character of an identifier happens to be a digit, an extra underscore is prepended to the mangled variable name.

    You can incorporate the values of regular Python variables in the Boolean expression simply by using Python’s string formatting technique, e.g.:

        threshold = float(sys.argv[1])
        pipeline.modifiers.append(ExpressionSelectionModifier(expression = f"ShearStrain>{threshold}"))

    Keep in mind though that the string the modifier uses now contains a constant literal in place of the original Python variable. In case the Python value changes, it thus is necessary to update the expression string after the modifier was inserted into the pipeline. Re-evaluating the data pipeline will recompute the selection, letting you perform several calculations in a for-loop, for example:

        modifier = ExpressionSelectionModifier()
        pipeline.modifiers.append(modifier)
        for threshold in numpy.arange(0.0, 1.0, 0.05):
            modifier.expression = f"ShearStrain>{threshold}"
            data = pipeline.compute()
            print(threshold, data.attributes['ExpressionSelection.count'])

  property operate_on: str

    Selects the kind of data elements this modifier should operate on. One of the following strings:

    > - `'particles'`

    > - `'bonds'`

    > - `'surface_regions'`

    > - `'lines'`

    > - `'vectors'`

    Default:

      `'particles'`

class ovito.modifiers.FindOverlappingParticlesModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.15.0.

  Selects particles that are within a given distance of each other. This selection can be used to subsequently remove particles that are too close to each other, for example after constructing an input structure for a simulation.

  See the corresponding user manual page for more information.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Selection` | The selection state of the input particles (only used if `only_selected` is `True`).

  Outputs:

  Particle properties |
  --- | ---
  `Selection` | The output particle selection.

  Global attributes |
  --- | ---
  `FindOverlappingParticles.count` | The number of particles that were selected by the modifier.

  Changed in version 3.16.0: Renamed from `SelectOverlappingParticlesModifier`

  property keep_one: bool

    When two or more particles are within the `overlap_distance` of each other, this option controls whether the modifier selects all of the particles in the overlap group or excludes one of them from the selection.

    When `keep_one` is `True`, one randomly picked particle from each overlap group will not be selected. Use this mode if the goal is to delete duplicate particles and keep exactly one. You can subsequently apply a `DeleteSelectedModifier` to remove the selected particles from the system.

    If set to `False`, all particles in the overlap group will be selected. Use this mode when the goal is to identify particles that are close to each other.

    Default:

      `True`

  property move_to_mean_position: bool

    If two or more particles are within the `overlap_distance` of each other and this option is `True`, the modifier moves all particles in the overlap group to their mean position (centroid).

    Default:

      `False`

    Added in version 3.16.0.

  property only_selected: bool

    Controls whether the modifier should operate only on currently selected particles. Requires an input selection, which will be replaced by the output selection of overlapping particles.

    Default:

      `False`

  property overlap_distance: float

    Determines the maximum distance up to which particles are considered to be overlapping.

    Default:

      `0.05`

class ovito.modifiers.FindRingsModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.14.0.

  Identifies rings up to a specified maximum size within the bond network of a particle system.

  This modifier requires the input system to contain a `Bonds` object with bond topology. The bond information can be loaded directly from a simulation file or generated using the `CreateBondsModifier`.

  The modifier outputs identified rings as `DataTable` objects, each corresponding to a specific ring size. These tables can be exported to text files using the `export_file()` function or accessed directly from the pipeline output via the `DataCollection.tables` dictionary.

  Additionally, the modifier provides a histogram of ring size distribution as a separate `DataTable`.

  Outputs:

  `DataTable` | Description
  --- | ---
  `ring-size-histogram` | The computed histogram of ring size distribution.
  `N-rings` | Topology information for all rings of size N identified by the modifier.

  Example:

  The following Python script demonstrates how to load a particle system (without bond topology) from a file, create the bond topology using OVITO’s `CreateBondsModifier`, and then find all rings in the size range from 4 to 10.

      from ovito.io import import_file, export_file
      from ovito.modifiers import FindRingsModifier, CreateBondsModifier

      # Set up data pipeline:
      pipeline = import_file("input/Voronoi1.POSCAR.gz")
      pipeline.modifiers.append(CreateBondsModifier(mode=CreateBondsModifier.Mode.VdWRadius))
      pipeline.modifiers.append(FindRingsModifier(maximum_ring_size=10))

      # Export the topology of all rings of size 5 to a text file.
      export_file(pipeline, "output/5_rings_topology.txt", "txt/table", key="5-rings")

      # Convert ring size histogram to a NumPy array and print it to the terminal.
      data = pipeline.compute()
      print(data.tables["ring-size-histogram"].xy())

  property maximum_ring_size: int

    Maximum size of the rings identified by the modifier (inclusive). The maximum ring size must be greater than the minimum ring size and no greater than 36, the maximum ring size supported by the modifier.

    Default:

      `8`

  property minimum_ring_size: int

    Minimum size of the rings identified by the modifier (inclusive). The minimum ring size must be greater than 2.

    Default:

      `4`

  property vis: SurfaceMeshVis

    The `SurfaceMeshVis` element controlling the visual appearance of the generated ring surface mesh in rendered images.

class ovito.modifiers.FreezePropertyModifier

  Base: `ovito.pipeline.Modifier`

  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 (RadialDistributionFunctionModifier, FreezePropertyModifier,
                                  ExpressionSelectionModifier)

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

      # Add modifier for computing the coordination numbers of particles.
      pipeline.modifiers.append(RadialDistributionFunctionModifier(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)
      pipeline.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.
      pipeline.modifiers.append(ExpressionSelectionModifier(expression='Coordination != Coord0'))

      # Write out number of particles exhibiting a change in coordination number.
      export_file(pipeline, 'output/changes.txt', 'txt/attr',
                  columns = ['Timestep', 'ExpressionSelection.count'],
                  multiple_frames = True)

  property destination_property: str

    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: int

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

    Default:

      `0`

  property operate_on: str

    Selects the kind of properties this modifier should operate on. Supported values are: `'particles'`, `'bonds'`, `'voxels'`.

    Default:

      `'particles'`

  property select_new: bool

    If set to `True`, the modifier will select any newly appearing particles at the current timestep that were not present in the initial configuration. These newly occurring particles won’t have any frozen property values, because they don’t have any counterparts in the initial configuration to copy from.

    This option is useful in conjunction with the `tolerate_new` option, which tells the modifier to accept the appearance of elements with new identities. It is typically employed for non-conservative simulations, where particles are created or deleted during the simulation.

    Default:

      `False`

    Added in version 3.13.0.

  property source_property: str

    The name of the input property that should be evaluated by the modifier on the animation frame specified by `freeze_at`.

  property tolerate_new: bool

    Determines whether newly appearing particles in the current configuration that were not yet present in the frozen configuration are acceptable or not.

    If set to `False`, the modifier will throw an error if the current timestep contains previously unknown particles that were not present at the time the property was frozen. This is the default behavior, which prevents situations where some of the particles do not have counterparts in the initial configuration.

    If set to `True`, the modifier will ignore the appearance of new particles and only copy the property values of the elements that were already present at the time of freezing. Newly appearing particles, e.g. when new particles are created during the course of the simulation, will either maintain their current property values (if the `destination_property` already exists or is identical to `source_property`) or be initialized to some default value (if the `destination_property` is new).

    Attention

    This option is useful if you want to freeze a property in a system with varying particle numbers, e.g. in a simulation with creation and deletion of particles. But keep in mind that, after application of this modifier, some of the particles will have frozen property values while others will not – depending on whether they were already present in the initial configuration or not.

    You can additionally activate `select_new` to let the modifier select any newly appearing particles. This gives you the option to visualize the newly created particles in a different way, e.g. by coloring them differently.

    Default:

      `False`

    Added in version 3.13.0.

class ovito.modifiers.GenerateTrajectoryLinesModifier

  Base: `ovito.pipeline.Modifier`

  This modifier periodically samples the time-dependent positions of the particles to produce a `Lines` object. The modifier is typically used to visualize the paths of motion of particles as continuous curves. See the corresponding user manual page for more information.

      from ovito.io import import_file
      from ovito.modifiers import GenerateTrajectoryLinesModifier

      # Load a particle simulation sequence:
      pipeline = import_file("input/simulation.*.dump")

      # Insert the modifier into the pipeline for creating the trajectory lines.
      # It will automatically sample the particle positions over the entire animation interval.
      modifier = GenerateTrajectoryLinesModifier(only_selected=False)
      pipeline.modifiers.append(modifier)

      # Configure trajectory line visualization:
      modifier.vis.width = 0.4
      modifier.vis.color = (1, 0, 0)
      modifier.vis.flat_shading = False

      # Insert pipeline into the scene to make the particles and
      # the trajectory lines visible in rendered images.
      pipeline.add_to_scene()

  property frame_interval: tuple[int, int] | None

    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`

  property only_selected: bool

    Controls whether or not trajectory lines are generated only for selected particles. If this option is enabled, trajectory lines will be generated only for the subset of particles that are selected in the initial frame of the trajectory sequence, i.e., at the beginning of the `frame_interval`. If disabled, trajectory lines are generated for all particles.

    Default:

      `True`

  property sample_particle_property: str

    Name of the particle property to sample along the generated trajectory lines.

    This option transfers the specified particle property to the trajectory line vertices. In other words, the time-dependent input property of the particles becomes a position-dependent property of the generated trajectory lines. The sampled values will become available in the `Lines` object and may subsequently be used for pseudo-coloring of the trajectory lines. See the `LinesVis.color_mapping_property` option.

    The following code example demonstrates how to color trajectory lines based on the velocity magnitude of the particles at the corresponding simulation times:

        from ovito.io import *
        from ovito.modifiers import *
        from ovito.vis import *
        import numpy

        # Import an MD simulation trajectory. The snapshots stored in the trajectory file contain the instantaneous
        # particle velocities (vector property "Velocity") at each timestep and OVITO automatically
        # computes the scalar velocities (particle property "Velocity Magnitude") during file import.
        pipeline = import_file("../../../tests/files/data/GSD/trajectory.gsd")

        # Turn off the display of particles.
        pipeline.compute().particles.vis.enabled = False

        # Configure modifier:
        modifier = GenerateTrajectoryLinesModifier(only_selected=False)
        modifier.sample_particle_property = "Velocity Magnitude"
        # Configure trajectory line display:
        modifier.vis.width = 0.1
        modifier.vis.flat_shading = False

        # Locally color the trajectory lines based on the 'Velocity Magnitude' property, which was transferred
        # from the particles to the trajectory line vertices.
        modifier.vis.color_mapping_property = "Velocity Magnitude"

        # Insert modifier into the pipeline to generate the trajectory lines.
        pipeline.modifiers.append(modifier)

        # To determine the correct min/max value range for pseudo-coloring, we need to access the
        # array of property values associated with the generated trajectory lines:
        trajectories = pipeline.compute().lines["trajectories"]

        # Now we can set the min/max value range for the color mapping.
        # Note that this change to the visual element does NOT trigger a re-evaluation of the modifier.
        modifier.vis.color_mapping_interval = (
            numpy.min(trajectories["Velocity Magnitude"]),
            numpy.max(trajectories["Velocity Magnitude"]),
        )

        # Insert pipeline into the scene to make the trajectory lines visible in rendered images.
        pipeline.add_to_scene()

    Default:

      `''`

  property sampling_frequency: int

    Length of the animation frame intervals at which the particle positions should be sampled.

    Default:

      `1`

  property unwrap_trajectories: bool

    Controls whether or not trajectory lines should be automatically unwrapped at the box boundaries when the particles cross a periodic boundary.

    Default:

      `True`

  property vis: LinesVis

    The `LinesVis` element controlling the visual appearance of the trajectory lines created by this modifier.

class ovito.modifiers.GrainSegmentationModifier

  Base: `ovito.pipeline.Modifier`

  This analysis modifier identifies the individual grains in a polycrystalline microstructure. See the corresponding user manual page for more information on this modifier.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Structure Type` | The local structure types computed by the `PolyhedralTemplateMatchingModifier`.
  `Orientation` | The local lattice orientations computed by the `PolyhedralTemplateMatchingModifier`.

  Outputs:

  Particle properties |
  --- | ---
  `Grain` | The numeric identifier of the grain a particle has been assigned to by the algorithm.
  `Color` | A per-particle color representing either the grain (if `color_particles` is `True`) or the identified PTM structure type.

  Global attributes |
  --- | ---
  `GrainSegmentation.grain_count` | Number of grains that have been found by the algorithm.

  `DataTable` |
  --- | ---
  `grains` | A data table containing the list of grains found by the algorithm. It consists of several data columns, each being a separate `Property` object: `Grain Identifier`: The numeric ID of each identified grain (1-based). `Grain Size`: The number of atoms in each grain. `Color`: The random display color assigned to each grain. `Structure Type`: The crystal phase of each grain. `Orientation`: The mean lattice orientation of each grain, expressed as a quaternion [X, Y, Z, W]. `Center of Mass`: The XYZ coordinates of the center of mass of each grain. Grains straddling a periodic cell boundary are unwrapped before the center is computed. Atomic masses are used as weights if the `Mass` particle property or per-type masses are present, otherwise all atoms are weighted equally. `Radius`: The radius of the smallest sphere around the center of mass enclosing the whole grain, in simulation units of length. `Radius of Gyration`: The radius of gyration of each grain, in simulation units of length. It is computed from the same unwrapped coordinates and mass weights as the center of mass.
  `grains-merge` | A scatter plot of the ordered cluster merge steps computed by the grain segmentation algorithm.

  property algorithm: GrainSegmentationModifier.Algorithm

    Selects the cluster merge algorithm to use. One of the following constants:

    > - `GrainSegmentationModifier.Algorithm.GraphClusteringAuto`

    > - `GrainSegmentationModifier.Algorithm.GraphClusteringManual`

    > - `GrainSegmentationModifier.Algorithm.MinimumSpanningTree`

    Default:

      `GrainSegmentationModifier.Algorithm.GraphClusteringAuto`

  property color_particles: bool

    Controls whether the modifier colors atoms according to the grains they have been assigned to.

    Default:

      `True`

  property handle_stacking_faults: bool

    Controls whether the algorithm should handle stacking faults and coherent twin boundaries explicitly. If turned off, atoms with cubic and hexagonal crystal structure will simply be treated as separate phases and will never be merged into the same grain.

    Default:

      `True`

  property merging_threshold: float

    Specifies the maximum graph edge contraction distance and determines the resulting number and sizes of grains. A lower threshold produces more (and smaller) grains; a larger threshold produces fewer (and larger) grains.

    This parameter is ignored if `algorithm` is `GraphClusteringAuto`, in which case the merging threshold is automatically determined by the algorithm to give optimal segmentation results.

    Default:

      `0.0`

  property min_grain_size: int

    Minimum number of atoms in a grain. Crystallite clusters smaller than this threshold get dissolved during the grain segmentation and their atoms are merged into neighboring grains.

    Default:

      `100`

  property orphan_adoption: bool

    Controls the merging of non-crystalline atoms (e.g. grain boundary atoms) into adjacent grains.

    Default:

      `True`

class ovito.modifiers.HistogramModifier

  Base: `ovito.pipeline.Modifier`

  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 to `True`. In this case the range of the histogram is controlled by the `xrange_start` and `xrange_end` parameters.

  Example:

      from ovito.modifiers import 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/table", key="histogram[peatom]")

  property bin_count: int

    The number of histogram bins.

    Default:

      `200`

  property fix_xrange: bool

    Controls how the value range of the histogram is determined. If set to `False`, the interval and bin widths are chosen automatically by the modifier to include all input values. If set to `True`, the histogram’s value range may be specified explicitly by setting `xrange_start` and `xrange_end`.

    Default:

      `False`

  property normalization: HistogramModifier.NormalizationMode

    Selects how the histogram’s bin values are normalized. One of the following constants:

    > - `HistogramModifier.NormalizationMode.AbsoluteCount`: The integer number of samples in each bin

    > - `HistogramModifier.NormalizationMode.RelativeFrequency`: Bin count divided by total number of samples

    > - `HistogramModifier.NormalizationMode.ProbabilityDensity`: Bin count divided by total number of samples times the bin width

    Default:

      `HistogramModifier.NormalizationMode.AbsoluteCount`

    Added in version 3.13.0.

  property only_selected: bool

    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 input particles/bonds.

    Default:

      `False`

  property operate_on: str

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

    Default:

      `'particles'`

  property property: str

    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 select_elements: bool

    Lets the modifier create a selection containing all elements whose property values are in the range [`selection_start`, `selection_end`].

    Default:

      `False`

    Added in version 3.11.0.

  property selection_end: float

    Upper bound of the selection interval if the `select_elements` option is turned on.

    Default:

      `0.0`

    Added in version 3.11.0.

  property selection_start: float

    Lower bound of the selection interval if the `select_elements` option is turned on.

    Default:

      `0.0`

    Added in version 3.11.0.

  property xrange_end: float

    If `fix_xrange` is true, then this parameter controls the upper end of the value interval covered by the histogram. Input values higher than this range limit will be discarded from the computed histogram.

    Default:

      `0.0`

  property xrange_start: float

    If `fix_xrange` is true, then this parameter controls the lower end of the value interval covered by the histogram. Input values lower than this range limit will be discarded from the computed histogram.

    Default:

      `0.0`

class ovito.modifiers.IdentifyDiamondModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  Analyzes the local neighborhood of each particle to identify cubic or hexagonal diamond lattices. See the corresponding user manual page for more information.

  Note that this class inherits several important parameter fields from its `StructureIdentificationModifier` base class.

  Modifier inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is `True`.

  Modifier outputs:

  Particle properties |
  --- | ---
  `Structure Type` | The structure type computed by the algorithm for each particle, encoded as an integer value:
  Numeric id | 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` | Particle coloring to indicate the identified structure type for each particle; only if `color_by_type` is `True`. See the `structures` array on how to customize the colors.

  Global attributes |
  --- | ---
  `IdentifyDiamond.counts.OTHER` | Number of particles not matching any of the recognized 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.

  Data tables |
  --- | ---
  `structures` | A bar chart with the particle counts for each structure type identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.

class ovito.modifiers.IdentifyFCCPlanarFaultsModifier

  Base: `ovito.pipeline.ModifierInterface`

  This Python-based modifier identifies different planar defect types in face-centered cubic (fcc) crystals such as stacking faults and coherent twin boundaries. All of these planar defects have in common that they are made of hcp-like atoms arranged in {111} planes of the fcc crystal. See also the corresponding user manual page for more information.

  The identification algorithm relies on intermediate results provided by the `PolyhedralTemplateMatchingModifier`, which must be inserted into the data pipeline first to identify all hcp-like defect atoms in the fcc crystal:

      from ovito.modifiers import PolyhedralTemplateMatchingModifier, IdentifyFCCPlanarFaultsModifier
      pipeline.modifiers.append(PolyhedralTemplateMatchingModifier(output_orientation=True, output_interatomic_distance=True))
      pipeline.modifiers.append(IdentifyFCCPlanarFaultsModifier())

  The modifier subsequently analyzes the neighborhood of each hcp-like atom to identify which kind of planar fault it is part of. Each atom in the input system is attributed to one of the following classes:

  > - 0 = Non-hcp structure (e.g. perfect fcc)

  > - 1 = Indeterminate hcp-like (e.g. isolated hcp-like atoms, not a planar defect)

  > - 2 = Intrinsic stacking fault (two hcp-like layers)

  > - 3 = Coherent twin boundary (one hcp-like layer)

  > - 4 = Multilayer stacking fault (three or more hcp-like layers)

  The modifier writes the corresponding numeric values to the `Planar Fault Type` output particle property. Furthermore, the modifier produces a `DataTable` which lists the total atom count and estimated total area for each planar defect type. This information can be accessed as follows:

      data = pipeline.compute()
      table = data.tables['planar_faults']
      num_atoms_isf  = table['Atom Count'][IdentifyFCCPlanarFaultsModifier.Types.ISF]
      num_atoms_twin = table['Atom Count'][IdentifyFCCPlanarFaultsModifier.Types.TWIN]
      area_isf       = table['Estimated Area'][IdentifyFCCPlanarFaultsModifier.Types.ISF]
      area_twin      = table['Estimated Area'][IdentifyFCCPlanarFaultsModifier.Types.TWIN]

  Added in version 3.8.0.

  class Types(*values)

    The possible classifications for hcp-like defect atoms.

    ISF

      Intrinsic stacking fault

    MULTI

      Multilayer stacking fault

    NONHCP

      Non-hcp structure

    OTHER

      Indeterminate hcp-like

    TWIN

      Coherent twin boundary

  color_isf: tuple[float, float, float]

    Color value to be assigned to all hcp-like atoms that are part of an intrinsic stacking fault (`Types.ISF`).

    Default:

      `(0.9, 0.7, 0.2)`

  color_multi: tuple[float, float, float]

    Color value to be assigned to all hcp-like atoms that are part of a multi-layer stacking fault (`Types.MULTI`).

    Default:

      `(0.0, 1.0, 0.9)`

  color_other: tuple[float, float, float]

    Color value to be assigned to all hcp-like atoms that are not part of an identified planar fault (`Types.OTHER`).

    Default:

      `(1.0, 0.4, 0.4)`

  color_twin: tuple[float, float, float]

    Color value to be assigned to all hcp-like atoms that are part of a coherent twin boundary (`Types.TWIN`).

    Default:

      `(0.4, 0.4, 1.0)`

class ovito.modifiers.InvertSelectionModifier

  Base: `ovito.pipeline.Modifier`

  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: str

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

    Default:

      `'particles'`

class ovito.modifiers.LoadTrajectoryModifier

  Base: `ovito.pipeline.Modifier`

  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 the `LoadTrajectoryModifier` to the topology dataset, which loads the trajectory file. The modifier will replace the static atom positions from the topology dataset with the time-dependent positions from the trajectory file.

  Example:

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

      # Load static topology data from a LAMMPS data file.
      pipeline = import_file('input/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)

  Furthermore, it is possible to let the modifier load varying bond topologies for each trajectory frame from a LAMMPS dump local file:

      bonds_mod = LoadTrajectoryModifier()
      bonds_mod.source.load('input/bonds.dump.local',
          columns = [None, 'Bond Type', 'Particle Identifiers.1', 'Particle Identifiers.2', 'Length', 'Energy'])
      pipeline.modifiers.append(bonds_mod)

  Here, the `columns` function parameter specifies the mapping of data columns in the imported dump file to corresponding target bond properties within OVITO. The dump local file `bonds.dump.local` contains six data columns and has been produced by the following LAMMPS commands:

      compute 1 all property/local btype batom1 batom2
      compute 2 all bond/local dist engpot
      dump bonds all local 100 bonds.dump.local index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]

  property source: FileSource

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

class ovito.modifiers.PolyhedralTemplateMatchingModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  This modifier analyzes the local neighborhood of each particle to identify common structural motifs and crystalline structures. The structure identification is based on the Polyhedral Template Matching (PTM) algorithm. See the corresponding user manual page for more information. The PTM algorithm is able to compute local crystal orientations, elastic lattice strains, and can identify local chemical orderings in binary compounds.

  Note that this modifier inherits several important parameter fields from the `StructureIdentificationModifier` base class.

  Modifier inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Particle Type` | The chemical types of the input particles; only used if `output_ordering` is `True`.
  `Selection` | The selection state of the input particles; only used if `only_selected` is `True`.

  Modifier outputs:

  Particle properties |
  --- | ---
  `Structure Type` | The structure type computed by the algorithm for each particle, encoded as an integer value:
  Numeric id | Python constant | Initial state
  --- | --- | ---
  0 | `PolyhedralTemplateMatchingModifier.Type.OTHER` |
  1 | `PolyhedralTemplateMatchingModifier.Type.FCC` | enabled
  2 | `PolyhedralTemplateMatchingModifier.Type.HCP` | enabled
  3 | `PolyhedralTemplateMatchingModifier.Type.BCC` | enabled
  4 | `PolyhedralTemplateMatchingModifier.Type.ICO` | disabled
  5 | `PolyhedralTemplateMatchingModifier.Type.SC` | disabled
  6 | `PolyhedralTemplateMatchingModifier.Type.CUBIC_DIAMOND` | disabled
  7 | `PolyhedralTemplateMatchingModifier.Type.HEX_DIAMOND` | disabled
  8 | `PolyhedralTemplateMatchingModifier.Type.GRAPHENE` | disabled
  The algorithm only identifies enabled structure types; see `structures` array for details.
  `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.
  Numeric id | 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` | Particle coloring to indicate the identified structure type for each particle; only if `color_by_type` is `True`. See the `structures` array on how to customize the colors.

  Global attributes |
  --- | ---
  `PolyhedralTemplateMatching.counts.OTHER` | Number of particles not matching any of the recognized 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.
  `PolyhedralTemplateMatching.counts.GRAPHENE` | Number of particles identified as 2d graphene structure.

  `PolyhedralTemplateMatching.ordering_counts.NONE` | Number of particles not matching any of the recognized chemical ordering types.
  `PolyhedralTemplateMatching.ordering_counts.PURE` | Number of particles with pure chemical ordering (i.e. all neighbors have the same chemical type as the central particle).
  `PolyhedralTemplateMatching.ordering_counts.L10` | Number of particles with L10 chemical ordering.
  `PolyhedralTemplateMatching.ordering_counts.L12_A` | Number of particles with L12 (A site) chemical ordering.
  `PolyhedralTemplateMatching.ordering_counts.L12_B` | Number of particles with L12 (B site) chemical ordering.
  `PolyhedralTemplateMatching.ordering_counts.B2` | Number of particles with B2 chemical ordering.
  `PolyhedralTemplateMatching.ordering_counts.ZINCBLENDE_WURTZITE` | Number of particles with zincblende/wurtzite-like chemical ordering.
  `PolyhedralTemplateMatching.ordering_counts.BORON_NITRIDE` | Number of particles with boron nitride-like chemical ordering.

  Data tables |
  --- | ---
  `structures` | A bar chart with the particle counts for each structure type identified by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.
  `ptm-rmsd` | A histogram with the RMSD value distribution computed by the modifier. You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.
  `chemical-ordering` | A bar chart with the particle counts for each chemical ordering type identified by the modifier (only if `output_ordering` is set to `True`). You can retrieve this `DataTable` from the `DataCollection.tables` dictionary.

  static calculate_misorientation(a: ArrayLike, b: ArrayLike, symmetry: str = 'none', output: str = 'angle') → NDArray[float64]

    Helper function for computing the misorientation or disorientation of a pair of crystal orientations in 3d space. The misorientation is defined as the 3d rotation mapping crystal orientation a to orientation b – without taking into account lattice symmetries. The disorientation is obtained by subsequently mapping the misorientation into the fundamental zone, i.e., minimizing the rotation angle by considering all equivalent orientations due to lattice symmetry.

    Orientations a and b must both be specified as quaternions of the form \((x,y,z,w)\), i.e., as arrays of size 4. `PolyhedralTemplateMatchingModifier` outputs the local lattice orientations of crystalline atoms in this form (see `output_orientation`) and `GrainSegmentationModifier` calculates the mean lattice orientation of each grain in this form for a polycrystal.

    The parameter output controls whether the function should return just the scalar angle of rotation (in radians) or the full 3d crystal rotation (as a quaternion).

    Parameters:

      - a – First crystal orientation in the form of a 4-component quaternion.

      - b – Second crystal orientation in the form of a 4-component quaternion.

      - symmetry –

        Selects between misorientation and disorientation calculation:

        - `'none'`: Calculate misorientation (ignore lattice symmetry).

        - `'cubic'`: Calculate disorientation for lattices with cubic symmetry (e.g. fcc, bcc, diamond).

        - `'hexagonal'`: Calculate disorientation for lattices with hexagonal symmetry (e.g. hcp, hex-diamond, graphene).

      - output –

        Controls the type of output value returned by the function:

        - `'angle'`: Return scalar misorientation/disorientation angle in radians.

        - `'rotation'`: Return 3d rotation from a to b expressed as quaternion.

    Parameters a and b may both be arrays of shape (N,4) specifying two orientation lists of the same length N. In this case the function will compute the list of N pair-wise misorientations in one go, which is usually much faster than calling the function in a loop.

    Usage example:

        pipeline.modifiers.append(PolyhedralTemplateMatchingModifier(output_orientation=True))
        pipeline.modifiers.append(GrainSegmentationModifier())
        data = pipeline.compute()

        # Assuming the input structure is an fcc bicrystal consisting of exactly two grains.
        assert data.attributes['GrainSegmentation.grain_count'] == 2
        grain_orientations = data.tables['grains']['Orientation']

        # Calculate the disorientation angle between the two bicrystal grains.
        disorientation_angle = PolyhedralTemplateMatchingModifier.calculate_misorientation(
            grain_orientations[0], grain_orientations[1],
            symmetry='cubic')

    Added in version 3.7.10.

  property output_deformation_gradient: bool

    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 respect to an ideal reference lattice configuration. See the OVITO user manual for details.

    Default:

      `False`

  property output_interatomic_distance: bool

    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: bool

    Boolean flag that controls whether the modifier should identify local chemical ordering types and output them as a new particle property named `Ordering Type`.

    Default:

      `False`

  property output_orientation: bool

    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 respect to a reference lattice orientation. See the OVITO user manual for details.

    Default:

      `False`

  property output_rmsd: bool

    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: float

    The maximum allowed root mean square deviation for positive structure matches. If 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`

class ovito.modifiers.PythonModifier

  Base: `ovito.pipeline.Modifier`

  This is a wrapper for user-defined Python modifiers, which allows inserting them into a `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. Please see the User-defined modifiers section.

  Example using the simple programming interface:

      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 PythonModifier instance and appending it:
      #
      #   pipeline.modifiers.append(PythonModifier(function=assign_color))

      # Evaluate data pipeline. This will make the system invoke assign_color().
      data = pipeline.compute()
      print(data.particles.colors[...])

  Example using the advanced programming interface:

      from ovito.io import import_file
      from ovito.pipeline import ModifierInterface

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

      # Define our custom modifier class, which assigns a uniform color
      # to all particles, similar to the built-in AssignColorModifier.
      class AssignColor(ModifierInterface):

          def modify(self, data, **kwargs):
              color_property = data.particles_.create_property('Color')
              color_property[:] = (0.2, 0.5, 1.0)

      # Insert the user-defined modifier into the data pipeline.
      pipeline.modifiers.append(AssignColor())
      # Note that appending an instance of your class to the pipeline is equivalent to
      # wrapping it in a PythonModifier instance:
      #
      #   pipeline.modifiers.append(PythonModifier(delegate=AssignColor()))

      # Evaluate data pipeline. This will make the system invoke AssignColor.modify().
      data = pipeline.compute()
      print(data.particles.colors[...])

  property delegate: ModifierInterface | None

    A `ModifierInterface` object implementing the logic of the user-defined modifier. This field is only used if the user-defined modifier is implemented using the advanced programming interface.

    Default:

      `None`

  property function: Callable[[int, DataCollection], Any] | None

    The Python function to be called each time the data pipeline is evaluated by the system. This field is only used if the user-defined modifier is implemented using the simple programming interface.

    The function must have a particular signature as shown in the first 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 to modify the data collection and the data objects stored in it.

    Default:

      `None`

  property working_dir: str

    A path that will be set as active working directory while the Python modifier function is executed by the pipeline system. This setting mainly plays a role if the modifier function is used within the GUI of OVITO and if it performs some file I/O. Relative file paths will then get resolved with respect to this working directory.

    If no specific working directory is set for the modifier function, the application’s current working directory will be used.

    Default:

      `''`

class ovito.modifiers.RadialDistributionFunctionModifier

  Base: `ovito.pipeline.Modifier`

  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:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Particle Type` | Required if `partial` is set to `True`.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is set to `True`.

  Outputs:

  Particle properties |
  --- | ---
  `Coordination` | The number of neighbors of each particle.
  `Per Type Coordination` | The number of neighbors of each particle, grouped by particle type. This property is only computed if `partial` is set to `True`.

  `DataTable` |
  --- | ---
  `coordination-rdf` | The RDF computed by the modifier. You can retrieve the RDF data through the `tables` dictionary of the output `DataCollection` under the lookup key `"coordination-rdf"`, see the code examples below.

  Examples:

  The following Python program 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 RadialDistributionFunctionModifier

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

      # Print the computed g(r) function values.
      print(data.tables['coordination-rdf'].xy())

  The following code demonstrates how to use the `TimeAveragingModifier` to compute the RDF for every frame of an MD simulation and generate a time-averaged RDF histogram. Finally, the RDF histogram is written to an output file.

      from ovito.io import import_file, export_file
      from ovito.modifiers import RadialDistributionFunctionModifier, TimeAveragingModifier
      import numpy

      # Load a simulation trajectory consisting of several frames:
      pipeline = import_file("input/simulation.dump")
      print("Number of MD frames:", pipeline.num_frames)

      # Insert the RDF calculation modifier into the pipeline:
      pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff = 5.0, number_of_bins = 200))

      # Insert the time-averaging modifier into the pipeline, which accumulates
      # the instantaneous DataTable produced by the previous modifier and computes a mean histogram.
      pipeline.modifiers.append(TimeAveragingModifier(operate_on='table:coordination-rdf'))

      # Data export method 1: Convert to NumPy array and write data to a text file:
      total_rdf = pipeline.compute().tables['coordination-rdf[average]'].xy()
      numpy.savetxt("output/rdf.txt", total_rdf)

      # Data export method 2: Use OVITO's own export function for DataTable objects:
      export_file(pipeline, "output/rdf.txt", "txt/table", key="coordination-rdf[average]")

  property cutoff: float

    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: int

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

    Default:

      `200`

  property only_selected: bool

    Restricts the calculation to currently selected particles. Unselected particles will be treated as if they did not exist and their `Coordination` value is set to zero when this option is enabled.

    Default:

      `False`

  property partial: bool

    This modifier option requests the calculation of element-specific (partial) RDFs. The resulting RDF table will contain one tabulated g(r) function for each pair-wise combination of particle types in the input. By default, the modifier uses the `Particle Type` property for type classification, but you can specify a different typed property by setting `type_property`. This code example demonstrates how to access the partial RDFs computed by the modifier:

        from ovito.io import import_file
        from ovito.modifiers import RadialDistributionFunctionModifier

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

        # Print the list of input particle types.
        # They are represented by ParticleType objects attached to the 'Particle Type' particle property.
        for t in pipeline.compute().particles.particle_types.types:
            print(f"Type {t.id}: {t.name}")

        # Calculate partial RDFs:
        pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff=5.0, number_of_bins=100, partial=True))

        # Access the output DataTable:
        rdf_table = pipeline.compute().tables['coordination-rdf']

        # The y-property of the data points of the DataTable is now a vectorial property.
        # Each vector component represents one partial RDF.
        rdf_names = rdf_table.y.component_names

        # Print a list of partial g(r) functions.
        for component, name in enumerate(rdf_names):
            print("g(r) for pair-wise type combination %s:" % name)
            print(rdf_table.y[:,component])

        # The DataTable.xy() method yields everything as one combined NumPy table.
        # This includes the 'r' values in the first array column, followed by the
        # tabulated g(r) partial functions in the remaining columns.
        print(rdf_table.xy())

    Default:

      `False`

  property type_property: str

    Selects the particle property that is used as the source for type classification when computing partial RDFs. This property must be a typed property with defined element types, e.g., `Structure Type`.

    Default:

      `'Particle Type'`

    Added in version 3.14.0.

class ovito.modifiers.ReducePropertyModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.14.0.

  This modifier reduces a selected data property to a single value by applying a specified reduction operation over all data elements. For example, the modifier allows computing the mean value of a property across all particles. See the user manual for more details.

  This modifier supports processing elements from the following kinds of containers. You select the input container by setting the `operate_on` parameter to the corresponding string.

  Property container type | Value of `operate_on`
  --- | ---
  `Particles` | `"particles"` (default)
  `Bonds` | `"bonds"`
  `SurfaceMesh.vertices` | `"vertices:<MESH_ID>/vertices"`
  `SurfaceMesh.faces` | `"faces:<MESH_ID>/faces"`
  `SurfaceMesh.regions` | `"regions:<MESH_ID>/regions"`
  `VoxelGrid` | `"voxels:<GRID_ID>"`
  `DataTable` | `"table:<TABLE_ID>"`
  `Lines` | `"lines:<LINES_ID>"`
  `Vectors` | `"vectors:<VECTORS_ID>"`

  Placeholders such as `<MESH_ID>` in the `operate_on` string must be replaced with the unique `identifier` of the data object to be processed by the modifier.

  The modifier supports the following reduction operations. You select an operation by setting the `reduction_operation` parameter to the corresponding enum value.

  Reduction operation | Python enum | Description
  --- | --- | ---
  Minimum | `ReducePropertyModifier.Operation.Min` | Lowest value
  Maximum | `ReducePropertyModifier.Operation.Max` | Highest value
  Sum | `ReducePropertyModifier.Operation.Sum` | Sum of all values
  Non-zero count | `ReducePropertyModifier.Operation.Nonzero` | Number of elements with non-zero values
  Mean | `ReducePropertyModifier.Operation.Mean` (default) | Arithmetic mean
  Median | `ReducePropertyModifier.Operation.Median` | Median value
  Variance | `ReducePropertyModifier.Operation.Variance` | Sample variance
  Standard deviation | `ReducePropertyModifier.Operation.StdDev` | Sample standard deviation
  Argmin | `ReducePropertyModifier.Operation.ArgMin` | Zero-based index of the lowest value
  Argmax | `ReducePropertyModifier.Operation.ArgMax` | Zero-based index of the highest value

  Finally, you must specify the input property to be processed by the modifier by setting the `property` parameter. If the property has multiple components, e.g., the XYZ components of the particle coordinates, you can either specify no vector component (e.g., just `'Position'`) to apply the operation to all components individually or specify a particular component (e.g., `'Position.X'`) to apply the operation only to that component.

  By default, the modifier operates on some property of the particles. You can change this behavior by setting the `operate_on` attribute. This is shown in the following code snippet, which determines the length of the shortest bond in the system:

      pipeline = import_file("input/1AKI.gro", generate_bonds=True)
      # First, compute the length of each bond:
      pipeline.modifiers.append(ComputePropertyModifier(
              operate_on='bonds',
              expressions='BondLength',
              output_property='Length'))
      # Then, let the ReducePropertyModifier find the shortest bond.
      pipeline.modifiers.append(ReducePropertyModifier(
              operate_on="bonds",
              property="Length",
              reduction_operation=ReducePropertyModifier.Operation.Min))
      data = pipeline.compute()
      print(f"Shortest bond length: {data.attributes['ReduceProperty.particles.bonds.Min.Length']}")

  When the pipeline is computed, the modifier stores the results in the `DataCollection.attributes` dictionary as a global attribute. The attribute names have the following format:

  > `ReduceProperty.[<PARENT>.]<CONTAINER>.<OPERATION>.<PROPERTY_NAME>[.<COMPONENT>]`

  For example:

  Modifier configuration | Output attribute name
  --- | ---
      operate_on="bonds"
      property="Length"
      reduction_operation=ReduceProperty.Operation.Min
  | `ReduceProperty.particles.bonds.Min.Length`
      operate_on="table:clusters"
      property="Cluster Size"
      reduction_operation=ReduceProperty.Operation.Variance
  | `ReduceProperty.clusters.Variance.Cluster Size`
      operate_on="regions:voronoi-polyhedra/regions"
      property="Surface Area"
      reduction_operation=ReduceProperty.Operation.ArgMax
  | `ReduceProperty.voronoi-polyhedra.regions.ArgMax.Surface Area`

  The `.<COMPONENT>` part is included only if the input property has multiple vector components, as shown in this example:

      pipeline = import_file("input/nylon.data", atom_style="full")
      # Compute per-particle momentum vectors:
      pipeline.modifiers.append(ComputePropertyModifier(
          output_property = 'Momentum',
          expressions = {'X': 'Velocity.X * Mass', 'Y': 'Velocity.Y * Mass', 'Z': 'Velocity.Z * Mass'}))
      # Compute sum of particle momentum vectors:
      pipeline.modifiers.append(
          ReducePropertyModifier(
              property = "Momentum",
              reduction_operation = ReducePropertyModifier.Operation.Sum,
          )
      )
      # Evaluate pipeline:
      data = pipeline.compute()
      # Access the computed results:
      total_momentum = (
          data.attributes["ReduceProperty.particles.Sum.Momentum.X"],
          data.attributes["ReduceProperty.particles.Sum.Momentum.Y"],
          data.attributes["ReduceProperty.particles.Sum.Momentum.Z"]
      )

  property only_selected: bool

    If set to `True`, the modifier will operate only on currently selected elements. You can use this to restrict the calculation to a subset of input particles, for example.

    Default:

      `False`

  property operate_on: str

    Selects the kind of data elements this modifier will operate on. Supported values are:

    > - `'particles'` - to operate on a property in a `Particles` container

    > - `'bonds'` - to operate on a property in a `Bonds` container

    > - `'vertices:<ID>/vertices'` - to operate on a property in a `SurfaceMesh.vertices` container

    > - `'faces:<ID>/faces'` - to operate on a property in a `SurfaceMesh.faces` container

    > - `'regions:<ID>/regions'` - to operate on a property in a `SurfaceMesh.regions` container

    > - `'voxels:<ID>'` - to operate on a property in a `VoxelGrid` container

    > - `'tables:<ID>'` - to operate on a property in a `DataTable` container

    > - `'lines:<ID>'` - to add a property to a `Lines` container

    > - `'vectors:<ID>'` - to add a property to a `Vectors` container

    In these strings, the placeholder `<ID>` refers to the `identifier` of the container object to be processed by the modifier.

    Default:

      `'particles'`

  property property: str

    The name of the input property to which the reduction operation is applied. The property can be a scalar or vector property.

    For vector properties, a component name can be appended, e.g. `"Velocity.X"`, to restrict the operation to that particular component.

    Default:

      `''`

  property reduction_operation: ReducePropertyModifier.Operation

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

    > - `ReducePropertyModifier.Operation.Min` - Lowest value

    > - `ReducePropertyModifier.Operation.Max` - Highest value

    > - `ReducePropertyModifier.Operation.Sum` - Sum of all values

    > - `ReducePropertyModifier.Operation.Nonzero` - Number of elements with non-zero values

    > - `ReducePropertyModifier.Operation.Mean` - Arithmetic mean

    > - `ReducePropertyModifier.Operation.Median` - Median value

    > - `ReducePropertyModifier.Operation.Variance` - Sample variance

    > - `ReducePropertyModifier.Operation.StdDev` - Sample standard deviation

    > - `ReducePropertyModifier.Operation.ArgMin` - Zero-based index of the minimum value

    > - `ReducePropertyModifier.Operation.ArgMax` - Zero-based index of the maximum value

    The operation `Variance` computes the sample variance of the input values and behaves equivalent to `numpy.var()` with ddof=1 and axis=0.

    The operation `StdDev` computes the sample standard deviation of the input values and behaves equivalent to `numpy.std()` with ddof=1 and axis=0.

    Default:

      `ReducePropertyModifier.Operation.Mean`

class ovito.modifiers.RemovePropertyModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.16.0.

  The modifier removes one or more properties from a `ovito.data.PropertyContainer`. You specify the container by setting the `operate_on` parameter to an object identifier string. See `ReducePropertyModifier` for a detailed description of the `operate_on` parameter format.

  After specifying the container the modifier should operate on, you must set `properties` to a list of property names that should be removed from the container by the modifier.

  The modifier can only remove entire properties, but not individual components of a vector property.

  property operate_on: str

    Selects the kind of data elements this modifier will operate on. See `ReducePropertyModifier` for a detailed description of the `operate_on` parameter and what string values it can take.

    Default:

      `'particles'`

  property properties: str | Sequence[str]

    The name or the names of properties to be removed from the property container.

    Default:

      `()`

class ovito.modifiers.RenderLAMMPSRegionsModifier

  Base: `ovito.pipeline.ModifierInterface`

  This Python-based modifier allows visualizing spatial regions with different 3d geometries as defined by the region command of the LAMMPS simulation code. See also the corresponding user manual page for more information on this OVITO modifier.

  The `SurfaceMesh` generated by the modifier is accessible in the pipeline output `DataCollection` under the unique `identifier` lammps-regions:

      data = pipeline.compute()
      mesh = data.surfaces['lammps-regions']

  color_by_region: bool

    Controls whether the modifier should color the parts of the surface mesh by region. The effect of this option is the same as if you would additionally insert the `ColorByTypeModifier` into the pipeline.

    If turned off, the mesh will have a uniform color by default and you can make use of the color mapping options of the `vis` element to configure a different coloring scheme if necessary.

    If turned on, the modifier will generate the mesh region property `Color`, and the mesh will be rendered using the values stored in this property. The modifier assigns a prescribed set of colors to the regions in a cyclic manner.

    Default:

      `False`

    Added in version 3.10.0.

    Changed in version 3.11.0: Renamed from `color_by_type`

  commands: str

    The LAMMPS region command(s) to be interpreted by the modifier. If multiple commands are specified, they must be separated by new-line characters.

    Default:

      `'region 1 sphere -20 0 0 15'`

  select_atoms: bool

    Turns on the selection of all particles that are located within any of the generated regions.

    Default:

      `False`

  vis: SurfaceMeshVis

    The `SurfaceMeshVis` element that is responsible for rendering the surface mesh generated by the modifier. It controls the visual appearance of the region surfaces.

class ovito.modifiers.ReplicateModifier

  Base: `ovito.pipeline.Modifier`

  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 specifier | Description
  --- | ---
  `particles` | Duplicates `Particles` and `Bonds`.
  `surfaces` | Duplicates the mesh geometry of `SurfaceMesh` objects.
  `voxels` | Duplicates the voxel elements of `VoxelGrid` objects.
  `vectors` | Replicates the arrows stored in all `Vectors` objects.
  `lines` | Duplicates the lines stored in all `Lines` 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: bool

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

    Default:

      `True`

  property num_x: int

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

    Default:

      `1`

  property num_y: int

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

    Default:

      `1`

  property num_z: int

    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', 'dislocations', 'lines', 'surfaces', 'vectors', 'voxels'}`

  property unique_ids: bool

    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.SelectTypeModifier

  Base: `ovito.pipeline.Modifier`

  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:

  Global attributes |
  --- | ---
  `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: str

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

    Default:

      `'particles'`

  property property: str

    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: MutableSet[str | int]

    Specifies the 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 ID for a type name using `Property.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.SliceModifier

  Base: `ovito.pipeline.Modifier`

  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`.
  `voxels` | Creates a cross-sectional cut of a `VoxelGrid`.
  `lines` | Cuts the lines stored in `Lines` objects.
  `dislocations` | Cuts dislocation lines of a `DislocationNetwork`.
  `vectors` | Cuts the arrows stored in `Vectors` objects.

  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 the `only_selected` option.

  The `select` option lets you select all elements on one side of the plane instead of deleting them. Currently, the selection mode works only for `Particles` or `SurfaceMesh` vertices, which get selected by setting their `Selection` particle property to 1.

  property distance: float

    The distance of the slicing plane from the origin (along its normal vector). Its interpretation depends on whether `miller` mode is enabled or not.

    Default:

      `0.0`

  property gridslice_vis

    The `SurfaceMeshVis` controlling the visual appearance of the cross-sectional slice being extracted from a `VoxelGrid` by the modifier. The visual element is only used if `operate_on` includes `'voxels'` and the input data collection contains a `VoxelGrid`.

  property inverse: bool

    Reverses the sense of the slicing plane.

    Default:

      `False`

  property miller: bool

    Controls whether the `normal` vector and the `distance` parameter are given in terms of the reciprocal cell vectors.

    If enabled, the modifier will interpret the components of the `normal` vector as Miller indices \(hkl\). Note that the indices do not have to be integer. The `distance` parameter measures the (signed) offset of the plane from the simulation cell origin. It is specified in terms of the interplanar spacing \(d_{\mathrm{hkl}}\), which depends on the simulation cell vectors and the Miller indices \(hkl\).

    If Miller index mode is off, the `normal` vector is specified in the Cartesian simulation coordinate system. The `distance` from the origin (0,0,0) is measured in simulation units of length along the normal vector.

    The `slab_width` parameter is always specified in real-space units.

    Default:

      `False`

  property normal: tuple[float, float, float]

    The normal vector of the slicing plane. Its interpretation depends on whether `miller` mode is enabled or not.

    Default:

      `(1.0, 0.0, 0.0)`

  property only_selected: bool

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

    Default:

      `False`

  property operate_on: MutableSet[str]

    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', 'dislocations', 'lines', 'surfaces', 'vectors', 'voxels'}`

  property plane_vis: TriangleMeshVis

    The `TriangleMeshVis` controlling the visual appearance of the cutting plane in rendered images. The visual element is only used when `render_plane` has been set to `True` to visualize the mathematical plane of the modifier as a visible polygon.

  property render_plane: bool

    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: bool

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

    Default:

      `False`

  property slab_width: float

    The thickness of the slab to cut (in simulation units of length). If zero, the modifier cuts away everything on one side of the cutting plane.

    Default:

      `0.0`

class ovito.modifiers.SmoothTrajectoryModifier

  Base: `ovito.pipeline.Modifier`

  This modifier smoothens the particle motion by averaging the particle positions from several successive snapshots of a simulation trajectory. It can be used to create smooth-looking animations from a relatively coarse sequence of simulation snapshots and reduce fluctuations or thermal vibrations in particle trajectories. See also the corresponding user manual page for this modifier.

  Note: Make sure you insert this modifier at the beginning of a data pipeline, in particular before any other modifiers that delete or filter particles, because it needs to see the complete particle system in order to perform the trajectory smoothing.

  property minimum_image_convention: bool

    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 input particle coordinates are already in unwrapped form.

    Default:

      `True`

  property window_size: int

    Controls how many input animation frames to take into account when calculating the time-averaged particle coordinates. The modifier uses a sliding time window of the given size that is centered around the current animation time. A window size of 1 disables smoothing.

    Default:

      `1`

class ovito.modifiers.SpatialBinningModifier

  Base: `ovito.pipeline.Modifier`

  The modifier outputs a 1-, 2- or 3-dimensional grid of field values. See also the corresponding user manual page for more information. This grid contains coarse-grained information of the `Particles` or a `DislocationNetwork` found in the `DataCollection`:

  - Particles: This modifier maps the particles to the binning grid and applies a reduction operation (mean, sum, min, max, etc.) to some property of the particles located within each spatial bin. You have to specify the input particle property which should be transferred to the grid cell by setting the modifier’s `property` field to the name of an existing particle property.

  - DislocationNetwork: In this mode, the modifier calculates the local dislocation density and Nye tensor in each bin. The dislocation density is expressed in units of 1/length2, depending on the unit system used in the input simulation.

  The `direction` parameter of the modifier selects the dimensionality of the bin grid and the spatial direction(s) along which the grid cells are oriented. The `bin_count` parameter controls the resolution of the generated grid, which always covers the entire `SimulationCell`.

  If the dimensionality of the selected output grid is one-dimensional, then the modifier will generate a `DataTable` object containing the computed bin values along the selected spatial `direction`. The data table may later be retrieved from the `tables` dictionary of the pipeline’s output `DataCollection` under the lookup key `'binning'`.

  If the dimensionality of the selected output grid is two- or three-dimensional, then the modifier will generate a `VoxelGrid` object. The generated voxel grid may later be retrieved from the `grids` dictionary of the pipeline’s output `DataCollection` under the lookup key `'binning'`.

  Examples

  The following example shows how to calculate the gradient of the `Velocity.X` field along the spatial Z-axis. For this, we use the `first_derivative` option, which lets the modifier compute the first derivative of the data points using a finite differences scheme.

      pipeline.modifiers.append(SpatialBinningModifier(
          property = 'Velocity.X',
          direction = SpatialBinningModifier.Direction.Z,
          bin_count = 80,
          reduction_operation = SpatialBinningModifier.Operation.Mean,
          first_derivative = True
      ))

  The output `DataTable` can then be exported to an output file using OVITO’s `export_file()` function or printed to the console:

      export_file(pipeline, 'output/velocity_profile.txt', 'txt/table', key='binning')
      data = pipeline.compute()
      print(data.tables['binning'].xy())

  The following example demonstrates how to compute a three-dimensional `VoxelGrid` containing the local particle number densities. Since we do not specify any input `property`, the modifier will use a uniform value 1, which can be used to count the particles in each bin:

      pipeline.modifiers.append(SpatialBinningModifier(
          direction = SpatialBinningModifier.Direction.XYZ,
          bin_count = (100, 100, 100),
          reduction_operation = SpatialBinningModifier.Operation.SumVol
      ))

  The resulting `VoxelGrid` may now be exported to an output file, for example in the VTK format:

      export_file(pipeline, 'output/density.vtk', 'vtk/grid', key='binning')

  Or it can serve as input for subsequent modifiers in your data pipeline, for example the `CreateIsosurfaceModifier`.

  property bin_count: int | tuple[int, int] | tuple[int, int, int]

    Specifies the number of bin cells to generate along each axis of the binning grid. You should assign a tuple containing one, two, or three positive integers to this parameter field, depending on the grid’s dimensionality set by the `direction` parameter.

    Note that the entries in the tuple specify the number of bins along the grid’s first, second, and third dimension and not along the spatial axes. For example, if the binning `direction` is `Direction.YZ`, setting `bin_count` to `(100, 50)` will let the modifier generate a two-dimensional grid with 100 bins along the second simulation cell vector (spatial y-axis) and 50 bins along the third cell vector (z-axis) of the 3-dimensional simulation box. Examples:

        SpatialBinningModifier(direction=SpatialBinningModifier.Direction.Z, bin_count=100)
        SpatialBinningModifier(direction=SpatialBinningModifier.Direction.XZ, bin_count=(40, 80))
        SpatialBinningModifier(direction=SpatialBinningModifier.Direction.XYZ, bin_count=(80, 80, 80))

    If you assign just a single number, or a tuple with fewer entries than required for the selected grid dimensionality, the bin count in any of the remaining grid dimensions will be implicitly set to 1.

    Default:

      `(50, 50, 20)`

  property direction: SpatialBinningModifier.Direction

    Selects the alignment of the bins and the dimensionality of the grid. Possible values:

    > - `SpatialBinningModifier.Direction.X`

    > - `SpatialBinningModifier.Direction.Y`

    > - `SpatialBinningModifier.Direction.Z`

    > - `SpatialBinningModifier.Direction.XY`

    > - `SpatialBinningModifier.Direction.XZ`

    > - `SpatialBinningModifier.Direction.YZ`

    > - `SpatialBinningModifier.Direction.XYZ`

    For modes `X`, `Y`, and `Z`, the modifier will generate a one-dimensional grid with bins aligned perpendicular to the selected simulation cell vector. For modes `XY`, `XZ`, and `YZ`, the modifier will generate a two-dimensional grid with bins aligned perpendicular to both selected simulation cell vectors (i.e. parallel to the third vector). In the last case (`XYZ`), the modifier generates a three-dimensional voxel grid.

    Default:

      `SpatialBinningModifier.Direction.X`

  property first_derivative: bool

    Set this to `True` to let the modifier numerically compute the first derivative of the binned data points using a finite differences approximation. This works only if binning is performed in a single `direction` (`Direction.X`, `Direction.Y` or `Direction.Z`). For two- or three-dimensional binning modes, this option is ignored.

    Default:

      `False`

  property grid_vis: VoxelGridVis

    The `VoxelGridVis` element controlling the visual appearance of the 2d or 3d grid generated by the modifier in rendered images. The visual element is ignored if `direction` parameter is set to a 1-dimensional binning mode.

  property only_selected: bool

    This option lets the modifier take into account only the currently selected particles. Unselected particles will be excluded from the binning process. You can use this option to restrict the calculation to a subset of particles.

    Default:

      `False`

  property operate_on: str

    Selects the data element this modifier will operate on. Valid values are:

    > - `'particles'`

    > - `'dislocations'`

    Default:

      `'particles'`

    Added in version 3.11.0.

  property property: str

    The name of the input particle `Property` which the reduction operation should be applied to. This can be the name of one of the standard particle properties or of a user-defined particle property.

    If no input property is specified, then the modifier uses unity as uniform input value for all particles. Use this to compute the number density of particles in each bin, for example, with `reduction_operation` set to `SumVol`.

    If the input is a vector property, a component name may be appended after a dot, e.g. `"Velocity.X"`, to perform the reduction operation only on that specific vector component. The output will then be a scalar field. Otherwise, the reduction operation is applied to all vector components independently and the output will be a vector field or vector-valued function.

    Default:

      `''`

  property reduction_operation: SpatialBinningModifier.Operation

    Selects the reduction operation to be carried out. Supported parameter 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 the number density of particles or pressure/stress within each bin from the per-atom virial.

    Default:

      `SpatialBinningModifier.Operation.Mean`

class ovito.modifiers.SpatialCorrelationFunctionModifier

  Base: `ovito.pipeline.Modifier`

  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.tables['correlation-real-space']
      rdf = data.tables['correlation-real-space-rdf']
      export_file(C, 'output/real_correlation_function.txt', 'txt/table')
      export_file(rdf, 'output/rdf.txt', 'txt/table')

      # Compute normalized correlation function (by co-variance):
      C_norm = C.xy()
      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: bool

    This flag controls whether non-periodic directions have a Hann window applied to them. Applying a window function is necessary to remove spurious oscillations and power-law scaling of the (implicit) rectangular window of the non-periodic domain.

    Default:

      `True`

  property direct_summation: bool

    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: float

    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: int

    This integer value controls the number of bins for the direct calculation of the real-space correlation function.

    Default:

      `50`

  property neighbor_cutoff: float

    This parameter determines the cutoff of the direct calculation of the real-space correlation function.

    Default:

      `5.0`

  property property1: str

    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:

      `''`

  property property2: str

    The name of the second particle property for which to compute the correlation, P2. If this is the same as `property1`, then the modifier will compute the autocorrelation.

    Default:

      `''`

class ovito.modifiers.StructureFactorModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.13.0.

  Calculates the structure factor for the particle model (either the entire system or just the subset of currently selected particles). See the corresponding user manual page for more information.

  Inputs:

  Particle properties |
  --- | ---
  `Position` | The input coordinates of the particles.
  `Particle Type` | Required if `partial` is set to `True`.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is set to `True`.

  Outputs:

  `DataTable` |
  --- | ---
  `structure-factor` | The tabulated SF computed by the modifier. You can retrieve the table data through the `tables` dictionary of the output `DataCollection` under the lookup key `"structure-factor"`, see the code examples below.
  `faber-ziman-structure-factor` | The tabulated Faber-Ziman partial factors, \(A_{\alpha\beta}(k)\), computed by the modifier. This table is only generated if `partial` is set to `True`.

  Examples:

  The following Python program demonstrates how to load a particle configuration, compute the SF using the modifier, and export the data to a text file:

      from ovito.io import import_file
      from ovito.modifiers import StructureFactorModifier

      # Load a particle dataset, apply the modifier, and evaluate pipeline.
      pipeline = import_file("input/simulation.dump")
      pipeline.modifiers.append(StructureFactorModifier(k_bins=120, k_min=0, k_max=10))
      data = pipeline.compute()

      # Print the computed S(k) function values.
      print(data.tables['structure-factor'].xy())

  You can also compute the structure factor for every frame of an MD simulation and generate a time-averaged SF function using the `TimeAveragingModifier`. A code example for this technique is found in the documentation of the `RadialDistributionFunctionModifier`.

  property atomic_form_factors: bool

    Tells the modifier to use atomic form factors f to weigh the atoms’ individual contributions to S(k). Atomic form factors are taken from TU Graz.

    Default:

      `False`

  property k_bins: int

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

    Default:

      `100`

  property k_max: int

    Maximum \(k\) value for which the SF is calculated. Only \(k\) vectors with a magnitude <= `k_max` are included in the calculation.

    Default:

      `10`

  property k_min: int

    Minimum \(k\) value for which the SF is calculated. Only \(k\) vectors with a magnitude > `k_min` are included in the calculation.

    Default:

      `0`

  property mode: StructureFactorModifier.Mode

    Selects the calculation method used by the modifier. Possible values:

    > - `StructureFactorModifier.Mode.Direct`

    > - `StructureFactorModifier.Mode.Debye`

    In mode `Direct`, the k-space method is used to calculate the structure factor. This method is slower but yields precise results, especially at small k values. In mode `Debye`, the RDF-based method is used to calculate the structure factor. This method is suitable for large particle systems, since it is faster and requires less memory.

    Default:

      `StructureFactorModifier.Mode.Debye`

  property only_selected: bool

    Restricts the calculation to the currently selected particles. Unselected particles will be treated as if they did not exist.

    Default:

      `False`

  property partial: bool

    This option requests the calculation of element-specific (partial) SFs. The resulting SF table will contain one tabulated S(k) function for each pair-wise combination of particle types in the input system.

        from ovito.io import import_file
        from ovito.modifiers import StructureFactorModifier

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

        # Print the list of defined particle types.
        # They are represented by ParticleType objects attached to the 'Particle Type' particle property.
        data = pipeline.compute()
        for t in data.particles.particle_types.types:
            print(f"Type {t.id}: {t.name}")

        # Insert modifier into pipeline to calculate partial SFs:
        pipeline.modifiers.append(StructureFactorModifier(partial=True))

        # Evaluate pipeline and access the output DataTable:
        sf_table = pipeline.compute().tables['structure-factor']

        # The y-property of the data points of the DataTable is now a vectorial property.
        # Each vector component represents one partial SF.
        sf_names = sf_table.y.component_names

        # Print a list of partial S(k) functions.
        for component, name in enumerate(sf_names):
            print(f"S(k) for pair-wise type combination {name}:")
            print(sf_table.y[:,component])

        # The DataTable.xy() method yields everything as one combined NumPy table.
        # This includes the 'k' values in the first array column, followed by the
        # tabulated S(k) partial functions in the remaining columns.
        print(sf_table.xy())

    Default:

      `False`

class ovito.modifiers.StructureIdentificationModifier

  Base: `ovito.pipeline.Modifier`

  Abstract base class for all modifiers in OVITO that analyze the local neighborhood of particles to identify structural motives or crystalline structures. It contains parameter fields that are common to all these modifiers:

  > - `AcklandJonesModifier`

  > - `ChillPlusModifier`

  > - `CommonNeighborAnalysisModifier`

  > - `IdentifyDiamondModifier`

  > - `PolyhedralTemplateMatchingModifier`

  > - `VoroTopModifier`

  property color_by_type: bool

    Controls the coloring of particles by the modifier to indicate their identified structure type. See the documentation of the `structures` list on how to change the colors representing the different structure types recognized by the modifier.

    Default:

      `True`

  property only_selected: bool

    Set this to `True` to perform the analysis on selected particles only. Particles that are not selected will be treated as if they did not exist and are assigned to the “OTHER” structure category. Use a `SelectTypeModifier` in your pipeline, for example, to restrict the structure identification to a sub-lattice formed by one species of particles in a multi-component system.

    Default:

      `False`

  property structures: Sequence[ElementType]

    A list of `ElementType` instances managed by this modifier, one for each recognized structural type. You can modify the type objects in this list to adjust the coloring and to turn the identification of certain structural types on or off. The ordering of the `ParticleType` objects in this list corresponds to the numeric type IDs defined by the concrete structure identification modifiers. In the following code snippets, the `CommonNeighborAnalysisModifier` serves as an example.

    Your can change the color of a type by setting its `color` property to a new RGB value:

        modifier = CommonNeighborAnalysisModifier()
        modifier.structures[CommonNeighborAnalysisModifier.Type.FCC].color = (0.2, 1.0, 0.8)
        modifier.structures[CommonNeighborAnalysisModifier.Type.HCP].color = (0.0, 0.4, 1.0)

    To turn the identification of a particular structure type on or off, you set its `enabled` property:

        modifier.structures[CommonNeighborAnalysisModifier.Type.BCC].enabled = False
        modifier.structures[CommonNeighborAnalysisModifier.Type.ICO].enabled = True

    .

class ovito.modifiers.TextLabelsModifier

  Base: `ovito.pipeline.Modifier`

  Added in version 3.16.0.

  Turns the values of a property into text labels, which are rendered next to the data elements they belong to. See also the corresponding user manual page for more information.

  The modifier can operate on the elements of different kinds of `PropertyContainer` objects:

  Data elements |
  --- | ---
  `particles` | Labels `Particles`.
  `bonds` | Labels `Bonds` at their midpoints.
  `lines:<ID>` | Labels the vertices of the `Lines` container with the given `identifier`.
  `voxels:<ID>` | Labels `VoxelGrid` cells at their centers.
  `vertices:<ID>`, `faces:<ID>` | Labels the vertices or faces of the `SurfaceMesh` with the given `identifier`.
  `vectors:<ID>` | Labels the arrow glyphs of the specified `Vectors` container.
  `table:<ID>` | Labels the points of the `DataTable` with the given `identifier`.

  By default, the modifier acts on particles. Set the `operate_on` field to change this.

  A `DataTable`, unlike the other kinds of `PropertyContainer`, has no standard position property. When labeling the points of a table, use the `position_property` field to select the table column providing the 3d coordinates at which the labels are placed. The modifier assigns that column to the table’s `positions` field. For example, you can label the clusters identified by the `ClusterAnalysisModifier` by their size, and place the labels at the center of mass of each cluster:

      pipeline.modifiers.append(
        ClusterAnalysisModifier(cutoff=2.8, compute_com=True, compute_gyration=True)
      )
      pipeline.modifiers.append(
        TextLabelsModifier(operate_on='table:clusters', position_property='Center of Mass', property='Cluster Size')
      )

  If the table additionally contains a column named `Radius` or `Radius of Gyration` holding one floating-point value per row, that value is taken as the size of the object the row stands for, which affects the placement of the label. The label is then pushed outward and toward the camera by that amount instead of sitting right on the anchor point.

  Output:

  The modifier generates a new string property, named `Text Label` (see `output_property`), which holds the finished label text of every data element. A `TextLabelsVis` element is attached to that property, which renders the labels in the viewports. Access it through the `vis` field of the modifier to configure the font, size, color and placement of the labels:

      pipeline = import_file("input/simulation.dump")
      modifier = TextLabelsModifier(property="Particle Identifier", format_string="#%g")
      modifier.vis.font_size = 0.05
      modifier.vis.alignment = QtCore.Qt.AlignmentFlag.AlignTop | QtCore.Qt.AlignmentFlag.AlignRight
      pipeline.modifiers.append(modifier)

  Values are converted to text as follows:

  - A floating-point property is formatted using the C-style `format_string`.

  - An integer property is rendered as a plain decimal number.

  - A typed property, e.g. `Particle Type`, is rendered as the name of the corresponding `ElementType`.

  - A string property is used as is.

  For the latter three, which bring their own text representation, only the literal parts of the `format_string` are used, and they are placed around that representation. A format string of `'#%g'` therefore labels particle identifiers as `#1`, `#2`, and so on.

  A vector property may be selected either as a whole, e.g. `property='Position'`, or as an individual component, e.g. `property='Position.X'`. The `format_string` must follow the rules of the standard printf() C function and provide one conversion specifier per value that goes into a label. Labeling particle positions with `format_string='(%.2f, %g, %g)'`, for example, produces labels such as `(1.00, 2, 3)`. A single conversion specifier is accepted for a whole vector property too; it is then applied to every component in turn, and the components are joined with `', '`. Any other number of conversion specifiers raises an error. A format string containing no conversion specifier at all gives every element the same constant label text.

  Several instances of the modifier can be applied to the same data elements. Each one is automatically assigned a different `output_property` (`Text Label`, `Text Label 2`, …) when it is inserted into the pipeline, so their labels do not overwrite each other and can be styled independently.

  property format_string: str

    The format string used with the printf() C function function to generate the text representation of the property values. You can change this format string to control the number of displayed decimal places, e.g. `'%.2f'`.

    When a vector property is selected as a whole, you may either give one conversion specifier per component, e.g. `'(%.2f, %g, %g)'` for particle positions, or a single specifier, which is then applied to every component in turn and the components are joined with `', '`. Any other number of conversion specifiers raises an error.

    Literal text may be incorporated into the format string to include physical units or a marker character, for example `'%.2f eV'` or `'#%d'`. A format string containing no conversion specifier at all gives every element the same constant label text.

    Properties with a string or typed data type bring their own text representation, which is likewise used verbatim; only the literal parts of the format string are placed around it.

    Default:

      `'%g'`

  property only_selected: bool

    If `True`, only currently selected data elements are given a label; the label strings of all unselected elements remain empty and nothing is rendered for them.

    Default:

      `False`

  property operate_on: str

    Controls the kind of data elements that are being labeled by this modifier. Supported values are: `'particles'`, `'bonds'`, `'lines:<ID>'`, `'voxels:<ID>'`, `'vertices:<ID>'`, `'faces:<ID>'`, `'vectors:<ID>'`, and `'table:<ID>'`. Here, `<ID>` must be replaced with the `identifier` of the data object to be labeled.

    Default:

      `'particles'`

  property output_property: str

    The name of the string property generated by the modifier, which receives the label texts and to which the modifier’s `vis` element is attached. This read-only field is assigned automatically when the modifier is inserted into a pipeline: the first instance uses `'Text Label'`, further instances operating on the same data elements use `'Text Label 2'`, `'Text Label 3'`, and so forth.

    Default:

      `'Text Label'`

  property position_property: str

    The name of the property providing the 3d coordinates (anchor positions) at which the labels are placed. The property must have 3 components and a floating-point data type.

    This parameter is used only when the modifier operates on a `DataTable`, which, unlike particles or other kinds of data elements, has no standard position property. The modifier assigns the selected property to the table’s `positions` field. For all other input types the parameter is ignored. Note that all text label modifiers acting on the same data table share this setting.

    Default:

      `''`

  property property: str

    The name of the input property whose values are turned into label texts. A vector property may be selected either as a whole, e.g. `'Position'`, in which case all of its components go into one label, or as an individual component using the `'Name.Component'` syntax, e.g. `'Position.X'`.

    Default:

      `''`

  property vis: TextLabelsVis

    The `TextLabelsVis` element controlling the appearance of the labels generated by this modifier.

class ovito.modifiers.TimeAveragingModifier

  Base: `ovito.pipeline.Modifier`

  This modifier computes the time average of one or more time-dependent input quantities by sampling them over all frames of the loaded trajectory. The following types of input quantities are supported:

  > - time-dependent global attributes

  > - `DataTable` objects, e.g. histograms or distribution functions computed by other analysis modifiers in the pipeline

  > - element-wise property values, e.g. particle coordinates or other particle properties

  > - `SimulationCell` (the cell shape)

  The selected input quantities to be averaged must be produced in the upstream data pipeline or loaded from the input trajectory file. See also the corresponding user manual page for more information on this modifier.

  Averaging scalar quantities:

  The following code example demonstrates how to use the `TimeAveragingModifier` to calculate the mean value of a scalar quantity that changes with simulation time. In this example, the `CreateBondsModifier` is added to the pipeline to dynamically create bonds between the moving particles (thus, the number of created bonds will change with time). The modifier reports the number of bonds that have been created in the current simulation frame as an output attribute named `'CreateBonds.num_bonds'`. This varying attribute is then selected as the input quantity to be averaged by the following `TimeAveragingModifier`, which in turn outputs the time-averaged value it computes as a new attribute named `'CreateBonds.num_bonds (Average)'`. This value can be retrieved from the `DataCollection` produced by `Pipeline.compute()`. Note that it does not matter at which simulation time we evaluate the data pipeline – the mean number of bonds is a static quantity and remains constant over the entire trajectory.

      pipeline = import_file('input/trajectory.dump')
      pipeline.modifiers.append(CreateBondsModifier(cutoff=2.9))
      pipeline.modifiers.append(TimeAveragingModifier(operate_on='attribute:CreateBonds.num_bonds'))
      data = pipeline.compute()
      print(data.attributes['CreateBonds.num_bonds (Average)'])

  Averaging data tables:

  Some analysis modifiers of OVITO output their results as `DataTable` objects, which can represent histograms or distribution functions. For example, the `RadialDistributionFunctionModifier` computes the radial pair distribution function (RDF) of a particle system for the current simulation time and outputs it as a data table named `'coordination-rdf'`. We can have the `TimeAveragingModifier` compute the time average of this varying distribution function over all frames of the loaded trajectory:

      pipeline = import_file('input/trajectory.dump')
      pipeline.modifiers.append(RadialDistributionFunctionModifier(cutoff=6.0, number_of_bins=50))
      pipeline.modifiers.append(TimeAveragingModifier(operate_on='table:coordination-rdf'))
      data = pipeline.compute()
      print(data.tables['coordination-rdf[average]'].xy())

  Note that, in case of data tables, the output table’s `identifier` is given the suffix `[average]` by the `TimeAveragingModifier`.

  An average of a `DataTable` can only be computed if the table’s x-axis `interval` does not vary with time and the `x`-coordinates of the data points remain fixed. That’s because the modifier simply averages the time-varying y-coordinate of each data point. Thus, to generate a histogram `DataTable` using the `HistogramModifier` that is suitable for time averaging, you will have to activate the `HistogramModifier.fix_xrange` option.

  Averaging properties:

  The modifier can time-average properties that belong to a `Particles` object, `VoxelGrid`, or other type of `PropertyContainer`. When setting the `operate_on` field, you need to specify the container’s identifier and the name of the property to average:

      pipeline.modifiers.append(TimeAveragingModifier(operate_on='property:particles/Coordination'))
      data = pipeline.compute()
      print(data.particles['Coordination Average'][...])

  Note that the output `Property` is given the suffix `'Average'` by the `TimeAveragingModifier`.

  property interval: tuple[int, int] | None

    The animation frame interval over which the input trajectory is sampled to compute the average. You can set this to a pair of integers specifying the first and the last frame of the averaging interval; or assign `None` to let the modifier compute the average over the entire trajectory.

    For example, to restrict the average to the second half of the loaded simulation trajectory, you can specify the frame interval based on the `num_frames` value:

        modifier.interval = (pipeline.num_frames//2, pipeline.num_frames-1)

    Default:

      `None`

  property operate_on: str | Sequence[str]

    Selects the input quantity to be averaged by this modifier. Supported values for this field are:

    > - `'attribute:<NAME>'`

    > - `'table:<ID>'`

    > - `'property:<CONTAINER>/<PROPERTY>'`

    > - `'cell'`

    Here, `<NAME>` refers to the name of a global attribute to be averaged. `<ID>` is the `identifier` of the `DataTable` to be averaged, `<CONTAINER>` is the `identifier` of a `PropertyContainer` and `<PROPERTY>` the `name` of the `Property` in that container, which should be averaged. Note that the `Particles` property container has the standard identifier `'particles'`. Its `Bonds` child container is referenced by the hierarchical identifier `'particles/bonds'`.

    Furthermore, it is possible to let the modifier average multiple input quantities in one pass by specifying a list of input references of the kind described above. The following code demonstrates how to compute the time averages of two global attributes:

        pipeline.modifiers.append(TimeAveragingModifier(
            operate_on = ('attribute:CommonNeighborAnalysis.counts.FCC',
                          'attribute:CommonNeighborAnalysis.counts.BCC')
        ))
        data = pipeline.compute()
        print(data.attributes['CommonNeighborAnalysis.counts.FCC (Average)'])
        print(data.attributes['CommonNeighborAnalysis.counts.BCC (Average)'])

    Default:

      `''`

  property overwrite: bool

    If set to false, the averaged values computed by the modifier are output as new quantities with the suffix “Average” appended to keep the original and averaged values separate. If set to true, the modifier will overwrite the current time-dependent values in the trajectory with the static averaged values.

    Default:

      `False`

  property sampling_frequency: int

    Animation step interval at which the quantity to be averaged is sampled from the input trajectory. You can set this to a larger value to perform a coarser sampling and reduce the total number of trajectory frames that need to be loaded into memory.

    Default:

      `1`

class ovito.modifiers.TimeSeriesModifier

  Base: `ovito.pipeline.Modifier`

  This modifier samples a varying input quantity computed by the data pipeline over all frames of the loaded trajectory to produce a time series, which can then be plotted to visualize the time evolution of the quantity. See also the corresponding user manual page for more information on this modifier.

  The modifier takes one or more global attributes as input, samples their values over the simulation trajectory, and outputs the generated time series as a new `DataTable` with the identifier `time-series`.

      pipeline = import_file('input/trajectory.dump')
      pipeline.modifiers.append(ConstructSurfaceModifier(radius = 1.9))
      pipeline.modifiers.append(TimeSeriesModifier(operate_on = 'ConstructSurfaceMesh.surface_area'))
      data = pipeline.compute()
      print(data.tables['time-series'].xy())

  This code samples the value of the global attribute `ConstructSurfaceMesh.surface_area`, which is computed by the `ConstructSurfaceModifier` for each frame of the loaded simulation trajectory. The result is a static `DataTable` with the number of rows equal to the number of trajectory frames, which is inserted by the `TimeSeriesModifier` into the pipeline’s output data collection.

  Note that you do not need the `TimeSeriesModifier` in order to output a global attribute to a text file as a function of time. This can be accomplished simply by calling the `export_file()` function, which can automatically sample an attribute’s value and write it to the output file one line per frame:

      pipeline = import_file('input/trajectory.dump')
      pipeline.modifiers.append(ConstructSurfaceModifier(radius = 1.9))
      export_file(pipeline, 'output/surface_area.txt',
          format='txt/attr',
          columns=["SourceFrame", "ConstructSurfaceMesh.surface_area"],
          multiple_frames=True)

  property interval: tuple[int, int] | None

    The interval of animation frames over which the input trajectory is sampled to generate the time series. You can set this to a pair of integers specifying the first and the last frame of the sampling interval; or assign `None` to let the modifier generate the time series over the entire trajectory.

    For example, to restrict the time series to the first half of the loaded simulation trajectory, you can specify the frame interval based on the `num_frames` value:

        modifier.interval = (0, pipeline.num_frames//2)

    Default:

      `None`

  property operate_on: str | Sequence[str]

    Specifies the name of the input global attribute to be sampled by the modifier. The attribute must be generated by the trajectory file reader or dynamically computed by a modifier in the upstream data pipeline.

    You can also specify several global attributes as a Python tuple of strings. Then the modifier will simultaneously sample each of the input attributes and produce a `DataTable` with a vector data column containing the set of time series.

        pipeline.modifiers.append(TimeSeriesModifier(
            operate_on = ('ConstructSurfaceMesh.surface_area',
                          'ConstructSurfaceMesh.filled_volume')))
        data = pipeline.compute()
        series = data.tables['time-series'].y
        print("Surface area:", series[:,0])
        print("Solid volume:", series[:,1])

    Default:

      `''`

  property sampling_frequency: int

    Animation interval at which the attribute(s) is sampled from the input trajectory. You can set this to a larger value to perform a coarser sampling and reduce the total number of trajectory frames that need to be loaded/computed.

    Default:

      `1`

  property time_attribute: str

    The name of a global attribute that should be queried by the modifier to obtain the time-axis coordinates of the data samples. If set to an empty string (the default), the modifier uses the animation frame number as time axis. You can alternatively tell the modifier to use the `Timestep` or `Time` global attributes, which are created by some file readers based on the information found in the input trajectory, in order to plot the selected input attribute as a function of MD timestep number or physical simulation time.

    Default:

      `''`

class ovito.modifiers.UnwrapTrajectoriesModifier

  Base: `ovito.pipeline.Modifier`

  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.

  Note that, to unwrap the particle coordinates, the modifier may have to step through all frames of the input simulation trajectory to detect jumps in the trajectories. This will not be necessary, however, if the `Periodic Image` particle property has been loaded from the input simulation file, because then the modifier can directly use this information to unwrap the particle coordinates.

      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.
      # Note that the modifier should typically precede any other modifiers in the pipeline.
      pipeline.modifiers.append(UnwrapTrajectoriesModifier())

      # For demonstration purposes, request last frame of the trajectory.
      # The returned DataCollection will contain modified particle coordinates, which are computed
      # by the unwrap modifier by tracing the trajectories of the particles and unfolding
      # them whenever crossings of the periodic cell boundaries are detected.
      data = pipeline.compute(pipeline.num_frames - 1)

class ovito.modifiers.VoroTopModifier

  Base: `ovito.modifiers.StructureIdentificationModifier`

  “This modifier uses the Voronoi cell topology of particles to characterize their local structural environments “[Lazar, Han, Srolovitz, PNAS 112:43 (2015)]. See the corresponding user manual page for more information on this modifier. Note that this modifier inherits several important parameter fields from its `StructureIdentificationModifier` base class.

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

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

  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.

  property filter_file: str

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

    Default:

      `''`

  property use_radii: bool

    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.VoronoiAnalysisModifier

  Base: `ovito.pipeline.Modifier`

  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:

  Particle properties |
  --- | ---
  `Position` | The coordinates of the input particles.
  `Radius` | Per-particle radii are used if `use_radii` is set to `True`.
  `Particle Type` | Per-type radii are used if `use_radii` is set to `True` and `Radius` property is not present.
  `Selection` | The selection state of the input particles. Only needed if `only_selected` is set to `True`.

  Outputs:

  Particle properties |
  --- | ---
  `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 to `True`.
  `Max Face Order` | The maximum number of edges in any face of a particle’s Voronoi polyhedron. Only if `compute_indices` is set to `True`.
  `Cavity Radius` | Distance from a center particle to the farthest vertex of its Voronoi polyhedron.

  Global attributes |
  --- | ---
  `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).

  Bond properties |
  --- | ---
  `Topology` | The connectivity information of newly created `Bonds` (one bond for each Voronoi face). Only if `generate_bonds` is set to `True`.

  property bonds_vis: BondsVis

    The `BondsVis` object controlling the visual appearance of the bonds generated by the modifier if `generate_bonds` is set to `True`.

  property compute_indices: bool

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

    Default:

      `False`

  property edge_threshold: float

    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: float

    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: bool

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

    Default:

      `False`

  property generate_polyhedra: bool

    Controls whether the modifier outputs the computed Voronoi cells as a polyhedral `SurfaceMesh` object.

    Default:

      `False`

  property mesh_vis: SurfaceMeshVis

    The `SurfaceMeshVis` object controlling the visual appearance of the polyhedral mesh generated by the modifier if `generate_polyhedra` is set to `True`.

  property only_selected: bool

    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: float

    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: bool

    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: `ovito.pipeline.ReferenceConfigurationModifier`

  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:

  Particle properties |
  --- | ---
  `Occupancy` | The computed site occupation numbers, one for each site in the reference configuration, if `output_displaced` is set to false. Otherwise, total number of atoms occupying the same reference site as the atom from the displaced configuration.
  `Site Index` | Zero-based index of the reference site to which the atom from the displaced configuration has been assigned. Only available if `output_displaced` is set to true.
  `Site Identifier` | Unique identifier of the reference site to which the atom from the displaced configuration has been assigned. Only available if `output_displaced` is set to true and if reference sites have a Particle Identifier property.
  `Site Type` | Type of the reference site to which the atom from the displaced configuration has been assigned. Only available if `output_displaced` is set to true.

  Global attributes |
  --- | ---
  `WignerSeitz.vacancy_count` | The total number of vacant sites (having `Occupancy` == 0).
  `WignerSeitz.interstitial_count` | The total number 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 you to select specific types of point defects, e.g. antisites, using OVITO’s selection tools. One option is to use the `ExpressionSelectionModifier` to pick sites having a certain occupancy. The following script exemplarily shows how a custom `PythonModifier` function can be used 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: bool

    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 interested 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 named `Site 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: bool

    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 the `Occupancy` property counts the number of particles of the corresponding type that occupy the site. For example, the property component `Occupancy.1` contains the number of particles of type 1 that occupy a site.

    Default:

      `False`

class ovito.modifiers.WrapPeriodicImagesModifier

  Base: `ovito.pipeline.Modifier`

  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`. See also the corresponding user manual page for this modifier. This modifier has no configurable parameters.