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: 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.

num_threads or nt (integer)

Number of threads to use.

Note: 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

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

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

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)

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.
Column number	Column heading	Description
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: One 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.