ModeCode is available as-is for LAMMPS versions around 2021-2022, and not for newer LAMMPS versions.
ModeCode is a massively parallel and modular program that aids in the study of vibrational modes. Vibrational modes are collective movements in a system, also known as collective variables in the molecular simulation community. In atomic systems, these collective motions are composed of atoms and they vibrate at specific frequencies. All the motion in an atomic system is determined by Newton's 2nd law, and this motion may be decomposed into the individual modes. This is illustrated below for atoms in a diamond crystal with seemingly random thermal vibrations at finite temperature.
These motions influence all phenomena that we observe in materials, including thermal and electrical transport, mass diffusion, and chemical reactions. For example consider the vibrational mode of atoms in a superlattice below, modes like these aid in the transfer of heat through superlattice thermoelectric devices, and understanding their behavior will help us engineer better thermoelectric devices.
ModeCode is a massively parallel and modular program that aids in the study of vibrational modes. This program is the first of its kind, as all other open-source programs only deal with vibrational modes/phonons in ideal crystals. By interfacing with a large library of interatomic potentials and alleviating the assumption of periodicity, ModeCode allows for the study of vibrational modes in all materials.
Before we install ModeCode, we must first install LAMMPS as a shared library.
Go into the src/ directory of your LAMMPS installation and do:
make yes-MANYBODY mode=shlib g++_openmpi
or any other setting (aside from g++_openmpi) according to the instructions on the LAMMPS website (http://gensoft.pasteur.fr/docs/lammps/12Dec2018/Python_shlib.html).
This should make a liblammps.so file (or some similar name).
If that doesn't work, you may need to use cmake to install LAMMPS (e.g. on MacOS). For that, go into your lammps/ directory and do:
mkdir build
cmake ../cmake -DPKG_MANYBODY=yes -DBUILD_SHARED_LIBS=yes
make
Which should make a liblammps.dylib file on MacOS.
Now we are ready to install ModeCode by linking to the LAMMPS shared library.
First download ModeCode from github:
git clone https://github.com/rohskopf/modecode
Then edit src/Makefile to have the appropriate paths pointing towards your LAMMPS shared library installation.
On Linux, it should just work.
On MacOS, it's important to set the environment variable
export OMPI_CXX=clang++
To tell your MPI to use clang as a compiler instead of g++. On MacOS we also need to copy lammps/build/liblammps.0.dylib to /usr/local/lib/liblammps.0.dylib to run ModeCode.
Go into src/ and install with:
make clean
make
That's it! We just made a ModeCode executable called modecode.
ModeCode is simple - you declare a calculation task and settings and must have an INPUT file in the directory that you run it in. These details are explained below.
The general format for running ModeCode is to do:
mpirun -np P modecode task setting1 setting2 setting3 ...
where
Pis the number of processes.taskis calculation/task we are performing, which typically referes to the C++ module/class being used.settingsfurther specify which function in thetaskis used, or input values needed to run the function.
There may be few or many settings, depending on which task we use. Before we get into the multiple tasks, it's first important to understand the input files required to use ModeCode.
This file is composed of LAMMPS commands that declare your system geometry, potential, neighborlist settings, etc. Please refer to the LAMMPS documentation to declare desired settings for your system. It's important to declare LAMMPS settings here, because some tasks in ModeCode such as finite difference will evaluate the potential at many different geometries; we therefore need to declare neighborlist settings, a system geometry via LAMMPS data files, atom styles, and pair styles.
Other than the INPUT file, other files required depend on whatever your INPUT file uses. For example if you use the LAMMPS read_data command in your INPUT file, you need to also include the data file in your directory. If your LAMMPS pair style has a file it reads parameters from, then that file must also be included in the directory. Any file used by your INPUT file must also be included in the directory.
Now that we understand the different inputs used by ModeCode, let's consider the different tasks or calculations that are possible.
This task uses finite difference to extract the 2nd, 3rd, or 4th order interatomic force constants (IFCs).
The general use of this task is:
mpirun -np P modecode fd delta cutoff tolerance order
where
Pis the number of processes to split the IFC calculations over.fdrefers to the finite difference task.deltais the finite difference step size, a number depending on the stiffness of your material with the same units declared by LAMMPS in the INPUT file.cutoffis the interatomic interaction cutoff for force constants, in whatever units declared by LAMMPS.tolerancetells the program to ignore force constants below this absolute value. Units are determined by LAMMPS.orderis the order of finite difference, e.g. 2, 3, 4.
- FC2, FC3, or FC4 depending on the
orderparameter.
These FC files are converted from LAMMPS metal units to Ryd/Bohr units internally inside in.cpp.
This task calculates the self-interaction 2nd order IFCs, given the file FC2 which does not contain self terms.
The general use of this task is:
modecode asr order tolerance
where
asrrefers to the ASR task.orderrefers to the IFC order, although for now ModeCode only supports 2nd order ASR.toleranceis the absolute value below which we ignore IFCs.
- FC2_ASR
- Same as FC2, except includes self-terms.
This task diagonalizes the dynamical matrix to get the mode frequencies and eigenvectors.
Currently this is not implemented in the C++ code; we use a simple Python script instead.
See tools/calc_eig3.py. This takes FC2_ASR, DATA (LAMMPS data file), and you must ensure in the script that your units are what is desired. Simply do:
python calc_eig.py
The outputs here have SI units, if your force constants were in Ryd/Bohr^2 units.
- FREQUENCIES
- EMAT
This task computes various quantities associated with the modes.
The general use of this task is:
modecode compute compute_task setting1 setting2 ...
where
computerefers to the compute task.compute_taskis the sub-task which refers to the quantity we are computing.settingsdetermine the necessary inputs for the calculation.
There are a few separate sub-tasks which will be explained here.
Run with:
modecode compute pr natoms
where
prrefers to the participation ratio sub-task.natomsis the number of atoms in the system.
Run with:
modecode compute esp
where
esprefers to the ESP task.
This task converts IFCs to mode coupling constants (MCCs), in various different ways.
There are many different ways of converting IFCs into MCCs, so we have many different options.
Generally, do this with:
mpirun -np P modecode ifc2mcc subtask setting1 setting2 ...
where
subtaskrefers to a particular sub-task (an integer).settingsare the settings for that sub-task.
To simply convert IFCs to MCCs of any order, do:
mpirun -np P modecode ifc2mcc 0 order tolerance
where
orderis the Taylor expansion order of the IFCs.toleranceis the tolerance of MCC3s to ignore below.
To calculate generalized velocities used in the Quasi-Harmonic Green Kubo formulation, do:
mpirun -np P modecode ifc2mcc 8 alpha
where
alphais the Cartesian direction of the generalized velocities.
More subtasks will be documented.
- Coming soon.
This is nice to make sure everything works.
Go into examples/Si_8atoms and follow the README there.