Run the HyperWorks in Batch Mode

The HyperWorks runs in batch mode using the Python script, mit_batch.py. With this script, the HyperWorks generates one output .gbs file and one output .spd file for one bushing. The .gbs file can be used for downstream simulation with MBD solvers or applications such as MATLAB, while the output .spd file provides information about the behavior of a model. For example, you can interactively load the output .spd file in the HyperWorks, and then review the performance of your model against the same tests that were used to generate the input .spd file. For more information about .gbs and .spd files, see Altair Bushing Model.

From <HW_INSTALLATION>/utility/scripts/plotting/mit/batch, invoke the script, mit_batch.py.
Tip: To fit or analyze multiple bushings, you need to invoke mit_batch.py multiple times. You can do this conveniently using a .bat file for Windows, shell script for Linux, or Python script for Windows or Linux.

Set the Location of HyperWorks Python

If Python is not installed on your system, then include the location of HyperWorks Python in your path as follows:

  1. On Windows, enter:
    set PATH <HW_INSTALLATION>/hw/python/python27/win64;%PATH%
  2. On Linux, enter:
    setenv PATH <HW_INSTALLATION>/hw/python/python27/linux64:$PATH
    1. The system does not know that files with the .py extension are Python files. Therefore, invoke mit_batch.py as follows:
      python.exe mit_batch.py –i ./F0_Fx.spd –o ./F0_Fx
      Note:
      • Windows style path names with “\” are allowed.
      • Blanks in paths are allowed inside of double quotes: “test directory\testName”.
      • The default .xml file contains only HyperWorks options. You cannot specify path names for input and output files in this file.

Create Shortcuts to the Python Script

Using shortcuts to invoke mit_batch.py helps minimize typing. You can create shortcuts as follows:

  1. On Windows, from <HW_INSTALLATION>/utility/scripts/plotting/mit/batch/, right-click mit_batch.py and select Send to > Desktop.
    A batch mode shortcut appears on your desktop. You can copy or move the shortcut as needed.
  2. On Linux, using the ln -s command, create a symbolic link to <HW_INSTALLATION>/utility/scripts/plotting/mit/batch.
    Note:
    • Windows style path names with “\” are allowed.
    • Blanks in paths are allowed inside of double quotes: “test directory\testName”.

Modes of Operation

The batch mode process using mit_batch.py includes two principal modes of operation as described in the following table. Regardless of the mode of operation, mit_batch.py includes a set of optional arguments to control the behavior of the HyperWorks.
Mode Description
option -i Invokes mit_batch.py with a list of input .spd files.
option -d Invokes mit_batch.py with a directory containing a set of .spd files for a bushing.

Synopsis of Batch Mode Options

The following is a synopsis of the options in the batch mode process:
mit_batch.py i <input_files_list> -o <output_directory> <options>
mit_batch.py -d <input_directory> -o <output_directory> <options>

Arguments

The following are arguments you can use in batch mode:
Argument
Description
-i <input_files_list>
Specifies a list of comma-separated .spd file names that are to be fitted. You can provide a maximum of six files as input. The directions to be fitted are obtained from the .spd files and must be unique.
-d <input_directory>
Specifies a path that contains the files that are to be fitted. The tool attempts to run all .spd files in this directory. The directory must contain a maximum of six .spd files, each of which contains a unique direction. The bushing directions to be fitted are obtained from the .spd files. The arguments -i and -d are mutually exclusive.
-o <output_directory>
Specifies a path where all outputs from the run are placed. <output_directory> is created if necessary. /staff/brown/rear-gear-box is an example of a valid output directory path. <output_directory> contains the following five files:
Output .gbs file
<name>.gbs
Contains the fitted bushing. For the example above, a .gbs file with name, rear-gear-box.gbs is created in /staff/brown/rear-gear-box.
Batch .log file
<name>.batch.log
Contains the output from the batch run. For the example above, a batch .log file, rear-gear-box.batch.log, is created in /staff/brown/rear-gear-box. When the –e <experiment-directory> option is used, the batch .log file is created in <experiment-directory>.
.xml file
<name>.xml
Contains the HyperWorks options for the batch run. For the example above, an .xml file with name rear-gear-box.xml is created in /staff/brown/rear-gear-box. When the –e <experiment-directory> option is used, the .xml file is created in <experiment-directory>.
Fit .log files
These files summarize the fit effort. One .log file is generated for each fitted .spd file. The prefix of each .log file matches the .spd file that is fitted. Thus corresponding to the .spd file rear-gear-box-z.spd, a .log file rear-gear-box-z.log is created. When the –e <experiment-directory> option is used, the fit .log files are created in <experiment-directory>.
Subdirectory, 1_Cycle
This directory contains files useful for the HyperWorks. You should not change the contents of this directory. When the –e <experiment-directory> option is used, the subdirectory, 1_Cycle is created in <experiment-directory>.

