<?xml version="1.0" encoding="utf-8"?>
<chapter version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="tutorial" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Tutorial - First steps with OVITO</title>

  <para>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 <filename
  class="directory">share/ovito/examples/tutorial1/</filename> of your OVITO
  installation.</para>

  <section xml:id="tutorial.import">
    <title>Importing the simulation dataset</title>

    <para>The first step when using OVITO is to import the simulation data to
    be visualized. OVITO can read a number of <link
    linkend="atomviz.importing">file formats</link> 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 <menuchoice>
        <guimenu>File</guimenu>

        <guimenuitem>Import</guimenuitem>
      </menuchoice> command from the main menu, the corresponding button in
    the toolbar, or with the <shortcut>
        <keycombo>
          <keycap>Ctrl</keycap>

          <keycap>i</keycap>
        </keycombo>
      </shortcut> keyboard shortcut. This will open a file selector dialog as
    shown in <xref linkend="tutorial.figures.importfile"/>.</para>

    <figure xml:id="tutorial.figures.importfile">
      <title>The File Selector Dialog</title>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/tutorial/02-import-file.small.png"
                       format="png"/>
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <para>Go to the directory <filename
    class="directory">share/ovito/examples/tutorial1/</filename>, which
    contains the example file <filename>NanocrystallinePd.dump.gz</filename>.
    This file is a compressed <link
    xlink:href="http://lammps.sandia.gov/doc/dump.html">LAMMPS dump
    dataset</link> 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 <filename>*.gz</filename> name
    suffix.</para>

    <figure xml:id="tutorial.figures.importsettings">
      <title>The import settings dialog</title>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/tutorial/03-import-settings.small.png"
                       format="png"/>
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <para>After opening the file, a second dialog (<xref
    linkend="tutorial.figures.importsettings"/>) pops up, letting you assign
    data columns stored in the file to OVITO's internal data channels. OVITO's
    internal <link linkend="atomviz.overview.data_model">data model</link>
    consists of so-called <firstterm>data channels</firstterm> 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 <link linkend="atomviz.data_channels">set of
    standard data channels</link> 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.</para>

    <para>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 (<literal>id</literal>, <literal>x</literal>,
    <literal>y</literal>, <literal>z</literal>, and
    <literal>c_epot</literal>). 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 <guibutton>Auto-assign
    columns</guibutton> button. As shown in <xref
    linkend="tutorial.figures.importsettings"/>, 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
    <guibutton>Auto-assign columns</guibutton> button will be disabled, and
    you have to specify the data channels manually.</para>

    <para>As can be seen in <xref linkend="tutorial.figures.importsettings"/>,
    there are five data columns in the example file (<literal>id</literal>,
    <literal>x</literal>, <literal>y</literal>, <literal>z</literal>,
    <literal>c_epot</literal>), 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 <literal>Atom Index</literal>, <literal>Position</literal>, and
    <literal>Potential Energy</literal>. The <literal>Position</literal> data
    channel is a so-called <emphasis>vector data channel</emphasis>, which is
    composed of three sub-components (X, Y, and Z).</para>

    <para>Since the example file contains only a single simulation snapshot,
    leave the option <guibutton>File contains single snapshot</guibutton>
    selected and press <guibutton>OK</guibutton> to import the data.</para>
  </section>

  <section xml:id="tutorial.gui">
    <title>Using the viewports</title>

    <para>After importing the simulation dataset you are now back to OVITO's
    main window (<xref linkend="tutorial.figures.mainwindowimported"/>). 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. <figure
        xml:id="tutorial.figures.mainwindowimported">
        <title>OVITO after loading the sample dataset</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/tutorial/04-main-window-just-imported.small.png"
                         format="png"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>The viewports display a three-dimensional view of the
    simulation snapshot that we just imported. Note how the four viewports,
    which are called <literal>Top</literal>, <literal>Front</literal>,
    <literal>Left</literal>, and <literal>Perspective</literal>, 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 <guibutton>Maximize Active Viewport</guibutton>
    (<inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/viewport_control_toolbar/maximize_viewport.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>) 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. <figure
        xml:id="tutorial.figures.singleviewport">
        <title>Main window with a maximized viewport</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/tutorial/05-main-window-single-viewport.small.png"
                         format="png"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure></para>

    <para>At the bottom of the main window you find more buttons to control
    the viewports. The three navigation buttons (<inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/viewport_control_toolbar/zoom.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>, <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/viewport_control_toolbar/pan.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>, <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/viewport_control_toolbar/orbit.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>) 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.</para>

    <para>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 <keycap>shift</keycap> 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 <link
    linkend="gui.viewports_area">section of the reference
    manual</link>.</para>

    <para>To the right of the viewport area you find the <firstterm>command
    panel</firstterm>. It is organized into three tabs located at the top: the
    <firstterm>Modify</firstterm> <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/command_panel/tab_modify.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>, <firstterm>Render</firstterm> <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/command_panel/tab_render.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject> and <firstterm>Utilities</firstterm>
    <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/command_panel/tab_utilities.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject> tab. The <firstterm>Modify</firstterm> 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 <firstterm>Render</firstterm> tab lets you <link
    linkend="atomviz.rendering">create images for publication</link> and the
    <firstterm>Utilities</firstterm> tab provides access to additional tools
    that you might find useful.</para>

    <para>Further information on the user interface of OVITO can be found in
    <xref linkend="gui.main_window"/> of the reference manual.</para>
  </section>

  <section xml:id="tutorial.modifiers">
    <title>Working with modifiers</title>

    <para>Before you continue with the tutorial, you should read <xref
    linkend="atomviz.overview"/> of the manual to learn about
    <firstterm>modifiers</firstterm> and the <firstterm>processing
    pipeline</firstterm>. These fundamental concepts will be demonstrated in
    the following.</para>

    <section xml:id="tutorial.modifiers.slice">
      <title>Applying the <literal>Slice</literal> modifier</title>

      <para>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.</para>

      <para>The list of available modifier types can be found in the drop-down
      listbox labeled "Modifier List" at the top of the
      <emphasis>Modify</emphasis> tab in the command panel. Select the entry
      named <literal>Slice</literal> from the list to insert a <link
      linkend="atomviz.modifiers.slice"><literal>Slice</literal>
      modifier</link> into the pipeline. The current pipeline is displayed in
      the listbox below the drop-down field. It should now contain several
      entries: The <literal>Slice</literal> modifier that you just inserted
      and the entry <literal>Data source</literal>, which denotes the input of
      the modification pipeline. The <literal>Data source</literal> has two
      subitems, <literal>Simulation cell</literal> and <literal>Atoms
      display</literal>, which allow you to control the display of the
      simulation box and the atoms. The <literal>Data source</literal> 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!</para>

      <para><figure xml:id="tutorial.figures.slice">
          <title>Using the <emphasis>Slice</emphasis> modifier</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/tutorial/06-main-window-slice.small.png"
                           format="png"/>
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>The <link
      linkend="atomviz.modifiers.slice"><literal>Slice</literal>
      modifier</link> 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.</para>

      <para>To change the value of a numerical parameter of the Slice modifier
      such as <literal>Distance</literal>, 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.</para>

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

    <section xml:id="tutorial.modifiers.color">
      <title>Assigning colors to atoms</title>

      <para>The <literal>Slice</literal> 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 <link
      linkend="atomviz.modifiers.color_coding"><literal>Color Coding</literal>
      modifier</link>. 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.</para>

      <para>From the modifier drop-down list, select the entry <literal>Color
      Coding</literal> to add this modifier to the pipeline. In the parameter
      panel of the newly added modifier, select <literal>Potential
      Energy</literal> from the data channel list and click the
      <guibutton>Adjust range</guibutton> button. This will adjust the color
      scale to the minimum and maximum energies stored in the LAMMPS file. The
      <literal>Color Coding</literal> modifier maps the atomic energies in the
      range specified by <literal>Start value</literal> and <literal>End
      value</literal> 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. <figure xml:id="tutorial.figures.colorcoding">
          <title>Color coding</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/tutorial/07-main-window-color-coding.small.png"
                           format="png"/>
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure></para>
    </section>

    <section xml:id="tutorial.modifiers.select">
      <title>Selecting atoms</title>

      <para><figure xml:id="tutorial.figures.selectbyexpr">
          <title>Expression Select modifier</title>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/tutorial/08-main-window-select-by-expression.small.png"
                           format="png"/>
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>Sometimes you might want to select atoms with specific
      properties. OVITO provides a powerful mechanism for this: the <link
      linkend="atomviz.modifiers.select_by_expression"><literal>Expression
      Select</literal> modifier</link>.</para>

      <para>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 <literal>TRUE</literal> then
      the atom is selected; otherwise it is deselected. The syntax of Boolean
      expressions is described in <xref
      linkend="atomviz.modifiers.add_expression_channel"/>.</para>

      <para>Enter the text <command>PotentialEnergy &gt; -3.85</command> into
      the expression field and press the <keycap>Enter</keycap> 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
      <emphasis>Variables</emphasis> panel.</para>

      <para>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 <link
      linkend="atomviz.modifiers.assign_color"><literal>Assign Color</literal>
      modifier</link> from the modifier list and select a color of your choice
      by clicking on the color field.</para>
    </section>
  </section>

  <section xml:id="tutorial.render">
    <title>Rendering</title>

    <para>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 <emphasis>rendering</emphasis> 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 <emphasis>Render</emphasis> tab (<inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/command_panel/tab_render.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>) in the command panel. This tab provides <link
    linkend="core.rendering.render_settings">controls</link> to adjust the
    output image size, the background color, and the output filename etc.
    Press the <guibutton>Render Active Viewport</guibutton>
    (<inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/rendering/render_active_viewport.png"
                     format="png"/>
        </imageobject>
      </inlinemediaobject>) button to produce an image of the active viewport.
    The rendered image is displayed in a new window. Use the <guibutton>Save
    to file</guibutton> or <guibutton>Copy to clipboard</guibutton> buttons to
    save the image.</para>
  </section>

  <section xml:id="tutorial.cna">
    <title>Performing data analysis</title>

    <para><figure xml:id="tutorial.figures.cna">
        <title>Common neighbor analysis</title>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="images/tutorial/10-main-window-cna.small.png"
                         format="png"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>OVITO was not only made to visualize simulation data, it also
    provides analysis functions. One example is the <link
    linkend="atomviz.modifiers.common_neighbor_analysis">Common Neighbor
    Analysis</link> (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.</para>

    <para>There is one caveat when using an analysis modifier like the <link
    linkend="atomviz.modifiers.common_neighbor_analysis">Common Neighbor
    Analysis</link>: It requires access to the complete dataset to perform the
    analysis. We, however, have previously deleted part of the atoms with the
    <literal>Slice</literal> modifier. Since the <literal
    linkend="atomviz.modifiers.common_neighbor_analysis">Common Neighbor
    Analysis</literal> modifier follows the <literal>Slice</literal> 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 <literal
    linkend="atomviz.modifiers.common_neighbor_analysis">Common Neighbor
    Analysis</literal> 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 <literal>Slice</literal>
    modifier as shown in <xref linkend="tutorial.figures.cna"/>, 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
    <guibutton>Calculate</guibutton> 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
    <literal>Color Coding</literal> and the <literal>Assign Color</literal>
    modifiers, the colors get overwritten later in the pipeline. Therefore,
    double-click the <literal>Color Coding</literal> and the <literal>Assign
    Color</literal> entries in the pipeline box to temporarily deactivate
    these modifiers.</para>
  </section>

  <section xml:id="tutorial.save">
    <title>Saving your work</title>

    <para>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 <menuchoice>
        <guimenu>File</guimenu>

        <guimenuitem>Save Scene</guimenuitem>
      </menuchoice> menu command to save the entire scene, including all
    modifiers and settings, to an OVITO file.</para>
  </section>
</chapter>
