Basic Operation

Resource Files

Resources can be specified via a resource file. Here is an example of a resource file:

#!CEIResourceFile 1.0
SOS:
                host: localhost
SERVER:        
                prologue: “setup_job” 
                epilogue: “cleanup_job” 
                host: server1
                host: server2 
                host: server3 
                host: server4

COLLABHUB:
                host: pc0

RENDERER:
                prologue: “setenv DISPLAY :0.0”
#               epilogue: host: pc1 
                host: pc2
                host: pc2

Resource files must begin with the '#!CEIResourceFile 1.0 ' line. Afterwards, they may have up to four optional sections: SOS, SERVER, COLLABHUB, and RENDERER. Each of the four sections contains one or more 'host: hostname' lines. These lines specify which computers to use for the corresponding section. ' hostname ' must be an Internet/intranet routable host name or IP address. A given host name may appear on multiple lines within a section or in different sections. If it appears multiple times within a section, then that host will run multiple instances of the corresponding EnSight component if needed.

Additionally, each section may have an optional 'prologue: cmd' line and/or an optional 'epilogue: cmd ' line. These specify a command to execute on each host before and after the corresponding EnSight component.

Note: The cmd string must be quoted, and may include appropriate job backgrounding symbols (for example, &).

At version 2.0, the resource file can accept an optional 'shell:' line, like:

#!CEIResourceFile 2.0
SOS:
        host: bunker
        shell: "/usr/local/bin/ssh"

Note: Keep in mind the new version number (2.0) and that the shell line string must be double quoted.

How to Specify Resources

Resources can be specified via resource files, environment variables, and command line options. Precedence rules determine which resources will be used. Basically, the last occurrence of a resource section (for example, SERVER) will be used in its entirety. For example, if multiple SERVER resource sections are found, only one will be used as determined by the precedence rules.

Since the EnSight Client, SOS, and CollabHub start other EnSight processes, they can use resources. The EnSight Server and distributed renderers do not start other EnSight processes that require resources.

While many ways exist to specify resources, in practice only one or two will be used given the particular user's computational environment.

Client Resources

The EnSight client supports the following ways for specifying resources:

the ENSIGHT10_RES environment variable;
the ENSIGHT10_SERVER_HOSTS environment variable;
the ENSIGHT10_RENDERER_HOSTS environment variable;
the ‘-use_lsf_for_servers’ command line option;
the ‘-use_lsf_for_renderers’ command line option;
the ‘-use_pbs_for_servers’ command line option;
the ‘-use_pbs_for_renderers’ command line option;
the ‘-sosres file_name’ command line option;
the ‘-chres file_name’ command line option; and
the ‘-res file_name’ command line option.

If multiple resources are specified to the client, then they will be evaluated in the order indicated above with the later methods taking higher precedence for a given section.

The ENSIGHT10_RES environment variable specifies a resource file name that the client reads.

ENSIGHT10_SERVER_HOSTS and ENSIGHT10_RENDERER_HOSTS specify quoted strings of space delimited host names (for example, "host1 host2 host1 host3") to be used for EnSight servers and distributed renderers, respectively. The host names are used in the order they occur. A host name may occur multiple times.

If either the '-use_lsf_for_servers ' or '-use_lsf_for_renderers ' command line options are specified, then the client will evaluate the environment variable LSB_MCPU_HOSTS for the resources. The environment variable specifies a quoted string such as "host1 5 host2 4 host3 1 " which indicates 5 CPUs should be used on host1, 4 CPUs should be used on host2, and 1 CPU should be used on host3. The hosts will be used in a round-robin fashion.

If either of the '-use_pbs_for_servers ' or '-use_pbs_for_renderers ' command line options are specified, then the client will evaluate the environment variable PBS_NODEFILE for the resources. The environment variable specifies a filename in which the file contains list of line delimited host names that were allocated by the PBS scheduler.

The '-sosres file_name ' command line option specifies the pathname to a resource file. This file name is passed to the SOS and processed by it; therefore the file name must be accessible and readable by the ensight.sos process. If multiple ' -sosres ' options are specified, only the last will be used.

The '-chres file_name ' command line option specifies the pathname to a resource file. This file name is passed to the CollabHub and processed by it; therefore the file name must be accessible and readable by the ensight_collabhub process. If multiple '-chres ' options are specified, only the last will be used.

