# AcuTransTrace

Translate acuRunTrace solution binary record output to other formats.

## Syntax

acuTransTrace [options]

## Type

acuRunTrace Post-Processing Program

## Description

The results of AcuRunTrace are stored using an internal format in a number of files in the directory specified by the working directory option, ACUSIM.DIR by default. These files are written in binary record format by default. AcuTransTrace can gather and translate results in binary record format into various formats more suited for post-processing or visualizing by third party products. For example, to translate the trace output results of the channel problem in order to visualize with FieldView, issue the command:
acuTransTrace -pb channel -to fieldview -fvopt streamline,steady
which creates the file channel.trace.fvp for visualization by FieldView. Alternatively place the option(s) in the configuration file Acusim.cnf as follows:
problem               = channel
translate_to          = fieldview
fieldview_options     = streamline,steady
and issue the command:
acuTransTrace
AcuRunTrace generates three types of results: TRACE_OUTPUT, TIME_CUT_OUTPUT and POINCARE_OUTPUT. The corresponding AcuTransTrace options for translating them are streamline, time_cut, and poincare. The term streamline is used here to refer to both true streamline output for steady AcuSolve flows and pathline output for unsteady flows. The results may be translated into one of the following formats: ensight, fieldview, endstats, and poincaretable. In addition, query reports which AcuRunTrace result types are available. The following table lists the supported combinations:
Table 1.
AcuTransTrace option EnSight FieldView Endstats Poincare Table AcuDisplay Query
streamlin no yes yes no yes yes
time_cut yes yes yes no yes yes
poincare yes yes yes yes yes yes
For all formats except query, AcuTransTrace reports the output variables found in the AcuRunTrace results, for example:
acuTransTrace:                 Outputs are:
acuTransTrace:           velocity_magnitude
acuTransTrace:                   element_id
acuTransTrace:               element_set_id
acuTransTrace:                       marker
acuTransTrace:                     x_length
acuTransTrace:                     y_length
acuTransTrace:                     z_length
acuTransTrace:                   x_velocity
acuTransTrace:                   y_velocity
acuTransTrace:                   z_velocity

Note that particle position is required by all the translation formats and therefore is not listed. Particle time is only listed for the poincaretable and Poincare EnSight formats; it is required by all the other formats and therefore not listed for those.

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.
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.
run_id or run (integer)
Number of the AcuSolve run used by the trace run. If run_id is set to 0, this option is ignored. This parameter needs to explicitly set only in rare cases.
trace_run_id or trun (integer)
Number of the AcuRunTrace run to translate. If trace_run_id is set to 0, the last trace run in the working directory is assumed.
translate_to or to (enumerated)
Translate the AcuRunTrace output to this format:
query
Print information about available AcuRunTrace result types.
ensight
Translate to EnSight Gold format.
fieldview
Translate to FieldView format.
endstats
Report the end point statistics, that is, the reasons the trace of each particle ended.
poincaretable
Translate Poincare results into an AcuTraceClassic style Poincare table.
Number of threads to use. Note that MPI is not available, so there is no np option. This option is available only with translate_to = ensight.
fieldview_options or fvopt (string)
A comma separated list of FieldView translation options. The list may include:
streamline
Use streamline (pathline) results if available.
time_cut
Use timecut results if available.
poincare
Use Poincare results if available.
pseudotc
Use pseudo timecut values for time with Poincare results.
ascii
Convert to FieldView ASCII Particle Path format. This format is for use with steady-state flows and is a synonym for steady.
binary
Convert to FieldView BINARY Particle Path format. This format is for use with transient flows and is a synonym for unsteady.
ensight_options or ensopt (string)
A comma separated list of EnSight translation options. The list may include:
time_cut
Use timecut results if available.
poincare
Use Poincare results if available.
pseudotc
Use pseudo timecut value for time with Poincare results.
binary
Write binary EnSight files.
ascii
Write ASCII EnSight files.
nomesh
Do not write the AcuSolve mesh file. This can be a run time savings if the mesh file exists and is current.
end_stat_options or endopt (string)
A comma separated list of end point statistics translation options. The list may include:
streamline
Use streamline (pathline) results if available.
time_cut
Use timecut results if available.
poincare
Use Poincare results if available.
acudisplay_options or acdopt (string)
A comma separated list of AcuDisplay translation options. The list may include:
streamline
Use streamline (pathline) results if available.
time_cut
Use timecut results if available.
poincaretable_options or ptbopt (string)
A comma separated list of Poincare table translation options. The list may include:
ordered
Sort the table by seed number and Poincare plane number. This can take a while.
unordered
Do not sort the table.
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, including the output variables found, is printed in addition to warning and error messages. This level is recommended.

