Chapter 5. Reference

Table of Contents

5.1. Main window
5.1.1. Main menu
5.1.2. Main toolbar
5.1.3. Viewports
5.1.4. Animation toolbar
5.2. Rendering
5.2.1. Render settings
5.2.2. Preview renderer
5.2.3. POV-Ray renderer
5.3. Atoms object
5.3.1. Simulation cell
5.4. Import atoms object
5.5. Modifiers
5.5.1. Ackland Analysis
5.5.2. Add Expression Channel
5.5.3. Assign Atom Type Color
5.5.4. Assign Color
5.5.5. Affine Transformation
5.5.6. Calculate Displacements
5.5.7. Color Coding
5.5.8. Common Neighbor Analysis
5.5.9. Delete Selected Atoms
5.5.10. Invert Selection
5.5.11. Freeze Selection
5.5.12. Select Atom Type
5.5.13. Select By Expression
5.5.14. Show Periodic Images
5.5.15. Slice
5.5.16. Wrap Periodic Images
5.6. Standard data channels
5.6.1. Atom Type
5.6.2. Position
5.6.3. Displacement
5.6.4. CNA Atom Type
5.6.5. Color
5.7. Import formats
5.7.1. LAMMPS dump files
5.7.2. LAMMPS data files
5.7.3. XYZ files
5.7.4. POSCAR files
5.7.5. IMD files
5.8. Export formats
5.8.1. LAMMPS dump files
5.8.2. LAMMPS data files
5.8.3. XYZ files
5.8.4. POSCAR files
5.8.5. POV-Ray files

This chapter is a reference of OVITO's functions.

5.1. Main window

The main window is divided into several areas described in the next sections.

5.1.1. Main menu

The main menu contains the following menu items:

FileNew (Ctrl+n)

Loads an empty scene.

FileReset

Loads an empty scene and also resets the whole application to its initial state.

FileOpen (Ctrl+o)

Loads an existing scene file from disk.

FileSave (Ctrl+s)

Saves the current scene to disk.

FileSave As

Saves the current scene to disk after letting the user choose a filename.

FileImport (Ctrl+i)

Imports a file that has not the native OVITO format. The user must select the right file format in the drop-down box in the file dialog. The number of supported file formats depends on the installed plugins.

FileExport (Ctrl+e)

Exports the current scene to a file with a format specified by the user. It can be selected with the file format drop-down box in the file dialog. The number of supported file formats depends on the installed plugins.

FileExit (Ctrl+q)

Exits the application.

EditUndo (Ctrl+z)

Reverses the last command or the last change made to the scene. The number of steps that can be undone is not limited but there are some exceptions: Loading a new scene file cannot be undone and changing the viewport views is not considered as editing operation so it is not recorded on the undo stack.

EditRedo (Ctrl+Shift+z)

Reverses the action of the last Undo command.

EditDelete (DEL)

Deletes the currently selected objects from the scene.

RenderRender Active Viewport

Renders the current viewport using a high-quality method so it can be saved to disk.

RenderSelect Renderer

Opens a dialog box that lets the user choose the render to be used for high-quality image output.

OptionsSettings

Opens a dialog box that lets the user adjust the general settings of the application.

HelpWhat's This?

Activates the inline help mode. After activating this menu item click on a user interface element to get a help text describing it.

HelpAbout

Shows a dialog box displaying information about the application like version number and author.

5.1.2. Main toolbar

Undo

Reverses the last command or the last change made to the scene. Same as the Undo menu item in the Edit menu.

Redo

Reverses the action of the last Undo command. Same as the Redo menu item in the Edit menu.

Select Tool

Activates the selection mode. When the selection mode is active objects can be selected in the viewports by clicking on them.

Move Tool

Activates the translation mode. When the translation mode is active objects can be selected and moved in the viewports with the mouse.

Rotate Tool

Activates the rotation mode. When the rotation mode is active objects can be selected and rotated in the viewports with the mouse.

5.1.3. Viewports

5.1.3.1. Viewports area

The main window contains four viewports by default which are laid out in a 2 x 2 grid. Each viewport shows a different view of the scene as denoted by the label in the upper left corner of each of the viewports. Clicking with the right mouse button on the label in the corner opens the context menu for a viewport. The interpretation of mouse clicks in the main viewport area depends on the input mode that is currently active. But independently of the current input mode you can always zoom, pan and rotate the view using the following shortcuts:

  • Use the mouse wheel in one of the viewports to zoom in or out.
  • Press the middle mouse button in one of the viewports and drag the mouse to pan the view.
  • Press the middle mouse button in one of the viewports while holding the shift key down and drag the mouse to rotate the point of view around the current selection.

There is always one active viewport which is indicated by a by a colored border around it. Clicking in one of the other viewports makes a new viewport the active one. With the Maximize Active Viewport button in the viewport control toolbar the active viewport can be enlarged to fill the whole viewports area. Clicking the button again restores the original 2 x 2 viewport layout.