Options

Option
Description
-a
Specifies that the HyperWorks is to perform an analyze operation. The analyze operation performs a test on a virtual bushing and compares the results to the physical test results. The virtual bushing is specified as an input .gbs file. The physical test is specified in an input .spd file. When this option is not specified, the system tries to perform a fit operation with the specified inputs.
-e
Specifies the directory name where the intermediate files that the HyperWorks generates from a fit or analyze operation are stored. You can use these files to reload existing runs in a new HyperWorks session. You should not change the contents of this directory. When this option is not used, all output files are created in the output folder.
If <experiment-directory> already exists, then all the existing content is saved to a new folder. The archive folder name is determined at run time to be unique. The new content generated from the batch run is added to <experiment-directory>.
-f <xml-file>
Specifies the .xml file containing the options that are to be used for fitting. These options take precedence over the options in the default .xml file that is used by the HyperWorks.
-h
Provides information about how to use mit_batch.py. Invoking mit_batch.py without parameters also provides Help, which is this content shown in plain text.
-n
Specifies the name of the output .gbs file, output .pdf file, batch .log file and .xml file. If not specified, <name> is the lowest level directory name in <output_directory>.
-t <directory>
This option is meant for use only when the –i argument is used. This option specifies a test directory where the .spd files reside.
-x
Does not execute the HyperWorks, but generates an output directory that includes the .xml file of default options.

Return Status

The batch mode return status includes the following:
Status
Description
0
The fitting tasks were completed successfully.
64
The analyze tasks were completed successfully.
1
The fitting task for FX direction failed.
2
The fitting task for FY direction failed.
4
The fitting task for FZ direction failed.
8
The fitting task for TX direction failed.
16
The fitting task for TY direction failed.
32
The fitting task for TZ direction failed.
Multiple directions failure is represented with the sum of individual failures:
  • Fitting task failed for FX and FZ: the return code is 0+1+4 = 5.
  • Analyze task failed for FX and FZ: the return code is 64+1+4 = 69.

Batch Mode Examples

Example 1
mit_batch.py  –i ./F0_Fx.spd  –o ./F0_Fx
  • The file F0_Fx.spd in the current working directory is used as the input .spd file.
  • The HyperWorks creates an output directory file, ./F0_Fx, in the current working directory. The ./F0_Fx file contains the fit results:
    Table 1.
    Result Description
    F0_Fx.gbs Output .gbs file for simulations.
    F0_Fx.pdf Output .pdf file.
    F0_Fx.batch.log .log file for the batch run.
    F0_Fx.xm Parameters used by the HyperWorks for this run.
    F0_Fx.log .log file for the fit operation on F0_Fx.spd.
    1_Cycle Sub-directory containing intermediate files generated by the HyperWorks.
Example 2
mit_batch.py  –d /staff/pbrown/rear-gear-box   –o /staff/pbrown/rear-gear-box-09-19-2013
  • All .spd files in /staff/pbrown/rear-gear-box are used as input to the HyperWorks. Assume that there are three .spd files in /staff/pbrown/rear-gear-box, rgb-90210-x.spd, rgb-90210-y.spd, rgb-90210-tz.spd, for directions x, y and tz respectively.
  • The HyperWorks creates an output directory, /staff/pbrown/rear-gear-box-09-19-2013, which contains:
    Table 2.
    Result Description
    rear-gear-box-09-19-2013.gbs Output .gbs file to use for simulations.
    rear-gear-box-09-19-2013.pdf Output .pdf file.
    rear-gear-box-09-19-2013.batch.log .log file for the batch run.
    rear-gear-box-09-19-2013.xml Parameters used by the HyperWorks for this run.
    rgb-90210-x.log .log file for the fit operation on rgb-90210-x.spd.
    rgb-90210-y.log .log file for the fit operation on rgb-90210-y.spd.
    rgb-90210-tz.log .log file for the fit operation on rgb-90210-tz.spd.
    1_Cycle Sub-directory containing intermediate files generated by the HyperWorks.