## Examples

For query format, AcuTransTrace simply reports the available AcuRunTrace result types and which AcuSolve run was used. For example, if the output of
acuTransTrace -to query
is
acuTransTrace: -----------------------------------------------------------------
acuTransTrace:                         Date = Tue Aug 30 20:54:35 2011
acuTransTrace:                      Problem = mixer
acuTransTrace:                     Flow Run = 1
acuTransTrace:                    Trace Run = 8
acuTransTrace:        Streamline trace type = Available
acuTransTrace:           Timecut trace type = Available
acuTransTrace:          Poincare trace type = Available
acuTransTrace:                     Hostname = COOT
acuTransTrace:                     Platform = Whistler 5.1 i686
acuTransTrace:                      Machine = WIN
acuTransTrace:                      Release = 1.8a
acuTransTrace:                 Release date = Aug 30 2011
acuTransTrace: -----------------------------------------------------------------
then the last AcuRunTrace trace run ID is 8 and all three possible result types are available for translation. If the output of
acuTransTrace -to query -trun 1
includes
acuTransTrace:        Streamline trace type = Available
acuTransTrace:           Timecut trace type = Available
acuTransTrace:          Poincare trace type = Unvailable

then streamline and timecut results are available for trace_run_id = 1, but Poincare results are not.

For fieldview format, AcuTransTrace translates the output to either FieldView ASCII Particle Path or Binary Particle Path format. The ASCII format is specified by the steady option, while binary is specified by the unsteady option. For either option, the file is named <problem>.trace.fvp. streamline (pathline) and poincare output can be converted to ASCII format only. The conversion of poincare output uses the time values associated with the plane hits. If pseudotc is set, Poincare plane numbers are converted to time values, and these times are used instead of the actual times. In the case of multiple plane hits, the pseudo time cut value is given by
(hit_number - 1) * number_of_planes + plane_number
To convert trace output to FieldView format, run
acuTransTrace -to fieldview -fvopt steady,streamline
Alternatively, the ascii option can be used as a synonym for steady:
acuTransTrace -to fieldview -fvopt ascii,streamline
To convert time cut output to FieldView format, run
acuTransTrace -to fieldview -fvopt steady,time_cut
or
acuTransTrace -to fieldview -fvopt unsteady,time_cut
which is also equivalent to
acuTransTrace -to fieldview -fvopt binary,time_cut
To convert Poincare output to FieldView format, run
acuTransTrace -to fieldview -fvopt poincare
or
acuTransTrace -to fieldview -fvopt poincare,pseudotc
For ensight format, AcuTransTrace translates the output to EnSight Gold format. This option creates a number of files. The primary one is problem.trace.case, which references the other files. These other files are all contained in the directory ENSIGHT.DIR. With the exception of particle position, the particle and flow outputs are written in files named problem.varname.nnnnn, where varname is the variable name and nnnnn is the time cut or Poincare plane number; particle position outputs are written in files named problem.mgeo.nnnnn. For example, if AcuRunTrace wrote time cut output for two time cuts for particle_coordinates and particle_time,
acuTransTrace -to ensight -ensopt ascii,time_cut
creates the file mixer.trace.case and the ASCII files mixer_mesh.geo, mixer.mgeo.00001, mixer.mgeo.00002, mixer.time.00001, and mixer.time.00002. The file mixer.trace.case looks like:
#===============================================
# EnSight Gold Case file for particle
#
# Problem       : mixer
#
# Generated by  : acuTransTrace
# Release       : 1.8a
# Release date  : Aug 30 2011
# Date          : Tue Aug 30 18:35:21 2011
#
#===============================================
FORMAT
type: ensight gold
GEOMETRY
model: ENSIGHT.DIR/mixer.mesh.geo
measured: ENSIGHT.DIR/mixer.mgeo.*****
VARIABLE
scalar per measured node: time ENSIGHT.DIR/mixer.time.*****
TIME
time set: 1
number of steps: 2
filename numbers: 1 2
time values: 0 0.0001

