SHELL 22.1

Customising the GUI SHELL

The 'oa_pref' file controls the setup of a number of the programs in the software suite. Most of the programs will look for this file in the following 4 locations in the order given to allow individual users to customise the programs for their own needs :

The OA_ADMIN_xx directory
The directory containing the executables (OA_INSTALL directory)
The user's login directory
The current working directory

The 'xshell_22' SHELL will look for this file in all four directories. However to stop users trying to override the system settings, it will only read a seletion of the SHELL preferences from the home and current working directory (those that do not affect system settings). This section only deals with the options for setting up the GUI SHELL, the options for the other programs are covered in the relevant manuals.

From v94 preferences can be locked. If a preference is locked it cannot be changed in an oa_pref file in a more junior directory. To lock a preference use the syntax 'shell#' rather than 'shell*' .

From v94 Environment variables can be used and they will be expanded by the SHELL. For example on Windows you could specify the temp folder with shell*temp_folder: %USERPROFILE%/my_temp_folder.

Any line in the 'oa_pref' file that does not start with the string 'shell*' or 'shell#' is ignored, normally comment lines will be prefixed with a # for clarity. The relevant sections of this file follows below.

# Preferences file for software. # # SHELL stuff: #
# Definition	Type	Valid arguments	Default
# online	logical	TRUE or FALSE	TRUE
# background	logical	TRUE or FALSE	TRUE
# batch	logical	TRUE or FALSE	TRUE
# queue	logical	TRUE or FALSE	TRUE
# default	string	ONLINE or BACKGROUND or BATCH or QUEUE	ONLINE
# display_factor	real	Factor on display size (0.5-2.0)	1.0
# button_gradation	real	Button shade gradation (0.0-1.0)	0.5
# dyna_keyword_manual	string	Pathnames of up to 4 Dyna keyword manuals, separated by commas
# dyna_theory_manual	string	Pathname of Dyna theory manual
# batch_type	string	NQS,LSF,SGE,PBS,PBSPRO7 or PBSPRO71	NQS
# queue_output_file	logical	Add output file directive to job script	TRUE
# queue_error_file	logical	Add error file directive to job script	TRUE
# queue_error_path	logical	Add job path to output/error directive in job script	TRUE
# queue_memory	real	Batch Queue Memory Size	15000000
# queue_memory_units	string	WORDS or MWORDS	WORDS
# queue_cpu	real	Batch Queue CPU Limit	0
# queue_cpu_units	string	SECONDS, MINUTES or HOURS	SECONDS
# queue_space	real	Batch Queue File Space Limit 1024	1024
# queue_machine	string	Name of LSF queuing machine
# request_cpu_limit	logical	TRUE or FALSE	TRUE
# request_memory_limit	logical	TRUE or FALSE	TRUE
# request_space_limit	logical	TRUE or FALSE	FALSE
# system_cpu	real	Minimum System Time (seconds)	90
# job_format	string	KEYWORD or FIXED	KEYWORD
# file_names	string	ARUP or LSTC	ARUP
# job_memory	real	Job Memory Size	9000000
# job_memory_units	string	WORDS or MWORDS	WORDS
# job_cpu	real	Job CPU Limit	0
# job_cpu_units	string	SECONDS, MINUTES or HOURS	SECONDS
# allow_mem_change	logical	TRUE or FALSE	TRUE
# file_size	integer	Binary File Size	1024
# write_ctf	logical	TRUE or FALSE	FALSE
# write_ztf	logical	TRUE or FALSE	TRUE
# batch_display	string	TRUE or FALSE
# keep_files	logical	TRUE or FALSE	FALSE
# d3plot64_version	string	name of 64 bit D3PLOT executable	d3plot<ch:var name="version"/>_64.exe
# this64_version	string	name of 64 bit T/HIS executable	this<ch:var name="version"/>_64.exe
# primer64_version	string	name of 64 bit PRIMER executable	primer<ch:var name="version"/>_64.exe
# reporter64_version	string	name of 64 bit REPORTER executable	reporter<ch:var name="version"/>_64.exe
# shell_release	string	version # displayed for shell	<ch:var name="version"/>.0
# max_cpus	integer	Maximum number of CPUS	4
# max_mpp_cpus	integer	Maximum number of CPUs for MPP	4
# default_cpus	integer	Default number of CPUs for SMP	1
# default_mpp_cpus	integer	Default Number of CPUs for MPP	1
# max_node_cpus	integer	Maximum number of CPUs per node for MPP jobs	2
# pack_nodes	logical	Pack MPP jobs on the minimum number of nodes	TRUE
# submit_shell	string	CSHELL or BSHELL	CSHELL
# unix_type	string	SYSTEM5 or BSD	SYSTEM5
# manual_reader	string	location of ADOBE ACROBAT reader	acroread
# enable_job_monitoring	logical	TRUE or FALSE	TRUE
# temp_folder	string	Location to write .bat file to on a PC	C:\TEMP
# max_hybrid_mpp_threads	integer	Maximum number of MPP threads for Hybrid Dyna	4
# max_hybrid_smp_threads	integer	Maximum number of SMP threads for Hybrid Dyna	4
# default_hybrid_mpp_threads	integer	Default number of MPP threads for Hybrid Dyna	1
# default_hybrid_smp_threads	integer	Default number of SMP threads for Hybrid Dyna	1
# case_option	logical	case option	FALSE
# mcheck_option	logical	mcheck option	FALSE
# xterm_start	logical	Start programs from an xterm console	TRUE
# default_code_type	string	SMP, MPP or HYBRID	MPP
# default_precision	string	SINGLE or DOUBLE	SINGLE
# default_mpi_type	string		PMPI
# default_ls_dyna_executable	string
# default_mpi_executable	string
# reporter_format	string	ORR,ORRX	ORRX
# write_reporter	logical	TRUE,FALSE	FALSE
# write_html	logical	TRUE,FALSE	FALSE
# write_pdf	logical	TRUE,FALSE	TRUE
# write_ppt	logical	TRUE,FALSE	FALSE
# combine_reporter	logical	TRUE,FALSE	TRUE
# skip_generate	logical	TRUE,FALSE	TRUE
# combine_reporter_pdf	logical	TRUE,FALSE	TRUE
# combine_reporter_pptx	logical	TRUE,FALSE	TRUE
# combine_reporter_html	logical	TRUE,FALSE	TRUE
# run_reporter_iconised	logical	TRUE,FALSE	TRUE
# oasys_batch	logical	TRUE,FALSE	TRUE
# run_reporter_in_batch	logical	TRUE,FALSE	TRUE
# automatically_exit_reporter	logical	TRUE,FALSE	TRUE
# write_reporter_logfile	logical	TRUE,FALSE	TRUE
# create_names_file	string	PRE-V20,ALWAYS,NEVER	PRE-V20

