RSoft Installation Guide

RSoft Design Group, Inc. 400 Executive Blvd. • Suite 100 Ossining, NY 10562 Phone: 1•914•923•2164 Fax: 1•914•923•2169 info@rsoftdesign.com www.rsoftdesign.com Copyright © 1993 - 2007 All Rights Reserved.

Contents

Preface 1 Notices .......................................................................................................................................1

Limited Warranty ........................................................................................................1 Copyright Notice .........................................................................................................1 RSoft Design Group™ Trademarks ............................................................................1 Acknowledgments .......................................................................................................1

System Requirements ................................................................................................................2

Chapter 1: Before Installing 3 1.A. Installation Steps................................................................................................................3 1.B. Installation Notes ...............................................................................................................3

Chapter 2: Installation for Windows Platforms 5 2.A. Getting Ready To Install ....................................................................................................5 2.B. Installing the Package under Windows ..............................................................................5

Notes: ..........................................................................................................................6 2.C. Backing up the Examples...................................................................................................6 2.D. Finishing the Installation....................................................................................................6

Testing a Non-Cluster Installation...............................................................................6 Testing a Cluster Installation.......................................................................................7

Chapter 3: Installation for Linux Platforms 9 3.A. Getting Ready to Install .....................................................................................................9 3.B. Installing the Package under Linux....................................................................................9 3.C. Setting up the PATH ........................................................................................................10 3.D. Installing the Licensing Scheme .....................................................................................10

License file ................................................................................................................10 Local hardlock key (node-locked) .............................................................................11 Local hardlock key (network key).............................................................................11 Remote network key..................................................................................................11

3.E. Backing up the Examples .................................................................................................12 3.F. Environment variables......................................................................................................12 3.G. Finishing the Installation..................................................................................................13

Testing a Non-Cluster Installation.............................................................................13 Testing a Cluster Installation.....................................................................................13

Chapter 4: MPI Installation for Clustered Simulation 15 Step 1: Installing the Software on Each Node ........................................................................15 Step 2: Testing Each Node as a Standalone Simulator ...........................................................15 Step 3: Ensuring Network Connectivity .................................................................................16

Windows Clusters: ....................................................................................................16 Linux Clusters: ..........................................................................................................17

RSoft Installation Guide Contents • iii

Step 4: Testing the Cluster......................................................................................................18 FullWAVE cluster users:............................................................................................18 MOST cluster users:...................................................................................................18

Chapter 5: Installation Troubleshooting 19 5.A. Windows Installation Trouble-Shooting ..........................................................................19

Directory/PATH Issues .............................................................................................19 License File Issues.....................................................................................................19 Hardware Key Issues.................................................................................................20

5.B. Unix/Linux Installation Trouble-Shooting.......................................................................21 Linux Hardlock Protection Key.................................................................................21 Linux License File Issues ..........................................................................................21 DOS format *.ind files ..............................................................................................21 Missing Shared Libraries...........................................................................................22 Write Access..............................................................................................................22

Chapter 6: Uninstalling the Package 23 6.A. RSoft CAD 5.0g, OptSim 4.0, and LaserMOD 2.0 and Later ..........................................23

Windows: ..................................................................................................................23 UNIX/Linux ..............................................................................................................23 Uninstalling the Hardlock Drivers.............................................................................23

6.B. Versions earlier than RSoft CAD 5.0g, OptSim 4.0, and LaserMOD 2.0 ........................23 Windows: ..................................................................................................................24 Linux: ........................................................................................................................24

Chapter 7: What Next? 25 7.A. Product Manuals & README File .................................................................................25 7.B. Directory Structure...........................................................................................................25 7.C. Technical Support & Software Upgrades.........................................................................26

iv • Contents RSoft Installation Guide

Preface

This document describes the installation procedure for software packages including device tools (BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD, FemSIM, and LaserMOD) and system tools (OptSim and ModeSYS).

Notices This section has a list of legal and other miscellaneous information pertaining to the software.

Limited Warranty RSoft Design Group, Inc. warrants that under normal use, the physical media (diskette and documentation) will be free of material defects for a period of thirty days from the date of purchase. Upon written notice, RSoft Design Group, Inc. will replace any defective media. No other warranty of any sort, either expressed or implied, is provided with this software. No liability for damage to equipment or data, or any other liability, is assumed by RSoft Design Group, Inc.

Copyright Notice Copyright © 1993-2006 RSoft Design Group, Inc. All Rights Reserved.

Copyright is claimed for both this manual and the software described in it.

RSoft Design Group™ Trademarks RSoft Design Group, RSoft Inc., RSoft, The RSoft CAD Environment, BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD, FemSIM, LaserMOD, OptSIM, LinkSIM, EDFA for Vendors, ModeSYS, Artifex, MetroWAND, SWAT, WinPLOT, and RPlot are trademarks of RSoft Design Group, Inc.

Acknowledgments Portions of OptSim are based on Ptolemy II and Ptolemy Classic – copyright by University of California, Berkeley. OptSim and ModeSYS include models and algorithms licensed by RSoft Design Group from two prominent university optical link simulation packages. These are iFROST (illinois FibeR-optic and Optoelectronic Systems Toolkit) from the University of Illinois at Urbana-Champaign, and FOLD (Fiber Optic Link Demonstrator) from the University of California at Santa Barbara. iFROST, in collaboration with IBM, was validated and used for the modeling and simulation of the DARPA-funded Optoelectronic Technology Consortium’s 32 channel 16 Gbps OETC parallel optical bus. FOLD was validated and used for the modeling and simulation of the DARPA-funded WEST (WDM with Electronic Switching Technology) program’s 12 channel 120 Gbps optical communication switch.

