Write Solver Scripts

Solver scripts can be written in any language, and its contents can be as simple as a single line or a detailed set of commands. This generality is intentional so that HyperStudy remains flexible enough to be wrapped around any non-interactive process.

Suggestions for writing solver scripts:

For each run, HyperStudy creates a separate run folder. In the case of multiple models, a separate model folder is also created. These folders are called Study Run folders.
For each run, HyperStudy writes the solver input file to the Study Run folder.
If any other files need to reside in the Study Run folder, they will need to be copied. For example, RADIOSS needs a starter file and an engine file to reside in the Study Run folder. A file can be copied from the study directory by adding its name to the solver input file. Separate names in the solver input file with a semi-colon.
In order for HyperStudy to execute properly, verify that the solver returns control back to HyperStudy only after the execution is finished. Otherwise, HyperStudy will attempt to extract results before all files are finished writing and the study will fail. In order to avoid, this, if possible, the solver should be run in interactive mode. Otherwise, you will need to include a wait command in your batch file. For abaqus, this is <PATH>/abaqus.exe job=jobname.inp interactive.
In a study that uses more than one model, the models are executed in a sequence determined by HyperStudy. To control the sequence of runs, specify the priority option for the model. The results are extracted after the solvers have finished, or earlier depending on any model dependencies.
A failure during the script execution can be noted by creating a file titled task__exe_err.txt. If this file is present in the run directory, HyperStudy will detect the execution as a failure. A similar error file can be created for other task failures: write (task__wri_err.txt), extraction (task__ext_err.txt) and purge (task__pur_err.txt).

Access Process Environment Variables

View a list of process environment variables set by HyperStudy, which can be useful when writing solver scripts.

In the Message Log window, right-click and select Verbose > Level 3 from the context menu.
Evaluate any approach.

The values of the environment variables for the current study approach will be displayed in the Message Log window.

Common CAE Solver Script Inline Commands

Solver script inline commands commonly used in HyperStudy.

Note: For a complete list of available options, refer to the corresponding solver specific documentation.

Abaqus

To be used with solver input file $filebasename.

Windows: <PATH>/abaqus.exe job=%1 interactive
Linux: <PATH>/abaqus.exe job=$1 interactive

ANSYS

Windows: <PATH>/ansysXXX.exe -b -i %1
Linux: <PATH>/ansysXXX.exe -b -i $1

Compose/OML

Windows: <PATH>/hwx/Compose_batch.bat –f %1
Linux: <PATH>/Compose_Batch –f $1

LS-DYNA

Windows: <PATH>/dyna.exe i=%1
Linux: <PATH>/dyna.exe i=$1

OptiStruct

Windows: <PATH>/optistruct.bat %1
Linux: <PATH>/optistruct.bat $1

Example Solver Script Files Run Locally

Note: The following examples are structured to become progressively more complicated. It is recommended that the examples are read in sequence and not treated independently. The examples show the use of OptiStruct, but the script concepts highlighted are general enough to be applied to many processes.

Direct Call to an Executable

Many programs already have a simple command line executable to begin a batch solution. This command generally takes some additional arguments. In general, the command line syntax to perform these operations takes the form of an executable command followed by space separated arguments.

[Command] [ Arguments]

For example, the file to call the OptiStruct solver may be located, on windows, at C:\Program Files\Altair\14.0.120\hwsolvers\scripts\optistruct.bat. This command can take several optional arguments, for example the name of the input file and a selection of the number of cpus. In this case, the command line syntax would be:

“C:\Program Files\Altair\12.0.110\hwsolvers\scripts\optistruct.bat” test.fem –ncpu 4

The [Command] is

“C:\Program
                    Files\Altair\14.0.120\hwsolvers\scripts\optistruct.bat”

, and [Arguments] is test.fem –ncpu 4. The command is stored in HyperStudy as the solver execution script, and the solver input arguments entry would take the text

test.fem –ncpu
                4

Another HyperStudy entry is the solver input file, which is the name of the file that will be written by HyperStudy during the model writing phase. The value of this entry is accessible from the internal variable $file, which in turn can be accessed in the solver input arguments, letting HyperStudy substitute this entry for you. In this case the solver input arguments would take the form

$file –ncpu
                    4

Figure 1.

Basic Solver Script with Arguments (System Native)

Rather than having to type out a set of input arguments, you can create a general purpose script that has preferred options hard coded. A general purpose script can still take a variable input file. The windows batch file (*.bat) that will perform this operation contains the line:

“C:\Program
        Files\Altair\14.0.110\hwsolvers\scripts\optistruct.bat” %1 –ncpu 4 –core
      in