The '-res file_name ' command line option specifies the pathname to a resource file. This command line option can be specified multiple times. This might be useful when generating resource files dynamically: a single file might specify only a particular type of resource (for example, SERVER or RENDERER ). The last occurrence of a particular section takes precedence when multiple ' -res ' options are given.

Finally, a resource file may be selected in the File → Open dialog for the SOS to use.

SOS Resources

The EnSight SOS supports the following ways for specifying resources:

resources gathered and sent from the client;
the ‘-sosres file_name’ command line option;
the ENSIGHT10_RES environment variable;
the ENSIGHT10_SERVER_HOSTS environment variable;
the ‘-use_lsf_for_servers’ command line option;
the ‘-use_pbs_for_servers’ command line option
the ‘-res file_name’ command line option; and
a resource file specified via the File → Open dialog.

If multiple resources are specified to the SOS, then they will be evaluated in the order indicated above with the later methods taking higher precedence for a given section. However, the SOS only uses SERVER section resources; the other sections are ignored.

The '-sosres file_name ' command line option specifies the pathname to a resource file. If multiple '-sosres ' options are specified, only the last will be used.

The ENSIGHT10_RES environment variable specifies a resource file name that the SOS reads.

ENSIGHT10_SERVER_HOSTS specifies a quoted string of space delimited host names (for example, "host1 host2 host1 host3 ") to be used for EnSight servers.

If the '-use_lsf_for_servers ' command line option is specified, then the SOS will evaluate the environment variable LSB_MCPU_HOSTS for the resources. The environment variable specifies a quoted string such as "host1 5 host2 4 host3 1 " which indicates 5 CPUs should be used on host1, 4 CPUs should be used on host2, and 1 CPU should be used on host3. The hosts will be used in a round-robin fashion.

If the '-use_pbs_for_servers ' command line option is specified, then the SOS will evaluate the environment variable PBS_NODEFILE for the resources. The environment variable specifies a filename in which the file contains list of line delimited host names that were allocated by the PBS scheduler.

The '-res file_name ' command line option specifies the pathname to a resource file. This command line option can be specified multiple times. The last occurrence of a particular section takes precedence when multiple '-res ' options are given.

Finally, a resource file may be selected in the File → Open dialog for the SOS to use.

CollabHub Resources

The EnSight CollabHub supports the following ways for specifying resources:

resources gathered and sent from the client;
the ‘-chres file_name’ command line option;
the ENSIGHT10_RES environment variable;
the ENSIGHT10_RENDERER_HOSTS environment variable;
the ‘-use_lsf_for_renderers‘ command line option;
the ‘-use_pbs_for_renderers’ command line option; and,
the ‘-res file_name’ command line option.

If multiple resources are specified to the CollabHub, then they will be evaluated in the order indicated above with the later methods taking higher precedence for a given section. However, the CollabHub only uses RENDERER section resources; the other sections are ignored.

The '-chres file_name ' command line option specifies the pathname to a resource file. If multiple '-chres ' options are specified, only the last will be used.

The ENSIGHT10_RES environment variable specifies a resource file name that the CollabHub reads.

ENSIGHT10_RENDERER_HOSTS specifies a quoted string of space delimited host names (for example, "host1 host2 host1 host3 ") to be used for EnSight distributed renderers.

If the '-use_lsf_for_renderers ' command line option is specified, then the CollabHub will evaluate the environment variable LSB_MCPU_HOSTS for the resources. The environment variable specifies a quoted string such as "host1 5 host2 4 host3 1 " which indicates 5 CPUs should be used on host1, 4 CPUs should be used on host2, and 1 CPU should be used on host3. The hosts will be used in a round-robin fashion.

If the '-use_pbs_for_renderers ' command line option is specified, then the CollabHub will evaluate the environment variable PBS_NODEFILE for the resources. The environment variable specifies a filename in which the file contains list of line delimited host names that were allocated by the PBS scheduler.

The '-res file_name ' command line option specifies the pathname to a resource file. This command line option can be specified multiple times. The last occurrence of a particular section takes precedence when multiple '-res ' options are given.

When using distributed rendering, any hosts specified via a .prdist file are used instead of those given by RENDERER resources. Additionally, any .prdist file specified directly to the collabhub, will override one specified to the client.

