Documentation

3. Installation

This part of the manual describes the setup process of PI-DSMC. Administrator privileges are required to perform the installation. If you do not have administrator privileges, please contact your system administrator.

In order to install PI-DSMC, simply extract the archive containing the program files and copy them to a directory of your choice. It might be useful to add that directory to the PATH environment variable.


3.1 License server

First of all, the demo version does not require a license server nor a usb dongle.

The license server (DinkeyServer64) is a separate application. The license server is required for license management. The license server must be running before and during the execution of PI-DSMC. Otherwise, PI-DSMC will not start.

The license server can be executed as an application or as a service. In order to run the license server, the kernel must support USB. The kernel version must be 2.4.0 or higher. If USB is not enabled in your current kernel you have to rebuild the kernel. The license server must be restarted after the machine was rebooted. Before starting the license server the USB dongle must be connected to the computer. The dongle must not be removed while the license server is running.

There are two possible configurations for the setup of the license server: First, the license server can be running on the same computer that will be executing the PI DSMC programs. Second, the license server can be running on another machine that is connected to the computer performing the calculations via network. The PI-DSMC programs will detect the server if the server is running and if the network is configured correctly. See the chapter "Network configuration" for more details.

In order for the license server and the dongle to work correctly, please execute the script "inst.sh" before attaching the dongle to the machine.

A Windows version of the license server (DinkeyServer.exe) is provided for convenience.


Start / Stop license server

To see whether the license server is running (application of service) type:
"ps -A | grep DinkeyServer64"

To terminate any running instance of the license server type:
"DinkeyServer64 -t"

To start the license server type:
"DinkeyServer64"

You will be asked whether the license server should run as an active application or as a service in the background. After that you will be asked for the network interface to listen on and a port number.

If you chose to run the license server as an application, a status window will show up. If you choose to run as a service, the status window can be shown by executing "DinkeyServer64 --viewer".


Error codes

The programs that use the license server will generate error codes and error message if a problem is encountered. Some common error codes are listed below

422
The license has expired.

435
The program was not able to communicate with the license server. This error occurs if the license server is not running or if the communication is blocked by a firewall. The following actions might solve the problem:

  1. If the server is not running, please start the server.

  2. If the server is running already restart the server.

  3. Try another interface in the license server start menu.

  4. Make sure the firewall is not blocking traffic to the selected port. Disable the firewall for testing.

  5. Run the license server on the same machine as the PI-DSMC programs.


441
This error means that the license server is busy. If this error occurs for a few parallel instances, there is a problem with the machine running the license server. The license server should not run on a machine that is running any other USB licensing software or hardware.

"failed to check for an existing instance of DinkeyServer64"
DinkeyServer64 uses a file (/tmp/dinkeyserver64_LOCK) to indicate that the server is running. Remove this file to fix the error.

In order to test if the PI-DSMC programs can communicate with the license server type:
"PIDS2geo"
If the server is running and the network is configured correctly, the program will complain that no configuration file was specified. Everything is fine in this case. If something is wrong, the program will display an error code.



3.2 Network configuration

The dongle system uses multicast broadcast messages. The network must be configured so that each machine that runs PI-DSMC can communicate with the machine that runs the license sever. If a firewall is installed, traffic to the port that the license server is listening on must be allowed. The port is selected during the execution of the license server. The license server uses the TCP/IP and UDP network protocols.

To add a route for multicast broadcast type as root:
"route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0"
where eth0 should be replaced by the interface that connects to your network.



3.3 MPI and NFS

A working MPICH2 installation is required to run PI-DSMC, unless you are using the demo version. You can test if you have a working MPICH2 installation by entering the following commands:
"mpiexec -n 10 hostname"

This command will list the hostnames of the machines that execute the hostname command. If the command cannot be found, you have no working MPICH2 installation and you need to proceed with the installation of MPI. Please consult your system administrator.

The directory that is used to store the data files for a simulation must be accessible from every machine that executes an instance of PI-DSMC. If there is no such directory, please consult your system administrator.



3.4 Shared memory

PI-DSMC has uses shared memory. The maximum size of a shared memory object is controlled via the file /proc/sys/kernel/shmmax. If the size specified in this file is too small, PI-DSMC will abort while loading the restart files. In this case, the size must be increased.



3.5 Netgen library

The 3D part of PI-DSMC relies on the Netgen library (libnglib.so). It is possible that the binary version of libnglib supplied with PI-DSMC is not compatible with the system. In that case the library needs to be rebuilt.

  1. Install the packages tk-dev and tcl-dev

  2. Extract the file netgen-4.9.13.zip

  3. Run "./configure"
    it might be necessary to define the paths to the tcl and tk configuration file:
    "./configure --with-tcl=/usr/lib64/ --with-tk=/usr/lib64/"

  4. Run "make"
    The build process might abort with error messages but it seems to be no problem. The library was not built yet.
    change to directory nglib and run make
    change to directory .libs

  5. Copy the library into the PI-DSMC installation folder.



3.6 License update

The license is stored on the USB dongle. The license can be updated remotely without exchanging the dongle. A program called DinkeyChange is used to update the license and the required file is sent by email. To update the license, please follow the procedure below:

  1. Copy the license file (e.g. update.ducf) to the computer where PI-DSMC is installed.

  2. Attach the USB dongle to the computer.

  3. Execute DinkeyChange by typing:
    "DinkeyChange update.ducf"

    DinkeyChange will display a four digit confirmation code. Please, send this code to technical support for documentation.

To display the dongle number and the update number type:
"DinkeyChange -i"



3.7 32-bit libraries for PIDSMCconfig

PIDSMC runs on 64-bit systems only. However, PIDSMCconfig is still a 32-bit application which requires a few 32-bit libraries. These libraries have to be installed if they are not present. The commands below work under Ubuntu 16.04 LTS.

  1. sudo dpkg --add-architecture i386

  2. sudo apt-get update

  3. sudo apt-get install libc6:i386 libstdc++6:i386

    PIDSMCconfig will now be recognized as an executable so that "ldd ./PIDSMCconfig" will tell what libraries are missing.

  4. sudo apt-get install libcairo2:i386 libpango-1.0-0:i386 libpangocairo-1.0-0:i386

  5. sudo apt-get install libgtk2.0-0:i386 libgl1-mesa-glx:i386