The syntax %1 is a substitution of the first argument to this script, which should be the input file. The argument %2 would be second argument, and so on. This batch file can be registered as the solver script, and can have the solver input arguments as $file.

A similar syntax is available on linux/unix shells. The exact syntax depends on the type of shell script being written, but for Bash shells the syntax is $n to access the nth argument.

Figure 2.

Basic Solver Script with Arguments (Python)

Writing a script to run in the system native command layer can be instructive, but these languages are limited. Other languages can be used to create more detailed and featured scripts. This example uses Python, a full featured and platform neutral language. See any python reference for details on the specifics of this language.

Tip: It is recommend that you use a language that you are comfortable.

The script in Basic Solver Script with Arguments (System Native) can be re-written to work with python. This script has some additional features such a functionality that corrects operating system path differences and logs the output into text files for better transparency when debugging.

# import statements
import os
import subprocess
import sys

f = open('logFile.txt', 'w')

#set path to file
file_exe = 'C:/Program Files/Altair/14.0/hwsolvers/scripts/optistruct.bat' 

#set arguments
file_args = sys.argv[1] + ' -ncpu 4' + ' -core in'

#correct the path for the operating system, concatenate, and execute
file_exe = os.path.normpath(file_exe)
lstCommands = [file_exe, file_args]
f.write('Running the command:\n' + ' '.join(lstCommands) + '\n')
p1 = subprocess.call(' '.join(lstCommands), stdout=subprocess.PIPE , stderr=subprocess.PIPE)

#write output and close
f.write('\nStandard out:' + '\n' + p1.communicate()[0] + '\n')
f.write('\nStandard error:' + '\n' + p1.communicate()[1] + '\n')
f.close()

Script with Simple Logic

Sometimes a script must perform several operations in sequence. This script copies a file into the current directory. This script is also designed to take a second argument, which is a file that should be removed if it exists. The same solution used in Basic Solver Script with Arguments (Python) can be executed.

Figure 3.

# import statements
import os
import subprocess
import sys
import shutil

f = open('logFile.txt', 'w')

#set path to files
file_exe = 'C:/Program Files/Altair/14.0/hwsolvers/scripts/optistruct.bat'
file_to_copy = 'C:/Users/jmpajot/Documents/HMath_solutions/HST/documentation_changes/solver_script/target.txt'

#set arguments
file_args = sys.argv[1] + ' -ncpu 4' + ' -core in'

#copy the file
f.write('\nCopying the file: ' + file_to_copy + '\n')
shutil.copy(os.path.normpath(file_to_copy),os.getcwd())

#remove the file if it exists
if os.path.isfile(sys.argv[2]):
  f.write('\nRemoving the file: ' + sys.argv[2] + '\n')
  os.remove(sys.argv[2])

#correct the path for the operating system, concatenate, and execute
file_exe = os.path.normpath(file_exe)
lstCommands = [file_exe, file_args]
f.write('Running the command:\n' + ' '.join(lstCommands) + '\n')
p1 = subprocess.call(' '.join(lstCommands), stdout=subprocess.PIPE , stderr=subprocess.PIPE)

#write output and close
f.write('\nStandard out:' + '\n' + p1.communicate()[0] + '\n')
f.write('\nStandard error:' + '\n' + p1.communicate()[1] + '\n')
f.close()

Script with Environment Variables

Dynamic scripts can be used to maintain portability by taking advantage of HyperStudy’s environment variables. For example, consider the script in Script with Simple Logic. The file to be copied is defined with a fully qualified path. Instead you may require that the file be located in the HyperStudy study directory’s _usr directory, and be copied to the current run directory. The _usr directory is always in the study directory, and that path is stored in the environment variable named HST_STUDY_PATH. HyperStudy will write a complete list of available environment variables to a file in the run directory if the verbose level is increased to level 3. Because these are HyperStudy environment variables, a script with these variables can only be run successfully from within HyperStudy.

# import statements
import os
import subprocess
import sys
import shutil
import time

f = open('logFile.txt', 'w')

#length of sleep command (seconds)
time_to_sleep = 1
time_out =  10

#set path to files
file_exe = 'C:/Program Files/Altair/14.0/hwsolvers/scripts/optistruct.bat'
file_to_copy = 'target.txt'

#set arguments
file_args = sys.argv[1] + ' -ncpu 4' + ' -core in'

#copy the file
file_to_copy = os.path.join(os.getenv('HST_STUDY_PATH'),'_usr',file_to_copy)
f.write('\nCopying the file: ' + file_to_copy + '\n')
shutil.copy(os.path.normpath(file_to_copy),os.getcwd())