A Client/Server Example

Resources are not used to specify where a server runs when it is part of a normal client/server session. The default server connection in the Connection Setting dialog determines on which computer the server runs unless the Client command line option '-c connection_name ' is specified.

A Simple SOS Example

The SOS can read any of the supported file formats in addition to the SOS Case file format. When a SOS Case file is not used, then the number of EnSight Servers used is equal to the number of hosts specified in the SERVER resource section.

The following resource file my_hosts.res is created:

#!CEIResourceFile 1.0
SOS:
                host: borg
SERVER:
                host: drone1
                host: drone2
                host: drone3
                host: drone1

EnSight is started with this command line:
ensight -res my_hosts.res -sos
The EnSight Client will automatically check out an Enterprise (formerly HPC or gold) key and will run on the local workstation, the SOS (ensight.sos) will be automatically started on computer borg and will connect back to the client. Borg will need to recognize the name of the computer that the client is running on.
In the File → Open dialog the LS-Dyna file d3plot is selected and the Load All button is clicked.
The SOS will start four EnSight Servers on computers drone1, drone2, drone3, and drone1 (presumably,drone1 might be a SMP). The drone computers need to recognize the hostname borg in order to connect back to the sos running on this computer.
Each of the servers will read 1/4 of the data set since the Auto Distribute flag (on the SOS tab of the File → Open dialog) is on by default for the LS-Dyna reader.

Another SOS Example

EnSight is started with this command line:
ensight
The Case → Connection Settings dialog is opened. On the ' SOS ' tab, an entry for host 'borg' is created. For that entry, 'Executable:' is set to the name of command file 'my_sos ', 'Use default rsh cmd' is deselected, and 'Alt rsh cmd:' is set to 'ssh '. The entry is saved and EnSight is terminated.

The following resource file 'my_hosts.res ' is created:

#!CEIResourceFile 1.0
SOS:
                host: borg
SERVER:
                host: drone1
                host: drone2
                host: drone3
                host: drone1

