# Tutorial - First steps with OVITO

The aim of this tutorial is to make you familiar with the software OVITO. To let you repeat the steps, the example dataset used in this tutorial is included in the subdirectory `share/ovito/examples/tutorial1/` of your OVITO installation.

## Importing the simulation dataset

The first step when using OVITO is to import the simulation data to be visualized. OVITO can read a number of file formats written by popular simulation packages, and will try to detect the format of a file automatically. We import the simulation snapshot into OVITO by selecting the File Import command from the main menu, the corresponding button in the toolbar, or with the Ctrl i keyboard shortcut. This will open a file selector dialog as shown in .

The File Selector Dialog

Go to the directory `share/ovito/examples/tutorial1/`, which contains the example file `NanocrystallinePd.dump.gz`. This file is a compressed LAMMPS dump dataset obtained from an MD simulation of nanocrystalline palladium. OVITO detects the format of the file automatically, and decompresses it on the fly since it has the `*.gz` name suffix.

The import settings dialog

After opening the file, a second dialog () pops up, letting you assign data columns stored in the file to OVITO's internal data channels. OVITO's internal data model consists of so-called data channels that store the atomic properties read from an input file. Each data channel holds a single atomic property, e.g. the position or the velocity vector of each atom. OVITO provides a set of standard data channels for often-used properties like the atomic coordinates, atom type, energy, etc. Beyond that, you are free to define your own data channels in OVITO and feed them with data generated by your simulation software.

Since dump files produced by the LAMMPS simulation code may contain an arbitrary set of data columns, it is necessary to tell OVITO which column contains what, e.g. the atomic positions (X, Y, and Z coordinates). That is, we need to map columns in the input file to OVITO's internal data channels. The header of our example file already contains auxiliary information describing the contents of each file column. The column titles, as read from the input file, are shown in the left-most column ob the table (`id`, `x`, `y`, `z`, and `c_epot`). Based on these column identifiers written by LAMMPS, OVITO can automatically guess the mapping to its internal data channels. All you need to do is to press the Auto-assign columns button. As shown in , OVITO selects a proper data channel for each input data column. Note that only newer versions of LAMMPS produce such self-describing dump files. Dump files written by older versions, or XYZ files written by other codes, do not store the data column identifiers in the file header. In such cases, the Auto-assign columns button will be disabled, and you have to specify the data channels manually.

As can be seen in , there are five data columns in the example file (`id`, `x`, `y`, `z`, `c_epot`), each one being represented by a row in the mapping table. The first file column contains the atomic index, which is a unique identifier assigned to each atom, followed by the three coordinates, and finally the atomic potential energy in the fifth column. These five columns are mapped to three internal data channels in OVITO named `Atom Index`, `Position`, and `Potential Energy`. The `Position` data channel is a so-called vector data channel, which is composed of three sub-components (X, Y, and Z).

Since the example file contains only a single simulation snapshot, leave the option File contains single snapshot selected and press OK to import the data.

## Using the viewports

After importing the simulation dataset you are now back to OVITO's main window (). You find the usual menu and tool bars at the top and the bottom of the window. The center part of the main window is divided into two areas: The large viewport area on the left (which itself is sub-divided into four viewports) and the command panel on the right.

OVITO after loading the sample dataset

The viewports display a three-dimensional view of the simulation snapshot that we just imported. Note how the four viewports, which are called `Top`, `Front`, `Left`, and `Perspective`, show the same data from different viewing directions. Click on the title of one of the viewports to activate its viewport menu. It allows you to choose a different viewing direction. You might prefer one large viewport at times. For this, select one of the viewports by right-clicking into it first; then press the Maximize Active Viewport ( ) button in the lower right corner of the main window to enlarge the current viewport. Press the same button again to restore the 4-viewports layout.

Main window with a maximized viewport

At the bottom of the main window you find more buttons to control the viewports. The three navigation buttons ( , , ) allow you to navigate in the three-dimensional scene by moving the virtual camera associated with a viewport. First activate one of the buttons, then click and drag the mouse in one of the viewport windows. When done, right-click in the viewport to exit the navigation mode again.

It is highly recommended to use the keyboard shortcuts to navigate in the viewports, because it is considerably faster than using the tool buttons. For instance, by holding down the shift key on your keyboard while using the middle mouse button in the viewports you can rotate the camera at any time. To learn how to navigate in the viewports with such keyborard shortcuts, see this section of the reference manual.

To the right of the viewport area you find the command panel. It is organized into three tabs located at the top: the Modify , Render and Utilities tab. The Modify tab lets you modify the simulation data and control its visualization (see next section). This is where you will spend most of the time while working with OVITO. The Render tab lets you create images for publication and the Utilities tab provides access to additional tools that you might find useful.

Further information on the user interface of OVITO can be found in of the reference manual.

## Working with modifiers

Before you continue with the tutorial, you should read of the manual to learn about modifiers and the processing pipeline. These fundamental concepts will be demonstrated in the following.

### Applying the `Slice` modifier

The processing pipeline of OVITO is initially empty. So let us now insert a first modifier, which will be applied to the dataset that we just imported into OVITO.

The list of available modifier types can be found in the drop-down listbox labeled "Modifier List" at the top of the Modify tab in the command panel. Select the entry named `Slice` from the list to insert a `Slice` modifier into the pipeline. The current pipeline is displayed in the listbox below the drop-down field. It should now contain several entries: The `Slice` modifier that you just inserted and the entry `Data source`, which denotes the input of the modification pipeline. The `Data source` has two subitems, `Simulation cell` and `Atoms display`, which allow you to control the display of the simulation box and the atoms. The `Data source` entry is separated from the actual modification pipline by a horizontal line, and the modifiers in the current pipeline are applied to the input data in bottom-up order!