#remove the file if it exists
if os.path.exists(sys.argv[2]):
  f.write('\nRemoving the file: ' + sys.argv[2] + '\n')
  os.remove(sys.argv[2])

#correct the path for the operating system, concatenate, and execute
file_exe = os.path.normpath(file_exe)
lstCommands = [file_exe, file_args]
f.write('Running the command:\n' + ' '.join(lstCommands) + '\n')
p1 = subprocess.call(' '.join(lstCommands), stdout=subprocess.PIPE , stderr=subprocess.PIPE)

#write output and close
f.write('\nStandard out:' + '\n' + p1.communicate()[0] + '\n')
f.write('\nStandard error:' + '\n' + p1.communicate()[1] + '\n')
f.close()

Waiting for an Output File

While most commands wait until they are completed to give control back to the script, some commands return control immediately. This is common, for example, with queuing systems. In this case, additional logic is required in the script to make the script wait before moving onto the next steps. One solution to this problem is to wait for a particular file that only exists when the process in complete.

For example, HyperStudy checks for the task__exe_err.txt file, which indicates a failure in the execution when present.

# import statements
import os
import subprocess
import sys
import shutil
import time

f = open('logFile.txt', 'w')

#length of sleep command (seconds)
time_to_sleep = 1
time_out =  10

#set path to files
file_exe = 'C:/Program Files/Altair/14.0/hwsolvers/scripts/optistruct.bat'
file_to_copy = 'target.txt'

#set arguments
file_args = sys.argv[1] + ' -ncpu 4' + ' -core in'

#copy the file
file_to_copy = os.path.join(os.getenv('HST_STUDY_PATH'),'_usr',file_to_copy)
f.write('\nCopying the file: ' + file_to_copy + '\n')
shutil.copy(os.path.normpath(file_to_copy),os.getcwd())

#remove the file if it exists
if os.path.exists(sys.argv[2]):
  f.write('\nRemoving the file: ' + sys.argv[2] + '\n')
  os.remove(sys.argv[2])

#correct the path for the operating system, concatenate, and execute
file_exe = os.path.normpath(file_exe)
lstCommands = [file_exe, file_args]
f.write('Running the command:\n' + ' '.join(lstCommands) + '\n')
p1 = subprocess.Popen(' '.join(lstCommands), stdout=subprocess.PIPE , stderr=subprocess.PIPE)

#wait for the file to appear
init_time = time.time()
while not os.path.exists(sys.argv[2]):
  f.write('\n ... Waiting for file to appear: ' + sys.argv[2] + '\n')
  time.sleep(time_to_sleep)
  time_delta = time.time() - init_time
  if time_delta > time_out:
     f2 = open('task__exe_err.txt', 'w')
     f2.write('Time of waiting for ' + sys.argv[2])
     f2.close()
     break

#write output and close
f.write('\nStandard out:' + '\n' + p1.communicate()[0] + '\n')
f.write('\nStandard error:' + '\n' + p1.communicate()[1] + '\n')
f.close()

Example Solver Scripts Run on Distributed Machines

Run Solvers Using a Queuing System on Unix

This example script runs a solver using a queuing system on UNIX.

The sample file is set up for running LS-DYNA with the NQS queuing system.

The script contains a ‘wait loop’, which makes sure that the optimization process stops until the solver has completely finished. This is necessary for an optimization study where all analyses must be performed in sequence. The wait loop can be omitted when performing a DOE study. This allows for multiple analyses to be carried out in parallel, with the network queuing system controlling the allocation of resources. The wait loop is checking the d3hsp file for the string N o r m a l t e r m i n a t i o n, which signals the end of the solution process. If another solver or queuing system is used, the script needs to be changed accordingly. For optimization studies, the respective ASCII output file should be screened for a string signaling the proper end of the solver run.

The sample script also shows how to include certain post-processing tasks such as translating the results into a HyperMesh result file and deleting files not needed to save disc space.

#!/bin/sh
#
#  Set base filename for the optimization study
#
 base=filename
#
#  Set name of the que
#
 que =quename
#
#  Set environment variables for the solver
#
LSTC_FILE=/soft/usr/dyna/pass/v940_902
export LSTC_FILE
#
#  Submit solution to the que
#
(
echo "cd $PWD"
echo "/soft/usr/dyna/v940_902 i=$base.bdf x=99 memory=50000000"
) | qsub -q $que
#
#  Wait for the solver run to be finished. This can be omitted when
#  running a DOE Study. Thereby allowing multiple runs to be performed
#  in parallel, with the queuing system controlling the allocation of
#  resources.
#
MSG=""
while [ "$MSG" = "" ] ; do
 MSG=`grep "N o r m a l    t e r m i n a t i o n" d3hsp 2>/dev/null`
 sleep 30