5.1.3.2. Viewport context menu

The viewport context menu can be activated by right-clicking on a viewport's label in the upper left corner of the viewport. The menu contains the following items:

Wireframe

Sets the shading mode to wireframe mode for the current viewport. Only object edges will be shown.

Shaded

Sets the shading mode to shaded mode for the current viewport. Object faces will be shown.

Shaded+Edges

Sets the shading mode to shaded and edges mode for the current viewport. Object faces will be shown with highlighted edges.

Show Grid

Turns the construction grid on or off.

Show Render Frame

Controls the display of the render frame that depicts the aspect ratio of the rendered image.

View

Selection the type of view shown in the viewport. The first six view types are axis-aligned views with orthogonal projection. The Ortho view type gives an orthogonal projection of the scene from an arbitrary direction whereas the Perspective view type gives a perspective projection of the scene.

5.1.3.3. Viewport control toolbar

Zoom Mode

Activates the zoom mode. With the zoom mode being active the user can click and drag in one of the viewports to zoom in or out by moving the mouse cursor while pressing the left mouse button. Pressing the right mouse button in one of the viewports leaves the zoom mode and re-activates the input mode that had been active before the zoom mode was selected. Note that you can zoom in or out at all times using the mouse wheel even when the zoom mode is not active.

Pan Mode

Activates the pan mode. With the pan mode being active the user can click and drag in one of the viewports to pan the visible area in the viewport by moving the mouse cursor while pressing the left mouse button. Pressing the right mouse button in one of the viewports leaves the pan mode and re-activates the input mode that had been active before the pan mode was selected. Note that you can pan the viewports at all times using the middle mouse button even when the pan mode is not active.

Orbit Mode

Activates the orbit mode. With the orbit mode being active the user can click and drag in one of the viewports to rotate the viewport's point of view by moving the mouse cursor while pressing the left mouse button. Pressing the right mouse button in one of the viewports leaves the orbit mode and re-activates the input mode that had been active before the orbit mode was selected. Note that you can rotate the point of view at all times by dragging the viewport with the middle mouse button while holding down the shift key.

Zoom All

Zooms the active viewport in or out until all objects in the scene are completely visible and fill out the viewport area.

Zoom Selection

Zooms the active viewport in or out until all selected objects are completely visible and fill out the viewport area. If no objects are currently selected then this command acts like the command above.

Maximize Viewport

Maximizes the active viewport to fill the complete viewport area of the main window. All other viewports will be temporarily hidden behind the maximized viewport. Invoking this command again restores the old viewport layout.

5.1.4. Animation toolbar

Go to first frame

Jumps to the first frame of the animation.

Go to last frame

Jumps to the last frame of the animation.

Go to previous frame

Steps one frame back in the animation.

Go to next frame

Steps one frame forward in the animation.

Play Animation

Starts/stops playing the animation in the viewports.

Animation Mode

Enables/disables animation mode. Changing a numerical parameter or the position of some object in the scene while the animation mode is active will generate an animation keyframe. A red animation time slider and a red viewport border indicates that the animation mode is active.

Animation Settings

Opens the Animation Settings Dialog box.

Current Animation Frame

Numerical input box that controls the current animation position. It is meant as an alternative way of jumping to a certain animation time in addition to the Animation Time Slider.

5.1.4.1. Animation time slider

The animation time slider is located below the viewports area. It can be dragged with the mouse to navigate in time. The available slider range is defined by the current animation interval which can be set in the Animation Settings Dialog.

5.1.4.2. Animation settings dialog

This dialog lets the user setup the animation for the current scene. The animation speed is given as frames per second and can only be changed in discrete steps because OVITO internally works with a time unit called time ticks. One time tick is a 1/4800 of a second allowing only integer divisors of 4800 for the frames per second value.

The duration of the animation is defined by the start frame number and the end frame number. The number of animation frames is given by the formula (end – start + 1).

Changing the frames per second value will automatically alter the number of animation frames to keep the animation length in seconds constant. It will also rescale the positions of all animation keys in the scene to preserve their timing.

To just change the playback speed for the animation in the viewports without touching the animation keys and the animation interval a playback speed multiplier can be set in the dialog.

5.2. Rendering

5.2.1. Render settings

Figure 5.1. The Render settings panel

The Render settings panel


This parameter panel lets you control the general settings used for rendering a static image or movie sequence of your scene.

Rendering range

You can either render a single image of the current time frame or the complete animation if you have loaded a sequence of snapshots into OVITO. If you select the Complete Animation option then you have to specify an output image file. This filename will be used as a basename for a sequence of numbered image files.

Image width/height

Specifies the output image width and height in pixels. The ratio of both values controls the shape of the final image. To check the current aspect ratio you can right-click on the title of a viewport in its top left corner and activate the Show Render Frame option.

Background color

Controls the background color of the output image.

Generate alpha channel

