.. _StartupOptions:

Startup Options
---------------

You can get help on starting VisIt_ with the commands

::

    visit -help
    visit -fullhelp

For convenience, the output from ``visit -fullhelp`` is shown below.

USAGE: visit [options]::

    Interface options
    ---------------------------------------------------------------------------
        -gui                 Run with the Graphical User Interface (default).
        -cli                 Run with the Command Line Interface.

    Movie making options
    ---------------------------------------------------------------------------
        -movie               Run the CLI in a movie making mode. Must be
                             combined with -sessionfile. Will produce a simple
                             movie by drawing all the plots in the specified
                             session for every timestep of the database.

    Startup options
    ---------------------------------------------------------------------------
        -o <filename>        Open the specified data file at startup.
        -s <filename>        Run the specified VisIt script.
        -sessionfile <filename>  Open the specified session file at startup
                             Note that this argument only takes effect with
                             -gui or -movie.
        -config <filename>   Initialize the viewer at startup using the named
                             config file.  If an absolute path is not given,
                             the file is assumed to be in the .visit directory.
        -noconfig            Don't process configuration files at startup.
        -launchengine <host> Launch an engine at startup. The <host> parameter
                             is optional. If it is not specified, the engine
                             will be launched on the local host. If you wish
                             to launch an engine on a remote host, specify 
                             the host's name as the <host> parameter.
        -nosplash            Do not display the splash screen at startup.

    Window options
    ---------------------------------------------------------------------------
        -small               Use a smaller desktop area/window size.
        -geometry <spec>     What portion of the screen to use.  This is a
                             standard X Windows geometry specification. This
                             option can be used to set the size of images
                             generated from scripts and movies.

        -viewer_geometry <spec> What portion of the screen the viewer windows
                                will use. This is a standard X Windows geometry
                                specification. This option overrides the
                                -geometry option that the GUI passes to the
                                viewer.

        -window_anchor <x,y> The x,y position on the screen where VisIt's GUI
                             will show its windows (Main window excluded).
        -style <style>       One of: windows,cde,motif,sgi.
        -locale <locale>     The locale that you want VisIt to use when displaying
                             translated menus and controls. VisIt will use the
                             default locale if the -locale option is not
                             provided.
        -background <color>  Background color for GUI.
        -foreground <color>  Foreground color for GUI.
        -nowin               Run with viewer windows off-screen (i.e. OSMesa).
                             This is typically used with the -cli option.
        -stereo              Enable active stereo, also known as the
                             page-flipping, or 'CrystalEyes' mode.
        -nowindowmetrics     Prevents X11 from grabbing and moving a test
                             widget used in calculating window borders. This
                             option can be useful if VisIt hangs when 
                             displaying to an Apple X-server.

    Version options
    ---------------------------------------------------------------------------
        -version             Do NOT run VisIt. Just print the current version.
        -git_version         Do NOT run VisIt. Just print the Git version it
                             was built from.
        -beta                Run the current beta version.
        -v <version>         Run a specified version. Specifying 2 digits,
                             such as X.Y, will run the latest patch release
                             for that version. Specifying 3 digits, such as
                             X.Y.Z, will run that specific version.

    Other resources for help
    ---------------------------------------------------------------------------
        run-time:            While running VisIt, look under the "Help" menu.
        on-line:             https://visit-help.llnl.gov


    ***************************************************************************
                              ADDITIONAL OPTIONS
    ***************************************************************************

    Parallel launch options
    ---------------------------------------------------------------------------
        Notes: All of these options are ordinarily obtained from host profiles.
        However, the command line options override anything in the profiles. 

        When parallel arguments are added but the engine is not the
        component being launched, -launchengine is implied.  Explicitly
        add -launchengine to launch a remote parallel engine.
    ---------------------------------------------------------------------------
        -setupenv            Use the VisIt script to set up the environment
                             for the engine on the compute nodes.
        -par                 Run the parallel version. This option is implied
                             by any of the other parallel options listed below.
        -l    <method>       Launch in parallel using the given method.
        -pl   <method>       Launch only the engine in parallel as specified.
        -la   <args>         Additional arguments for the parallel launcher.
        -sla  <args>         Additional arguments for the parallel sub-launcher.
        -np   <# procs>      The number of processors to use.
        -nn   <# nodes>      The number of nodes to allocate.
        -p    <part>         Partition to run in.
        -n    <name>         The parallel job name.
        -b    <bank>         Bank from which to draw resources.
        -t    <time>         Maximum job run time.
        -machinefile <file>  Machine file.
        -expedite            Makes DPCS give priority scheduling.

        -icet                In scalable rendering mode, use the IceT parallel
                             image compositor (default).
        -no-icet             Do not use the IceT parallel compositor.

    Hardware accelerated parallel (scalable) rendering options
    ---------------------------------------------------------------------------
        Notes: These options should only be used with parallel clusters that
        have graphics cards.  If you are using a serial version of VisIt, you
        are already getting hardware acceleration and these options are not 
        needed.  Furthermore, you must be in scalable rendering mode for VisIt
        to utilize a cluster's GPUs.  By default, VisIt is configured to
        switch into scalable rendering mode when rendering complexity exceeds
        a predefined limit.

        VisIt can manage the creation and tear down of X servers for you.  It
        will do this automatically if you specify the -launch-x parameter,
        but you can customize the process with the -x-args and -display
        parameters, which respect %l and %n format specifiers.

    ---------------------------------------------------------------------------
        -hw-accel              Tells VisIt that it should use graphics cards.
        -n-gpus-per-node <int> Number of GPUs per node of the cluster (1).
        -launch-x              Tell VisIt to manage the X servers
        -no-launch-x           Let the cluster manager X servers [default]
        -display               Tells VisIt which display to use.
        -x-args '<string>'     Extra arguments to X server.

    Load balance options
    ---------------------------------------------------------------------------
        Note: Each time VisIt executes a pipeline the relevant domains for the
        execution are assigned to processors. This list of domains is sorted in
        increasing global domain number. The options below effect how domains
        in this list are assigned to processors. Assuming there are D domains
        and P processors...
    ---------------------------------------------------------------------------
        -lb-block            Assign the first D/P domains to processor 0, the
                             next D/P domains to processor 1, etc.
        -lb-stride           Assign every Pth domain starting from the first
                             to processor 0, every Pth domain starting from the
                             second to processor 1, etc.
        -lb-absolute         Assign domains by absolute domain number % P. This
                             guarantees a given domain is always processed
                             by the same processor but can also lead to poor
                             balance when only a subset of domains is selected.
        -lb-random           Randomly assign domains to processors.
        -allowdynamic        Dedicate one processor to spreading the work 
                             dynamically among the other processors.  This mode
                             has limitations in the types of queries it can 
                             perform.  Under development.
        -lb-stream           Similar to -lb-block, but have the domains travel
                             down the pipeline one at a time, instead of all
                             together.  Under development.

    Database differencing options
    ---------------------------------------------------------------------------
        Use the '-diff <ldb> <rdb>' option to run VisIt in a database
        differencing mode. VisIt will generate expressions to facilitate
        visualization and analysis of the difference between the left-database,
        <ldb>, and right-database, <rdb>. VisIt will open windows to display
        both the left and right databases as well as their difference.

        VisIt uses the Cross-Mesh Field Evaluation (CMFE) expression functions
        to help generate these differences. A CMFE function creates an instance
        of a variable from another (source) mesh on the specified (destination)
        mesh. VisIt can use two variants of CMFE expression functions depending
        on how similar the source and destination meshes are; connectivity-based
        (conn_cmfe) which assumes the underlying mesh(s) for the left and right
        databases have identical connectivity and position-based (pos_cmfe) which
        does not make this assumption. VisIt will attempt to automatically select
        which variant of CMFE expression to use based on some simple heuristics.
        For meshes with identical connectivity, conn_cmfe expressions are
        preferrable because they are higher performance and do not require VisIt
        to perform any interpolation. In fact, the conn_cmfe operation is
        perfectly anti-symmetric. That is <ldb> - <rdb> = -(<rdb> - <ldb>).
        The same cannot be said for pos_cmfe expressions. However, pos_cmfe
        expressions will attempt to generate useful results regardless of the
        similarity of the underlying meshes.

        Note that the differences VisIt will compute in this mode are single
        precision. This is true regardless of whether the input data is itself
        double precision. VisIt will convert double precision to single 
        precision before processing it. Although this is a result of earlier
        visualization-specific design requirements and constraints, the intention
        is that eventually double precision will be supported.

        Finally, be sure to bring up Controls->Macros in the GUI to find a set
        of useful operations specifically tailored to database differencing. Also,
        typing 'help()' (including the '()') at the python prompt after starting
        'visit -diff' will generate a more detailed help message.

        -diff <ldb> <rdb>    Indicate you wish to run VisIt in database
                             differencing mode and specify the two databases
                             to difference.

                             Note: All options occurring on the command-line
                             *after* the '-diff' option are treated as options
                             to the differencing script while all options
                             occurring *before* the '-diff' option are treated
                             as options to VisIt.

        -diffsum <ldb> <rdb> Run only the difference summary method of the
                             'visit -diff' script, in nowin mode so its fast,
                             print the results, and immediately exit.

        -force_pos_cmfe      Force use of position-based CMFE expressions.

    Advanced options
    ---------------------------------------------------------------------------
        -guesshost           Try to guess the client host name from one of
                             the SSH_CLIENT, SSH2_CLIENT, or SSH_CONNECTION
                             environment variables.
        -noloopback          Disable use of the 127.0.0.1 loopback device.
        -sshtunneling        Tunnel all remote connections through ssh.  NOTE:
                             this overrides values set in the host profiles.
        -noint               Disable interruption capability.
        -nopty               Run without PTYs.
        -norun <compname>    Don't run the specified component, but instead
                             print the environment variables to set and the 
                             command to run when launching a specific 
                             component. For example, '-norun engine_par' will
                             show the full launch command for the parallel 
                             engine without executing it.
        -verbose             Prints status information during pipeline
                             execution.
        -dir <directory>     Run a version of VisIt in the specified directory.
                             The directory argument should specify the 
                             path to a VisIt installation directory.
                             /bin is automatically appended to this path.
        -forceversion <ver>  Force the given version.  Overrides all
                             intelligent version selection logic.
        -publicpluginsonly   Disable all plugins but the default ones.
        -compiler <cc>       Require version built with the specified compiler.
        -objectmode <mode>   Require a specific object file mode.
        -forceinteractivecli Force the CLI to behave interactively, even if run
                             with no terminal; similar to python's '-i' flag.
        -fullscreen          Create the viewer window in full screen mode.
                             May not be compatible with all window managers.
        -viewerdisplay <dpy> Have the viewer use a different display than the
                             current value of DISPLAY.  Can be useful for
                             power wall displays with a separate console.
        -cycleregex <string> A regex-style regular expression to be used
                             in extracting cycle numbers from file names. It
                             is best to bracket this string in single
                             quotes (') to avoid shell interpretation of
                             special characters such as star (*). The format
                             of the string begins with an opening '<' character,
                             followed by the regular expression itself followed
                             by a closing '>' character, optionally followed by
                             a space ' ' character and sub-expression reference
                             to indicate which part of the regular expression is
                             the cycle number.  Default behavior is as if
                             -cycleregex '<([0-9]+)[^0-9]*\$> \\0'
                             was specified meaning the last sequence of one
                             or more digits before the end of the string found
                             is used as the cycle number. Do a 'man 7 regex'
                             to get more information on regular expression
                             syntax.
        -ui-bcast-thresholds <int1> <int2> 
                             Two integers controlling behavior of parallel
                             engine waiting in a broadcast for the next RPC
                             from the viewer. VisIt used to rely solely upon
                             MPI_Bcast for this. However, many implementations
                             of MPI_Bcast use a polling loop that winds up
                             keeping all processors busy and can make them
                             unuseable by other processes. This is particularly
                             bad for SMPs. So, VisIt implemented its own
                             broadcast using MPI's send/receive methods. <int1>
                             specifies the number of nanoseconds a processor
                             sleeps while polling for completion of the
                             broadcast. Specifying a value of zero (0) for <int1>
                             results in falling back to older behavior using
                             MPI's MPI_Bcast. <int1> effectively controls how
                             'busy' processors will be, polling for completion
                             of the broadcast. <int2> specifies the number of
                             seconds all processors should spin, polling as fast
                             as possible, checking for completion of the
                             broadcast BEFORE inserting sleeps into their
                             polling loops. <int2> effectively controls how
                             many seconds VisIt's server will be maximally
                             responsive (although also keeping all processors
                             occupied) before becoming more 'friendly' to
                             other processes on the same node. The defaults
                             are <int1> = 50000000 nanoseconds (1/20th of a sec)
                             and <int2> = 5 seconds meaning VisIt will spin
                             processors maximally for 5 seconds before inserting
                             sleeps such that polling happens at the rate of 20
                             times per second.
        -idle-timeout <int>  An integer representing the number of minutes an
                             engine is allowed to idle (e.g. sit there doing no
                             execution whatsoever, waiting for commands from
                             the viewer). If this timeout is reached, the engine
                             will terminate itself. The default is 480 minutes
                             (8 hours).
        -exec-timeout <int>  An integer representing the number of minutes an
                             executing engine is allowed to remain in the
                             execution of any single command from the viewer.
                             If this timeout is reached, the engine will
                             terminate itself. the default is 30 minutes.
                             Beware that among other things, this timeout
                             effects how long orphaned parallel processes will
                             hang around, tying up parallel compute resources,
                             following an exit-triggering error condition on
                             any one process.
                     
    Developer options (most for xml2... tools)
    ---------------------------------------------------------------------------
        -public              xml2cmake: force install plugins publicly
        -private             xml2cmake: force install plugins privately
        -clobber             Permit xml2... tools to overwrite old files
        -noprint             Silence debugging output from xml2... tools
        -outputtoinputdir    Force xml2... tools to write output files to
                             the directory containing the input XML file
        -arch                print supported architecture(s) and exit

    Debugging options
    ---------------------------------------------------------------------------
        Note: Debugging options may degrade performance 
    ---------------------------------------------------------------------------
        -debug <level>       Run with <level> levels of output logging.
                             <level> must be between 1 and 5. This will generate
                             debug logs (called 'vlogs' for ALL components.
                             Note that debug logs are unbuffered. However, if
                             you also specify 'b' immediately after the digit
                             indicating the debug level (e.g. '-debug 3b'), the
                             logs will be buffered. This can substantially improve
                             performance when a lot of debug output is generated.
                             However, also beware that when debug logs are buffered,
                             there isn't necessarily any guarantee they will contain
                             the most recent debug output just prior to a crash.
        -debug_<compname> <level>
                             Run specified component with <level> of output
                             logging. For example, '-debug_mdserver 4' will run
                             the mdserver with level 4 debugging. Multiple
                             '-debug_<compname> <level>' args are allowed.
        -debug_engine_rank <r>
                             Restrict debug output to the specified rank.
        -debug-processor-stride N
                             Have only every Nth processor output debug logs.
                             Prevents overwhelming parallel file systems.
        -clobber_vlogs       By default, VisIt maintains debug logs from the 5
                             most recent invocations or restarts of each VisIt
                             component. They are named something like
                             A.mdserver.5.vlog, A.engine_ser.5.vlog, etc with
                             the leading letter (A-E) indicating most to least
                             recent. The clobber_vlogs flag causes VisIt to remove
                             all debug logs and begin creating them anew.
        -vtk-debug           Turn on debugging of VTK objects used in pipelines.
        -pid                 Append process ids to the names of log files.
        -timing              Save timing data to files.
        -withhold-timing-output
                             Withhold timing output during execution. Prevents
                             output of timing information from affecting
                             performance.
        -never-output-timings
                             Never output timings files.  This is used when
                             you want the timer to be enabled (for usage by
                             developers to measure inner loops), but you
                             want to avoid blowing memory with the bookkeeping
                             for each and every timing call.
        -timing-processor-stride N
                             Have only every Nth processor output timing info.
                             Prevents overwhelming parallel file systems.
        -env                 Print env. variables VisIt will use when run.
        -dump (dump_dir)     Dump intermediate results from AVT filters,
                             scalably rendered images, and html pages.
                             Takes an optional argument that specifies the 
                             directory for -dump output files.
        -info-dump (dump_dir) 
                             Dump html pages only. 
                             Takes an optional argument that specifies the 
                             directory for -info-dump output files.
        -gdb <args> <comp>   Run gdb with <args> on component <comp>.
                             Default <args> is whitespace.
        -break <funcname>    Add the specified breakpoint in gdb.
        -xterm               With -gdb-something, run gdb in an xterm window.
        -newconsole          Run any VisIt component in a new console window.
        -totalview <args> <comp>
                             Run totalview with <args> on component <comp>.
                             Default <args> is whitespace.
        -valgrind <args> <comp>
                             Run valgrind with <args> on component <comp>.
                             Default <args> is --tool=memcheck --error-limit=no
                             --num-callers=50.
        -strace <args> <comp>
                             Run strace with <args> on component <comp>.
                             Default <args> is -ttt -T.

                             In the above, all arguments between the tool name
                             and the VisIt component name are treated as args
                             to the tool.

        -apitrace <args> <comp>
                             Run apitrace with <args> on component <comp>.
                             Default <args> is trace --api gl.

                             In the above, all arguments between the tool name
                             and the VisIt component name are treated as args
                             to the tool.

        -debug-malloc <args> <comp>
                             Run the component with the libMallocDebug library
                             on MacOS X systems. The libMallocDebug library
                             lets the MallocDebug application attach to the
                             instrumented application and retrieve memory
                             allocation statistics. The -debug-malloc flag
                             also sets up the environment for the leaks and
                             heap tools.

                             Printing heap allocations:
                             % visit -debug-malloc gui &
                             % Get the gui's <pid>
                             % heap <pid>

                             Printing memory leaks:
                             % visit -debug-malloc gui &
                             % Get the gui's <pid>
                             % leaks <pid>

                             Run with MallocDebug:
                             Perl does not seem to be happy with libMallocDebug
                             so you can run the GUI like this:
                             % visit -cli 
                             >>> OpenGUI('-debug-malloc', 'MallocDebug', 'gui')
                             Connect to the gui with MallocDebug and do your
                             sampling.
        -nsys <args> <comp>
                             Run Nsight Systems cli with <args> on component <comp>.
                             Default <args> are: profile --stats=true --gpu-metrics-device=all

        -numrestarts <#>     Number of attempts to restart a failed engine.
        -quiet               Don't print the Running message.
        -protocol            Print the definitions of the state objects that
                             comprise the VisIt protocol so they can be compared
                             against the values on other computers.


.. toctree::
    :maxdepth: 2