Preferences marked with a '*' can be read from all four directories. If desired they can still be locked in the OA_ADMIN_xx or OA_INSTALL directories using the 'shell#' syntax:

shell*online: TRUE
shell*background: TRUE
shell*batch: TRUE
shell*queue: TRUE
shell*default: ONLINE
shell*dyna_keyword_manual: (*)
shell*dyna_theory_manual: (*)
shell*batch_type: NQS
shell*queue_output_file: TRUE
shell*queue_error_file:TRUE
shell*queue_error_path:TRUE
shell*queue_memory: 15000000
shell*queue_memory_units:WORDS
shell*queue_cpu: 0
shell*queue_cpu_units: SECONDS
shell*batch_type: NQS
shell*queue_space: 1024
shell*queue_machine:
shell*request_cpu_limit: TRUE
shell*request_memory_limit: TRUE
shell*request_space_limit: FALSE
shell*system_cpu: 90
shell*job_format: KEYWORD
shell*file_names: ARUP (*)
shell*job_memory: 9000000
shell*job_memory_units: WORDS
shell*job_cpu: 0
shell*job_cpu_units: SECONDS
shell*allow_mem_change: TRUE
shell*file_size: 1024 (*)
shell*write_ctf: FALSE (*)
shell*write_ztf: TRUE (*)
shell*batch_display: (*)
shell*keep_files: FALSE (*)
shell*d3plot64_version: d3plot22_64.exe (*)
shell*this64_version: this22_64.exe (*)
shell*primer64_version: primer22_64.exe (*)
shell*reporter64_version: reporter22_64.exe (*)
shell*shell_release: 22.1
shell*max_cpus: 1
shell*max_mpp_cpus: 1
shell*default_cpus: 1 (*)
shell*default_mpp_cpus: 1 (*)
shell*max_node_cpus: 2
shell*pack_nodes: TRUE
shell*submit_shell: CSHELL
shell*unix_type: SYSTEM5
shell*manual_reader: acroread (*)
shell*temp_folder: C:\TEMP (*)
shell*max_hybrid_mpp_threads: 1
shell*max_hybrid_smp_threads: 1
shell*default_hybrid_mpp_threads: 1
shell*default_hybrid_smp_threads: 1
shell*case_option: FALSE
shell*mcheck_option: FALSE
shell*xterm_start: TRUE
shell*default_code_type: MPP (*)
shell*default_precision: SINGLE (*)
shell*write_reporter: FALSE (*)
shell*write_html: FALSE (*)
shell*write_pdf: TRUE (*)
shell*write_ppt: FALSE (*)

