# Running USim from the Command Line¶

The following sections describe how to run USim from the command line.

## PATH Definitions¶

The following definitions will be used for the remainder of this section.

On Mac:

<ULIXES_BIN_DIR>=/Applications/USimComposer.app/Contents/engine/bin
<ULIXES_LIB_DIR>=/Applications/USimComposer.app/Contents/engine/lib
<ULIXES_SHARE_DIR>=/Applications/USimComposer.app/Contents/engine/share


On Linux (assuming you have chosen /usr/local/USimComposer as your default installation directory):

<ULIXES_BIN_DIR>=/usr/local/USimComposer/Contents/engine/bin
<ULIXES_LIB_DIR>=/usr/local/USimComposer/Contents/engine/lib
<ULIXES_SHARE_DIR>=/usr/local/USimComposer/Contents/engine/share


On Windows (e.g. 64-bit)

<ULIXES_BIN_DIR>=C:\Program Files\Tech-X (Win64)\USim 6.0\Contents\engine\bin
<ULIXES_SHARE_DIR>=C:\Program Files\Tech-X (Win64)\USim 6.0\Contents\engine\share


## Running a USim Pre File¶

Your USim distribution package contains two executable programs for running USim, one for serial computations (ulixesser) and another for parallel computations (ulixes). Both versions of the USim executables are located in the ULIXES_BIN_DIR directory.

### Command Line Features¶

If USim is run from the command line, input file and runtime options are specified as command line options. USimComposer sets up your environment prior to running USim, and therefore you must set up your environment when running USim from the command line. You will need to modify the environment variables LD_LIBRARY_PATH and PATH.

If you are using the bash shell, you will need to modify LD_LIBRARY_PATH by adding the following line to your .bashrc:

export LD_LIBRARY_PATH=<ULIXES_LIB_PATH>:$LD_LIBRARY_PATH  Instead, if you are using the csh shell (or one of its variants such as tcsh), you will need to add the following line to your .cshrc: setenv LD_LIBRARY_PATH <ULIXES_LIB_DIR>:$LD_LIBRARY_PATH


Similarily, to set your PATH in the bash shell, you will need to add the following line to your .bashrc:

export PATH=<ULIXES_BIN_DIR>:$PATH  whereas in csh/tcsh, you will need to add the following line to your .cshrc: setenv PATH <ULIXES_BIN_DIR>:$PATH


Note that any changes you make to your .bashrc/.cshrc do not take effect until the next time you log in, so after modifying your startup file, you must execute the following command in your current shell, but will not need to do it in the future:

source ~/.bashrc    (for bash)


or

source ~/.cshrc     (for csh/tcsh)


### Order of Parameter Precedence¶

If a parameter is both set within the input file and specified on the command line, the command line parameter value takes precedence. The command line override enables you to configure an input file with default values while exploring alternative parameter settings from the command line. From the command line, you can quickly change simulation run lengths, dimensionality, output timing, etc.

### Examples of Running USim from the Command Line¶

In these examples, it is assumed that you are either in the directory in which the ulixesser is installed or you have added the appropriate directory to your shell path.

### Command Line Options¶

The first step in running USim on the command line is to preprocess the input file. Run the preprocessor (txpp.py) on the .pre file as follows

./txpp.py filaname.pre


The output will be a file called filename.in. The .in file is then used with the ulixes executable as follows To use multiple options, the command line syntax is:

./ulixesser -i filename.in [-o prefix_name] [-r num]


in which ./ulixesser is used to run a serial computation. See Serial Computation for details about serial computation. See the Parallel Computation for details of command line invocation with parallel computation scripts.

Commonly used options that you can specify on the command line include:

-i filename.in

Read input from file named filename.

For example:

./ulixesser -i sodShock.in

-o prefix_name

Base names of output files on the text string prefix_name.

For example, if you want output files named newforwardFacingStep rather than forwardFacingStep, use:

./ulixesser -i forwardFacingStep.in -o newforwardFacingStep

-r num

Restart USim from dump num.

For example, if you want to restartforwardFacingStep using the output dumped at time step 50, use:

./ulixesser -i sodShock.in -r 50


More details on how to restart USim are given in Restarting a USim Simulation

## Serial Computation¶

The USim executable for use in serial computation is named ulixesser. Except as noted, the explanations and tutorials within the USim In Depth and USim Quick Start demonstrate USim usage for serial computations. Here is an example of USim command line invocation using a pre file named myfile.pre with corresponding .in file myfile.in. By default, the output files for this example would be named using the format myfile.out.

ulixesser -i myfile.in


Note

The above invocation line assumes you added <ULIXES_BIN_DIR> to your PATH, as noted in the Command Line Features section.

Note

When running USim via USimComposer, command line options are not directly available, however -i and -o command line options described in this document are implicit; that is, these options are automatically invoked when running USimComposer.

## Parallel Computation¶

The USim executable for use in parallel computation is named ulixes. This section explains use of the USim executable program for parallel computations.

USim for parallel computations requires the Message Passing Interface (MPI). For information about MPI for use with USim, see Running USim with mpiexec.

### Parallel Computation Scripts¶

Running USim with MPI or Parallel Queuing Systems requires use of different shell scripts to enable invocation of the USim executable as discussed in the following sections.

### Running USim with mpiexec¶

USim comes bundled with a distribution of Open MPI, which must be used to run USim in parallel (in other words, even if you have an installation of Open MPI on your machine, you should use the one included with USim).

In order to run USim in parallel via the command line, you must first add the <ULIXES_BIN_DIR> to your PATH, as noted in the Command Line Features section.

To run USim in parallel, execute the following command:

mpiexec -np <#> ulixes -i filename.in


in which <#> is the number of processors, ulixes is the executable program for parallel computations, and filename.in is the name of the USim .in file (which must be in the current directory, or must be specified by a full path).

Following mpiexec, but before <ULIXES_BIN_DIR>, you can specify a variety of mpiexec options. For more information about mpiexec, including the complete list of options, see a man page or other documentation for mpiexec.

Following ulixes, you can specify a variety of USim options. For a list of commonly used options, see Command Line Features.

USim automatically adjusts its decomposition to match the number of processors it is given.

### Running USim with Parallel Queuing Systems¶

Parallel queuing systems, such as LoadLeveler and PBS, require the submission of a shell script with embedded comments that the systems interpret. Here is an example of a basic shell script for a PBS-based system:

#PBS -N NDS_ulixes
#PBS -l nodes=2:ppn=2
cd /directory/containing/your/input/file
mpiexec -np 4 ulixes -i your_input_file.in


### Running USim in Parallel under Windows¶

To run USim in parallel on a Windows system, bring up a DOS window. From the command prompt,

<ULIXES_BIN_DIR>\mpiexec.exe -np 2 <ULIXES_BIN_DIR>\ulixes.exe -i your_input_file.in


### Running SEACAS partitioner on Linux¶

To decompose a meshfile for a number of processors use the provided SEACAS partitioner script (decomp). For example, if you plan to use 8 processors, from the command line run:

<ULIXES_BIN_DIR>/decomp -p 8 meshfile.g


<ULIXES_BIN_DIR>/decomp -h