done
#
#   Post-process data, if necessary (Create HyperMesh result file)
#
/soft/net/hmdyna d3plot $base.res
#
#   Delete data not needed
#
/bin/rm –f d3p* d3d*
#
#   End of script
#

Run Solvers using PBS Professional on Unix

This example script runs a solver using PBS Professional on Unix.

The sample file is set up for running LS-DYNA.

The script contains a ‘wait loop,’ which makes sure that the optimization process stops until the solver has completely finished. This is necessary for an optimization study where all analyses must be performed in sequence. The wait loop can be omitted when performing a DOE study. This allows for multiple analyses to be carried out in parallel, with the network queuing system controlling the allocation of resources. The wait loop is checking for the existence of the .pbslock file. Its disappearance signals the end of the solution process.

If another solver or queuing system is used, the script needs to be changed accordingly.

#!/bin/sh
#################################################
# Script to run pbs-submit from HyperStudy
#################################################
cd $HOME/$2;
pbs-submit -c dyna -v 970_5434asingle_smp -m 300 -i $1
#################################################
# Don't return until the job completes.
# Monitor the existence of the .pbslock file
#################################################
echo "Waiting for job to complete...";
while [ -f .pbslock ]
do
continue;
done;
echo "Job completed. Returning to HyperStudy"
#################################################

Run Solvers on Unix, While Study is on a Unix Mapped Drive

This example demonstrates how files on Unix can be accessed from the PC by mapping a network drive to the Unix side of the network.

In order to facilitate running HyperStudy on a PC while running a solver on Unix, HyperStudy sets a process environment variable called STUDY_UNIX_PATH. The value of this process environment variable is set to the full path of the current run directory, excluding the drive letter of the mapped drive. This environment variable keeps changing with each run.

A batch file must be created to facilitate the execution of the solver on Unix from HyperStudy running on PC.

Below is a simple example of such a batch file:

rsh unix_mc –l user_name solver_script $HOME%STUDY_UNIX_PATH%/%1

The batch file uses the rsh command to log into the UNIX machine and execute the solver on the iterative designs created by HyperStudy.
The variable solver_script is the script to run the solver on UNIX.
The batch file assumes that the mapped drive is the user’s home directory on the UNIX machine, therefore, the $HOME UNIX environment variable is used in the path to the input file.
The variable unix_mc is the host name of the UNIX computer where the solver is executed.
The variable user_name is a UNIX login name.
In order to be able to execute the rsh into the UNIX side, the file .rhosts needs to be modified by adding the host name of the PC and your login. You can do that using vi or any other editor on UNIX. The .rhosts file must have read and write permissions for the user that is specified. If a secure shell (ssh) is installed on a user’s system, the ssh can be configured with host and user keys in order to avoid password requirements. A user authentication key needs to be created on the machine running HyperStudy. This gets passed on to the Unix machine (where the solver resides) when the ssh is invoked. The solver machine needs to have a copy of the authentication key so that it can verify the user.

Run Solvers on UNIX, without a UNIX Mapped Drive

This example demonstrates how to use a PC batch file and Unix shell script to run solvers on Unix, without a Unix mapped drive.

When you are running solvers on Unix, without a Unix mapped drive, the files are kept locally on the PC. Files are copied to a temporary location on the Unix machine, where the solver is executed, result files are then copied back to the study_directory on the PC where output responses are evaluated. HyperStudy sets a process environment variable called STUDY_PC_PATH, which facilitates this process. The value of this process environment variable is set to the full path of the current run directory on the PC. This environment variable changes with each run.

For this scenario, a PC batch file and a Unix shell script are required.

When entering the values for the variables, it is important not to leave spaces after the last character or surrounding the '=' symbol.
The file uses rcp and rsh commands.
Note: Check with your system administrator to see if these are enabled in your network.
The batch file was created for Windows NT 4.0.
The UNIX shell script was created on IRIX 6.5.
You want to test to see that your batch file and script are working correctly before using HyperStudy. You will need to replace %STUDY_PC_PATH% in the batch file with the full path for the directory containing your test file, then at the command prompt enter: batch_filename.bat input_filename.
It is possible to adapt the Unix script to run with a queuing system.

Batch File

In the example batch file you should only need to edit the USER INPUT SECTION. However, depending on your system, you may need to alter other parts of the file.

