AcuRunTrace

Syntax

acuRunTrace [options]

Type

AcuSolve Post-Processing and Co-Processing Program

Description

AcuRunTrace computes particle traces for flows computed by AcuSolve. These include unsteady as well as steady flows, flows with mesh motion as well as without, and flows computed on meshes with interface surfaces. AcuRunTrace can also compute traces for flows on meshes with multiple reference frames in either of two ways: by converting flow velocities to the local reference frame or by treating the boundaries between stationary and rotating reference frames as interface surfaces and the flow as pseudotransient.

AcuRunTrace is actually a script that executes the program AcuTrace in scalar or parallel environments. The program AcuTraceClassic is an older version of AcuTrace with less functionality. Most of the inputs to AcuTrace are provided in a trace input file. The AcuTrace Command Reference Manual describes these inputs. The command line options of AcuRunTrace control the run environment of AcuTrace as well as high level options, such as the name of the trace input file. The program AcuTrace does not ever need to be invoked directly.

There are four types of output that can be generated by AcuRunTrace: trace, time cut, Poincare plane, and interpolate. Output is controlled by commands in the trace input file. Particle traces are computed by AcuRunTrace as a series of segments using fifth-order time-discontinuous Galerkin (TDG) with error control. Trace output records the endpoints of these segments.

Poincare plane output is written only when a particle path crosses through and inside of the Poincare section rectangles. The particle path is interpolated between the segment endpoints that are on either side of the rectangle. Three points define a rectangle as follows: the first two points define one edge of the rectangle, and the third point is projected to the closest plane that is normal to this edge and passes through one of the first two points. The fourth point is constructed to finish the rectangle.

Time cut output is produced for all particles at the time cuts. The particle path is interpolated in time between the segment endpoint steps on either side of the time cut.

Interpolate output does not require any particle tracing. It records the initial seed values of the particle. Interpolate output is a legacy format provided for backward capability.

The other three types of output can be converted to other formats, such as EnSight and FieldView, by the utility AcuTransTrace.

In the following, the full name of each AcuRunTrace option is followed by its abbreviated name and its type. For a general description of option specifications, see Command Line Options and Configuration Files. See below for individual option details:

help or h (boolean)

If set, the program prints a usage message and exits. The usage message includes all available options, their current values and the source of their current values.

problem or pb (string)

The name of the problem is specified via this option. This name is used to build internal file names and to generate output files.

file_format or fmt (enumerated) [=bin_rec]

Format of the trace output files.

bin_rec

Binary record format.

ascii

ASCII text format.

binary

Raw binary format.

trace_input_file or tin (string)

Name of the trace input file is specified via this option. If trace_input_file is set to _auto, name.tin is used, where name is the string supplied to the problem. See the AcuTrace Command Reference Manual for trace input file details.

working_directory or dir (string)

All internal files are stored in this directory. This directory does not need to be on the same file system as the user-supplied input files.

problem_directory or pdir (string)

The home directory of the problem. This is where the user input files reside.

log_output or log (boolean)

If set, the printed messages of AcuRunTrace are redirected to the .log file problem.run.tlog, where problem is the string supplied to the problem option and run is the ID of the current trace run. Otherwise, the messages are sent to the screen and no logging is performed.

append_log or append (boolean)

If log_output is set, this parameter specifies whether to create a new log file or append to an existing one.

echo_help or eh (boolean)

Echo the command help, that is, the results of acuRunTrace -h, to the .log file.

message_passing_type or mp (enumerated)

Type of message passing environment used for the parallel processing of a particle tracer:

none

Run in single-processor mode.

impi

Run in parallel on all platforms using Intel MPI.

pmpi

Run in parallel on all platforms using Platform MPI.

mpi

Run in parallel on all platforms using MPICH.

msmpi

Run in parallel on Windows using Microsoft MPI.

hpmpi

Run in parallel on all platforms using Platform MPI.

Note: HP-MPI has been replaced by Platform MPI and this option is only included for backward compatibility. Identical to setting mp=pmpi.

openmp

Run in parallel on all platforms using OpenMP.

num_processors or np (integer)

This option specifies the total number of threads to be used. The number of physical processors used is num_processors divided by num_threads. If message_passing_type is set to none, num_processors is reset to 1.

num_threads or nt (string)