If you save the renderer image to a file format that supports an alpha channel (in addition to the RGB channels) then this option will let you save the transparency information to the output file. The PNG format is a popular image format that supports alpha channels. The transparency information is very useful if you plan to position the rendered image in front of an arbitrary background, i.e. on a presentation slide. Then, the background will show through those parts of the image that are not covered by atoms.

Output filename

The destination file path for the rendered image. The file suffix specifies the file format to be used. Common image formats like .JPG and .PNG are supported. If you do not specify an output filename here then the rendered image will only be shown in a window and you have the possibility to save it later.

To start the rendering process press the Render Active Viewport button above the Render Settings panel.

5.2.2. Preview renderer

Figure 5.2. The Preview renderer settings panel

The Preview renderer settings panel


This renderer backend is the default built-in renderer used by OVITO to create static images of the current scene. It utilizes the same display engine used for the realtime viewports.

Antialiasing level

To reduce aliasing effects the scene can be rendered with a higher resolution than the final image. This factor controls how much higher this resultion is. A factor of 1 means no anti-aliasing. Higher values lead to a better quality. Be aware that higher resolutions require more graphics card memory.

5.2.3. POV-Ray renderer

Figure 5.3. The POV-Ray Renderer settings panel

The POV-Ray Renderer settings panel


This renderer backend is based on the external POV-Ray program. See Section 4.4 on how to activate this renderer.

POV-Ray is a third-party raytracing program that is freely available. It can produce high-quality pictures of geometric objects taking into account reflections, lighting, shadows and textures. The POV-Ray rendering plug-in of OVITO first translates the current scene including all the atoms into the format of POV-Ray. It then invokes the external POV-Ray program in the background and lets it render the image. After POV-Ray has finished, the resulting image is read back into OVITO. This all happens transparently for the user.

Note

This function is only available if you have built OVITO with the OVITO_BUILD_PLUGIN_POVRAY option enabled.

This renderer requires the external povray program to be installed on your system.

OVITO also has an export function that let's you export the scene to a file in the POV-Ray format. This allows you to further customize the POV-Ray scene before it is processed by the POV-Ray program.

5.3. Atoms object

Figure 5.4. The parameter panel of the Atoms object

The parameter panel of the Atoms object


Note

Sorry, this topic is not documented yet.

5.3.1. Simulation cell

Figure 5.5. The parameter panel of the simulation cell

The parameter panel of the simulation cell
The parameter panel of the simulation cell


Note

Sorry, this topic is not documented yet.

5.4. Import atoms object

Figure 5.6. The parameter panel of the Import Atoms object

The parameter panel of the Import Atoms object


After importing a data file an instance of this object is created in the scene. It acts as a source for the processing pipeline by creating an Atoms Object from the data parsed from the input file. The properties of the Atoms Object are shown below the Import Object in the properties panel.

Note

Sorry, this topic is not fully documented yet.

5.5. Modifiers

Modifiers are the basic building blocks of OVITO's processing pipeline. Each type of modifier performs a particular operation. They modify the atomistic simulation data loaded into OVITO before it is displayed on the screen.

You can add a new modifier to the current processing pipeline by choosing an entry from the modifier drop-down list in the upper right part of the main window. To see the drop-down list you might have to activate the Modify tab first.

Table 5.1. Modifiers

Modifier nameShort description
Ackland AnalysisPerforms an Ackland-Jones bond-angle analysis to determine the local crystal structure.
Add Expression ChannelCreates/assigns a new property to each atom based on a user defined expression.
Assign Atom Type ColorAssigns a color to each atom based on the its type.
Assign ColorAssigns a color to all selected atoms.
Affine TransformationApplies a coordinate transformation to atoms.
Calculate DisplacementsCalculates displacement vectors for atoms based on an initial and final state of the system.
Color CodingAssigns a color to each atom based on some other property.
Common Neighbor AnalysisPerforms a common neighbor analysis (CNA) to determine the local crystal structure.
Delete Selected AtomsDeletes all currently selected atoms.
Invert SelectionInverts the selection state of each atom.
Freeze SelectionPreserves the current selection state over time.
Select Atom TypeSelects atoms of a certain type.
Select By ExpressionSelects atoms based on a user defined criterion.
Show Periodic ImagesDisplays the periodic images of every atom.
SliceCuts out a slice or a cross-section from the atomic structure.
Wrap Periodic ImagesMaps atoms outside of the simulation box into the box.


5.5.1. Ackland Analysis

This modifier performs an analysis based on the Ackland-Jones bond-angle distribution [Ackland and Jones, Phys. Rev. B 73, 054104 (2006)] to classify atoms w.r.t. to their local crystalline structure (FCC, BCC, HCP etc.).

The usage of this modifier is similar to the Common Neighbor Analysis modifier. See its documentation for details.

5.5.2. Add Expression Channel

Figure 5.7. The parameter panel of the Add Expression Channel modifier

The parameter panel of the Add Expression Channel modifier


