Running USim from the Command Line¶

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

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

For more information about the decomp script, run the script with the help option:

<ULIXES_BIN_DIR>/decomp -h