This option specifies the number of threads per processor to be used. If num_threads>1, this option converts an MPI run to a hybrid MPI/OpenMP run. If this option is set to _auto, AcuRunTrace automatically detects the number of cores on the machine and sets the thread count accordingly. This forces AcuTrace to use shared memory parallel message passing whenever possible.

host_lists or hosts (string)

List of machines (hosts) separated by commas. This list may exceed num_processors; the extra hosts are ignored. This list may also contain fewer entries than num_processors. In this case, the hosts are populated in the order that they are listed. The process is then repeated, starting from the beginning of the list, until each process has been assigned to a host. Multiple process may be assigned to a single host in one entry by using the following syntax: host:num_processes, where host is the host name, and num_processes is the number of processes to place on that machine. When this option is set to _auto, the local host name is used.

The following examples illustrate the different methods of assigning the execution hosts for a parallel run:

Example 1:

acuRunTrace -np 6 -hosts node1,node2

Result: The node list is repeated to use the specified number of processors. The processes are assigned: node1, node2, node1, node2, node1, node2

Example 2:

acuRunTrace -np 6 -hosts node1,node1,node2,node2,node1,node2

Result: The processes are assigned: node1, node1, node2, node2, node1, node2

Example 3:

acuRunTrace -np 6 -hosts node1:2,node2:4

Result: The processes are assigned: node1, node1, node2, node2, node2, node2

pbs (boolean)

Set parallel data, such as np and hosts, from PBS variable PBS_NODEFILE. Used when running AcuTrace through a PBS queue.

lsf (boolean)

Set parallel data, such as np and hosts, from LSF variable LSB_HOSTS. Used when running AcuTrace through a LSF queue.

sge (boolean)

Set parallel data, such as np and hosts, from SGE file $TMPDIR/machines.

nbs (boolean)

Set parallel data, such as np and hosts, from NBS var NBS_MACHINE_FILE.

ccs (boolean)

Set parallel data, such as np and hosts, from CCS var CCP_NODES.

slurm (boolean)

Set parallel data, such as np and hosts, from output of srun hostname -s command.

acutrace or acutrace_executable (string)

Full path of the AcuTrace executable.

acu_port or acuport (integer)

Port for establishing connection to AcuSolve.

acu_wait or acuwait (integer)

The maximum time to wait when trying to establish a connection to AcuSolve.

flush_freq or flush (integer)

Output flush frequency. Output is flushed after every flush_freq segments of the current particle are computed.

user_libraries or libs (string)

Comma-separated list of user libraries. These libraries contain the user-defined functions and are generated by AcuMakeLib or AcuMakeDll.

mpirun_executable or mpirun (string)

Full path to mpirun, mpimon, dmpirun or prun executable used to launch an MPI job. If _auto, executable is determined internally.

mpirun_options or mpiopt (string)

Optional arguments to append to the mpirun command that is used to launch the parallel processes. When this option is set to _auto, AcuRun internally determines the options to append to the mpirun command.

remote_shell or rsh (string)

Remote shell executable for MPI launchers. Usually this is rsh but can be set to ssh if needed. If _auto, executable is determined internally.

memv (boolean)

Print memory allocations.

automount_path_remove or arm (string)

Automount path remove. If automount_path_remove is set to _none, this option is ignored.

automount_path_replace or arep (string)

Automount path replacement. If automount_path_replace is set to _none, this option is ignored.

automount_path_name or apath (string)

Automount path name. If automount_path_name is set to _none, this option is ignored.

lm_daemon or lmd (string)

Full address of the network license manager daemon, AcuLmd, that runs on the server host. When this option is set to _auto, the value is internally changed to $ACUSIM_HOME/$ACUSIM_MACHINE/bin/acuLmd. This option is only used when lm_service_type = classical.

lm_service_type or lmtype (enumerated)

Type of the license manager service:

hwu

Altair Units licensing.

token

Token based licensing.

classical

Classical Acusim style licensing.

lm_server_host or lmhost (string)

Name of the server machine on which the network license manager runs. When set to _auto, the local host name is used. This option is only used when lm_service_type = classical.

lm_port or lmport (integer)

TCP port number that the network license manager uses for communication. This option is only used when lm_service_type = classical.

lm_license_file or lmfile (string)

Full address of the license file. This file is read frequently by the network license manager. When this option is set to _auto, the value is internally changed to $ACUSIM_HOME/$ACUSIM_MACHINE/license.dat. This option is only used when lm_service_type = classical.