This modifier can be used to fill a data channel with new values based on a user-defined math expression. The mathematical formula specified by the user is evaluated by the modifier for every atom in the input structure an the results are stored in the selected target channel. The target data channel can be any existing or non-existing channel. This allows to control every atomic property (like position, color, etc.) with this modifier.

The mathematical expression can contain references to other atomic properties stored in the data channels of the input atoms objects. The list of input variables that may be used in the formula is derived from the available data channels and is displayed in the lower part of the modifier interface. Variable names are case-sensitive.

Parameters

Data channel to create

Specifies the target data channel that should be filled with the calculated values. You have the choice between a new custom data channel to be used as target channel and one of the predefined standard data channels.

A new custom data channel might be right choice if your want to derive a new per-atom value from the existing atomic properties based on a math formula. For example, you could calculate the length of the velocity vector to gain the scalar velocity of each atom and store it in a new channel. This new channel would then be usable as basis for color-coding the atoms.

Using one of the standard data channels, e.g. the Position data channel, as target channel can be useful if you want to modify the atoms in some way, e.g. to recalculate their positions, apply a displacement field, etc.

Name

The name of the new custom data channel to create. This parameter does not apply if you have chosen one of the standard channels as target channel.

Data type

The data type of the new custom data channel to create. You have the choice between integer numbers and floating-point numbers. If you choose integer here then the values obtained from the user-defined formula will automatically be truncated to iunteger numbers. This parameter does not apply if you have chosen one of the standard channels as target channel.

Number of components

The number of vector components of the new custom data channel to create. This parameter allows you to create channels that contain more than one value per atom. For each vector component you will have to specify a formula. This parameter does not apply if you have chosen one of the standard channels as target channel. In this case the number of vector components is determined by the standard channel you chose.

Show channel

This controls the visibility of the target channel. Each data channel has a visibility flag that controls whether the information stored in the channel is displayed in the viewports. The meaning of the visibility flags depends on the type of the data channel. For example, the visibility flag of the Position data channel controls whether the atoms are rendered in the viewports or not. The visibility flag of the Displacement data channel contromotionls whether the displacement vectors are shown in the viewports. For most of the other standard data channels and for all custom data channels the visibility flag does not have a meaning and is ignored.

Calculate values only for selected atoms

If this flag is set then the math formula is only evaluated for those atoms that are selected in the input structure. This option makes only sense if you choose an existing data channel as target channel to overwrite the values stored in this channel. This option allows you to recalculate only the values of the selected atoms.

Expressions

This panel contains one input field for every vector component of target data channel. In each field you have to enter a mathematical expression that will be evaluated for each atom. The expression syntax understood by the modifier is very similar to the C-syntax. Arithmetic expressions can be created from float literals, variables or functions using the following operators in this order of precedence:

()expressions in parentheses are evaluated first
A^Bexponentiation (A raised to the power B)
A*B, A/Bmultiplication and division
A+B, A-Baddition and subtraction
A==B, A!=B, A<B, A<=B, A>B, A>=Bcomparison between A and B (result is either 0 or 1)
A and Bresult is 1 if A and B differ from 0, else 0
A or Bresult is 1 if A or B differ from 0, else 0

The expression parser supports the following functions:

abs(A)Absolute value of A. If A is negative, returns -A otherwise returns A.
acos(A)Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A.
acosh(A)Same as acos() but for hyperbolic cosine.
asin(A)Arc-sine of A. Returns the angle, measured in radians, whose sine is A.
asinh(A)Same as asin() but for hyperbolic sine.
atan(A)Arc-tangent of A. Returns the angle, measured in radians, whose tangent is A.
atan2(A,B)Two argument variant of the arctangent function. Returns the angle, measured in radians. This function is documented here.
atanh(A)Same as atan() but for hyperbolic tangent.
cos(A)Cosine of A. Returns the cosine of the angle A, where A is measured in radians.
cosh(A)Same as cos() but for hyperbolic cosine.
exp(A)Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.
if(A,B,C)If A differs from 0, the return value of this function is B, else C.
rint(A)Rounds A to the closest integer. 0.5 is rounded to 1.
ln(A)Natural (base e) logarithm of A.
log10(A)Base 10 logarithm of A.
log2(A)Base 2 logarithm of A.
max(A,B,...)Returns the maximum of all values.
min(A,B,...)Returns the minimum of all values.
sin(A)Sine of A. Returns the sine of the angle A, where A is measured in radians.
sinh(A)Same as sin() but for hyperbolic sine.
sqrt(A)Square root of a value.
tan(A)Tangent of A. Returns the tangent of the angle A, where A is measured in radians.

Examples for expressions understood by the modifier:

						  exp(PotentialEnergy)
						  sqrt(Velocity.X^2 + Velocity.Y^2 + Velocity.Z^2) 
						

5.5.3. Assign Atom Type Color

This modifier fills the Color channel according to the colors assigned to the atom types.

This modifier has no parameters.

5.5.4. Assign Color

This modifier assigns a color to all selected atoms. If no selection of atoms has been defined then the color is assigned to all atoms.