shell*combine_reporter: TRUE (*)
shell*skip_generate: TRUE (*)
shell*combine_reporter_pdf: TRUE (*)
shell*combine_reporter_pptx: TRUE (*)

shell*combine_reporter_html: TRUE (*)
shell*run_reporter_iconised: TRUE (*)
shell*oasys_batch: TRUE (*)
shell*run_reporter_in_batch: TRUE (*)

shell*automatically_exit_reporter: TRUE (*)
shell*write_reporter_logfile: TRUE (*)
shell*create_names_file: PRE-V20 (*)

shellonline / shellbackground / shellbatch / shellqueue

The XSHELL can submit Ansys LS-DYNA jobs using four different options. Any of these methods can be made inaccessible by setting the relevant variable to FALSE . If an option is not available on a machine then the variable should also be set to FALSE .

shell*online - Allows jobs to be submitted interactively. Delayed start times cannot be specified.

shell*background - Allows jobs to be submitted to background. If a delayed start times is specified then the job will be submitted using the LINUX 'at' command.

shell*batch - Allows jobs to be submitted using the LINUX 'batch' command. Delayed start times cannot be specified.

shell*queue - Allows jobs to be submitted to NQE style batch queues using 'qsub' or equivalent commands. Delayed start times,CPU/Memory limits and accounts may be specified.

If shell*queue is set to FALSE then sections 2.3.3 to 2.3.10 can be ignored.

shell*default

This variable controls the default option that will be used to submit Ansys LS-DYNA jobs. It should be set to either ONLINE , BACKGROUND , BATCH , or QUEUE to select the required default.

shell*dyna_keyword_manual

This variable should be set to the location of the Dyna keyword PDF manuals. Set the full pathname. Up to four PDFs can be specified (e.g. if there are separate volumes) by separating the pathnames with a comma.

shell*dyna_theory_manual

This variable should be set to the location of the Dyna theory PDF manual. Set the full pathname.

shell*batch_type

This variable controls the type of queue the QUEUE command (see shell*online / shell*background / shell*batch / shell*queue) submits the job to. At present this variable may be set to NQS , LSF, SGE (SUN GRID ENGINE), PBS, PBSPRO7 and PBSPRO71 . Due to the limitations of some of the queuing systems not all options are available with all queue types, see table below.

Function	NQS	PBS / PBSPRO7 / PBSPRO71	LSF	SGE
Analysis Start Time	Available	Available	Available	Unavailable
Analysis Start Day	Available	Available	Unavailable	Unavailable

shell*queue_output_file

This variable controls if the SHELL writes a queue directive to specify a file for output when a job is submitted to a queueing system. If this option is set to TRUE then the queue will add the following line to the top of the job submission script.

Queue Type	Command
NQS	#QSUB -o "job_directory"/"jobname".log
PBS / PBSPRO7/ PBSPRO71	#PBS -o "job_directory"/"jobname".log
SGE	#QSUB -o "job_directory"/"jobname".log
LSF	#BSUB -o "job_directory"/"jobname".log

shell*queue_error_file

These variable controls if the Shell writes a queue directive to specify a file for errors when a job is submitted to a queueing system. If this option is set to TRUE then the queue will add the following line to the top of the job submission script.

Queue Type	Command
NQS	#QSUB -eo #QSUB -o "job_directory"/"jobname".err
PBS / PBSPRO7/ PBSPRO71	#PBS -e "job_directory"/"jobname".err
SGE	#QSUB -e "job_directory"/"jobname".err
LSF	#BSUB -e "job_directory"/"jobname".err

shell*queue_error_path

This option can be used to specify if the queue directives for the output and error files should contain the job path or not. By default this option is set to TRUE.