Certain variables must be defined in the USER INPUT SECTION of the batch file.

username: Username for the Unix account used
unix_root: Home directory on the Unix machine for the define username
unix_tmp_dir: Subdirectory of the user's Unix home directory to which the input file will be written
unix_script: Complete path, including file name, of the Unix shell script shown in Unix Shell Script, which is called upon to execute the solver on the Unix machine
UNIX_machine: Name of the Unix machine where the solver is executed.

@echo off                                                                                                                                                                              


::::#### USER INPUT SECTION ###########################################

:: Please Input relevant information after '=' sign on each of the
:: lines in this section.
::
:: For information on what information is required on each line, go to
:: the 'Interacting with your system' page of the HyperStudy manual.
         
 
set username=user1

set unix_root=/home/user1

set unix_tmp_dir=study_dir/scratch

set unix_script=/home/user1/study_dir/scripts/study1.sh

set UNIX_machine=UNIX1

 
::::#### END OF USER INPUT SECTION ####################################

cls
echo.
echo.
echo ---------------------------------------------------
echo User Defined Shell Parameters on PC
echo ---------------------------------------------------
echo User name....................: %username%
echo UNIX home of user............: %unix_root%
echo UNIX Temp Dir................: %unix_root%/%unix_tmp_dir%
echo Unix run script..............: %unix_script%
echo Remote Unix Machine..........: %UNIX_machine%
echo.
echo.

 
set pc_dir=%STUDY_PC_PATH%

set input_deck=%1%

echo.
echo.
echo -------------------------------------------------------------
echo Copying input deck from PC to Unix ...
echo.
echo.

cd %pc_dir%

c:/winnt/system32/rcp.exe "%input_deck%" "%UNIX_machine%.%username%:%unix_tmp_dir%"

 
echo.
echo.
echo ...Done.
echo -------------------------------------------------------------

echo.
echo.
echo -------------------------------------------------------------
echo Launching Unix Shell...
echo.
echo.
c:/winnt/system32/rsh.exe %UNIX_machine% -l %username% "%unix_script% %unix_tmp_dir%/%input_deck%"
echo.
echo.
echo ...Unix Shell Done.
echo -------------------------------------------------------------

echo.
echo.
echo ------------------------------------------------------------
echo Moving all files back from unix to PC...

c:/winnt/system32/rcp.exe -b "%UNIX_machine%.%username%:%unix_tmp_dir%/*" "."

echo.
echo Deleting all files from %unix_root%/%unix_tmp_dir%...
echo.
c:/winnt/system32/rsh.exe %UNIX_machine% -l %username% "rm -f %unix_tmp_dir%/*"

echo ...Done.
echo ------------------------------------------------------------

Unix Shell Script

In the example Unix Shell script you should only need to edit the USER INPUT SECTION. However, depending on your system, you may need to alter other parts of the file.

Certain variables must be defined in the USER INPUT SECTION of the Unix shell script.

unix_root: User's home directory on the Unix machine
unix_tmp_dir: Subdirectory of the user's Unix home directory to which the input file will be written
UNIX_machine: Name of the Unix machine where the solver is executed
exe_path: Complete path, including file name, of the solver executable to be used on the input file

#!/bin/sh                                                                                                                                                                              

######## USER INPUT SECTION ###########################################

# Please Input relevant information after '=' sign on each of the
# lines in this section.
#
# For information on what information is required on each line, go to
# the 'Interacting with your system' page of the HyperStudy manual. 

unix_root=/home/user1

unix_tmp_dir=study_dir/scratch

UNIX_machine=UNIX1

exe_path=/soft/solver/solver.exe
 

######## END OF USER INPUT SECTION ####################################

echo -----------------------------------------------
echo User Defined Shell Paramters on UNIX
echo -----------------------------------------------

echo Unix home of User...................$unix_root

echo Unix Temp Dir.......................$unix_tmp_dir

echo Remote Unix Machine.................$UNIX_machine

echo Path of SOLVER Executable...........$exe_path
 

input_deck=$1

echo
echo
echo
echo -------------------------------------------------
echo "Stripping cntrl M's ....."

to_unix $unix_root/$input_deck $unix_root/$input_deck.tmp
mv -f $unix_root/$input_deck.tmp $unix_root/$input_deck

echo
echo
echo ...Done.
echo -------------------------------------------------
echo
echo


echo
echo -------------------------------------------------
echo "Launching SOLVER......"
echo
echo
echo "$exe_path $unix_root/$input_deck"
$exe_path $unix_root/$input_deck

exit