Note that selected atoms are usually shown in a special color (red) to indicate that they are selected. The selection color therefore masks the actual colors of the atoms (stored in the Color data channel). After applying this modifier the selection channel gets hidden, i.e. the selection color is no longer used to mark selected atoms. Instead you see the real colors of the atoms as they have been assigned by this modifier. But the selected atoms remain selected, i.e. you can apply additional modifiers that should operate on the same set of atoms.

Parameters

Color

The color to be assigned to every selected atom.

5.5.5. Affine Transformation

Figure 5.8. The parameter panel of the Affine Transformation modifier

The parameter panel of the Affine Transformation modifier


Applies an affine transformation to the atomic positions and/or the simulation cell. The transformation is specified as a 3 times 3 matrix plus a translation vector.

Parameters

Apply transformation to simulation box

Controls whether the affine transformation is applied to the simulation cell (excluding the atoms).

Apply transformation to atoms

Controls whether the affine transformation is applied to the atomic positions. You can choose which atoms are affected by the modifier: Either all atoms or only selected atoms.

Rotate/Scale/Shear

This 3x3 matrix specifies the affine transformation. The atomic position vectors are multiplied by this matrix.

Translation

An additional translation vector that is added to the atomic positions and/or the simulation box after they have been multiplied by the 3x3 matrix.

5.5.6. Calculate Displacements

This modifier calculates the atomic displacement vectors. This is done by comparing two different configurations of the same system.

The current input file is considered as the current configuration of the system by the modifier. Additionally the user specifies a second input file (with the same number of atoms) which is taken as the reference configuration of the system. The modifier then calculates the displacement vectors by subtracting the reference position from the current position of each atom. The results are stored in the Displacement channel and can be visualized as arrows in the viewports. One can use the Color Coding modifier to visualize the displacements via colors.

In the parameter panel of this modifier you find a [Choose File...] button that lets you choose the input file containing the atomic reference positions. Please note that this input file has to contain exactly the same number of atoms as the current configuration of the system. This also means that you should not delete atoms from the system at an earlier point in the processing pipeline. For example a Slice modifier should always be placed after the Calculate Displacements modifier to ensure that the Calculate Displacements modifier sees all atoms contained in the input file which is fed into the processing pipeline. If the number of atoms do not match the Calculate Displacements modifier reports an error and the displacement vectors are not calculated at all.

A second point you should be aware of when using the Calculate Displacements modifier is the ordering of the atoms. Many parallel MD codes write the atoms in a random order to the output file and the ordering of atoms can change between time steps, especially in parallel simulations. To facilitate the tracking of individual atoms they therefore write a unique identifier (or index) for each atom into the output file. You have to make sure that this index is read from the atoms file during import into OVITO for both the current configurations as well as for the reference configuration to ensure the same ordering for both sets. Because if, for some reason, the ordering of the atoms is different in the two configurations compared by the Calculate Displacements modifier then you will most likely observe huge displacement vectors.

Below the parameter panel of the Calculate Displacements modifier your find a second panel that lets you configure the display parameters for the Displacement channel that is created by the modifier.

Parameters

Show reference configuration

If this option is turned on then you will see the atomic positions as they are read from the second input file, i.e. the reference state. Actually this will swap the role of the current configuration of the system and the reference configuration. By default this option is turned off and you see the atoms located at their current positions and the displacement vectors point from the reference positions to the current positions.

5.5.7. Color Coding

Figure 5.9. The parameter panel of the Color Coding modifier

The parameter panel of the Color Coding modifier


This modifier colors all atoms based on a scalar property value of each atom. The Color coding modifier can be used to visualize a scalar and continuous property assigned to each atom, e.g. the atomic energy. The Color coding modifier operates as follows: The user first selects a data channel that should be used as source for the per-atom data values. For each atom the corresponding data value is scaled and clamped to the [0,1] range using the Start value and End value parameters of the modifier. This scaled value is then converted to a color based on the selected color gradient and then assigned to the atom.

The properties editor of the Color coding modifier provides two buttons that alter the start and end value parameters of the modifier: The Adjust range button sets the Start value and End value parameters to the minimum and maximum values found in the input data channel. This ensures that no clamping occurs during the color coding process. The Reverse range button swaps the Start value and End value parameters to reverse the color scale.

Parameters

Data channel

The input data channel that provides the scalar value for each atom from which the color coding is computed.

Color gradient

This parameter controls how scalar values are mapped to colors. In the current program version you have the choice between a rainbow color gradient and a grayscale gradient.

Start value, End value

These parameters control the linear mapping of the input values to the [0,1] range.

5.5.8. Common Neighbor Analysis

Figure 5.10. The parameter panel of the Common Neighbor Analysis modifier

The parameter panel of the Common Neighbor Analysis modifier


