Getting Started Guide

This guide describes how to download, install, and run CONVERGE and CONVERGE Studio. The instructions that this manual contains are specific to both version 2.2 and version 2.3 of CONVERGE and CONVERGE Studio.

Installing CONVERGE and CONVERGE Studio

The sections below describe the installation process for both CONVERGE and CONVERGE Studio in Windows and Linux. These instructions are applicable to both v2.2 and v2.3. 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 downloads page (https://download.convergecfd.com/download). The installation file is located in the path /CONVERGE_<version>/CONVERGE_Studio, for example,
      /CONVERGE_2.3/CONVERGE_StudioFiles in this path named according to the convention CONVERGE Studio_<operating system>_<architecture>_<release date>.<package type> (for example, a 64-bit Windows version will be named CONVERGE Studio_windows_64_022415.msi).

      After installation, the executable for CONVERGE Studio will be placed in the following directory:

      C:\Program Files\CONVERGE Studio\v2.3\bin\ (for Windows)
      C:\Program Files\CONVERGE Studio\bin\ (for v2.2 on Windows)
      /opt/CONVERGE Studio/v2.3/ (for Linux).
      /opt/CONVERGE Studio/ (for v2.2 on Linux).

      Note that the paths for CONVERGE Studio v2.3 include a subfolder v2.3 below the CONVERGE Studio folder.

      Windows

      The Windows executable (CONVERGE Studio_windows_64_.msi) is located in the following path:

      /CONVERGE_2.3/CONVERGE_Studio/CONVERGE Studio_windows_64_*.rpm

      where * represents the release date. To install, double-click the installation file.

      By default, the CONVERGE Studio executable will be located in

      C:\Program Files\CONVERGE Studio\v2.3\bin\

      RPM Package

      The RPM package (CONVERGE Studio_linux_64_*.rpm) is located in the following path:

      /CONVERGE_2.3.5/CONVERGE_Studio/CONVERGE Studio_linux_64_*.rpm

      where * represents the release date. To install this, while logged in as root, type:

      rpm -ivh CONVERGE Studio_linux_64_022415.rpm

      By default, the CONVERGE Studio executable will be located in:

      /opt/CONVERGE Studio/v2.3/

      Debian Package

      The Debian package CONVERGE Studio_linux_64_*.deb is located in the following path:

      /CONVERGE_2.2/CONVERGE_Studio/CONVERGE Studio_linux_64_*.deb

      where * represents the release date. To install this, while logged in as root, type:

      dpkg -i CONVERGE Studio_linux_64_022415.deb

      By default CONVERGE Studio executable will be located in

      /opt/CONVERGE Studio/v2.3/

      *.Tar Package

      You must place the CONVERGE Studio gzipped tar file in a temporary directory where it can be expanded. Unlike RPM and Debian packages, you do not need root privileges to install this version of CONVERGE Studio. Extract the content with
      the following command:

      tar –pxvfz CONVERGE Studio_linux_64_*.tar.gz

      Where * represents the release date. This command will create the directory with the necessary installation files. After expanding the tar file, run the INSTALL script.

      The INSTALL script will prompt you for the target path for the CONVERGE Studio executable.

    • To install CONVERGE on Windows, save the converge-<version>-setup-<architecture>.msi file (e.g., a 32 bit Windows machine may require converge-2.3.5-setup-32.msi). Double-click this file to install CONVERGE. Installing CONVERGE on Windows requires administrative privileges.

      Note that older version of CONVERGE are named by the convention converge-<version>-setup-<architecture>-<release-date>.msi (for example, a 64 bit Windows machine may use converge-2.2.0-setup-64-021715.msi).

    • You can install CONVERGE for a single user without root access privileges on the machine or for all users while logged in as root.

      To install and run CONVERGE:

      1. Unpack the distribution in the desired folder
      2. Run the INSTALL script (skip this step for CONVERGE v2.3)
      3. Set up the necessary environmental variables
      4. Obtain the lic file
      5. Start the Reprise (rlm) license server (floating licenses only).
    • The installation package for CONVERGE is in a gzipped tar file named:

      converge_install_*.tar.gz

      (where * represents the release date) that you need to expand. Place the file in a temporary directory where it can be expanded. Expanding the tar file will create a new directory named:

      converge_install_<version_number>

      This contains the necessary installation files. Unzip the file and open the archive using the tar utility:

      tar –xzvf converge_install_*.tar

    • This step is only required for CONVERGE v2.2 and earlier. If you are installing CONVERGE v2.3, skip this step.

      Before running the INSTALL script, make sure 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 there is a problem with permissions.

      There are three different components of CONVERGE that are installed separately as part of the INSTALL script:

      1. CONVERGE executables and associated utilities

      2. Documentation and input files for example cases

      3. The license server

      The INSTALL script file is located in the converge_install_<version_number+release_date> directory created when the archive was unpacked. The INSTALL script is an executable and can be run from the prompt by typing:

      INSTALL

      The INSTALL script will guide you through the installation process.

    • 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:

      export PATH=$PATH:/<install directory>/<architecture>/bin

      For example, for a 64-bit Linux install that used the default installation directory, you would type:

      export PATH=$PATH:/usr/local/converge-<version>/l_x86_64/bin

      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:

      /usr/local/converge-<version>

      If you do not have CONVERGE_ROOT set, then you must have RLM_LICENSE set to ensure proper licensing behavior.

      export RLM_LICENSE=2765@<license server hostname>

      See the license server error codes section for more information.

Licensing

    • If you installed CONVERGE or the license server, a sample license.lic file was placed in the license sub-directory of the installation directory. You must replace this file with a valid license file provided by Convergent Science, Inc. This file contains a hexadecimal number (hostid) that is unique to the machine on which the server runs. The Convergent Science, Inc. Licensing Team needs this number before the valid license.lic file can be generated. To determine the hostid of the machine, simply type:
      hostidIf the license is a floating license, the license.lic file needs the hostid of the machine on which the license server is running. If the license is node-locked, the license.lic file must contain the hostid values of all machines that will be running CONVERGE. To obtain a valid license.lic file, contact licensing@convergecfd.com.

    • This step is only necessary 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 the Reprise License Manager, you should refer to their website at reprisesoftware.com. One executable necessary for running the license manager is rlm. This can be found in the /<installation_directory>/<architecture>/rlm directory. Start the license manager (in the background) in this directory by typing:

      rlm &

      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, Inc. 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 rlm.

    • The first column of table 1 lists common error codes that you may encounter when starting the license server. 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.
    • Refer to the RLM User Administration Manual for setting up rlm as a service for your platform.

Running Your First Job

  • The workflow in CONVERGE consists of three steps:

    1. Pre-processing (editing the surface geometry and configuring the input and data files)

    2. Running the simulation

    3. Post-processing (analyzing the *.out ASCII files and using a visualization program to view the information in the *.out binary files saved in the output directory.

    The CONVERGE Theory Manual covers these steps in detail. The following steps describe how to verify inputs, run the code in serial and parallel, and restart the code.

    NOTE: When you install CONVERGE, the default shortcut or symbolic link (named converge) launches the HP-MPI 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 check_inputs

    CONVERGE will exit before starting the main solver. Using the check_inputs option creates the *.out files so that you can check the initialized values of the variables and related transport entities.

  • 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 v2.3 UDF Manual for information about executing CONVERGE with user-defined functions.

  • In a Windows Environment

    To run CONVERGE, open a command prompt 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:

    converge-<version>-serial-windows-<architecture>.exe

    Note that older versions have a <release date> appended to the name of the executable. To run a serial version of a 2.3.5 simulation on a 64-bit machine in Windows, type:

    converge-2.3.5-serial-windows-64.exe

    To simplify this process, you can create a shortcut to the appropriate executable. For instance, if you create a shortcut named converge that links to the appropriate executable, you need only to type converge in place
    of the full executable name.

    In a Unix/Linux Environment

    In a Unix environment, you need to type the name of the executable or the name of the link to the appropriate executable (converge) while in the directory where the input files reside. In a typical run, you redirect the screen
    output to a file so it can be stored and examined later (e.g., converge > log.out &).

  • To run CONVERGE in parallel, you must start CONVERGE in a manner consistent with the device interconnect (e.g., Myrinet, InfiniBand, Ethernet etc.), and MPI implementation (openmpi, mpich2, etc.) used on the machine.
    The placement of input and output files is the same as in the serial version. Note that older versions have a <release date> appended to the name of the executable.

    Windows with HP-MPI

    To execute CONVERGE with HPMPI, type:

    mpirun –np <number of processors> -1sided converge-<version>-hpmpi_windows-<architecture>.exe

    i.e., to start a 4-processor job you would type:

    mpirun –np 4 -1sided converge-2.3.5-hpmpi_windows-64.exe

    Windows with MPICH2

    Before you run an MPICH parallel job, an administrator must launch the smpd service by running:

    smpd.exe

    Prior to running your first MPICH2 job, register your user credentials with the MPICH2 user management system by running:

     

    mpiexec -register

    Now you can launch an MPICH2 job by running the following set of commands from a DOS prompt:

     

    chdir <location of CONVERGE input files>
    mpiexec –n <number of processors> converge-<version>-mpich2_windows-<architecture>

    Windows with MSMPI

    The standard MSMPI CONVERGE execution is:

    mpiexec –n <number of processors> converge-<version>-msmpi_windows-<architecture>.exe

    Linux with HP-MPI

    To run a parallel job with HP-MPI, 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 4-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., CONVERGE_ROOT, 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.

    Linux with MPICH2

    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 and typing at the prompt (while in the directory with the mpd.hosts file):

    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:

    mpdtrace

    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 would be:

    mpiexec –n <number of processors> converge

    To dump the output to a file and start a 4-processor job in the background, use the following command:

    mpiexec –n 4 converge < /dev/null > logfile.out &

    Linux with OpenMPI

    An example command to run CONVERGE with OpenMPI on 16 processors is as follows:

    mpirun --hostfile mpd.hosts -np 16 converge-2.3.5-openmpi-linux-64

  • 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, the most recently written restart file will be used when restarting the simulation. Change the value of the input variable rstrtflg in the input file inputs.in to 1. You can instruct CONVERGE to append a unique number to the output files generated from the restarted simulation by setting the input variable rstrtnum to the desired numeric value. Finally, start the code as described in the Running in Serial section (e.g., converge > log.out &).

Contact Us Today

Learn more about how CONVERGE helps you quickly and accurately solve your CFD problems.