Molssi Driver Interface Library
MDI Ecosystem

Overview

This section provides basic usage instructions for the drivers, engines, and other codes that compose the MDI ecosystem.

LAMMPS

To use LAMMPS as an engine, follow these steps:

  1. Acquire and compile LAMMPS, following the LAMMPS build guide. You will need to enable the USER-MDI package when building LAMMPS.
  2. Prepare a LAMMPS input file that specifies the initial molecular geometry of the system, the force field to be used, and any other desired settings. At the end of the input file, call the mdi/engine command, which does not accept any arguments. For example:
    units           real
    neigh_modify    delay 0 every 1 check yes
    atom_style      full
    bond_style      harmonic
    angle_style     harmonic
    pair_style      lj/cut/coul/long 10.0
    pair_modify     mix arithmetic
    kspace_style    pppm 1e-4
    special_bonds   amber
    
    atom_modify     sort 0 0
    
    read_data       lammps.data
    
    timestep        1.0
    
    dump            1 all custom 1 dump.lammpstrj id element xu yu zu
    dump            2 all custom 1 dump.force id element fx fy fz
    dump            3 all xyz 1 dump.xyz
    dump_modify     1 element O H
    dump_modify     2 element O H
    
    thermo_style    multi
    thermo          1
    
    fix             1 all nvt temp 300.0 300.0 70.0
    fix             2 all shake 0.0001 20 0 b 1 a 1
    
    mdi/engine
    
  3. Launch LAMMPS using the "-mdi" runtime option, which is described in Launching Codes with the MDI Library. For example:
    lammps -in lammps.in -mdi "-role ENGINE -name my_name -method TCP -port 8021 -hostname localhost" &
    

OpenMM

An MDI plugin for OpenMM is available that enables OpenMM to be run as an MDI engine. To use OpenMM as an engine, follow these steps:

  1. Install OpenMM
  2. Install the OpenMM MDI plugin
  3. Prepare OpenMM input files that specify the initial molecular geometry of the system and any other desired settings.
  4. In the OpenMM run script, replace the normal call to Simulation with a call to MDISimulation, which requires a new argument that corresponds to the MDI runtime options. For example:
    simulation = MDISimulation("-name MM -role ENGINE -method TCP -port 8021 -hostname localhost", pdb.topology, system, integrator, platform)
    
  5. At the end of the run script (or at whatever point OpenMM should begin accepting commands from the driver) call the runMDI() function on the MDISimulation object you created in the last step:
    simulation.runMDI()
    

Psi4

To use Psi4 as an engine, follow these steps:

  1. Install MDI as a Python package, using either Conda (conda install -c conda-forge pymdi) or pip (pip install pymdi).
  2. Acquire and compile Psi4, following the Psi4 installation guide. Installing via Conda is recommended.
  3. Prepare a Psi4 input file that specifies the initial molecular geometry of the system and any other desired settings. At the end of the input file, call the energy command with the mdi=True optional argument. For example:
    molecule {
    O 4.92718 4.99809 1.10308
    H 5.80905 5.31488 0.90767
    H 4.87602 4.14701 0.667997
    }
    
    energy("scf/sto-3g", mdi=True)
    
  4. Launch Psi4 using the "--mdi" runtime option, which is described in Launching Codes with the MDI Library. For example:
    psi4 -i psi4.dat --mdi "-role ENGINE -name my_name -method TCP -port 8021 -hostname localhost" &
    

QCEngine

To use QCEngine as an MDI engine, follow these steps:

  1. Install QCEngine, following the QCEngine installation guide.
  2. Prepare a QCEngine input file that specifies the initial molecular geometry of the system and any other desired settings. At the end of the input file, create an "MDIServer" object and call the "start()" method on it. For example:
    import qcengine as qcng
    import qcelemental as qcel
    
    mol = qcel.models.Molecule.from_data("""
    O  0.0  0.000  -0.129
    H  0.0 -1.494  1.027
    H  0.0  1.494  1.027
    """)
    
    o = qcng.MDIServer(mdi_options = "-role ENGINE -name QM -method TCP -port 8021 -hostname localhost",
                       program = "psi4",
                       molecule = mol,
                       model = {"method": "SCF", "basis": "sto-3g"},
                       keywords = {"scf_type": "df"})
    o.start()
    
  3. Run the input script as normal. Note that there is NOT a "--mdi" runtime option.

Quantum ESPRESSO

MolSSI provides an MDI-enabled fork of Quantum ESPRESSO (QE) that can be run as an MDI engine. To use QE as an engine, follow these steps:

  1. Acquire the MDI-enabled fork of QE:
    git clone --branch mdi git@github.com:MolSSI/q-e.git
    
  2. Compile pw.x, following the QE build guide.
  3. Prepare a QE input file that specifies the initial molecular geometry of the system and any other desired settings.
  4. Launch QE using the "-mdi" runtime option, which is described in Launching Codes with the MDI Library. For example:
    pw.x -in qe.in -mdi "-role ENGINE -name my_name -method TCP -port 8021 -hostname localhost" &
    

Tinker

An MDI-enabled fork of Tinker is available that can be run as an MDI engine. To use Tinker as an engine, follow these steps:

  1. Acquire the MDI-enabled fork of Tinker:
    git clone --branch mdi git@github.com:taylor-a-barnes/Tinker.git
    
  2. Compile dynamic.x, following the Tinker build guide.
  3. Prepare Tinker input files that specify the initial molecular geometry of the system and any other desired settings.
  4. Launch Tinker using the "-mdi" runtime option, which is described in Launching Codes with the MDI Library. For example:
    dynamic.x input -mdi "-role ENGINE -name MM -method TCP -port 8021 -hostname localhost" 1000 1.0 10.0 2 298.0 778.0