This modifier performs a common neighbor analysis [Honeycutt and Andersen, J. Phys. Chem., 91, p. 4950] to classify atoms according to their local crystalline structure (FCC, BCC, HCP etc.). This analysis method is based on a nearest-neighbor graph, i.e. a mathematical graph consisting of edges that connect nearest neighbor atoms. Which atoms are considered nearest neighbors is determined by a user-defined cutoff distance. Atoms closer to each other than the given threshold radius are connected by an edge in the abstract graph. The common neighbor analysis (CNA) then exclusively operates on this mathematical graph structure, i.e. only the topological nearest-neighbor information is used to determine the crystalline arrangement around each atom. Each crystal structure exhibits a characteristic local topology of the nearest-neighbor graph.

A typical application of the CNA is to identify crystal defects in a crystalline solid.

The user has to specify a reasonable cutoff radius first. This decision depends on the primary crystal structure and the lattice constant of the material under consideration. To detect face-centered cubic (FCC) and hexagonal close packed (HCP) structures the cutoff radius must be chosen such that it lies midway between the first and the second shell of neighbor atoms. For body-centered cubic (BCC) and crystalline materials with a diamond structure the cutoff radius should, however, be chosen between the second and the third neighbor shell.

OVITO provides a database of optimal nearest-neighbor cutoff distances for many pure elements. These presets can be accessed via the drop-down list in the parameter panel. When building the nearest-neighbor graph the CNA modifer uses the periodicity settings of the simulation box. The periodic boundary conditions can be specified in the properties panel of the simulation box. To access the simulation box properties select the imported atoms file at the bottom of the modifier stack.

Note: To build the nearest-neighbor list of atoms for perodic systems, the analysis code applies the minimum image convention. This requires the simulation cell to be at least twice as wide as the cutoff radius in each spatial for which perodic boundary conditions are enabled. The analysis code detects when the simulation box is too small and will show an error message.

The Common Neighbor Analysis modifier is a so called analysis modifier. That means, in contrast to normal modifier, it analyzes the atomic dataset instead of modifying it. The analysis is computationally intensive and cannot be done in realtime, hence, the user has to explicitely press the Calculate button to run it. The analysis results, i.e. the local crystalline structure of each atom, get stored in the CNA Atom Type data channel of the atoms. In addition, a color is assigned to each atom that indicates its detected crystal structure. The color legend is located in the parameter panel of the modifier and colors can be changed by double-clicking on the entries of the legend.

A technical detail must be noted: The analysis is always performed on the current state of the atomic system as it is visible to the Common Neighbor Analysis modifier in the processing pipeline. If, for example, the Common Neighbor Analysis modifier is preceded by a Slice modifer that deletes some of the atoms then the CNA will assume that these atoms have never been there. The Common Neighbor Analysis modifier should therefore be placed very early in the processing pipeline to let it operate on the full system including all atoms. Normal modifiers like the Slice modifer should always be placed after the analysis modifiers.

Parameters

Cutoff radius

This threshold parameter specifies the distance range within which atoms are considered nearest neighbors. As described above this parameter must chosen specific to the material under consideration.

Auto-update on time change

Activate this option to enable semi-automatic recalculation of the analysis for each animation timestep. This is necessary if you want to perform the analysis for a series of data files. When enabled the analysis is performed each time you change the current animation time. The same is true if you render the whole animation to a series of output images or if you export all timesteps in a row.

If this option is not set then the analysis results will only be updated when you explicitely press the Calculate button.

Type colors

This list box is a color legend that displays the color associated with each crystal structure type. Double-click on an entry in the list to change its color.

5.5.9. Delete Selected Atoms

This modifier simply deletes all atoms that are currently selected.

5.5.10. Invert Selection

This modifier inverts the atom selection. All atoms that have not been selected previously will be selected by this modifier. All atoms that have been selected before will become unselected.

5.5.11. Freeze Selection

This modifier can be used to preserve a selection over time. Immediately after the modifier is applied to the atoms it records the current selection state of all atoms. From then on it will override any existing atom selection with its cached selection set, independent of animation time.

A typical application of this modifier is making the displacement or motion of atoms visible. You first use e.g. the Slice modifier to select a slab of atoms in a region you want to track. Then you apply the Freeze Selection modifier to freeze this selection for all times. Now you can jump to another timestep in your simulation and the initially selected atoms stay selected. You can easily see where they have moved to. Without the Freeze Selection modifier the Slice modifier would have been re-eavluated for the new timestep and the old selection would have got overwritten.

Note that the preserved selection state can only be sustained by the Freeze Selection modifier as long as the number of atoms does not change. In such a case the modifier will not restore the saved selection state but will leave the current selection state of the input atoms untouched.

5.5.12. Select Atom Type

This modifier selects all atoms of a specific type.

Parameters

Data Channel

This drop-down list contains all data channels that can be used as input for the modifier. Sometimes an atom can belong to more than one group depending on the classification. For instance, an atom can be of type Fe and BCC at the same time. In the previous example the chemical element of the atoms is stored in the Atom Type data channel whereas the local lattice structure of the atoms is stored in the CNA Type data channel.

With this parameter you can choose on which information the selection should be based.

