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:

Acquire and compile LAMMPS, following the LAMMPS build guide. You will need to enable the USER-MDI package when building LAMMPS.

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

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:

Install OpenMM
Install the OpenMM MDI plugin
Prepare OpenMM input files that specify the initial molecular geometry of the system and any other desired settings.
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)
```
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:

Install MDI as a Python package, using either Conda (conda install -c conda-forge pymdi) or pip (pip install pymdi).
Acquire and compile Psi4, following the Psi4 installation guide. Installing via Conda is recommended.
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)
```
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:

Install QCEngine, following the QCEngine installation guide.

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()

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:

Acquire the MDI-enabled fork of QE:

git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git

Configure QE. You will need to configure QE to be compiled with position-independent code. If using GCC compilers, you can acomplish this by passing the "-fPIC" flag to the "FFLAGS", "FCFLAGS", "CFLAGS", and "try_foxflags" configuration options. For example:
```
cd q-e
./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" try_foxflags="-fPIC -cpp"
```

For additional information about configuring QE, see the QE build guide.

Compile "qemdi.x".
```
make mdi
```
Prepare a QE input file that specifies the initial molecular geometry of the system and any other desired settings.
Launch QE using the "qemdi.x" executable (which is located in "q-e/MDI/src") "-mdi" runtime option, which is described in Launching Codes with the MDI Library. For example:
```
qemdi.x -in qe.in -mdi "-role ENGINE -name my_name -method TCP -port 8021 -hostname localhost" &
```
The "q-e/MDI/src" directory also contains a QE MDI Plugin, called "qemdi".

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:

Acquire the MDI-enabled fork of Tinker:

git clone --branch mdi git@github.com:taylor-a-barnes/Tinker.git

Compile dynamic.x, following the Tinker build guide.
Prepare Tinker input files that specify the initial molecular geometry of the system and any other desired settings.

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