Using *TREAD in Ansys Mechanical APDL to Read External Data

The *TREAD Command and Comma-Separated Values (CSV)

Engineers using TREAD command in Ansys or the *VREAD command to get data into Ansys Mechanical APDL, sometimes get stuck in the process. The most common data reading needs include numbers from a two-column 2D table, or from a multiple-column 2D table. More complex data structures are possible, but not discussed in this document.

The *VREAD and *TREAD commands read numerical data from an ASCII text file. *VREAD, like *VWRITE, requires a format statement to follow immediately. *VREAD loads data into a numerical Array and requires a file with data in a fixed format specified by the format statement. This offers little flexibility. The *TREAD command can read data from a Comma Separated Variable (CSV) file, without a format statement. *TREAD loads data into a Table Array, and is flexible in whether the data is in floating point or exponential format (e.g. 0.123e-2 versus 0.00123), plus, a variety of numbers of digits of accuracy is supported. A CSV file is easily written from an EXCEL spreadsheet, or by other software. Users might use *TREAD to enter CSV file data, even if the ultimate use for the data was not in a Table Array.

This article illustrates use of the *TREAD command, and differences in where data is placed in a Table Array when a 2-column CSV file is read, versus a multi-column CSV file. Movement of data from a Table Array into a numerical ARRAY is also illustrated.

*TREAD Behavior with 2-Column CSV Files versus Multi-Column CSV Files

A Table Array in Ansys is created by the *DIM command, for example:

*DIM,my_table,TABLE,5,1,1,TIME

In the above command, the Table Array’s name will be “my_table”, it is an array of type Table, it is to have 5 rows, 1 column of data (plus a Zeroth column of data), and one plane of data. The Zeroth column is intended to represent the primary variable TIME if the above Table Array is used in an Ansys command, as indicated by the 6th argument.

The principal purpose of the *TREAD command is to load data into a table array that is in turn to be used in Ansys commands. If the data comes from a 2-column CSV data table, it is assumed that the first column of the data table is intended for use in the Zeroth column of the Table Array, and that the second column in the data table is intended for use in the First column of the Table Array. This can be seen in the figure above. What is special about the treatment of a 2 column CSV file table of data is that the First Row of the CSV file is to go into the First Row of the table array. It is assumed that there is no primary or other variable for the Column positions when a 2-column CSV file is loaded, so no data is placed in the Zeroth Row of the Table Array. The dimension for the number of rows is the same as the number of rows of data in the CSV file.

If data comes from a 3-column CSV file, or with more columns, each column is shifted one column to the left in the Table Array, with the first column of the CSV file going into the Zeroth column of the Table Array, and so on. What differs from 2-column CSV file treatment is that Ansys assumes that the First Row of the CSV file is intended for the Zeroth Row of the Table Array, as an index for interpolation. Unlike loading data from a 2-Column CSV file into a Table Array, all the rows are shifted up by one row when *TREAD brings in a multi-column CSV file. Users must be aware of this behavior. The dimension of the number of rows in such a Table Array can be reduced by one, since the Zeroth row will hold data.

In the figure above, in the view of Table Array data on the right, the (0,0) position in the Table Array contains a numerical value, even though it is not shown. In this example, it contains 0.0.

Reading a CSV File with *TREAD

Users should note that successful reading of a CSV file with *TREAD requires that each row of the CSV file have the same number of items, even if they are null entries separated by commas. The number of commas must be the same in each row of the incoming CSV file. If there are header lines, as illustrated in Figure 1 above with “Time,Value”, they can be skipped with an argument in the *TREAD command. The user has to know how many lines to skip in advance, entering the correct value.

The user does not need to know how many lines are in the CSV file. One way to discover the number of lines in a text file is with the APDL command:

/INQUIRE,numlines,LINES,data_example,csv

In the above command, the argument data_example is the name of the CSV file, and csv is the extension. The argument numlines is the scalar parameter that will hold the number of lines in the file. The user needs to know the number of columns in a row, and the number of rows to skip at the start of the file—this can usually be done discovered by visual inspection of the CSV file. From that information, the dimensions of the Table Array can be calculated.

If the CSV file has two columns, then the dimensioned number of rows for a 2D Table Array must be the same as the number of rows of numerical data. The number of columns must be one less than the number of columns in the CSV file.

If the CSV file has three or more columns, then the dimensioned number of rows for a 2D Table Array must be one less than the number of rows of data. The number of columns must be one less than the number of columns in the CSV file.

Documentation for the *TREAD command includes:

*TREAD, Par, Fname, Ext, –, NSKIP
Reads data from an external file into a table array parameter.

Argument Descriptions

Par Table array parameter name as defined by the *DIM command.
Fname
File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name.
File name has no default.

Ext Filename extension (eight-character maximum).
Extension has no default.
– Unused field.
NSKIP Number of comment lines at the beginning of the file being read that will be skipped during the reading. Default = 0.
The name of the previously dimensioned Table Array is supplied as the argument Par. The number of lines to skip at the beginning of the file is supplied as the argument NSKIP.

In the following commands, the user must supply the to_skip value, based on inspection of the CSV file.

For a 2-column CSV file, commands to read the file could be:

to_skip=0 ! enter number of lines to skip–NONE in this example
/INQUIRE,numlines,LINES,data_example,csv
to_read=numlines-to_skip
!
*DEL,mytable,,NOPR
*DIM,mytable,TABLE,to_read ! table array to hold data
*TREAD,mytable,data_example,csv,,to_skip

For a 3-column CSV file, commands to read the file could be:

to_skip=0 ! enter number of lines to skip–NONE in this example
/INQUIRE,numlines,LINES,data_example,csv
to_read=numlines-to_skip
!
*DEL,mytable,,NOPR
! Number of rows reduced by one:
*DIM,mytable,TABLE,to_read-1,2 ! table array to hold data
*TREAD,mytable,data_example,csv,,to_skip

Note that in the example for 3-columns, because the Zeroth row of the Table Array receives data, the number of rows to dimension with *DIM is reduced by one.

Moving Table Array Data to a Numerical Array

In some situations, users do not actually want a Table Array, but want an array’s worth of data loaded into Ansys for other purposes. If a CSV file has the same number of columns in every row, then the *TREAD command can read the data. The *VFUN command can be used to move the Table Array data into a numerical Array. Where to position the Table Array data in the numerical Array that receives the data depends on whether the original CSV file had two columns or more.

A numerical array is created by the *DIM command as in the following example:

*DIM,myarray,ARRAY,5,2,1

The above command creates a numerical array “myarray”, with 5 rows (there is no Zeroth row in an Array) and 2 columns (there is no Zeroth column in a numerical Array), plus one plane of data.

Here are APDL commands that read data from a CSV file called “two_column_example.csv” and transfer that data into a numerical Array called myarray. One line in the CSV file is to be skipped:

! Example reading 2-column data from a CSV file into a Table Array
! Enter the name of the CSV file below
! Column 0 of ‘mytable’ will hold first column of the CSV file
! Column 1 of ‘mytable’ will hold second column of the CSV file
!
to_skip=1 ! Enter number of lines to skip
/INQUIRE,numlines,LINES,two_column_example,csv
to_read=numlines-to_skip
!
*DEL,mytable,,NOPR
*DIM,mytable,TABLE,to_read ! table array to hold data
!
*TREAD,mytable,two_column_example,csv,,to_skip
!
! Show the result to the user
/title,Data read into the Table Array ‘mytable’
*VPLOT,mytable(1,0),mytable(1,1)
!
! Move data to Array
*DEL,myarray,,NOPR
*DIM,myarray,ARRAY,to_read,2
!
*vfun,myarray(1,1),copy,mytable(1,0) ! Shift column to right
*vfun,myarray(1,2),copy,mytable(1,1) ! Shift column to right

Note the *VPLOT command above that creates an X-Y plot of the Table Array data:

Below are APDL commands that read data from a 3-column CSV file called “three_column_example.csv”. when moved into a numerical Array, the data is moved one column to the right, and one row down. Note that the Table Array is dimensioned one less than the number of lines to read, because row Zero holds a row of data:

! Example reading 3-column data from a CSV file into a Table Array
! Enter the name of the CSV file below
! Column 0 of ‘mytable’ holds the first column of the CSV file
! Column 1 of ‘mytable’ holds the second column of the CSV file
! Column 2 of ‘mytable’ holds the third column of the CSV file
! Row 0 of ‘mytable’ holds the first row of the CSV file
!
to_skip=1 ! Enter number of lines to skip
/INQUIRE,numlines,LINES,three_column_example,csv
to_read=numlines-to_skip
!
*DEL,mytable,,NOPR
*DIM,mytable,TABLE,to_read-1,2 ! table array to hold data
!
*TREAD,mytable,three_column_example,csv,,to_skip
!
! Show the result to the user
/title,Data read into the Table Array ‘mytable’
*VPLOT,mytable(0,0),mytable(0,1),2 ! Plot columns vs “time”
!
! Move data to numerical Array
*DEL,myarray,,NOPR
*DIM,myarray,ARRAY,to_read,3
!
*vfun,myarray(1,1),copy,mytable(0,0) ! Shift down and right
*vfun,myarray(1,2),copy,mytable(0,1) ! Shift down and right
*vfun,myarray(1,3),copy,mytable(0,2) ! Shift down and right

Note the *VPLOT command above that creates an X-Y plot of the Table Array data for both data columns:

After the above 3-column CSV file has been read by *TREAD and moved into a numerical Array by *VFUN commands, the upper part of the data looks like this in the numerical Array:

Conclusions | Using TREAD Command in Ansys

Ansys Mechanical APDL can use the *VREAD or the *TREAD command to bring numerical data into Ansys. The *TREAD command is more versatile, reading data from a Comma Separated Values (CSV) data file.

The *TREAD command places data in a Table Array. 2-column data is sifted left one column in order to fill the Zeroth column of a Table Array. Data from 3-columns or more is also sifted up one row, in order to fill the Zeroth row of a Table Array. This difference must be noted by users who want to access all of the data in a Table Array.

The command *VFUN can be used to move columns of data between Table Arrays and numerical Arrays, and vice versa. This makes numerical data from CSV files accessible in Ansys for a wide variety of uses.

This article has reviewed the means of using *VREAD with 2-D tables, and means of moving the data inside Ansys by Using TREAD Command in Ansys.