AqwaReader is a stand-alone program run from the Windows command line, which allows you to navigate through an Aqwa database file (for example, a restart (RES) or plotting (PLT) file) and extract results from it.
Using AqwaReader from the Windows Command Line
The example below is based on the data files found in the Aqwa training folder located in \ANSYS Inc\v242\aqwa\training. You will need to execute the file Run_Training.bat (found in the training directory) to perform a simple Aqwa analysis before trying to view any database files.
Note: Run_Training.bat can be run from the command line. You may need to move the "training" folder to another location on your computer if you get a write permission error when you try to execute Run_Training.bat. If you move the training folder, rather than executing Run_Training.bat, execute the following command from the command line while in the training folder:
"C:\Program Files\Ansys
Inc\v242\aqwa\bin\winx64\Aqwa.exe" std
training.com
To run AqwaReader, from the Windows command line enter the command:
"C:\Program Files\ANSYS Inc\v242\aisol\workbench.bat" -cmd
"C:\Program Files\ANSYS Inc\v242\aisol\bin\winx64\AqwaReader.exe"
Note: You cannot run AqwaReader directly. It has to go through workbench.bat to ensure that the required libraries are loaded.
Running this command will display the following information:
AqwaReader can be configured in two ways: step-by-step, or by command line
arguments. If the user just runs the command "AqwaReader" without any arguments,
the program is configured through a series of input prompts. When the program exits
successfully the user is presented with a set of command line arguments, which can
be used to exactly repeat the previous operation. These arguments can be used as a
template to run the program repeatedly (e.g. from a script), for batch extraction of
results over multiple frequencies, directions, time steps, etc.
To avoid mistakes, the new user is recommended to use step-by-step configuration to
generate command line arguments.
The command line argument descriptors are as follows:
--Type [string] Operation type
--InFile [string] Input file (as generated by an Aqwa analysis)
--OutFile [string] Output file
--Format [string] Output file format
--Unit [string] Length unit of data in input file
--Struct [integer] Structure number
--Freq [integer] Frequency index in the hydrodynamic database
--Dir [integer] Direction index in the hydrodynamic database
--Comp [string] Pressure component identifier (I/D/R/H combination)
--Ampl [float] Incident wave amplitude
--Phase [float] Incident wave phase angle
--Cable [integer] Cable number
--Tether [integer] Tether number
--Step [integer] Time step number
--Config [integer] Mooring configuration number
--SpecGr [integer] Spectral group number
--PLT1 [integer] Index at the first level of the Aqwa plotting (PLT) file
--PLT2 [integer] Index at the second level of the Aqwa plotting (PLT) file
--PLT3 [integer] Index at the third level of the Aqwa plotting (PLT) file
--PLT4 [integer] Index at the fourth level of the Aqwa plotting (PLT) file
--ResType [integer] Index of the moonpool related hydrodynamic data type
--SubType [integer] Index of the moonpool related hydrodynamic data sub-type
--Moonpl1 [integer] Moonpool number among moonpools of the specified structure
--Exdend1 [integer] Index of the specified moonpool extension
--Dof1 [integer] Index of the moonpool pressure mode or structure rigid body motion
--Struct2 [integer] Structure number for the moonpool related matrix element column index
--Moonpl2 [integer] Moonpool number for the moonpool related matrix element column index
--Exdend2 [integer] Index of the moonpool extension for the moonpool related matrix element column index
--Dof2 [integer] Index of DOF for the moonpool related matrix element column index
****************************************************************************************
Available operations:
- 1. Get geometry and mesh from an Aqwa input (DAT) file or restart (RES) file
- 2. Get graphical results from an Aqwa plotting (PLT) file
- 3. Get hydrodynamic panel pressures from a Hydrodynamic Diffraction (Aqwa-Line) restart (RES) file
- 4. Get RAO-based node positions from a Hydrodynamic Diffraction (Aqwa-Line) restart (RES) file
- 5. Get frequency statistical results from a frequency domain Hydrodynamic Response (Aqwa-Fer) results (RSS) file
- 6. Get positions and tensions from a stability or time domain Hydrodynamic Response (Aqwa-Librium, Aqwa-Drift or Aqwa-Naut) dynamic cable position (DCP) file
- 7. Get node motions and forces from a stability or time domain Hydrodynamic Response (Aqwa-Librium, Aqwa-Drift or Aqwa-Naut) tether output (TET) file
- 8. Get element forces and stresses from a stability or time domain Hydrodynamic Response (Aqwa-Librium, Aqwa-Drift or Aqwa-Naut) tether output (TET) file
- 9. Get multi-directional quadratic transfer functions (QTFs) from a Hydrodynamic Diffraction (Aqwa-Line) multi-directional QTF (MQT) file
- 10. Get moonpool pressure mode hydrostatic stiffness matrix from a Hydrodynamic Diffraction (Aqwa-Line) restart (RES) file
- 11. Get moonpool pressure mode added mass or damping from a Hydrodynamic Diffraction (Aqwa-Line) restart (RES) file
- 12. Get moonpool pressure mode RAO or first order wave force from a Hydrodynamic Diffraction (Aqwa-Line) restart (RES) file
Select an operation: After some informational text, there is a prompt to select an operation number. For example, to read graphical results, enter the value 2 (corresponding to the operation 'Get graphical results from an Aqwa plotting (PLT) file').
Next the program asks you to enter the (relative or absolute) path to the input file. For example, to access Hydrodynamic Diffraction results in an Aqwa Workbench project, your path would look something like:
<path_to_your_project>\<project_name>_files\dp0\AQW\AQW\AQ\Analysis\Analysis.plt
You can then specify the (relative or absolute) output file path to which AqwaReader will write values in the comma-separated values (CSV) format (or you can enter "stdout" to just write the values to screen).
Select an operation: 2
Select an Aqwa file to read data from. Valid file extensions:
- plt: Aqwa plotting (PLT) file
Enter (relative or absolute) path to input file: antakbuy.plt
Full path for input file: C:\Aqwa\training\antakbuy.plt
Checking file access...
File accessed OK
Output file will be written in csv format
Specify output file (absolute or relative path; any file extension will be ignored), or enter 'stdout' for standard output: outfile.csv
Full path for output file: C:\Aqwa\training\outfile.csv
Checking directory exists...
Directory accessed OKFor each of the structures with which you have carried out an analysis, you can then set up the results type by selecting from the displayed option lists.
In the example below, you are extracting information for the first structure (option 1: Structure Number 1) of the COG position (option 1: POSITION OF COG) along the Z-direction (option 3: in Z direction).
The selected input file contains a single first level option "Motion Analysis Time History -", which is used by default
The selected input file contains the following second level options:
- 1. Structure Number 1
- 2. Structure Number 2
Select a second level option number: 1
The selected input file contains the following third level options:
- 1. POSITION OF COG
- 2. VELOCITY OF COG
- 3. ACCELERATION OF COG
- 4. RAO BASED POSITION
- 5. RAO BASED VELOCITY
- 6. GRAVITY FORCE
- 7. HYDROSTATIC FORCE
- 8. MORISON DRAG FORCE
- 9. FROUDE KRYLOV FORCE
- 10. CURRENT DRAG FORCE
- 11. WIND FORCE
- 12. DIFFRACTION FORCE
- 13. LINEAR DAMPING FORCE
- 14. MOORING FORCE
- 15. RADIATION FORCE
- 16. TOTAL REACTION FORCE
- 17. TOTAL FORCE
- 18. ERROR PER TIMESTEP
Select a third level option number: 1
The selected input file contains the following fourth level options:
- 1. in X direction
- 2. in Y direction
- 3. in Z direction
- 4. about X axis
- 5. about Y axis
- 6. about Z axis
Select a fourth level option number: 3After AqwaReader has successfully completed, it displays a set of arguments that can be used to exactly repeat the previous operation. For example:
Data input complete. Generating output file... Aqwa Reader has complete successfully. **************************************************************************************** To exactly repeat this operation (without prompts), use the command: AqwaReader --Type "Graphical" --InFile "C:\Aqwa\training\antakbuy.plt" --OutFile "C:\Aqwa\training\outfile" --Format "csv" --PLT1 1 --PLT2 1 --PLT3 1 --PLT4 3
You can then copy and paste the displayed commands into a script (remembering to put "..\..\workbench.bat -cmd" on the front of the command) with different values for the PLT command line options.
Caution: The integer values of the PLT options mean different things in different analyses so you should always check that you are getting the right output. The first lines of the output CSV file show you what it contains. To illustrate this, consider the following example from a different analysis that was performed in Workbench.
To plot the pitch RAO in 0° wave direction, select option 1 (STRUCTURE 1 PARAMETERS VERSUS FREQUENCY), then option 5 (DIRECTION NUMBER 5), then option 1 (FREE FLOATING RAOS), then option 5 (PITCH(Y)). This will generate a command line similar to:
AqwaReader --Type "Graphical" --InFile "<path_to_your_project>\<project_name>_files\dp0\AQW\AQW\AQ\Analysis\Analysis.plt" --OutFile "stdout" --Format "csv" --PLT1 1 --PLT2 5 --PLT3 1 --PLT4 5
where the wave direction index will depend on the number of wave directions in the analysis.