Example 3
mit_batch.py  –d /staff/pbrown/rear-gear-box   –o /staff/pbrown/rear-gear-box-09-19-2013 -x
  • All .spd files in /staff/pbrown/rear-gear-box are used as input to the HyperWorks. Assume that there are three .spd files in /staff/pbrown/rear-gear-box, rgb-90210-x.spd, rgb-90210-y.spd, rgb-90210-tz.spd, for directions x, y and tz respectively.
  • The HyperWorks creates an output directory, /staff/pbrown/rear-gear-box-09-19-2013, which contains:
    Table 3.
    Result Description
    rear-gear-box-09-19-2013.batch.log .log file for the batch run.
    rear-gear-box-09-19-2013.xml Parameters used by the HyperWorks for this run.
Example 4
mit_batch.py  –i F0_Fx.spd, F0_Tx.spd  –o ./F0 –t /staff/pbrown/rear-axle-bearing
  • The HyperWorks uses the files F0_Fx.spd and F0_Tx.spd in /staff/pbrown/rear-axle-bearing as the input .spd files.
  • The HyperWorks creates an output directory file, F0, in the current working directory. The F0 directory contains:
    Table 4.
    Result Description
    F0.gbs Output .gbs file to use for simulations.
    F0.pdf Output .pdf file.
    F0.batch.log .log file for the batch run.
    F0.xml Parameters used by the HyperWorks for this run.
    F0_Fx.log .log file for the fit operation on F0_Fx.spd.
    F0_Tx.log .log file for the fit operation on F0_Fy.spd.
    1_Cycle Sub-directory containing intermediate files generated by the HyperWorks.
Example 5
mit_batch.py  –i F0_Fx.spd, F0_Tx.spd  –o ./F0 –t /staff/pbrown/rear-axle-bearing -n exported
  • The HyperWorks uses the files F0_Fx.spd and F0_Tx.spd in /staff/pbrown/rear-axle-bearing as the input .spd files.
  • The HyperWorks creates an output directory file, F0, in the current working directory. The F0 directory contains:
    Table 5.
    Result Description
    exported.gbs Output .gbs file to use for simulations.
    exported.pdf Output .pdf file.
    exported.batch.log .log file for the batch run.
    exported.xml Parameters used by the HyperWorks for this run.
    F0_Fx.log .log file for the fit operation on F0_Fx.spd.
    F0_Tx.log .log file for the fit operation on F0_Fy.spd.
    1_Cycle Sub-directory containing intermediate files generated by the HyperWorks.
Example 6
mit_batch.py  –i F0_Fx.spd, F0_Tx.spd  –o ./F0 –t /staff/pbrown/rear-axle-bearing -n exported -e/staff/pbrown/Test
  • The HyperWorks uses the files F0_Fx.spd and F0_Tx.spd in /staff/pbrown/rear-axle-bearing as the input .spd files.
  • The HyperWorks creates an experiment directory, Test, in the current working directory. The Test directory contains:
    Table 6.
    Result Description
    exported.batch.log .log file for the batch run.
    exported.xml Parameters used by the HyperWorks for this run.
    F0_Fx.log .log file for the fit operation on F0_Fx.spd.
    F0_Tx.log .log file for the fit operation on F0_Fy.spd.
    1_Cycle Sub-directory containing intermediate files generated by the HyperWorks.
  • The HyperWorks creates an output directory, F0, in the current working directory. The F0 directory contains:
    Table 7.
    Result Description
    exported.gbs Output .gbs file to use for simulations.
    exported.pdf Output .pdf file