Using the Slice modifier

The `Slice` modifier cuts away all atoms on one side of an infinite plane in space. It can, for instance, be used to look inside a solid structure like our cubic specimen. The slicing plane is specified by its normal vector and its distance from the origin of the coordinate system. These parameters can be adjusted in the panel "Slicing plane" found below the pipeline listbox. Note that this parameter panel always displays the properties of the currently selected entry in the pipeline.

To change the value of a numerical parameter of the Slice modifier such as `Distance`, you can either enter a new numerical value into the corresponding input field or change the value interactively with the mouse by clicking the small up/down arrow buttons next to the input field. Hold and drag the mouse vertically to continuously adjust the parameter's value. Whenever you change a parameter's value, OVITO automatically recomputes the effect of the modifier and updates the viewports in realtime.

Now try to adjust the slicing plane such that it becomes parallel to the (110) plane by setting the parameter `Normal (Y)` to -1 as shown in . Since the coordinate system's origin is located in the center of the simulation box, a value of zero for the `Distance` parameter will let the slicing plane pass right through the box center. More information on the other settings of the `Slice` modifier can be found in of the reference manual -or simply by playing with the parameters yourself.

### Assigning colors to atoms

The `Slice` modifier deletes part of the atoms before the dataset is rendered in the viewports by OVITO. Other modifiers, in contrast, change the per-atom values stored in the data channels. One example for this type of modifier is the `Color Coding` modifier. It assigns a color to each atom based on the value of another property of that atom. We are going use this modifier now to visualize the local potential energy of atoms, which has been precomputed by the MD simulation code.

From the modifier drop-down list, select the entry `Color Coding` to add this modifier to the pipeline. In the parameter panel of the newly added modifier, select `Potential Energy` from the data channel list and click the Adjust range button. This will adjust the color scale to the minimum and maximum energies stored in the LAMMPS file. The `Color Coding` modifier maps the atomic energies in the range specified by `Start value` and `End value` to the color gradient displayed in the panel. You can play with the start and end values to see how the colors of the atoms change.

Color coding

### Selecting atoms

Expression Select modifier

Sometimes you might want to select atoms with specific properties. OVITO provides a powerful mechanism for this: the `Expression Select` modifier.

Add this modifier to the pipeline now. In the properties panel of the newly inserted modifier, you find a text field where you can enter a Boolean expression. This expression will be evaluated by OVITO for each individual atom. If the expression yields `TRUE` then the atom is selected; otherwise it is deselected. The syntax of Boolean expressions is described in .

Enter the text `PotentialEnergy > -3.85` into the expression field and press the Enter key to select all atoms with a potential energy above -3.85 eV. The set of per-atom variables that you can reference in the expression are listed in the Variables panel.

Now that we have selected a subset of the atoms, we can continue by adding more modifiers to the pipeline, which act only on the selected atoms. Let's assign a specific color to the selected atoms to highlight atoms having a high energy: To this end, select the `Assign Color` modifier from the modifier list and select a color of your choice by clicking on the color field.

## Rendering

After we have put together the modifier pipeline, we are now happy with the visualization results. The final step is to create a static picture from what we see in the viewports, such that we can share it with our collaborators or include it in a paper or presentation. Generating a static image of the scene is called rendering an image in OVITO. First, select the viewport that you want to render by right-clicking into it. The active viewport has a yellow border around it. Then activate the Render tab ( ) in the command panel. This tab provides controls to adjust the output image size, the background color, and the output filename etc. Press the Render Active Viewport ( ) button to produce an image of the active viewport. The rendered image is displayed in a new window. Use the Save to file or Copy to clipboard buttons to save the image.

## Performing data analysis

Common neighbor analysis

OVITO was not only made to visualize simulation data, it also provides analysis functions. One example is the Common Neighbor Analysis (CNA) modifier. It analyzes the local environment of each atom, and identifies ordered crystal structures such as FCC or BCC. In addition to coloring atoms according to their crystal structure type, the analysis modifier stores its results in a new data channel. This data channel can then be further used to select, delete, or process atoms of a certain type with other modifiers.

There is one caveat when using an analysis modifier like the Common Neighbor Analysis: It requires access to the complete dataset to perform the analysis. We, however, have previously deleted part of the atoms with the `Slice` modifier. Since the `Common Neighbor Analysis` modifier follows the `Slice` modifier in the pipeline, it will see only the modified dataset, from which atoms have been removed. (We effectively created a "free surface" with the slice operation.) To avoid this, we need to move the `Common Neighbor Analysis` modifier to the front of the pipeline using the arrow buttons (located to the right of the pipeline listbox). The analysis modifier should be placed in front of the `Slice` modifier as shown in , that means to the very bottom of the list. This ensures that it "sees" all atoms exactly as they are loaded from the input file. Now hit the Calculate button to let the analysis modifier do its work. The analysis modifier assigns a color to each atom based on the structure type determined for the atom. However, since we also used the `Color Coding` and the `Assign Color` modifiers, the colors get overwritten later in the pipeline. Therefore, double-click the `Color Coding` and the `Assign Color` entries in the pipeline box to temporarily deactivate these modifiers.

## Saving your work

After you have set up a complex modifier pipeline with OVITO, you might want to save it, such that it can be accessed again at a later time or applied to a different simulation dataset. You can use the File Save Scene menu command to save the entire scene, including all modifiers and settings, to an OVITO file.