Time cut or Poincare output can be converted to EnSight format. Since a particle may hit a Poincare plane multiple times, a given seed can appear multiple times in a single EnSight file. If the pseudotc option is used, however, Poincare plane numbers converted to time values, and so a seed does only appear once in a single EnSight file. In the case of multiple plane hits, the pseudo time cut value is again given by the expression described above in the FieldView discussion.

To convert Poincare output to EnSight format, then, use either
acuTransTrace -to ensight -ensopt poincare,binary (or ascii)
or
acuTransTrace -to ensight -ensopt poincare,pseudotc,binary (or ascii)

For endstats format, AcuTransTrace creates a text file problem.trace.end. The file consists of a table,

one line per particle, listing the possible reasons why the particle trace ended.

For example, if the AcuRunTrace run for problem mixer produced Poincare output, then
acuTransTrace  -to endstats -endopt poincare
produces the file mixer.trace.end. All end stats files have 19 columns as follows:
Table 2.
1 Seed Global seed number
2 X X coordinate of particle position
3 Y Y coordinate of particle position
4 Z Z coordinate of particle position
5 Time Particle time
6 Speed Magnitude of particle velocity
7 Lx X coordinate of particle stretch vector, or 1 if no stretch equation
8 Ly Y coordinate of particle stretch vector, or 0 if no stretch equation
9 Lz Z coordinate of particle stretch vector, or 0 if no stretch equation
10 ElmId Element set ID number (1-based)
11 ElemId Element ID (1-based)
12 Out 1 if particle left domain through an outflow face, 0 otherwise
13 Wall 1 if particle stopped at a wall surface; 0 otherwise
14 Node 1 if particle stopped at a wall node; 0 otherwise
15 Ssi 1 if particle stopped at an interface surface; 0 otherwise
16 Rff 1 if particle stopped at a reference frame boundary; 0 otherwise
17 Time 1 if particle time exceeded maximum trace time; 0 otherwise
18 Tcut 1 if particle hit the last time cut and only time cut output requested; else 0
19 Segs 1 if number of particle segments exceeds maximum; 0 otherwise

For columns 12 to 19, more than one column can contain a "1" because the table lists all the possible reasons why the particle trace ended. Note that 1 is not a possible value for Rff if the AcuRunTrace FLOW_FIELD type is pseudotransient.

For poincaretable format, AcuTransTrace creates a text file problem.pps. The file consists of a table, each line containing a single Poincare plane/particle pair. A Poincare plane/particle pair can appear multiple times. The first five columns of the table are always:
• global particle number
• Poincare plane number
• x,y,z coordinates of the intersection of the particle path line with the plane
The contents of the remaining columns are reported by AcuTransTrace. For example, if
acuTransTrace -to poincaretable
reports
acuTransTrace: -----------------------------------------------------------------
acuTransTrace:                 Outputs are:
acuTransTrace:                         time
acuTransTrace:                   element_id
acuTransTrace:               element_set_id
acuTransTrace:                   x_velocity
acuTransTrace:                   y_velocity
acuTransTrace:                   z_velocity
acuTransTrace: -----------------------------------------------------------------

then columns 6-11 of problem.pps are time, the element set and element IDs, and the particle velocity.