Atom Type

This list box shows all existing atom types for the selected data channel. You can select one or more entries in the list by holding down the Control key. All atoms belonging to the selected entries will become selected; all other atoms become unselected.

5.5.13. Select By Expression

This modifier selects atoms based on a user-defined criterion. The user can specify a math expression that is evaluated for each atom to yield a boolean value. That is, if the math expression evaluates to exactly zero then the atom is not selected; otherwise it is selected.

The mathematical expression can contain variables that reference other atomic properties stored in the data channels of the input atoms objects. Therefore this modifier can be used to select atoms based on arbitrary properties like their position, atom type, energy etc. and any combination thereof. The list of input variables that are derived from the available data channels is displayed in the lower part of the modifier interface. Variable names are case-sensitive.

Parameters

Boolean expression

This specifies the mathematical expression to be evaluated for each atom. The expression syntax understood by the modifier is very similar to the C-syntax. Arithmetic expressions can be created from float literals, variables or functions using the following operators in this order of precedence:

()expressions in parentheses are evaluated first
A^Bexponentiation (A raised to the power B)
A*B, A/Bmultiplication and division
A+B, A-Baddition and subtraction
A==B, A!=B, A<B, A<=B, A>B, A>=Bcomparison between A and B (result is either 0 or 1)
A and Bresult is 1 if A and B differ from 0, else 0
A or Bresult is 1 if A or B differ from 0, else 0

The expression parser supports the following functions:

abs(A)Absolute value of A. If A is negative, returns -A otherwise returns A.
acos(A)Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A.
acosh(A)Same as acos() but for hyperbolic cosine.
asin(A)Arc-sine of A. Returns the angle, measured in radians, whose sine is A.
asinh(A)Same as asin() but for hyperbolic sine.
atan(A)Arc-tangent of A. Returns the angle, measured in radians, whose tangent is A.
atan2(A,B)Two argument variant of the arctangent function. Returns the angle, measured in radians. This function is documented here.
atanh(A)Same as atan() but for hyperbolic tangent.
cos(A)Cosine of A. Returns the cosine of the angle A, where A is measured in radians.
cosh(A)Same as cos() but for hyperbolic cosine.
exp(A)Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.
if(A,B,C)If A differs from 0, the return value of this function is B, else C.
rint(A)Rounds A to the closest integer. 0.5 is rounded to 1.
ln(A)Natural (base e) logarithm of A.
log10(A)Base 10 logarithm of A.
log2(A)Base 2 logarithm of A.
max(A,B,...)Returns the maximum of all values.
min(A,B,...)Returns the minimum of all values.
sin(A)Sine of A. Returns the sine of the angle A, where A is measured in radians.
sinh(A)Same as sin() but for hyperbolic sine.
sqrt(A)Square root of a value.
tan(A)Tangent of A. Returns the tangent of the angle A, where A is measured in radians.

Examples for expressions understood by the modifier:

								
						  AtomType==1 or AtomType==2
						  
						  sqrt(Position.X*Position.X + Position.Y*Position.Y) < 10
						

Highlight selected atoms

Controls whether the atoms being selected by this modifier should be colored with the default selection color to make the selection visible.

5.5.14. Show Periodic Images

Copies all atoms and displaces them by the simulation cell vector to show the periodic images of the system.

This modifier can be used to check a simulation setup with periodic boundary conditions or to extend a small super cell. The display of the periodic images allows the user to quickly check whether a lattice, for instance, is properly continued on the other side of the simulation box.

Parameters

Show periodic images (X,Y,Z)

Enables the display of periodic images of the system in the three spatial directions.

Adjust simulation box size

If this option is enabled then the simulation cell size is adjusted to match the extended system.

5.5.15. Slice

Figure 5.11. The parameter panel of the Slice modifier

The parameter panel of the Slice modifier


The Slice modifier cuts away atoms based on their position. There are two operation modes for the Slice modifier. It can either cut the set of atoms into two halfs and throw away one of them. Or it can cut out a thin slice from the atoms.

When the Slice modifier is selected in the modifier list then the slicing plane is visualized in the viewports. Its position is indicated by lines showing the plane's intersection with the simulation box. You should be aware that the slicing plane is going through the coordinate origin by default when you create a new Slicing modifier. If the simulation cell is located in some distance from the origin than it might not be intersected by the slicing plane and you won't see any indicators in the viewports. In this case try to vary the Distance parameter to make the plane intersect the simulation box.

At the bottom of the modifier's parameter panel you'll find several buttons that allow to align the slicing plane with the viewing direction of the selected viewport and vice versa. In addition you can align the slicing plane to a space plane defined by three non-coplanar atoms. To use this function first press the button and then pick three atoms in the viewports.

Parameters

Distance

This parameter controls the distance of the slicing plane from the coordinate system's origin. It is measured in the direction of the normal vector of the plane given by the next three parameters. It can be either positive or negative.

Normal (X,Y,Z)

These three parameters specify the components of the slicing plane's normal vector. It doesn't have to be a unit vector.