RSoft Installation Guide Preface • 1

IBM is a registered trademark and IBM PC, PS/2, and OS/2 are trademarks of International Business Machines Corporation. Intel is a trademark of Intel Corporation. Microsoft and MS- DOS are registered trademarks and Windows is a trademark of Microsoft Corporation. UNIX and Motif are registered trademarks and X Windows is a trademark of The Open Group. Linux is a registered trademark of Linus Torvalds. Xfree86 is a registered trademark of the The Xfree86 Project. All other product names referred to in this document are trademarks or registered trademarks of their respective manufacturers.

System Requirements The system requirements for each software tool are listed in the manual for that product.

Note that Linux versions of the software require that Motif be installed. More information can be found in Chapter 3.

2 • Preface RSoft Installation Guide

Chapter 1: Before Installing

This chapter explains basic information that is required before installation. Please read through this chapter before installing the software.

1.A. Installation Steps The installation process can be broken down into the following steps:

• Gathering necessary installation materials.

• Installing the software on your computer.

• Backing up the example files.

These steps will be discussed in more detail in the following chapters.

1.B. Installation Notes Please keep the following notes in mind before starting to install the software:

• Please do not connect the USB key to your computer until the installation routine is complete if installing under Windows.

• The installation instructions for Windows versions can be found in Chapter 2; instructions for Linux can be found in Chapter 3.

• A license file that corresponds to the serial number of the hardlock key is required to run the software. Obtaining a license file is as follows:

New Installations – RSoft will send the user on record a license file via e-mail. If you have not received a license file, please contact RSoft at license@rsoftdesign.com with your name, organization, and serial number(s).

Upgrades – If you are upgrading to a new major release of the software, you will need a new license file.

A major update is denoted by a change in the first two version numbers. Upgrading from 5.0 to 5.1 would require a new license file; upgrading from 5.0.1 to 5.0.2 would not. If you need a license file, please contact RSoft at license@rsoftdesign.com with your name, organization, and serial number(s) if a new license file is required.

Only users who have a current maintenance contract with RSoft are entitled to free product upgrades. This includes access to the RSoft support webpage, as well as new license files as required. If you do not have a maintenance contract with RSoft, do not attempt to upgrade as your current version will not be archived resulting in a loss of data. Please contact RSoft with any questions.

RSoft Installation Guide Chapter 1: Before Installing • 3

• A new directory structure was introduced with RSoft CAD 5.0g, OptSim 4.0, and LaserMOD 2.0. If you are upgrading from a previous version, you will have to uninstall before installing the new version. Please see the notes in Chapter 6 before installing the new version.

• When upgrading, though not required, it recommended that you backup the existing RSoft installation directory in order to avoid data loss during the upgrade process.

• When upgrading, though you may be able to install newer version over the existing version, we recommend that you first uninstall the old version and then perform a clean install of the new version. Instructions for this can be found in Chapter 6.

4 • Chapter 1: Before Installing RSoft Installation Guide

Chapter 2: Installation for Windows Platforms

This chapter describes the procedures for installing RSoft software packages, including the RSoft CAD Environment, BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD, FemSIM, LaserMOD, OptSim, and ModeSYS on a Windows 2000/XP computer system. Please consult the appropriate product manual for any additional instructions.

The installation program will step you through the install process, and will attempt to do the following:

• Install the main program

• Install the hardlock key driver and license file

• Add the installation directory to the path and make any registry entries as needed.

If any of the above procedures fail, an error message will be produced. If this happens, please read through the troubleshooting guide in Chapter 5.

2.A. Getting Ready To Install For a Windows installation, you should have the following items accessible before continuing:

• Installation Executable – You can obtain the installation executable from either the installation CD included with the software package you received, or from RSoft’s support page located at www.rsoftdesign.com/support. If you are installing both device and system simulation packages, you will most likely have two separate installation executables. The setup procedure is the same for both packages.

• A Hardlock Key – You will receive a USB hardlock key with the software package you received.

• A License File – The license file corresponds to the serial number of the hardlock key and is licensed for the version(s) of the software that you are licensed to use. If you have not received a valid license file, read through the pertinent notes in Section 1.B before installing.

2.B. Installing the Package under Windows Note that you must be logged in as administrator to proceed with the installation. If upgrading, it is also recommended that you backup the RSoft installation directory to prevent the loss of data.

To install the package, place the distribution CD in your CD-ROM. Next, choose Run from the Start Menu and give the command:

x:setup

RSoft Installation Guide Chapter 2: Installation for Windows Platforms • 5

where x is the drive-letter of your CD-ROM. You will be asked several simple questions, and after providing the necessary information, the software will be installed on your system.

Notes: • The program should not be installed in a directory path containing spaces, such as C:\Program

Files\RSoft, since paths and file names with spaces are not recognized. It is recommended that you use the default directory if possible.

