\section{Running Tachyon}
\index{running}
  Since Tachyon runs on a wide variety of platforms, the exact commands
required to run it vary substantially.  The easiest way to get started
using Tachyon is to begin by running one of the sequential or multi-threaded
versions.  Tachyon includes a built-in help page describing all
available command line options with brief text descriptions, this 
help page is displayed when Tachyon is run with the {\tt -help} option.
Below we describe the Tachyon command line parameters in more detail.

\index{command line parameters}

\subsection{General command line options}
Several command line options are available to tune 
performance, display built-in help text, and set output verbosity.
\begin{itemize}
\item{{\tt +V}}: Enable verbose status messages, including reporting of
      the total number of parallel nodes, per-node processor counts,
      information on the construction of spatial subdivision acceleration
      structures, generation of MIP maps for textures, etc.
\item{{\tt -V}}: Disable verbose status messages.
\item{{\tt -nosave}}: disable saving of output images to disk files.  This 
      feature is normally only used when benchmarking, or when using one of
      the OpenGL-enabled Tachyon configurations which provide runtime display
      of rendered images.
\item{{\tt -camfile {\it filename}}}: run a fly-through animation from 
      the named camera file. 
\end{itemize}

\subsection{Command line shading controls}
Tachyon supports a number of command line parameters which affect the
quality and algorithms used to render scene files.  The parameters 
select one of several quality levels, which implement various 
compromises between rendering speed and quality.  Along with the
overall shading quality controls, several specific options provide 
control over individual rendering algorithms within Tachyon.

\begin{itemize}
\item{{\tt -fullshade}}: enables the highest quality rendering mode
\item{{\tt -mediumshade}}: disables computation of shadows, ambient occlusion
\item{{\tt -lowshade}}: minmalistic shading, using texture colors only
\item{{\tt -lowestshade}}: solid colors only
\item{{\tt -aasamples {\it sample\_count}}}: command line override for the number of 
      antialiasing supersamples computed for each pixel.  A value of
      zero disables antialiasing.  If this option is not used, the number
      of antialiasing samples is determined by the contents of the scen file.
\item{{\tt -rescale\_lights {\it scalefactor}}}: 
                              rescale all light intensity values by the
                              specified factor.  (performed before other
                              lighting overrides take effect)
\item{{\tt -auto\_skylight {\it aofactor}}}: 
                              force the use of ambient occlusion lighting,
                              automatically rescaling all other light sources
                              to compensate for the additional illumination
                              from the ambient occlusion lighting.
\item{{\tt -add\_skylight {\it aofactor}}}:
                              force the use of ambient occlusion lighting,
                              existing lights must be rescaled manually using
                              the {\tt -rescale\_lights} flag.
\item{{\tt -skylight\_samples {\it samplecount}}}: 
                              number of samples to use for ambient occlusion
                              lighting shadow tests.
\item{{\tt -shade\_phong}}: use traditional phong shading for specular
      highlights.
\item{{\tt -shade\_blinn}}: use Blinn's equation for specular highlights.
\item{{\tt -shade\_blinn\_fast}}: use a fast approximation to Blinn-style
      specular highlights.
\item{{\tt -shade\_nullphong}}: entirely disables computation of
      specular highlights by registering a no-op function pointer.
\item{{\tt -trans\_orig}}: use original Tachyon transparency mode.
\item{{\tt -trans\_vmd}}: a special transparency mode designed for
      use with VMD.  The resulting color is multiplied by opacity, 
      giving results similar to what one would see with screen-door
      transparency in OpenGL.
\end{itemize}


\subsection{Command line image format options}
Tachyon optionally supports several image file formats for output.
The output format is specified by the {\tt -format {\it formatname}} 
command line parameter.  Several of these formats are only available if
Tachyon has been compiled with optional features enabled.

\begin{itemize}
\item{{\tt -res {\it Xresolution Yresolution}}}: override the 
     scene-defined output image resolution parameters.
\item{{\tt TARGA}}: uncompressed 24-bit Targa file
\item{{\tt BMP}}: uncompressed 24-bit Windows bitmap 
\item{{\tt PPM}}: uncompressed 24-bit NetPBM portable pixmap (PPM) file
\item{{\tt RGB}}: uncompressed 24-bit Silicon Graphics RGB file
\item{{\tt JPEG}}: compressed 24-bit JPEG file
\item{{\tt PNG}}: uncompressed 24-bit PNG file
\end{itemize}


\subsection{Interactive ray tracing}
\index{interactive ray tracing}
Tachyon is fast enough to support ray tracing at interactive rates
when run on a large enough parallel computer, or with a simple enough
scene.  To this end, Tachyon can be optionally compiled with support for
the Spaceball 6DOF motion control device.  Using the Spaceball, one
can fly around in an otherwise static scene.  This is accomplished
with the {\tt -spaceball {\it serial\_port\_device}} command line parameters.


\subsection{Performance tuning options}
Although rendering performance is often dominated by 
the combination of image resolution, shading parameters,
and input scene, performance can be be further tuned 
by adjusting the number of worker threads, and 
the spatial subdivision parameters.  Tachyon normally sets
the number of worker threads to match the number of available
CPU cores.  In some cases, such as when running Tachyon on a 
large shared memory system that is already under load from other
processes, it may be beneficial to limit the number of worker threads
to a number smaller than or equal to the number of idle processor cores.

\index{performance tuning}
\begin{itemize}
\item{{\tt -numthreads {\it thread\_count}}}: 
      Command line override for the number of threads to spawn during 
      the ray tracing process.  When this options is not specified, 
      Tachyon automatically determines the number of threads
      to spawn based on the number of CPUs available.
\item{{\tt -nobounding}}: Disable automatic generation of hierarchical
      grid-based acceleration data structures (not recommended for 
      normal use, intended for testing only).
\item{{\tt -boundthresh {\it object\_count}}}: Override default threshold for 
      subdividing grid cells with a new grid
\end{itemize}


\subsection{Tips for running MPI versions}
\index{running with MPI}
Tachyon supports the use of MPI for distributed memory rendering
of complex scenes.  Most commercial supercomputers and cluster
vendors provide their own custom-tuned implementations of MPI
which perform optimally on their hardware.  Homegrown clusters
typically use open source implementations of MPI.
While Tachyon will work with any comformant implementation of MPI,
some implementations perform much better than others.  In the
author's experience, the  OpenMPI and MVAPICH implementations 
of MPI give the best performance on commodity cluster hardware.