Slice Width

Specifies the width of the slice to cut out from the atomic structure. If this parameter is exactly zero then a complete half of the structure on the positive side of the slicing plane is cut away. For positive values of the slice width parameter all atoms farther away from the slicing plane than half of the slice width get deleted. What remains is a thin slice with the given width.

Invert

Inverts the behavior of the modifier, i.e. reverses the slicing plane's orientation.

Select atoms (do not delete)

When this option is active then the modifier selects the atoms instead of deleting them.

Apply to selected atoms only

With this option active the modifier touches only those atoms that were selected previously. This option can be used to confine the modifier's operation to a sub-set of the atoms.

5.5.16. Wrap Periodic Images

This modifier wraps around the atomic positions of all atoms that are outside of the simulation box. After this modifier has been applied all atoms are located inside the box.

Please note that the modifier acts only in those spatial directions for which periodic boundary conditions have been enabled. This is the case for all three directions of the simulation cell by default.

5.6. Standard data channels

OVITO knows a number of standard properties that can be associated with atoms. These properties are organized into so-called data channels. This section contains descriptions of the standard data channels.

5.6.1. Atom Type

Stores the type of each atom. The definition of the atom types depends on the simulation software that produced the atom file. For example, the atom type could be encoded as the chemical element or as a plain number between 1 and the number of atom types in a simulation.

Internally, OVITO stores each atom's type as an integer starting with zero. It is used as an index into the array of atom types associated with the Atom Type data channel. Some of the entries in this list of atom types may be empty if there are no atoms of this type. For instance, the first atom type at index zerois undefined in most cases since most simulations programs start counting atom types at one. So there are no atoms with atom type zero and the Atom Type data channel contains only positive values.

The parameters of the Atom Type data channel control how the atom types are displayed in the viewports. This section of the manual is not complete yet.

5.6.2. Position

Stores the atomic positions as absolute XYZ values. The units used for the atomic coordinates depend on the input file.

The Position data channel has several parameters that control the display of atoms in the viewports. This section of the manual is not complete yet.

5.6.3. Displacement

Stores the displacement vector for each atom. The displacement vector specifies the motion of an atom between two states of the simulated system and can either be calculated using the Calculate displacements modifier or loaded from the input file if available.

The Displacement data channel has several parameters that control the display of displacement vectors in the viewports. This section of the manual is not complete yet.

5.6.4. CNA Atom Type

Stores the local crystal structure as determined by the Common Neighbor Analysis modifier.

This section of the manual is not complete yet.

5.6.5. Color

Stores the color of each atom. If the Color channel is present it overrides the colors specified in the Atom Type channel.

This section of the manual is not complete yet.

5.7. Import formats

OVITO can import several file formats written by different simulation packages. This section lists all supported formats.

5.7.1. LAMMPS dump files

OVITO can import dump files written by the LAMMPS molecular dynamics package.

The import filter can parse dump files in text and binary format. Compressed files (with a .gz suffix) are decompressed on the fly.

5.7.2. LAMMPS data files

OVITO can import data files written by the LAMMPS molecular dynamics package.

Only data files in the atomic format are supported. If the data files contains velocity vectors, they are imported.

Loading of compressed data files is supported. If the input file has a .gz suffix then it is decompressed on the fly.

5.7.3. XYZ files

OVITO can import XYZ text files written by several atomistic simulation packages. The XYZ format is a simple column-based format, which is documented here.

Note

The XYZ format doesn't store the simulation cell dimensions. OVITO assumes that the simulation cell is an axis aligned box that includes all atoms when loading a XYZ file.

Loading of compressed files is supported. If the filename has a .gz suffix then it is decompressed on the fly.

5.7.4. POSCAR files

OVITO can import POSCAR files written by the ab initio simulation package VASP.

5.7.5. IMD files

OVITO can import files written by the molecular dynamics code IMD.

5.8. Export formats

OVITO can export the atomic coordinates to several file formats. This section lists all supported formats.

5.8.1. LAMMPS dump files

OVITO can write dump files as produced by the LAMMPS molecular dynamics package.

The export filter can write dump files in text and binary format.

If the output filename has a .gz suffix then the dump file is compressed on the fly.

5.8.2. LAMMPS data files

OVITO can write data files, which can be read the LAMMPS molecular dynamics package.

If the atomic data to be exported contains velocity information it is written to the LAMMPS data file.

If the output filename has a .gz suffix then the data file is compressed on the fly.

5.8.3. XYZ files

OVITO can export the atomistic data to XYZ text files. The XYZ format is a simple column-based format, which is documented here.

5.8.4. POSCAR files

OVITO can write POSCAR files as produced by the ab initio simulation package VASP.

5.8.5. POV-Ray files

OVITO can export the atomistic data to scene description files in the POV-Ray format. POV-Ray is a raytracing program.

Note

This function is only available if you have built OVITO with the OVITO_BUILD_PLUGIN_POVRAY option enabled.