• If you are installing multiple installation executables, they should be installed to the same directory (c:\Rsoft\ by default). Please note that the passive device tools (BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD, FemSIM, are all contained in the same installation executable and do not need to be installed separately. All other products will have to be installed separately.

• Please be sure to choose the licensing scheme you have purchased. You can either select it during the installation process to have it installed automatically, of, if you do not have it accessible, you can place it in the licenses\ subdirectory in the installation directory at a later point. If you are installing a network key, you should use the same license file for each client computer.

• Do not connect the USB key to your computer until the installation routine is complete.

• If installing a network license on a client machine, you will be prompted to enter either the IP address or network name of the key server. If you are unsure of this information during the installation process, leave the entry blank and manually set the system environment variable RSLM_SERVER to the IP address or network name at a later time.

• If you have licensed a clustered simulation capability (for FullWAVE for example), you should check the appropriate option to install the included implementation. Additional steps are required to configure the MPI installation; please read through Chapter 4 for more details. OptSim, ModeSYS, and LaserMOD do not support cluster simulation capability.

2.C. Backing up the Examples RSoft software comes with a large set of examples and tutorial files which are used extensively throughout the documentation. Since it is easy to accidentally overwrite these files in the course of experimenting with the tools, we recommend copying the entire Examples directory in the RSoft install directory to another location, perhaps a subdirectory of your own home directory. Then you can perform the exercises and tutorials and retrieve the original versions when necessary. We suggest you do this now.

• Copy the directory c:\RSoft\examples to a suitable location.

2.D. Finishing the Installation Provided that the installation has completed correctly, attach the USB key and restart your computer. The software can now be tested.

Testing a Non-Cluster Installation If the software successfully starts, the installation has been successful. If not, please review the installation instructions in the previous section and the troubleshooting guide in Chapter 5. If an error message similar to “This hardlock key is not licensed for…”, please check that you have replaced any existing key or license file with the one supplied with your RSoft package. Contact RSoft if the problem persists.

If you receive no errors, then you can proceed to Chapter 7.

6 • Chapter 2: Installation for Windows Platforms RSoft Installation Guide

For Passive Device Tool Users: In order to test a BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD and/or FemSIM installation, start the CAD tool:

• Use the Windows Start Menu to open The RSoft CAD.

The RSoft CAD interface should open.

For Active Device Tool Users: In order to test a LaserMOD start the tool::

• Use the Windows Start Menu to open LaserMOD.

The LaserMOD interface should open.

For System Tool Users: In order to test an OptSim and/or ModeSYS installation, start the tool:

• Use the Windows Start Menu to open OptSim.

The OptSim interface should open.

Testing a Cluster Installation Instructions for testing the clustered installation are given in Chapter 4.

RSoft Installation Guide Chapter 2: Installation for Windows Platforms • 7

8 • Chapter 2: Installation for Windows Platforms RSoft Installation Guide

Chapter 3: Installation for Linux Platforms

The installation of RSoft products under Linux involves two stages: extraction of the distribution to the desired location and software installation of the hardlock license device and the license file. Please consult the appropriate product manual for any additional instructions. You will need root access to perform at least some of these steps.

3.A. Getting Ready to Install For both 32-bit and 64-bit Linux installations you should have the following items before continuing with an installation:

• Installation distribution – You can obtain the distribution from either the distribution CD included with the software package you received, or from RSoft’s download page at www.rsoftdesign.com/support.

• A Hardlock Key – You will receive a USB hardlock key with the software package you received.

• A License File – The license file corresponds to the serial number of the hardlock key and is licensed for the version(s) of the software that you are licensed to use. If you have not received a valid license file, read through the pertinent notes in Section 1.B before installing.

• The Linux version of the software requires that the openmotif package be installed. If you do not have this package installed, please contact your network administrator for help with the installation.

3.B. Installing the Package under Linux Installation of the RSoft software and its associated files under Linux is fairly straightforward.

If you are upgrading a previous installation, it is a good idea to back up your old distribution. This can be done by moving /usr/local/rsoft to say /usr/local/rsoft_6.0 before installing the new distribution. That way, if there is a problem with the new license or if you install the new version before receiving the required license update, you will still be able to use the previous version of the software until the problem is resolved.

The Linux version of the program is distributed on a DOS-formatted CD-ROM, and the files must be transferred in binary form to the directory /usr/local.

Installation of the software is accomplished with the following steps:

• Make sure that you have renamed or removed any existing rsoft install directory, such as /usr/local/rsoft.

RSoft Installation Guide Chapter 3: Installation for Linux Platforms • 9

• Copy all the files from any supplied distribution disks (in binary mode) to either /usr/local or to your home directory. At a minimum, the set of files will include the install script install.sh and the main software archive.

• From that directory, type sh install.sh. This shell script installs all the required files in the subdirectory ./rsoft.

• After installing the software, the installation program will remove the archive file from the current directory since it is no longer needed. The user should remove the file install.sh manually.

• If you are installing a FullWAVE cluster, additional steps are required to configure the MPI installation; please read through Chapter 4 for more details.

• To enable the use of more attractive fonts, copy the contents of the file <rsoft_dir>/etc/dotXresources to $HOME/.Xresources and either restart X windows or give the command ‘xrdb –load ~/.Xresources’

Now proceed to the next sections to configure your PATH and install the hardlock key and/or license file.

If, due to your company’s IT policy, you are unable to install to /usr/local, it is possible to install in a different location (referred to as <install_dir>). However, all features (such as FullWAVE clustering) are not guaranteed to function correctly. If this must be done, there are two recommended ways: 1) make a symbolic link in /usr/local to point to the installation directory (issue the command ‘ln –s <install_dir> rsoft’ or 2) set the environment variables RSOFT_PROGRAMPATH and LD_LIBRARY_PATH to the value ‘<install_dir>/bin’.