shell*queue_memory

This variable controls the value used for the default Queue Memory limit. The required value should be specified using the units defined by the shell*queue_memory_units variable (see Queue Memory Units). A value of 0 means that the job will be submitted with a unlimited Queue Memory.

shell*queue_memory_units

This variable controls whether the default Queue Memory limit is specified in words or megawords. It should be set to either WORDS or MWORDS respectively.

shell*queue_cpu

This variable controls the value used for the default Queue CPU Limit. The required value should be specified using the units defined by the shell*queue_cpu_units variable (see Queue Cpu Units). A value of 0 means that the job will be submitted with a unlimited Queue CPU.

shell*queue_cpu_units

This variable controls whether the default Queue CPU Limit is specified in seconds, minutes or hours. It should be set to either SECONDS , MINUTES or HOURS respectively.

shell*queue_space

This variable controls the value used for the default File Space limit. The required value should be specified in Mbytes. A value of 0 means that the job will be submitted with an unlimited File Space Limit.

shell*queue_machine

This variable may be used to specify the name of the queuing machine used by LSF batch queues. This option is passed as the -m parameter to the LSF bsub command.

e.g. bsub -m queue_machine

shell*request_cpu/memory_limit

These variables control whether Queue CPU and Memory limits have to be specified when jobs are submitted to NQS style queues. If they do have to be specified then set the relevant variable to TRUE , otherwise set them to FALSE.

shell*request_space_limit

This variable controls whether a Per-request File Space limit has to be specified when jobs are submitted to NQS style queues. If they do have to be specified then set this variable to TRUE , otherwise set it to FALSE .

shell*system_cpu

