The LDD suite computes atomic contributions to the London dispersion energy and the dispersion density. It is based on the Atomic Decomposition of London Dispersion energy (ADLD) method and includes the following tools:

• lddensity.py – computes atomic dispersion contributions using the selected Grimme's dispersion correction and generates a .cube file with the London dispersion density function.
• vmd.tcl – VMD script to automatically set visualization parameters for publication-quality images.

• Tools Description
• Installation
• Basic Usage
• Requirements
• Arguments Description
• Generate Only the Cube File
• Dispersion Density Difference
• Renderings
• Credits
• License
• Contacts

Python script to compute atomic contributions to the London dispersion energy and the London dispersion density function.

• Input:
  • {basename}.xyz: a classic XYZ file containing atomic coordinates of the system in ångström.
• Output:
  • {basename}.atomwise.txt: a file containing atomic coordinates of the system with an additional column indicating each atom contribution to the London dispersion energy.
  • {basename}.omega.cube: a .cube file that stores volumetric data of the LDD function, which can be used to easily visualize atomic contributions to London dispersion.

Script designed to visualize LD density function from a .cube file, adjusting VMD settings to generate publication-quality images.

Navigate to the directory you want to run the code and clone the repository:

cd /path/to/target/directory
git clone git@github.com:bistonigroup/LDDsuite.git .

Create the environment:

python -m venv venv

Load the environment:

source venv/bin/activate

Ensure pip is up to date and install the required packages:

pip install --upgrade pip
pip install -r requirements.txt

Once you are done, you can exit the virtual environment by simply typing:

deactivate

You don't need to reinstall python packages every time you want to run the code. Before run the code be sure to reload the environment with:

source venv/bin/activate

First, run the Python script to perform ADLD and generate the volumetric data (i.e., the .cube file). Use the following command:

python lddensity.py {basename}                

To see all available options and advanced settings, use the help flag:

python lddensity.py -h                   

Once the .cube file is generated, you can visualize the results with publication quality using the provided VMD script.
First, open vmd.tcl in a text editor and set the file_name variable to match your generated .cube file

set file_name "your_output_file.cube"

Finally, run the following command to load .cube file and apply the visualization settings:

vmd -e vmd.tcl

• Refer to requirements.txt for Python script.
• VMD must be installed for running vmd.tcl (download).

Below is a detailed table of the arguments that can be used with our script. Each entry provides you with the name of the argument, a brief description, information on whether the argument is optional, and the default value it takes if not specified by the user. This table is designed to help you quickly understand how to configure the script to meet your specific requirements.

If you have already calculated the atomic contributions (e.g., using ORCA) or if you wish to plot the dispersion density difference function, you can use the --onlycube flag in lddensity.py.

In this case, the input file is not a standard .xyz file. Instead, it is a formatted text file containing an extra column for the atomic dispersion contributions (in kcal/mol). The script expects a file named {basename}.atomwise.txt, which is the same format produced by lddensity.py when the --onlycube flag is not used.

An example of .atomwise.txt file for the $C_6H_6–Li$ system is shown below:

#
atom   x(Å)         y(Å)        z(Å)        Edisp(kcal/mol)
C      -2.378672     1.005050   -0.079453   -2.128400
C      -2.318663    -0.385217   -0.085888   -2.128400
C      -1.085955    -1.028059   -0.147588   -2.128400
C       0.086589    -0.280636   -0.203051   -2.128300
C       0.026549     1.109641   -0.196866   -2.127300
C      -1.206135     1.752463   -0.134993   -2.127300
H      -3.337288     1.505059   -0.038209   -0.486950
H      -3.230736    -0.966137   -0.050005   -0.487450
H       0.937922     1.690612   -0.246784   -0.486450
H      -1.253275     2.833395   -0.136867   -0.486550
H      -1.039495    -2.108952   -0.159689   -0.487350
H       1.044500    -0.780664   -0.258085   -0.486850
Li     -1.018560     0.350445    2.545363   -3.707400

To run the script, use the following command:

python lddensity.py {basename} --onlycube            

To generate the dispersion density difference between two molecular systems:

1. Compute the atomic dispersion contributions for both systems separately.
2. Be sure there's an atom-to-atom mapping between the two structures.
3. Build a new {basename}.atomwise.txt file where the atomic dispersion contribution for each atom corresponds to the difference between its values in the two systems.
4. Use this difference file as input to generate the .cube file with --onlycube (refer to Generate Only the Cube File section).

This procedure allows you to visualize the difference between atomic LD contributions for two different molecular structures (e.g., a pair of structures along a reaction profile).

An example command could be:

python lddensity.py system_diff --onlycube --npoints 80 --nprocs 2

The image below is a rendering generated with vmd.tcl for a $C_6H_6–Li$ system. Red/blu color indicates high/low atomic dispersion contribution.

If you use the LDD suite in your research or any publication, please cite:

• https://pubs.acs.org/doi/full/10.1021/acscentsci.5c00356

• https://pubs.acs.org/doi/abs/10.1021/acs.jctc.3c00977

• https://github.com/bistonigroup/LDDsuite

Distributed under GNU Lesser General Public License. See LICENSE for more information.

For general inquiries, feedback, or assistance with using the LDD suite, please contact us at:

Gianluca Regni - gianluca.regni@dottorandi.unipg.it
Lorenzo Baldinelli - lorenzo.baldinelli@dottorandi.unipg.it
Giovanni Bistoni - giovanni.bistoni@unipg.it