3.C. Setting up the PATH • Add the executable directory /usr/local/rsoft/bin to your PATH by editing the appropriate file for

your shell (~/.bashrc or ~/.cshrc).

Note that starting with the version RSoft CAD 5.0g, a new directory structure is in use. There are no longer links to RSoft programs inside /usr/local/bin.

3.D. Installing the Licensing Scheme The license file and hardlock key protect RSoft’s intellectual property and are required to run the software.

Linux systems require authentication using both a license file and a hardlock key. The license file is authenticated by the hardlock key, which may be attached directly to the USB port of your computer or located elsewhere on your LAN. If there is a key on your own computer, it may either be a node-locked key for use only at that workstation or a network key that provides access to the software to all computers on your LAN. The particular case that applies to you will have been determined when you arranged your purchase with RSoft.

You should follow the instructions under the heading License file and then choose one of the three possibilities for the hardlock key.

Installation of the hardlock key driver requires root access to the system.

License file • To install the license file, place it in the /usr/local/rsoft/licenses directory. The name of the

license file corresponds to the number on your hardware key, eg. 16840001.dat. Note that the transfer of files should be in binary form, and that the filename(s) should be all lowercase.

10 • Chapter 3: Installation for Linux Platforms RSoft Installation Guide

• If you are using a network key attached to a remote computer, you need to install the license file of that key on your own computer. It should be available in /usr/local/rsoft/licenses on the master machine.

• If you are using a network key, and you are upgrading the installation, remember that you must update the license file on every computer using the network key.

Local hardlock key (node-locked) This section applies if you have a node-locked key that resides on your computer.

The hardlock requires creation of a device node in the /dev directory, and that certain kernel modules are loaded. The device node is created once during the install procedure, but the kernel modules must be loaded any time the software is to be used.

• Move to the directory /usr/local/rsoft/hardlock and ensure that you are logged in as root.

• Type the following command: ./hldinst_usb

This command creates the device node, and loads the required kernel modules. Check for any error messages regarding loading the modules. If a module matching your kernel exactly can not be found, the script attempts to load a module for a similar kernel. This is usually successful but will generate warnings.

• In order that the required kernel modules are always loaded when you turn on the computer, this command needs to be appended to a suitable startup script. If you plan on using the script /etc/rc.d/rc.local, this can automatically be appended using the script setup_usb.

If you need to use another startup file, manually append the following command to suitable file from your distribution’s startup sequence: /usr/local/rsoft/hardlock/hldinst_usb

Local hardlock key (network key) This section applies if you have a networked key that resides on your computer.

Installation of the network key is similar to the node-locked key, but also requires activation of a daemon process to handle requests from other clients on the network.

• Carry out all the procedures in the previous section for a node-locked key to install the key driver.

• Move to the directory /usr/local/rsoft/bin and type the command rslmd &

• In order that the server alway runs, append the line /usr/local/rsoft/bin/rslmd &

to a suitable file from your distribution’s startup sequence, such as /etc/rc.d/rc.local. Make sure that this line follows the call to hldinst_usb in the same file.

• Each user should have the variable RSLM_SERVER set to localhost.

Remote network key This section applies if there is networked key that resides elsewhere on your network.

RSoft Installation Guide Chapter 3: Installation for Linux Platforms • 11

• First, ensure that the network key has been successfully setup on the network key host computer according to the previous section and that the software runs on that computer. You may need to check with your system administrator that this is the case.

• Copy the license file of the network key to your own computer and place it in the directory /usr/local/rsoft/licenses.

• Obtain the IP address of the network key server.

• In a suitable login file for your shell (~/.bash_profile or ~/.cshrc), define the variable RSLM_SERVER to the IP address of the key server. For instance: bash: export RSLM_SERVER=192.168.1.1 csh: setenv RSLM_SERVER 192.168.1.1 You must ensure that this variable is defined any time you wish to use the software.

Please contact RSoft with any problems.

3.E. Backing up the Examples RSoft software comes with a large set of examples and tutorial files which we use extensively throughout the documentation. These examples should be copied to a suitable subdirectory in the user’s home directory for two reasons:

• Since it is easy to accidentally overwrite these files in the course of experimenting with the tools, we recommend copying the entire Examples directory in the RSoft install directory to another location, perhaps a subdirectory of your own home directory. Then you can perform the exercises and tutorials and retrieve the original versions when necessary.

• The program will not run the examples from a directory in which the user does not have write access. The default installation directory (/usr/local/rsoft/examples/) does not usually have non-root write access, and so users will be unable to run the files from this location.

Please copy the example files now to avoid complications later.

3.F. Environment variables These variables can be defined in order to set several program defaults:

• RSOFT_EDITOR This variables determines the text editor used to view certain text files produced by RSoft programs. Depending on your environment, suitable values might be “gedit” (Gnome), “kedit” (KDE), or “xterm -geometry 120x20 -e vi” (generic desktop).

