Professional Documents
Culture Documents
Install
Install
Install
RSoft Design Group, Inc. 400 Executive Blvd. Suite 100 Ossining, NY 10562 Phone: 19149232164 Fax: 19149232169 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
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
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
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
Contents iii
Step 4: Testing the Cluster...................................................................................................... 18 FullWAVE cluster users:............................................................................................ 18 MOST cluster users:................................................................................................... 18
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
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
25
7.A. Product Manuals & README File ................................................................................. 25 7.B. Directory Structure........................................................................................................... 25 7.C. Technical Support & Software Upgrades......................................................................... 26
iv Contents
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.
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 Consortiums 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) programs 12 channel 120 Gbps optical communication switch.
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
This chapter explains basic information that is required before installation. Please read through this chapter before installing the software.
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.
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.
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.
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.
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 companys 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.
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.
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.
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.
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 distributions startup sequence:
/usr/local/rsoft/hardlock/hldinst_usb
to a suitable file from your distributions 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.
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.
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.
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.
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
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.
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
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/.
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
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.
This section contains some common problems that can be encountered during installation for both Windows and Linux platforms.
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.
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.
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.
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.
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.
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.
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.
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 users home directory. If this is not done, the program will be unable to run these examples.
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.
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
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.
Administrative settings
examples
Executables and other files for the mpich implementation of the MPI protocol.
products
Readme text files containing recent information and corrections to the manuals.
RPLOTDIR
uninstall