This webpage contains instructions for getting CONVERGE and CONVERGE Studio up and running. The information on this page is for versions 2.2, 2.3, and 2.4.
Table 1: Operating systems compatible with CONVERGE and CONVERGE Studio.
Hardware & Software
CONVERGE supports any hardware architecture that uses the x86-64 instruction set. Contact the Convergent Science Applications team ([email protected]) to discuss processor selection. We recommend OpenGL-compatible video drivers (3.3+) to run CONVERGE Studio.
Table 2 below lists the MPI (Message Passaging Interface) support packages that can be used to execute the solver in parallel.
Table 2: CONVERGE and MPI support package compatibility.
The sections below describe the installation process for both CONVERGE and CONVERGE Studio in Windows and Linux. These instructions are applicable to 2.2, 2.3, and 2.4. Note that the directions for installing versions 2.3 and 2.4 are identical. CONVERGE is licensed software that requires either a node-locked license or a floating license. A node-locked license allows you to run CONVERGE on a single machine. A floating license allows CONVERGE to run on any machine on a network. A floating license limits the number of CONVERGE simulations that can run concurrently. The system-specific installation instructions contain detailed licensing information.
You can download a CONVERGE Studio installation package from the Convergent Science hub (https://hub.convergecfd.com/downloads). Note that you must login to this website. The installation file is located in the path /CONVERGE 2.4/<operating system>/Studio, for example,
Files in this path are named according to the convention CONVERGE Studio_<version>_<operating system><architecture>_<release date>.<package type> (for example, a 64-bit Windows version will be labeled CONVERGE Studio 2.4 Win64.msi on the hub and named CONVERGE_Studio_2.4_win64_021819.msi on your operating system). You can select the minor version that you would like to download using the pull down menu on the right.
Table 4 below shows example paths and file names for CONVERGE Studio 2.4. Note that the directions for installing 2.3 are identical to 2.4.
Note that the directions for installing version 2.3 are identical to 2.4, except that you must download the installation file from the /Older Releases/CONVERGE_2.3/<operating system>Studio/directory.
Table 4: File names and installation instructions for CONVERGE Studio.
|Operating System||Installation package||To install|
||Double-click the installation file.|
||While logged in as root, type
Then run the INSTALL script.
1You must save the tar package in a temporary folder. Unpacking the tar package will create a directory with the necessary installation files.
After installation, the executable for CONVERGE Studio will be placed in the directory listed below in Table 5.
Table 5: Default directory in which the CONVERGE Studio executable is placed after installation.
|Platform||Version||Location of executable|
To install CONVERGE on Windows, download the file labeled Converge <version> Setup <architecture>.msi from the Convergent Science hub (https://hub.convergecfd.com/downloads). Use the pull down menu on the right to select the minor version number.
Double-click this file to install CONVERGE. Installing CONVERGE on Windows requires administrative privileges.
The directions for installing CONVERGE 2.3 are identical to the installation for CONVERGE 2.4, except that the installation file is located in the directory /Older Releases/CONVERGE 2.3/<operating system> on the Convergent Science hub.
The Setup Wizard will guide you through the CONVERGE installation steps.
Once you obtain the installation package, the directions for installing CONVERGE 2.3 and 2.4 are identical. If you do not have root access privileges, you can install CONVERGE for a single user. If you are logged in as root, you can install CONVERGE for all users.
To install and run CONVERGE 2.3 or 2.4:
- Download CONVERGE
- Unpack the distribution in the desired folder
- Set up the necessary environmental variables
- Obtain a valid license.lic file
- Start the RLM license server.
Download the appropriate installation file (labeled Converge <version> Setup <architecture>.msi) from the Convergent Science hub (https://hub.convergecfd.com/downloads). Use the pull down menu on the right to select the minor version number. Note that you must login to access this website. The installation file is located in the directory /CONVERGE 2.4/<operating system>, for example,
Note that the installation file for CONVERGE 2.3 is located in the directory /Older Releases/CONVERGE 2.3/<operating system> on the Convergent Science hub.
Unpacking the Distribution
The installation package for CONVERGE is in a gzipped tar file named Converge Install 2.4 on the hub (named converge_install_<version>.tar.gz) that you need to expand. Place the file in a temporary directory. Expand the tar file to create a new directory named Converge Install <version_number>. Note that CONVERGE 2.2 and earlier will also have a six-digit release date in the directory name. Unzip the file and open the archive using the tar utility
tar –xzvf converge_install_2.4.23.tar
The documentation and example cases will be unpacked into a subdirectory of this directory.
The package contains several different executables for CONVERGE. It will be convenient to create a shortcut or a symbolic link named converge that points to the specific executable that is appropriate to your operating system, machine architecture, and Message Passing Interface. With this link in place, you can simply type converge instead of the full executable name.
This step is only required for CONVERGE 2.2 and earlier. If you are installing CONVERGE 2.3 or 2.4, skip this step. Before running the
INSTALL script, ensure that proper permissions are set for the installation. If the
INSTALL script cannot create the necessary directories because the permissions are not correct, it will exit the installation and indicate that there is a problem with permissions.
There are three different components of CONVERGE that are installed separately as part of the
- CONVERGE executables and associated utilities (component 1)
- Documentation and input files for example cases (component 2)
- The license server (component 3).
INSTALL script file is located in the
converge_install_<version_number> directory created when the archive was unpacked. Note that earlier versions will additionally generate a release date in the folder name (i.e.,
converge_install_<version_number+release_date>) . The
INSTALL script is an executable and can be run from the prompt by typing
INSTALL script will guide you through the installation process.
Specifying the Installation Directory
For each component, the
INSTALL script will prompt you for an installation directory. The default installation directory will be shown in brackets (e.g.,
[/opt/converge-<version>]) and simply pressing Enter will select the default directory. Once any of the components are installed, the default installation directory for the remaining components will become the last directory used. Note that you can use the same installation directory for multiple architectures because the
INSTALL script will place any architecture-specific files in machine-specific subdirectories.
If you previously installed CONVERGE and wish to use the same installation directory for the new installation, simply remove the previous installation directory (and all subdirectories and files using
rm -r) or move the previous installation directory to a different location.
The default installation directory is
/opt/converge-2.2.12). This is an appropriate place to install CONVERGE to make it accessible to all users on the machine. If the installation is for a single user, the installation directory can exist as a subdirectory in your home directory. As mentioned earlier, verify that the permissions are appropriate for the type of installation being performed. When entering the directory name for the installation, make sure to use the full path (i.e., the directory name must start with a /).
INSTALL script will prompt you for a base installation directory. All components will be placed in subdirectories within this base directory. The directory tree that will be created is shown in Figure 1.
Figure 1 shows that it is possible to have multiple installation architectures in the same base directory. The binary executables will be in separate
bin directories for each architecture.
doc directory contains the manuals and example cases, all of which are machine-independent. This directory is created when the documentation and tutorials are installed (component 2).
license directory contains the license.lic file, which is an ASCII text file used for license authentication. This file is also architecture-independent. A valid license.lic file is required for both node-locked and floating license installations. An empty placeholder license file will be created as part of the installation of both the CONVERGE executable (component 1) and the license server (component 3).
There are three additional directories created for each architecture:
scripts. The bin and scripts directories are created as part of the CONVERGE installation (component 1). The
bin directory contains the CONVERGE executables and other tools useful for pre- and post-processing. The
scripts directory contains scripting text that can be used for setting up the runtime environment. Later sections will describe the use of these scripts in detail. The
rlm directory is created when the license server is installed. This directory contains the license server and a startup script that can be used to automatically start the license server when the machine boots.
Specifying Machine Architecture
When installing the CONVERGE executables and utilities and the license server, you will be prompted for the machine architecture. The
INSTALL script will, if possible, detect the architecture of the machine from which the script is being run and provide you with this information. Multiple architectures can be installed on the same machine, but these installations cannot occur concurrently. Note that the documentation is machine-independent (*.pdf files). The other components are specific to the desired architecture. Table 6 lists the machine architectures that CONVERGE currently supports, the subdirectory names used for each architecture, and the versions of MPI available for them. Note that MPI is not necessary for running in serial.
Table 6: Supported computer architecture and operating system combinations for CONVERGE 2.2.
|Machine Type||Operating System||Directory Name||MPI Version|
|Intel x86 64 bit (x64, x86-64, Intel64, AMD64).
Note IA-64 is not supported.
|Linux||l_x86_64||pmpi, mpich2, openmpi|
Scripts for Environmental Variables
At the end of the installation procedure for component 1, the
INSTALL script will ask if you want to create scripts to help set environment variables necessary for running CONVERGE. The next section will describe the use of these scripts. If you create scripts, the
INSTALL script creates a subdirectory named scripts within each architecture subdirectory. The scripts created in this step do not do anything by themselves—they are simply tools you can use later to set up environment variables.
Setting Necessary Environment Variables for CONVERGE
First, add the new installation directory to your
PATH variable so that the converge executable and associated tools are included in the search path on the machine by typing
export PATH=$PATH:/<install directory>/<architecture>/bin
For example, for a 64-bit Linux install that used the default installation directory, you would type
Second, if the environment variable
CONVERGE_ROOT is set in your environment, CONVERGE will first look in
$CONVERGE_ROOT/license/license.lic for a valid license.lic file. If this variable is not set, CONVERGE will look for the license.lic file in your present working directory. CONVERGE_ROOT should be set to the install directory. For the case of the default install directory, a valid
CONVERGE_ROOT value would be
If you do not have CONVERGE_ROOT set, then you must have RLM_LICENSE set to ensure proper licensing behavior.
export [email protected]<license server hostname>
See the license server errors section for more information.
Obtaining a valid license.lic file
CONVERGE is licensed software that requires either a node-locked license or a floating license. A node-locked license allows you to run CONVERGE on a single machine. A floating license allows CONVERGE to run on any machine on a network. A floating license limits the number of CONVERGE simulations that can run concurrently. The system-specific installation instructions contain detailed licensing information.
If you installed CONVERGE or the license server, a sample license.lic file was placed in the
license subdirectory of the installation directory. You must replace this file with a valid license file obtained from Convergent Science. To obtain a valid license.lic file, contact [email protected] with the
hostname and the MAC address of the server (for floating licenses) or all the machines (for node-locked licenses) that will run CONVERGE.
hostname is a string, such as DESKTOP-PE7C22J or webdev.jdlocal. MAC addresses are a set of six two-character strings separated by hyphens or colons, for example, 00-50-56-C0-00-01 or 00:0C:29:2D:92:06. Table 3 below explains how to obtain this information. If multiple MAC addresses are available (such as when you have both an ethernet and a WIFI adapter), choose the MAC address associated with an ethernet adapter over a WIFI adapter for a more reliable connection.
Table 3: Obtaining hostname and MAC address for your machine.
|Operating System||Steps to look up hostname||Steps to look up MAC address|
|Windows||Go to the command prompt and type
||Go to the command prompt and type
||The MAC address is the item next to
|Linux||Go to the terminal and type
||Go to the terminal and type
|The terminal will write out the
||The MAC address is the value next to
Starting the License Server
This step is necessary only if you have a floating license. If you have a node-locked license, you can skip this step.
Before CONVERGE will run, it needs to check out a license from the license manager. The license manager runs constantly on a server and listens for requests for licenses from processes on the network. The license manager keeps track of how many licenses are checked out and how many are still available.
The license manager provided with CONVERGE is the Reprise License Manager (RLM) developed by Reprise Software, Inc. For full documentation on RLM, refer to their website at www.reprisesoftware.com.
The main server executable necessary for running the license manager is
rlm. A number of other executable utilities are placed in the
rlm subdirectory. This can be found in the
/<installation_directory>/<architecture>/rlm directory. Start the license manager (in the background) in this directory by typing
When started, RLM will look for any files named *.lic that reside in the same directory. During the install procedure, a soft link to the license.lic file in the license directory was created, so RLM will see the license file. The license.lic file provided by Convergent Science indicates that the vendor-specific settings file named csci.set will also be used to handle the licensing. Once RLM starts and sees the valid license.lic file, it will use the csci.set to launch a second
rlm daemon as well. If you run the
ps command to see what processes are running, you should see two instances of
You can download the csci.set file from the Convergent Science hub (https://hub.convergecfd.com/downloads) Utilities > Licensing directory after logging in.
Running RML Automatically at Bootup
Refer to the RLM User Administration Manual for setting up RLM as a service for your platform.
License Server Errors
Table 7 lists some error codes that you may encounter when launching the client. Columns two and three list the corresponding meaning of each error code and potential solutions. Refer to the RLM license administration manual for further troubleshooting information.
Table 7: Common RLM Error Codes and Solutions.
|-1||Environment not established.||1. Set the
|-17||Failure during connection with the license server.||1. The client license environment is incorrect. Check the
|2. The license server is down. Consult your local IT staff to verify the license server is active.|
|3. A firewall on the client machine, server machine, or somewhere in between blocked the connection. Consult your network administrative staff.|
|-18||The license server is not hosting a license of the requested type.||1. You have to supply the super keyword for superbase licenses.|
|2. Your license is expired.|
|-22||Not enough licenses available to run.||1. Free up some licenses or wait for jobs to complete.|
Workflow for a CONVERGE CFD Simulation
The workflow in CONVERGE consists of three steps:
- Pre-processing (preparing the surface geometry and configuring the input and data files)
- Running the simulation
- Post-processing (analyzing the *.out ASCII files in the Case Directory and using a visualization program to view the information in the post*.out binary files saved in the
We recommend using CONVERGE Studio for pre-processing. The following steps describe how to verify inputs, run the code in serial or parallel, and restart the code.
NOTE: When you install CONVERGE, the default shortcut or symbolic link (named converge) launches the PMPI version of the solver. It will be convenient to reconfigure this shortcut or symbolic link so that it points to the specific executable that is appropriate to your operating system, machine architecture, and Message Passing Interface (MPI). With this link in place, you can simply type converge instead of the full executable name. Many of the instructions for executing CONVERGE described below are given with the assumption that a symbolic link named converge is used in place of the full executable name.
Type the following command to verify the inputs in the pre-processed files without checking out a license from the server:
CONVERGE will exit before starting the main solver. Using the
check_inputs option generates the mech_check.out file after it checks your mechanism data file for errors.
You can run CONVERGE in serial (one core) or in parallel (more than one core). The execution method differs for serial and parallel jobs.
Refer to the CONVERGE UDF Manual for information about executing CONVERGE with user-defined functions.
Running in Serial
To run CONVERGE, open a command prompt or terminal window and change directory (
cd) to the directory containing the input files for the case you wish to run (the Case Directory). Then type the name of the CONVERGE executable at the prompt or the name of the link to the appropriate executable (converge). The executable is named by the following convention:
For example, to run a serial version of CONVERGE 2.4 on a 64-bit machine in Windows, type
Note that the executable for older versions additionally includes the release date and is named by the convention:
converge-<version>-serial-<operating system>-<architecture>-<release date>
In a typical Unix run, you redirect the screen output to a file so it can be stored and examined later (e.g.,
converge > log.out &).
Running in Parallel
To run CONVERGE in parallel, you must start CONVERGE in a manner consistent with the device interconnect and MPI implementation used on the machine.
CONVERGE supports a number of device interconnect protocols (e.g., Intel Omni-Path Architecture, Myrinet, InfiniBand, Ethernet). Note that interconnect compatibility is dependent on the MPI package that you choose to use. For example, Omni-Path Architecture is compatible with openmpi, mpich2, and Intel mpi.
The placement of input and output files is the same as in the serial version.
The standard MSMPI CONVERGE execution is
mpiexec –n <number of processors> converge-<version>-msmpi_windows-<architecture>.exe
Note that for older versions, the executable name has a six-digit release date.
You can launch an MPICH2 job by running the following set of commands from a DOS prompt:
mpiexec –n <number of processors> converge-<version>-mpich2_windows-<architecture>
To start a parallel job with MPICH2, create a file named mpd.hosts that contains the hostnames of all machines on which the parallel job is to be run, with one machine name per line in the file. You can run the
mpdboot utility by logging in to one of the machines on the list, going to the directory with the mpd.hosts file, and typing
mpdboot –n <number of processors>
This will start a process named
mpd on each of the machines listed. This background process will listen for send and receive requests. Verify that
mpd started properly on all machines by typing
This command will list all machines that have the
mpd process running and are available for use in a parallel job.
You can now start the job with the
mpiexec command. You must be logged into one of the nodes in the mpd.hosts list and must be in the directory containing the input files. The most basic way to start CONVERGE in parallel is
mpiexec –n <number of processors> converge
To dump the output to a file and start a four-processor job in the background, use the following command:
mpiexec –n 4 converge < /dev/null > logfile.out &
An example command to run CONVERGE with OpenMPI on 16 processors is as follows:
mpirun --hostfile mpd.hosts -np 16 converge-2.4.8-openmpi-linux-64
Note that for older versions, the executable name has a six-digit release date.
To run a parallel job with PMPI, first create a hostfile containing the hostnames of all machines on which the parallel job is to be run, with one machine name per line in the file. Start the job using the mpirun command as follows:
mpirun –np <number of processors> –hostfile <hostfilename> -1sided converge
For example, to start a four-processor job in the background, with a hostfile named mpd.hosts and the output redirected to a file, use the following command:
mpirun –np 4 –hostfile mpd.hosts -1sided converge > logfile.out &
In some types of MPI (e.g., MPICH2), all environment variables are passed to the slave nodes when the processes are initiated. For HP-MPI, however, the environment variables must be explicitly passed to the slave nodes. To pass the environment variables to the slave nodes (e.g.,
PATH) when starting the job, use the
-e argument as in the following example:
mpirun -np 16 -hostfile mpd.hosts -1sided –e CONVERGE_ROOT=/path/to/converge_install converge > logfile.out &
This will ensure that the
CONVERGE_ROOT environment variable is set, which is necessary for CONVERGE to find the license file.
To restart the code from a restart file, it is best to first copy the restart file that will be used to restart.rst.
If a file named restart.rst does not exist, CONVERGE will use the highest numbered restart file. Set restart_flag = 1 in inputs.in (in 2.4; this parameter is rstrtflg in 2.3 and earlier). You can instruct CONVERGE to append a unique number to the output files generated from the restarted simulation by setting restart_number in inputs.in (in 2.4; this parameter is rstrtnum in 2.3 and earlier) to the desired numeric value. Finally, start the code as described in the Running in Serial section (e.g.,
converge > log.out &).