• RSOFT_BROWSER For displaying online documentation, The RSoft CAD attempts to identify the most suitable HTML browser for your particular setup. You can override its selection by defining this variable to your preference. Suitable values might be “galeon” or “epiphany” (Gnome), “konqueror” (KDE) or “mozilla” (generic desktop).

For the Firefox browser, copy the file <rsoft_dir>/etc/myfirefox.sh into $HOME/bin and set this variable to $HOME/myfirefox.sh to open the documentation correctly and in a new tab in an open browser if available.

12 • Chapter 3: Installation for Linux Platforms RSoft Installation Guide

3.G. Finishing the Installation Provided that the installation has completed correctly, restart your computer and test the installation.

Testing a Non-Cluster Installation If the software successfully starts, the installation has been successful. If not, please review the installation instructions in the previous section and contact RSoft if the problem persists. If an error message similar to “This hardlock key is not licensed for…”, please check that you have replaced any existing key or license file with the one supplied with your RSoft package.

If you receive no errors, then you can proceed to Chapter 7.

For Passive Device Tool Users: In order to test a BeamPROP, FullWAVE, BandSOLVE, GratingMOD, DiffractMOD, and/or FemSIM installation, start the CAD tool.

• Enter xbcad at a command prompt.

The RSoft CAD interface should open.

For Active Device Tool Users: In order to test a LaserMOD installation, start the CAD tool.

• Enter xlasermod at a command prompt.

The RSoft CAD interface should open.

For System Tool Users In order to test a OptSim and/or ModeSYS installation, start the tool:

• Enter xOptSim at a command prompt.

The OptSim interface should open.

Testing a Cluster Installation Instructions for testing the clustered installation are given in Chapter 4.

RSoft Installation Guide Chapter 3: Installation for Linux Platforms • 13

Chapter 4: MPI Installation for Clustered Simulation

RSoft only supports a customized version of the MPICH2 implementation of MPI from Argonne National Lab (Copyright 2002 Argonne National Lab), and the necessary components are automatically installed on your computer if you selected the appropriate option during installation. The complete distribution and further information regarding MPICH2 can be found at www.mcs.anl.gov/mpi/mpich2/.

This section outlines the necessary configuration steps in order to use MPICH2.

Please note that clustered simulations are licensed separately. Please contact RSoft for more information. OptSim, ModeSYS, and LaserMOD do not support cluster simulation capability.

In order to configure the MPI installation, several steps must be performed, as well as several conditions met. First, the software should be installed and tested on each computer, and then the actual clustering ability can be tested.

Step 1: Installing the Software on Each Node On every computer to be involved in a cluster simulation, the software must be installed as described in the previous chapters. For windows installations, be sure to choose the ‘Install MPI’ option during the installation to start the MPI process (smpd.exe). This process can alternatively be started via the command ‘smpd –install’ if the option was not checked. Linux clusters do not require any additional steps.

Step 2: Testing Each Node as a Standalone Simulator The installation on each computer should be tested in a standalone configuration. To test the installations:

• Testing a FullWAVE cluster nodes:

To test a FullWAVE cluster node, open a command prompt on the node, move to the <rsoft_dir>\examples\FullWAVE directory, and issue the following command:

fwmpirun –np1 –hosts localhost –show1 wg.ind

This command indicates that a clustered simulation of the file WG.IND should be performed on the local machine with one process. A FullWAVE window should open showing a “normal” simulation of a simple waveguide.

Next, issue this command to use two processes on the local machine: fwmpirun –np2 –hosts localhost –show1 wg.ind

RSoft Installation Guide Chapter 4: MPI Installation for Clustered Simulation • 15

A FullWAVE window should open that shows half of the simulation domain seen before. If this appears correctly, then MPICH has been installed correctly.

• Testing all other simulation engines:

Other simulation engines can be tested through the GUI be opening the CAD interface. Instructions for this can be found in the previous chapters.

Step 3: Ensuring Network Connectivity In order for a cluster to function, the master node must be able to access other nodes to start remote processes and access and store data. Additionally, a shared directory must be created which all the machines can access. The instructions for this are different for Windows and Linux machines:

Windows Clusters: To ensure network connectivity under Windows, follow these steps:

• Configuring a Firewall

Since clustered simulations need to access other computers, ensure that any firewall installed on the cluster has been configured to allow MPICH2 network traffic to pass through it.

• Running mpiexec

MPICH must have access to the username and password of a user account on the computers in the cluster so that it can log in and start remote simulation processes. The account used should be created on each node if the computers are part of a Windows workgroup, or created on the domain controller if the computers are part of a Windows domain.

To enable access, run the mpiexec utility on the master node by issuing the following command at a command prompt (if the PATH is set up correctly, then this command can be run from any directory. the executable is located in c:\rsoft\bin):

mpiexec -register

Enter the username and password to be used and choose to make the action persistent. Accounts with the name ‘administrator’ or blank passwords will not work.

To check whether this user is authorized to remotely login from the master node to a specific cluster node, issue the following command from the master node:

mpiexec –validate –host cluster_node

where cluster_node is the name of a specific node computer. This test should be repeated for each node computer in the cluster.

• Creating a shared workspace

The working directory where simulation files are stored must be a directory that is accessible to all machines. Additionally, this directory must be able to be accessed via the same name from each machine.

There are two basic ways to achieve this:

1) On the master node, open design files via their UNC path on the master node. For example, if a design file wg.ind is located in the local directory c:\tmp on a computer named master_node, and this directory is shared on the network with the name cluster_sims, then opening the file on the master node form the location ‘//master_node/cluster_sims’ will work since all the other nodes can access the design file by this path.