On computer borg (assuming it is running Unix or Linux), the file my_sos is created:
```
#!/bin/csh
setenv ENSIGHT10_SERVER_HOSTS ‘cat $PBS_NODEFILE‘
ensight.sos $*
```
The file must be in the user's default path and must be executable.
EnSight is started with this command line:
ensight -res my_hosts.res -sos
The EnSight Client will check out an Enterprise (formerly gold or HPC) license key and run on the local workstation, the command file 'my_sos ' will run on computer 'borg ' which must be able to connect back to the local workstation by hostname. The client will start up 'my_sos ' via ssh. 'my_sos ' sets the environment variable ENSIGHT10_SERVER_HOSTS to be the contents of the file specified by the environment variable PBS_NODEFILE (OpenPBS' dynamic list of allocated nodes).
In the File → Open dialog the LS-Dyna file 'd3plot' is selected and the Load All button is clicked.
The SOS will start EnSight Servers on computers specified in file $PBS_NODEFILE. Hosts specified in the SERVER section of my_hosts.res are ignored since ENSIGHT10_SERVER_HOSTS takes precedence.
Each of the servers will read 1/N of the data set since the 'Auto Distribute ' flag (on the SOS tab of the File → Open dialog) is on by default for the LS-Dyna reader.

A SOS Case File Example

When a SOS Case file is used with resources, it must be modified otherwise the resources will be ignored for the EnSight Servers. This is done for backwards compatibility.

The file SOS case file 'big_data.sos ' is modified. Two lines are added to the FORMAT section: 'use_resources: on ' and 'auto_distribute: on '. The 'casefile: ' line for each server is brought to the beginning of each subsection.
```
FORMAT type: master_server LS-DYNA3D
use_resources:         on
auto_distribute:       on
SERVERS
number of servers:     2
#Server 1
#---------
casefile:              d3plot
machine id:
executable:            ensight_server
directory:             /tmp
login id:
data_path:             /tmp
#Server 2
#---------
casefile:              d3plot
machine id:
executable:            ensight_server
directory:             /tmp
login id:
data_path:             /tmp
```
Note: The 'casefile:' line must appear before the other lines for that server when using resources.

The following resource file 'my_hosts.res ' is created:

#!CEIResourceFile 1.0
SOS:
                host: borg
SERVER:
                host: drone1
                host: drone2
                host: drone3
                host: drone1

EnSight is started with this command line:
ensight -res my_hosts.res -sos
The EnSight Client will run on the local workstation, the SOS (ensight.sos) will run on computer 'borg '.
In the File → Open dialog the SOS Case file 'big_data.sos ' is selected and the 'Load All' button is clicked.
The SOS will start two EnSight Servers on computers 'drone1 ' and 'drone2 '. Only two servers are used since two 'casefile: ' lines occur in the SOS Case file. The 'number of servers: 2 ' line is ignored as are the 'machine id: ' lines.
Each of the servers will read half of the data set due to the line 'auto_distribute: on ' in 'big_data.sos'.

Another SOS Case File Example

The file SOS case file 'big_data.sos ' is modified. Two lines are added to the FORMAT section: 'use_resources: on ' and 'auto_distribute: on '. The 'number of servers: ' line is modified. One server subsection is specified.
```
FORMAT
type: master_server LS-DYNA3D
use_resources:         on
auto_distribute:       on
SERVERS
number of servers:         4 repeat
#Server 1
#---------
casefile:              d3plot
machine id:
executable:            ensight_server
directory:             /tmp
login id:
data_path:             /tmp
```
The following resource file 'my_hosts.res ' is created:
```
#!CEIResourceFile 1.0
SOS:
                host: borg
SERVER:
                host: drone1
                host: drone2
                host: drone3                
                host: drone1
```
2. EnSight is started with this command line:
ensight -res my_hosts.res -sos
The EnSight Client will run on the local workstation, the SOS (ensight.sos) will run on computer 'borg '.
In the File → Open dialog the SOS Case file 'big_data.sos ' is selected and the 'Load All' button is clicked.
The SOS will start four EnSight Servers on computers 'drone1 ', 'drone2 ', 'drone3 ', and 'drone1 '. Since the 'number of servers: ' line has the word ' repeat ', the servers specified in the SERVERS resource is used to determine the number of servers used and their host names. All server subsections after the first in 'big_data.sos ' are ignored due to 'number of servers: 4 repeat '.
Each of the servers will read 1/4 of the data set since the 'Auto Distribute ' flag (on the SOS tab of the File → Open dialog) is on by default for the LS-Dyna reader.

A PRDIST Example

The following resource file 'my_hosts.res ' is created:

#!CEIResourceFile 1.0
SOS:
        host: borg
SERVER:
        host: drone1
        host: drone2
        host: drone3
        host: drone1
COLLABHUB:
        host: curly
RENDERER:
        prologue: “xhost +”
        host: larry
        host: moe

The following prdist resource file 'my_conf_with_res.prdist ' is also created:
```
#ParallelRender EnSight 1.0
router
pc
client
```
EnSight is started with this command line:
ensight -res my_hosts.res -prdist my_config_with_res.prdist
The EnSight Client will run on the local workstation, the SOS (ensight.sos) will run on computer 'borg '.
The EnSight CollabHub will run on computer 'curly '. Two distributed renderers will start on hosts 'larry ' and 'moe '.
The my_conf_with_res.prdist file here specifies both router and client followed by blank names which indicate to use the 'my_hosts.res' file. The pc option indicates to use parallel compositing which removes the from the composited display
Note: If pc is not specified, then a will wrap the composited display - which is a testing and debug mode. In addition, no display sync will be used during interactive transformations, producing a lag effect which is quite troublesome.
In the File → Open dialog the LS-Dyna file 'd3plot ' is selected and the Load All button is clicked.
The SOS will start four EnSight Servers on computers 'drone1 ', 'drone2 ', 'drone3 ', and 'drone1 ' (presumably, 'drone1 ' might be a SMP).
Each of the servers will read 1/4 of the data set since the 'Auto Distribute ' flag (on the SOS tab of the File → Open dialog) is on by default for the LS-Dyna reader.
Note: A .prdist file can be specified as an option to the '-prdist' command line option. However, if the defaults are adequate or overridden with command line options, then a prdist file is no longer needed. Furthermore, specifying the command line option '-prdist' automatically implies the command line option '-sos'; previous versions required you to specify it. Parallel Compositing of the Ansys EnSight User Manual for .prdist file documentation, including default values and manual connect support.