Molssi Driver Interface Library
MDI Library

Overview

The MDI Library enables inter-code communication in a manner compliant with the MDI Standard.

The MDI Library currently supports the following communication methods:

Launching Codes with the MDI Library

Whenever a code is launched as a driver or engine, it must be provided either the "-mdi" or "--mdi" runtime option (see MDI Ecosystem for details regarding which codes use the single dash and which codes use the double dash). The argument for this option is a string, in quotes, consisting of a sequence of options used by the MDI Library. The following options are available:

  • -role
    • required: always
    • argument: keyword
      • DRIVER - The code will run as a driver
      • ENGINE - The code will run as an engine
  • -name
    • required: always
    • argument: keyword, with possible values defined in the documentation of each individual driver
  • -method
    • required: always
    • argument: keyword
      • TCP - The codes will communicate via the TCP/IP protocol
      • MPI - The codes will communicate via MPI using a Multiple Programs, Multiple Data (MPMD) approach
  • -hostname
    • required: Only if method=TCP and role=ENGINE
    • argument: The hostname of the driver
  • -port
    • required: Only if method=TCP
    • argument: The port number over which the driver will listen for connections from the engine(s)
  • -ipi
    • This option turns on compatibility mode for i-PI, allowing codes that use MDI for communication to communicate with codes that use i-PI for communication. If none of the drivers or engines is using i-PI for communication, this option should not be used, as it disables some of the MDI Library's error checking.
    • required: Only if one of the engines or drivers is using i-PI for communication
    • argument: None
  • -out
    • This option redirects the standard output of the driver or engine to a user-specified file. It is primarily intended for use when method=MPI (e.g., running all of the codes as part of a single MPMD launch). When method=MPI, all codes will by default write to the same output file, which typically leads to unreadably mangled output. The -out option allows the user to override this behavior, specifying a unique output file for each driver and engine.
    • required: Never
    • argument: The name of the file to which the output will be redirected

For more information about running or developing codes that use the MDI Library, please see the tutorials.

Using TCP Communication

Launching a driver using TCP communication involves the general format: 

<driver_executable> <driver_options> -mdi "-role DRIVER -name driver -method TCP -port 8021" &

Launching an engine using TCP communication involves the general format: 

<engine_executable> <engine_options> -mdi "-role ENGINE -name my_name -method TCP -port 8021 -hostname localhost" &

The ampersand ("&") causes the code to run in the background, allowing additional drivers and/or engines to be launched from the same terminal or job script.

Note that some codes may use "--mdi" instead of "-mdi".

Using MPI Communication

When using MPI communication, the driver and engines must be launched as part of a single mpiexec launch command. The general format for this is: 

mpiexec -n <driver_nprocs>  <driver_executable>  -mdi "-role DRIVER -name driver -method MPI  -out driver.out"  : \
        -n <engine1_nprocs> <engine1_executable> -mdi "-role ENGINE -name engine1 -method MPI -out engine1.out" : \
        -n <engine2_nprocs> <engine2_executable> -mdi "-role ENGINE -name engine2 -method MPI -out engine2.out"

Compiling the MDI Library

The MDI Library uses CMake to compile. If you do not already have CMake installed on your machine, please follow the instructions on the official website to do so.

With CMake installed, you can build the MDI Library as follows:

git clone git@github.com:MolSSI/MDI_Library.git
mkdir MDI_Library/build
cd MDI_Library/build
cmake ..
make

By default, the CMake build will compile all necessary wrappers to support linking to C/C++, Fortran, and Python codes. The build can be restricted to only support a subset of these languages by using the -Dlanguage option. For example, doing the following will compile a build that only supports linking to C/C++ codes:

cmake -Dlanguage=C ..

The following is a full list of CMake options:

  • -Dlanguage
    • argument: keyword
      • C - The build will only support C/C++
      • Fortran - The build will only support C/C++ and Fortran
      • Python - The build will only support C/C++ and Python
  • -Dlibtype
    • argument: keyword
      • SHARED - The build will be compiled as a shared library (default)
      • STATIC - The build will be compiled as a static library (NOTE: this option prevents Python codes from using the library)

MDI Library Functions

MDI function calls are made in a similar style to that of MPI, with MDI_Send and MDI_Recv functions being conceptually analagous to MPI_Send and MPI_Recv, respectively. The key functions are:

Generated by   doxygen 1.8.17