2) Create a shared drive to the shared directory, such as Z:, on each computer and run all simulations from within this mapped drive on the master node. For exampe, if the local drive c:\tmp on the master node is

16 • Chapter 4: MPI Installation for Clustered Simulation RSoft Installation Guide

shared on the network and mapped as Z: on all the nodes, then opening the file from the mapped drive (Z:) on the master node and running a simulation will work since all nodes can access the design file by this path.

Both of the above scenarios assume that all cluster nodes can read and write from the shared directory.

Linux Clusters: To ensure network connectivity under Linux, follow these steps:

• Configuring a Firewall

Since clustered simulations need to access other computers, ensure that any firewall installed on the cluster has been configured to allow MPICH2 network traffic to pass through it.

• Enabling ssh

You must enable ssh to remotely access computers involved in a cluster simulation. You should ask your system administrator if these steps are necessary as some machines might already have ssh enabled. To enable ssh, follow these steps:

Add the following line to your standard shell initialization file (~/.cshrc or ~/.bashrc) export P4_RSHCOMMAND=ssh

Assuming that the cluster has a shared directory structure and that your home directory is the same when you log into any node, issue the following command from your home directory:

ssh-keygen -t dsa

Accept all the defaults (including the empty passphrase), and this will create special files in ~/.ssh Then issue the commands

cd ~/.ssh

cp id_dsa.pub authorized_keys2

This will allow you to ssh from one node to another without a password. You should test this to make sure that it is working properly by issuing the following command twice from the master node:

ssh cluster_node_name

The first time you try each node you will get a question about the authenticity of the host, and you should type yes to continue. After that, you will not be asked again. This should be repeated for each cluster node.

Note that if all processes will be run on the local host, ssh is not needed to start jobs. To disable the use of ssh for this case, set the variable P4_RSHCOMMAND=rshlocal.

• Creating a shared workspace

The working directory where simulation files are stored and run must be a shared directory that is accessible to all machines. All simulations should then be run from within this directory. This is most easily done by accessing all design files and running all simulations with UNC paths.

• Environment variables

In order for the remote shells created by ssh to function correctly, they require any variables defined locally to be set in the new shell. Since ssh only uses the standard shell initialization files (~/.cshrc or ~/.bashrc), make sure that any environment variables used for RSoft software or MPICH are defined in these files and not login files.

• X11 Forwarding

For FullWAVE simulation windows to appear, you must enable X11 forwarding in the ssh configuration file (ssh_config) which is normally located in /etc/ssh/.

RSoft Installation Guide Chapter 4: MPI Installation for Clustered Simulation • 17

• Older RedHat version compatibility

If running RedHat 7.3 or earlier, the RSPROC_METHOD = 1 variable must be set.

• MPICH documentation:

MPICH documentation can be found here:

http://www-unix.mcs.anl.gov/mpi/mpich/docs/mpichman-chp4/node128.htm

Step 4: Testing the Cluster Once each individual computer has been tested and is functioning correctly, the cluster can be tested:

FullWAVE cluster users: The easiest way to test a FullWAVE cluster is via the command line. Open a command prompt on the master node and move to the shared mapped directory described in the previous section. Copy the file <rsoft_dir>\examples\FullWAVE\wg.ind to this directory for testing purposes. Issue the following command:

fwmpirun –np2 –hosts master_node_name cluster_node_name –show1 wg.ind

where master_node_name and cluster_node_name are the machine names for the master and cluster nodes respectively. If everything has been set up correctly, a simulation window will open showing half of the simulation domain. Check the rest of the cluster nodes to ensure that they have been set up correctly as well.

MOST cluster users: Instructions for testing a MOST clustering setup can be found in the MOST manual.

18 • Chapter 4: MPI Installation for Clustered Simulation RSoft Installation Guide

Chapter 5: Installation Troubleshooting

This section contains some common problems that can be encountered during installation for both Windows and Linux platforms.

5.A. Windows Installation Trouble-Shooting If you have problems running the program after installation, the difficulty is usually related to one of the following areas.

Directory/PATH Issues • Ensure that the program is not installed in a directory containing spaces such as c:\Program

Files\RSoft. If so, reinstall as directed.

• Ensure that the \bin subdirectory in the installation directory (C:\RSoft\bin by default) is in the PATH, and that the computer has been rebooted after installation so that this new PATH takes effect. The installation program normally accomplishes this step, but in rare instances it does not. To test that the program is in the PATH, open a DOS or Command Prompt, and type the command bcadw32 for device tools or ‘JStart.exe -hide optsim40.bat JET &’ for system tools. If the program is not recognized at all, you should contact your system administrator to assist you in putting the program in the PATH. Otherwise, contact RSoft.

• If this installation is an upgrade to versions prior to RSoft CAD 5.0g or OptSim 4.0 note that the installation directory structure has changed, and so the old installation directory (c:\BeamPROP or c:\LinkSIM by default) should be removed from the path and the new installation directory (C:\RSoft\bin\ by default) should be added to the PATH. If logged in with administrative rights, this process is automatically done by the installation program. If it is not done, please contact your System Administrator to perform this task for you.

License File Issues If you receive an error message that states that the license file you are using is not licensed for an RSoft product that you own, there are three common problems:

• If you are installing RSoft software for the first time, please make sure that you have placed the license file that you will receive from RSoft in the \licenses subdirectory in the installation directory.

RSoft Installation Guide Chapter 5: Installation Troubleshooting • 19

• If you are upgrading to a new major release of the software, you will receive this message. If you are under a maintenance contract with RSoft, please contact RSoft to obtain a new license file. If you are not under a maintenance contract with RSoft, please contact RSoft for information about purchasing maintenance.

• If this problem persists even with a new license file from RSoft, the cause is usually the presence of the environment variable RSOFT_LICENSEPATH that was sometimes used to set the location of the license file by previous versions of the software. This variable is now unnecessary and should be removed from the environment. On older installations, note this variable is sometimes defined in the file autoexec.bat (even under NT-based Windows systems). If this is the case, the variable declaration should be removed from this file, and the computer restarted.

Hardware Key Issues There are two possible problems in this class. Either the driver is not recognized, or the driver is recognized but the key is not detected. The error message produced by the program will usually indicate which case has occurred.

• If you are using a network license, make sure you have set the RSLM_SERVER variable in the environment as documented elsewhere in this installation guide.

• If the driver is not found, the problem is usually that the driver has not been installed. Follow the instructions below to manually install the driver. If there are still problems, contact RSoft.

In the event that the installation routine does not correctly install the hardlock drivers, the following steps should be performed.

These procedures require administrative rights.

Installing a Local Hardlock Key (Node-Locked) Issue the following series of commands at a command prompt while logged on as Administrator:

c:

cd \rsoft\hardlock

haspdinst –install

If the software was installed in a different drive or directory, replace c: and \rsoft\hardlock with the appropriate locations. The above should produce messages indicating successful installation and running of the driver. You can safely ignore any messages relating to PCMCIA, as this type of key is not used. If the drivers are not successfully installed, contact RSoft.

To install the hardware key, simply insert it into your computers USB port.

If older versions of RSoft software were previously installed on your system, you may need to uninstall the old driver for the hardware key before installing the new one. To do this, give the command “hldinst –remove“ to remove the old driver, followed by the above command to install the new driver.

Installing a Network Hardlock Key (Floating License) If you have purchased a network license from RSoft, you need to perform these steps in order to install the RSoft License Server (rslmd). The instructions are different for the server and client computers.

For the Server: On the computer that will act as the key server, first install the standard hardlock key driver as described above. Then open a command prompt and run the commands

c:

cd c:\rsoft\bin

20 • Chapter 5: Installation Troubleshooting RSoft Installation Guide

rslmd -install

This will install the network key server that will allow other machines to access the network key. Each user account on the server should have the variable RSLM_SERVER set to localhost.

For Client Computers on the Network: While not strictly necessary on the client, it is recommended that you install the rslmd program on each client as described in the server installation above. This will provide the ability for the system to detect and correct for programs that have not terminated normally, and prevent them from occupying a license.

On each machine that is to use the software set the RSLM_SERVER environment variable to the IP address of the hardware key server. This tells the software where to find the network key.

To set this environment variable, right click on My Computer, select Properties, and go to the Advanced tab and set the variable under System Variables.

NAME = RSLM_SERVER

VALUE = <IP address of machine with network key>

After performing the above, the software should be able to run from any machine on the network that has been properly set up. Each copy of the software that is run will use up one license. When the maximum number of licenses has been used up, the software will give and error message and fail to run until another user frees a license by closing their copy of the program.

5.B. Unix/Linux Installation Trouble-Shooting This section contains some common problems that can be encountered during installation.

Linux Hardlock Protection Key There are two possible problems in this class. Either the driver is not recognized, or the driver is recognized but the key is not detected. The error message produced by the program will usually indicate which case has occurred.

• If you are using a network license, make sure you have set the RSLM_SERVER variable in the environment as documented elsewhere in this installation guide.

• If the driver is not found, the problem is usually that the driver has not been installed. Follow the instructions to manually install the driver. If there are still problems, contact RSoft.

Linux License File Issues If you receive an error message that states that the license file you are using is not licensed for an RSoft product that you own, there are three common problems:

• If you are installing RSoft software for the first time, please make sure that you have placed the license file that you will receive from RSoft in the /licenses subdirectory in the installation directory.

• If you are upgrading to a new major release of the software, you will receive this message. If you are under a maintenance contract with RSoft, please contact RSoft to obtain a new license file. If you are not under a maintenance contract with RSoft, please contact RSoft for information about purchasing maintenance.

DOS format *.ind files The Windows, UNIX, and Linux ports of RSoft software are functionally identical and input files can be interchanged freely between the platforms. However, input ASCII files transferred from Windows to UNIX/Linux or vice versa should usually be converted to the native format of the new platform. This is easily achieved using the programs

RSoft Installation Guide Chapter 5: Installation Troubleshooting • 21

dos2unix and unix2dos which are widely available on the Internet if they are not included with your distribution. Failing to convert input files in this way may result in a program error.

Missing Shared Libraries RSoft products rely on the presence of a number of shared libraries. In most cases, these libraries are included on Linux systems by default. The C++ standard library, however, may cause problems since different distributions include difference versions of the library and there is no consistent naming of the library. The symptom of such a problem is that on starting the program, it halts immediately, reporting a message about a missing library. This problem can be fixed in one of several ways.