This variable controls the minimum amount of 'system' time, in seconds, that a job submitted to a NQS style queue will require if the queue has been set up using a Queue CPU Limit, (see Request CPU Limit/ Request Memory Limit . When a job is submitted to such a queue a 'system' CPU time will be calculated as either 2.5% of the Analysis CPU time or the value of this variable. If the difference between the Queue CPU limit and the Analysis CPU limit is smaller than this value the Queue CPU limit will automatically be increased to allow enough system time for the job to terminate normally when the Analysis CPU limit has been reached.

shell*job_format

This variable controls the default file format that will be expected by Ansys LS-DYNA. It can be set to either KEYWORD or FIXED.

shell*file_names

This variable controls the names of the output files generated by Ansys LS-DYNA. This variable can be set to either ARUP or LSTC.

With Ansys LS-DYNA 970 onwards the names of the output files can also be specified using the *KEYWORD_ID option where a filename prefix for all of the output files is specified within the input file.

Output File	ARUP	LSTC	*KEYWORD_ID
Binary Complete State Database	'jobname'.ptf	d3plot	'prefix'.d3plot
Time History Database	'jobname'.thf	d3thdt	'prefix'.d3thdt
Extra Time History Database	'jobname'.xtf	xtfile	'prefix'.xtfile
Binary Output File	binout	binout	'prefix'.binout
Restart Dump File	'jobname'.dpf	d3dump	'prefix'.d3dump
Running Restart Dump File	'jobname'.adf	runrsf	'prefix'.runrsf

shell*job_memory

This variable controls the value used for the default Analysis Memory limit, the amount of CORE memory that Ansys LS-DYNA will use to store data. The required value should be specified using the units defined by the shell*job_memory_units variable (see Job Memory Units). A value of 0 means that the job will be submitted with a the default amount of CORE memory built into that Ansys LS-DYNA. The default value of 9000000 should be enough for models of up to 60000 elements.

shell*job_memory_units

This variable controls whether the default Analysis Memory limit is specified in words or megawords. It should be set to either WORDS or MWORDS respectively.

shell*job_cpu

This variable controls the value used for the default Analysis CPU limit. The required value should be specified using the units defined by the shell*job_cpu_units variable (see Job Cpu Units). A value of 0 means that the job will be submitted with no Analysis CPU limit.

shell*job_cpu_units

This variable controls whether the default Analysis CPU limit is specified in seconds, minutes or hours. It should be set to either SECONDS , MINUTES or HOURS respectively.

shell*allow_mem_change

This variable controls whether users can change the amount of CORE memory used by Ansys LS-DYNA. If this variable is set to FALSE then users will not be able to modify the Analysis Memory Limit and will be forced to use the default value built into Ansys LS-DYNA.

shell*file_size

This variable controls the default binary file size produced by Ansys LS-DYNA. The value specified gives the required file size in Mbytes.

shell*write_ctf

By default the 'xshell_22' is set up so that the default is for Ansys LS-DYNA to write out CTF binary files when a jobs is submitted ( see the Job Options menu). If this variable is set to FALSE then this option will be turned off by default.

shell*write_ztf

By default the 'xshell_22' is set up so that after an Ansys LS-DYNA run PRIMER is automatically run to generate a .ZTF file for D3PLOT to read (see the Job Options menu). If this variable is set to FALSE then this option will be turned off by default.

shell*batch_display

This variable can be used to specify a LINUX DISPLAY that can be used for batch processing commands.

shell*keep_files

This variable controls whether temporary files created during the submission process and any CORE files created if a job terminates abnormally are deleted automatically. If this variable is set to TRUE the files will not be deleted.

shell*<*****>_version

By default the 'xshell_22' is set up to access and run software that uses the default program names. This option allows the name of any executable to be modified as required and for the 'xshell_22' to be notified of this name change.

e.g. shell*d3plot64_version : d3plot90.exe

would force the version 22 Shell to run the version 9.0 copy of d3plot, ( d3plot90.exe would have to be in the directory containing the version 22 executables).

32 bit versions of D3PLOT, T/HIS, PRIMER and REPORTER are no longer released. The names for the 64 bit versions can be modified using

shell*this64_version:
shell*d3plot64_version:
shell*primer64_version:
shell*reporter64_version:

shell*shell_release

By default the 'xshell_22' is set up to display 22.1 as the version. This option allows the version number displayed to be changed if a customised installation is set up

shellmax_cpus/shellmax_mpp_cpus

These variable controls the maximum number of CPU's that can be selected for SMP and MPP parallel jobs.

shelldefault_cpus/shelldefault_mpp_cpus

These variable controls the default number of CPU's for SMP and MPP parallel jobs.

shell*max_node_cpus

This variable should be set to the number of CPUS each node has in a cluster. When a MPP job is submitted to a PBS queue this variable will be used to calculate the required number of nodes that will be requested from the PBS queuing system.

shell*pack_nodes

This variable is used along with shell*max_node_cpus to calculate the number of nodes required when submitting a MPP job to a PBS queuing system. If this is set to TRUE then the minimum number of nodes will be requested.

Note that if commands are specified in the "oasys_queue" file then the following defaults will be overidden.

# Job CPU's	max_node_cpus	pack_nodes	PBS node request	PBSPro 7.0 node request	PBSPro 7.1 node request
2	2	TRUE	nodes=1:ppn=2 (1x2)	nodes=1:ppn=1:ncpus=2	select=1:ncpus=2
2	2	FALSE	nodes=2:ppn=1 *(2x1)*	nodes=2:ppn=1:ncpus=1	select=2:ncpus=1
8	2	TRUE	nodes=4:ppn=2 (4x2)	nodes=4:ppn=1:ncpus=2	select=4:ncpus=2
8	2	FALSE	nodes=8:ppn=1 (8x1)	nodes=8:ppn=1:ncpus=1	select=8:ncpus=8
7	4	TRUE	nodes=1:ppn=4+1:ppn=3 (1x4 + 1x3)	nodes=1:ppn=1:ncpus=4 +1:ppn=1:ncpus=3	select=1:ncpus=4 +1:ncpus=3
7	4	FALSE	nodes=7:ppn=1 (7x1)	nodes=7:ppn=1:ncpus=1	select=7:ncpus=1

shell*submit_shell (LINUX only)

Ansys LS-DYNA jobs are submitted on LINUX systems using script files. This variable can be set to either CSHELL or BSHELL to create either CSHELL or BOURNE shell scripts.

shell*unix_type

This variable controls the default binary file size produced by Ansys LS-DYNA. The value specified gives the required file size in Mbytes.

shell*manual_reader (LINUX only)

This option should be set to point to where a copy of the Adobe Acrobat reader software can be found on the system.

shell*temp_folder (Windows only)

This option can be used to specify a folder that the SHELL can use to create temporary files while submitting Ansys LS-DYNA jobs. The directory should be on a local system disk not a networked disk as some Anti-Virus programs block running DOS batch files from Network Drives. The default folder is C:\TEMP