<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="usage.import" 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>Importing data</title>

  <para>To load a simulation file from your local filesystem into OVITO, select 
    <menuchoice><guimenu>File</guimenu><guimenuitem>Load File</guimenuitem></menuchoice> from the menu or use the corresponding button in the toolbar.
    OVITO detects the format of the file automatically (see the <link linkend="usage.import.formats">list of supported formats</link> below). 
    Compressed text-based files with a <filename>.gz</filename> suffix can directly be read by OVITO.
  </para>
  <para>
    Loading a data file creates a new visual object in the three-dimensial scene to display the data. 
    This object maintains a reference to the original source file, and it is possible to reload the data from the external
    file or to replace the source data with a different file later on. 
    The <link linkend="scene_objects.file_source">"External File" panel</link>, which is shown in the screenshot below,
    contains a toolbar with corresponding command buttons. Switching to a another input file 
    is useful if you have set up a visualization or a <link linkend="usage.modification_pipeline">data filtering sequence</link> and now want to 
    re-use it on a different simulation dataset.
  </para>

  <simplesect xml:id="usage.import.sequence">
    <title>Simulation sequences</title>
    <para>    
	    <figure>
	    	<title>The <link linkend="scene_objects.file_source">External File</link> panel</title>
	        <screenshot><mediaobject><imageobject>
	        <imagedata fileref="images/scene_objects/file_wildcard_pattern.png" format="PNG" scale="45" />
	        </imageobject></mediaobject></screenshot>
	    </figure>
       OVITO can load and display animated simulation trajectories. The following scenarios are supported:
       <variablelist>
         <varlistentry><term>Series of files, each containing one frame:</term><listitem>
           <para>
		       This is the default scenario. The program tries to automatically recognize sequences of files in a directory 
		       by looking for other files with a similar name as the one you picked. 
		       To this end, OVITO replaces the last number (if any) in the filename with the wildcard character <literal>*</literal> to generate a search pattern 
		       and find other files in the same directory belonging to the time series. 
		       For instance, if you load the file <filename>anim1c_5000.dump</filename>, OVITO generates the search pattern
		       <filename>anim1c_*.dump</filename> to find all matching frames (e.g. <filename>anim1c_0.dump</filename>,
		       <filename>anim1c_1000.dump</filename>, <filename>anim1c_2000.dump</filename>, etc). It is possible to
		       manually change the search pattern afterwards if the one generated by OVITO does not fit (see the screenshot on the right). 
           </para>
         </listitem></varlistentry>
         
         <varlistentry><term>Single file containing multiple frames:</term><listitem>
           <para>
		       The LAMMPS dump and the XYZ file formats can store multiple simulation timesteps in one file.
		       By default, OVITO loads only the first frame from the file to save time. You have to explicitly tell OVITO to look 
		       for additional frames by checking the <emphasis>File contains time series</emphasis> option
		       highlighted in the screenshot. OVITO will then quickly scan the entire file to find all simulation frames.
           </para>
         </listitem></varlistentry>
                  
         <varlistentry><term>Series of files, each containing several frames:</term><listitem>
           <para>
		       To load multiple files, each one containing multiple simulation frames, follow these steps: Load the first file from the sequence. 
		       Then check the <emphasis>File contains time series</emphasis> option. Finally, edit the file pattern
		       to include the '<literal>*</literal>' wildcard character to let OVITO find all other matching files in the directory. 
           </para>
         </listitem></varlistentry>
         
		 <varlistentry><term>Separate topology and trajectory files:</term><listitem>
           <para>
		     Some MD simulation codes work with separate topology and trajectory files. The topology file contains the static definitions of 
		     atoms, types, bonds, etc. while the trajectory file contains the trajectories of motion computed by the simulation code.
		     In such case, load the topology file in OVITO first (e.g. a LAMMPS <emphasis>data</emphasis> file).
		     The apply the <link linkend="particles.modifiers.load_trajectory">Load trajectory</link> modifier to the dataset to load the time-dependent atomic positions
		     from the trajectory file (e.g. a LAMMPS <emphasis>dump</emphasis> file).
           </para>
         </listitem></varlistentry>         
                  
       </variablelist>
    </para>
    
    <para>
       OVITO displays a timeline and a slider control at the bottom of main window when a simulation sequence is loaded, 
       which allows you to jump between frames. Note that OVITO only loads the currently displayed simulation frame into memory to avoid
       running out of memory in the case of large datasets and/or long trajectories.
    </para>
    
  </simplesect>
  
  <simplesect xml:id="usage.import.remote">
    <title>Importing files from remote computers</title>
    <para>
       OVITO comes with a built-in SSH client to directly access files on remote machines. This capability is useful when working with simulation data stored on 
       remote HPC clusters and saves you from transferring the data to your local desktop computer first.
       To open a simulation file on a remote machine, choose  
       <menuchoice><guimenu>File</guimenu><guimenuitem>Load Remote File</guimenuitem></menuchoice> from the menu.  
    </para>
    <para>
       OVITO currently does not allow you to browse directories on remote machines. That means you have to directly specify
       the full path to a remote file as an URL of the form:
       <screen><command>    sftp://user@hostname/path/filename</command></screen>
       Where <command>sftp://</command> is the file access protocol (Secure File Transfer Protocol), 
       <command>user</command> the SSH login name on the remote machine,
       <command>hostname</command> the name of the remote machine,
       and <command>/path/filename</command> the simulation file to import. It is possible to 
       specify a non-standard port number by appending <command>:portnumber</command> to the hostname.
    </para>
    <para>
       When OVITO connects to the remote machine, it will ask for the login password. Once established, 
       the SSH connection is kept alive until the end of the program session. OVITO makes a temporary copy of a remote file on the local computer before
       reading the data to speed up subsequent accesses to simulation frames. The local file copies are cached until the end of the program session or 
       until you press <emphasis>Reload</emphasis> in the <link linkend="scene_objects.file_source">External File panel</link>.
    </para>
  </simplesect>
   
  <simplesect xml:id="usage.import.tips">
    <title>Using the command line</title>
    <para>
      If you OVITO from a terminal, you can directly specify a file to load. This works with both local and remote
      files:
       <screen>
    <command>ovito /path/filename</command>
    <command>ovito sftp://hostname/path/filename</command>
       </screen>
    </para>
  </simplesect> 
  
  <simplesect xml:id="usage.import.formats">
  <title>Supported file formats</title>
  <para>
  	OVITO can read particle datasets in the following formats:  
    <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>File format</entry>
              <entry>Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>LAMMPS&#xA0;dump</entry>
              <entry><para>File format used by the <link xlink:href="http://lammps.sandia.gov">LAMMPS molecular dynamics code</link>. OVITO supports both text-based and binary dump files.</para></entry>
            </row>
            <row>
              <entry>LAMMPS&#xA0;data</entry>
              <entry><para>File format used by the <link xlink:href="http://lammps.sandia.gov/doc/read_data.html">LAMMPS molecular dynamics code</link>.</para>
              </entry>
            </row>
            <row>
              <entry>XYZ</entry>
              <entry><para>A simple column-based text format, which is documented <link xlink:href="http://en.wikipedia.org/wiki/XYZ_file_format">here</link>.</para>
			    <para>The basic XYZ format does not contain simulation cell information. OVITO takes the axis-aligned bounding box of particles as the simulation box in this case.
			    The program also supports the <link xlink:href="http://libatoms.github.io/QUIP/io.html#module-ase.io.extxyz">extended XYZ format</link>, which includes information on the simulation cell,
			    boundary conditions, and per-particle fields.</para>
                </entry>
            </row>
            <row>
              <entry>POSCAR / XDATCAR</entry>
              <entry><para>File formats used by the <emphasis>ab initio</emphasis> simulation package <link xlink:href="http://www.vasp.at/">VASP</link>.</para></entry>
            </row>
            <row>
              <entry>IMD</entry>
              <entry><para>File format used by the molecular dynamics code <link xlink:href="http://imd.itap.physik.uni-stuttgart.de/">IMD</link>.</para></entry>
            </row>
            <row>
              <entry>CFG</entry>
              <entry><para>File format used by the <link xlink:href="http://li.mit.edu/Archive/Graphics/A/">AtomEye</link> visualization program.</para></entry>
            </row>
            <row>
              <entry>PARCAS</entry>
              <entry><para>Binary file format written by the MD code <emphasis>Parcas</emphasis> developed in K. Nordlund's group at University of Helsinki.</para></entry>
            </row>
            <row>
              <entry>NetCDF</entry>
              <entry><para>Binary format for molecular dynamics data based on the standard NetCDF container. There exists an <link xlink:href="https://github.com/pastewka/lammps-netcdf">extension module for LAMMPS</link> that adds NetCDF output.</para></entry>
            </row>
            <row>
              <entry>PDB</entry>
              <entry><para>Protein Data Bank (PDB) files (experimental support).</para></entry>
            </row>
            <row>
              <entry>FHI-aims</entry>
              <entry><para>Geometry and log-file formats used by the <emphasis>ab initio</emphasis> simulation package <link xlink:href="https://aimsclub.fhi-berlin.mpg.de/index.php">FHI-aims</link>.</para></entry>
            </row>
            <row>
              <entry>GSD/HOOMD</entry>
              <entry><para>Binary format for molecular dynamics data used by the <link xlink:href="http://glotzerlab.engin.umich.edu/hoomd-blue/">HOOMD-blue code</link>. See <link xlink:href="http://gsd.readthedocs.io">GSD (General Simulation Data) format</link>.</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>  
  </para>
  <para>
  	OVITO can load triangle meshes (polygonal data) in the following format:  
    <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>File format</entry>
              <entry>Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>VTK</entry>
              <entry><para>Format used by the <emphasis>Visualization Toolkit</emphasis> (VTK). This text-based format is documented <link xlink:href="http://www.vtk.org/VTK/img/file-formats.pdf">here</link>. Note that OVITO supports only triangular cells.</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>  
  </para>
  </simplesect>
  
</section>