• In some cases, missing libraries can be obtained by installing the latest package from RedHat.

• For very old versions of the operating system, it may not be possible to install the required libraries because of incompatibilities built into the operating system. In this case, it would be necessary to upgrade the operating system to a version supported by RSoft software. Please note that RSoft reserves the right to change discontinue support for old versions periodically.

Write Access In order to run the examples included with the program, the user needs to have write access to the directory where the examples are stored. The default directory (/usr/local/rsoft/examples/) does not usually allow non-root write access by default, and so it is important to copy these examples to the user’s home directory. If this is not done, the program will be unable to run these examples.

22 • Chapter 5: Installation Troubleshooting RSoft Installation Guide

Chapter 6: Uninstalling the Package

Should you choose to uninstall the RSoft software, please follow these instructions.

Users who are upgrading from a version prior to RSoft CAD 5.0g, OptSIM 4.0, and LaserMOD 2.0 will need to remove the version from their machines as described below.

6.A. RSoft CAD 5.0g, OptSim 4.0, and LaserMOD 2.0 and Later To uninstall the software, do the following:

Windows: To uninstall the package under Windows, use the Add/Remove Programs option in the Control Panel. Note that you must be logged in as administrator to perform this task.

UNIX/Linux To uninstall the package under UNIX/Linux, simply delete the program directory. Additionally, you will have to remove any commands from your startup scripts related to the package.

Uninstalling the Hardlock Drivers To uninstall the hardlock key drivers on Windows, issue the command ‘haspdinst –remove’ from the <rsoft_dir>\hardlock directory. Note that for older versions of the driver, this may not work, and so the command ‘haspdinst –fremove’ can be tried. If this does not work, then try the command ‘hldinst –remove’.

6.B. Versions earlier than RSoft CAD 5.0g, OptSim 4.0, and LaserMOD 2.0 These versions use an old directory structure. This version includes, among other things, a new installation procedure, directory structure, and device drivers that are sufficiently different from prior versions that it is required that you uninstall the old program and remove prior drivers, environment variables, PATH settings, etc. The procedure to do this

RSoft Installation Guide Chapter 6: Uninstalling the Package • 23

is described here. For almost all procedures you should be logged on as Administrator (or root under UNIX). The exception is when performing an action for an individual user.

First, close any running programs, backup any license files, and backup and rename the old installation directory (usually C:\BEAMPROP, c:\LINKSIM, or c:\LaserMOD on Windows, /usr/local/beamprop on UNIX). Then, depending on the platform, perform the following:

Windows: • Remove the old hardware key driver by going to a command prompt (under Start/Programs/Accessories),

changing to the old installation directory using the "cd" command, and typing "hldinst -remove" or "hlinst -d". If you are running a network key server, you should first stop and remove the server by typing "hls32svc -remove".

• Remove any environment variables for RSoft products that you may have set (e.g. RSOFT_LICENSEPATH, HLS_IPADDR). Environment variables, including the PATH, are found by going to the Control Panel, choosing System, selecting the Advanced tab, and clicking on Environment Variables.

• Remove all PATH settings for both the System PATH and any user PATH's that refer to the old installation directory.

Linux: • Remove any lines in rc.local or other startup scripts that started the hardware key driver, and reboot the

computer.

• Remove any environment variables for RSoft products that you may have set (e.g. RSOFT_LICENSEPATH, HLS_IPADDR).

• You do not need to adjust any PATH settings at this point. Note that links in /usr/local/bin will be broken after renaming the old installation directory. During installation, you will be asked to run a script to remove them.

24 • Chapter 6: Uninstalling the Package RSoft Installation Guide

Chapter 7: What Next?

At this point, you are ready to begin using the software.

7.A. Product Manuals & README File Each software product includes a comprehensive manual that describes the program usage. The file readme.txt, which is located in the readme subfolder in the installation directory, should be read. This file may be viewed in any text editor, such as Windows Notepad. The README file provides important last minute program information that is not contained in the manuals, including new or improved features and options.

7.B. Directory Structure The installation directory structure beneath /rsoft is as follows:

• bin All executable programs

• docs Online documentation in printable PDF format.

• etc Administrative settings

• examples All examples and tutorials divided by tool.

• help Online documentation in HTML format.

• licenses Location for installing license files.

• mpi Executables and other files for the mpich implementation of the MPI protocol.

• products Miscellaneous data files maintained by individual tools.

• readme Readme text files containing recent information and corrections to the manuals.

• RPLOTDIR Miscellaneous files required for the xplot/WinPLOT plotting tool.

RSoft Installation Guide Chapter 7: What Next? • 25

• uninstall Executable to uninstall the program.

7.C. Technical Support & Software Upgrades Finally, the RSoft software comes with one year of maintenance, including technical support and product updates. Updates are released on our web site www.rsoftdesign.com/support every one to three months, and include program corrections as well as new features. To access updates, you must contact RSoft after receiving the software to obtain a username and password. Information regarding each update is located in the README file, which can be accessed on the website to determine if you need or want to upgrade, and should be read thoroughly after downloading and installing any update. If you have any questions regarding your maintenance contract, or to renew your maintenance, please contact RSoft.

26 • Chapter 7: What Next? RSoft Installation Guide

RSoft Installation Guide Chapter 7: What Next? • 27

28 • Chapter 7: What Next? RSoft Installation Guide