lm_checkout or lmco (string)

Full address of the license checkout co-processor, acuLmco. This process is spawned by the solver on the local machine. When this option is set to _auto, the value is internally changed to $ACUSIM_HOME/$ACUSIM_MACHINE/bin/acuLmco.

lm_queue_time or lmqt (integer)

The time, in seconds, to camp on the license queue before abandoning the wait. This option is only used when lm_service_type = classical.

line_buff or lbuff (boolean)

Flush standard output after each line of output.

print_environment_variables or printenv (boolean)

Prints all the environment variables in AcuRunTrace and those read by AcuTrace.

verbose or v (integer)

Set the verbose level for printing information to the screen. Each higher verbose level prints more information. If verbose is set to 0, or less, only warning and error messages are printed. If verbose is set to 1, basic processing information is printed in addition to warning and error messages. This level is recommended. verbose levels of 2 and 3 provide useful information on the progress of the trace. Levels greater than 3 provide information useful only for debugging.

Examples

EQUATION {
particle = massless
}
FLOW_FIELD {
problem = "channel"
}
AUTO_SOLUTION_STRATEGY {
}
TRACE_OUTPUT {
active = on
}
PARTICLE_SEED( "seeds" ) {
seed_coordinates = Read("channel.seed")
}
RUN {
}

acuRunTrace -tin channel.tin

acuTransTrace -to acudisplay -acdopt streamline

acuDisplay -psl channel.psl

acuRunTrace -tin channel.tin -mp pmpi -np 10

Here AcuRunTrace sets the PMPI parallel environment and runs AcuTrace.

acuRunTrace -tin channel.tin -mp openmp -np 10

Here AcuRunTrace sets the OpenMP parallel environment, and runs AcuTrace.

To run the channel problem in parallel on three processors with two threads per processor using a hybrid MPI/

acuRunTrace -tin channel.tin -mp mpi -np 6 -nt 2

Here AcuRunTrace sets up all the MPI related data and the OpenMP parallel environment, and runs AcuTrace.

The options acutrace_executable and mpirun_executable should rarely be changed. They are used to access executables other than the current ones.

Running AcuTrace in distributed memory parallel requires that the problem and working directories be accessible by all involved machines. Moreover, these directories must be accessible by the same name. In general, working_directory does not pose any difficulty, since it is typically specified relative to the problem_directory. However, problem_directory requires special attention.

By default, problem_directory is set to the current Unix directory ".". AcuRunTrace translates this address to the full Unix address of the current directory. It then performs three operations on this path name in order to overcome some potential automount difficulties. First, if the path name starts with the value of automount_path_remove, this starting value is removed. Second, if the path name starts with from_path, it is replaced by to_path, where the string "from_path,to_path" is the value of automount_path_replace option. Third, if the path name does not start with the value of automount_path_name, it is added to the start of the path name. These operations are performed only if problem_directory is not explicitly given as a command line option to AcuRunTrace, and also if the option associated with each operation is not set to _none. If problem_directory is explicitly given as a command line option, you are responsible for taking care of all potential automount problems.

The options lm_daemon, lm_server_type, lm_server_host, lm_port, lm_license_file, lm_checkout, and lm_queue_time are used for checking out a license from a network license manager. These options are typically set once by the system administrator in the installed system configuration file, Acusim.cnf. Given the proper values, AcuTrace automatically starts the license manager if it is not already running. For a more detailed description of these parameters consult AcuLmg. This executable is used to start, stop, and query the license manager.

The bin_rec format is the default. The other two formats are provided for backward compatibility with an older version of AcuTrace. Trace, timecut, and Poincare output written in the bin_rec format can be converted to a number of useful formats, such as FieldView and EnSight, by the AcuTransTrace command. It is recommended that bin_rec format be used when any of these three output types are active. INTERPOLATE_OUTPUT is a legacy output type provided for backward capability.

Generally, AcuTrace runs as a post-processor to AcuSolve. However, it is possible to run the two codes concurrently in a coupled manner. There are two AcuRunTrace options that control this co-processing mode. acu_port specifies the port for the socket connection and overwrites coupling_socket_port in the FLOW_FIELD command in the trace input file. The maximum amount of time to wait for the AcuSolve connection is given by acu_wait.