Welcome to this repository. Here you will find all the code needed to run the least-squares fit solution for the adjustment of charges while keeping the total dipole moment of a molecule.
This file explains how the dipole-charges derivation is done.
1- Run your QM calculation (MP2/6-31G - ESP) in your software of choice.
2- Translate the obtained charges to a .mol2 file. It is important that the "@<TRIPOS>ATOM" line is present in the .mol2 file, and that there is no empty line between "@<TRIPOS>ATOM" and the first atom.
NOTE: your .mol2 file should be named "example.mol2" (the "example" part can be modified).
Note that atomic charges placed in a cartesian space will generate a dipole moment vector. Since the atomic charges and coordinates were generated from a QM calculation, this "example.mol2" will carry a QM dipole moment vector. Its direction will be a reference for this protocol.
3- Run
python write_csv.py example.mol2
to obtain a "example.csv" file that will carry the charge boundaries.
This protocol is based on lower and upper boundaries for atomic charges, in a way that the solution generated by our protocol preserves the dipole moment direction.
This means that at each line, the two last columns in the .csv files are the lower and upper boundaries. By default the lower bound is set to -1.00, and the upper bound is set to 1.00:
ID Atom Fixed X coord Y coord Z coord QM charge Lower Upper
1, C, 0, -4.7584, 0.4116, -0.2313, 0.0477, -1.00, 1.00
2, H, 0, -6.1029, 2.1354, -0.1405, 0.0287, -1.00, 1.00
3, O, 0, -3.4992, 0.0043, 0.2795, -0.3798, -1.00, 1.00
So the user should change the lower and upper boundaries that the algorithm should use to generate a solution for his or her experiment.
In general, non-polar carbons vary from -0.20 to +0.20. Oxygens and Nitrogens upper limit is -0.20. Hydrogens are always positive (lower limit of +0.00). Of course this is only our experience and can be changed if the user is certain of what he or she is doing.
This is the place you should enter previously calibrated group charges. For example: benzenic C-H groups have -0.13 and +0.13 charge, respectivelly. Thus, the upper and lower limits will be equal, so the algorithm won't have any room to change it. If that is the case for the example above, it should be become:
ID Atom Fixed X coord Y coord Z coord QM charge Lower Upper
1, C, 0, -4.7584, 0.4116, -0.2313, 0.0477, -0.13, -0.13
2, H, 1, -6.1029, 2.1354, -0.1405, 0.0287, 0.13, 0.13
3, O, 0, -3.4992, 0.0043, 0.2795, -0.3798, -0.80, -0.20
Fixing the charge of an atom: If you need or want an atom to have a fixed value of charge (that it must not change), you should set the "fixed flag" (the third column in the .csv file) to 1. If the charge can change, the "fixed flag" should be 0. By default, the "fixed flag" of all atoms is 0. If you set the "fixed flag" of an atom to 1, you should also make so the lower and upper bounds of that atom are equal. In the example above, the second atom (H) should have a charge of 0.13, so its "fixed flag" was set to 1 and the lower bound = upper bound = 0.13.
4- Run
python getvector.py example.csv example.mol2 Q C
with Q = the magnitude of the dipole moment generated (as a fraction of 1, e.g. 1.0 is 100%) and C = the total net charge of the molecule (0 for neutral molecules).
Example:
Run
python getvector.py example.csv example.mol2 0.7 0.0
to obtain a new distribution of charges that sums 0 and, when applied to the coordinates from the .mol2 file, will generate a new dipole moment with the same direction of the QM, with 70% of its magnitude.
This step will generate a "example-lsql.mol2" file. It contains the same coordinates as the "example.mol2", but with a new set of atomic charges.
Please check if the boundaries were respected!!!! If the boundaries defined on your .csv is too restrict, it is more likely that they will be violated. If that is the case, try other boundaries.
A good output will respect the defined boundaries and the change in magnitude required.
TIP: open both .mol2 files in VMD and visualize them using the Dipole Moment Watcher!
Usage: python getvector.py file1.csv file2.mol2 1.0 0.0
Usage: python getvector.py file1.csv file2.mol2 module_coeficient (1.0 is default) molecule_charge (0.0 is default)
It reads the .csv file, it should follow this format for each text line:
index, atom_name, fixed_flag, x, y, z, ref_charge, charge_lower_bound, charge_upper_bound
And each line represents an atom.
POS is the matrix of atoms positions X, Y, Z, it is transposed in order to convert the .mol2 (and .csv) notation to the shape needed for the linear problem.
mol2 linear problem
X0 Y0 Z0 X0 X1 X2 ... Xn
X1 Y1 Z1 -> Y0 Y1 Y2 ... Yn
X2 Y2 Z2 Z0 Z1 Z2 ... Zn
...
Xn Yn Zn
The fixed flag: 0 if not fixed, 1 if fixed.
Atoms marked as fixed (= 1) will have their charges fixed to the value of their lower bound charges.
For fixed atoms the values of the lower bound and upper bound charge should be the same.
If the lower and upper bounds for a charge are equal, i. e., that charge value should be constant, a small value is added to the upper charge so the algorithm can run.
In order to satisfy the condition that the sum of all charges must be = mol_charge, a row of coeficients all equal 1.0 is appended at the end of the POS matrix and the value mol_charge is appended at the end of the vector of charges references. This way, when solving the linear problem, one of the equations will be
1 * c0 + 1 * c1 + ... + 1 * cn = mol_charge
Creates a new vector with 1.0 in all positions and add it as last row in the POS matrix.
For each atom marked with the fixed flag = 1, a row of coeficients all equal 0.0 is appended at the end of the POS matrix, except for the coeficient of the marked atom, that is equal 1.0, and the value of its lower bound charge is appended at the end of the vector of charges references. This way, when solving the linear problem, one of the equations will be
0 * c0 + 0 * c1 + ... + 1 * cmarked + ... 0 * cn = lb_charge
Creates a new vector with 0.0 in all positions except the position of the flag = 1 and adds it as last row in the POS matrix.
Add the lower bound charge of the marked atom at the end of the reference vector for charges.
Solving the linear problem
POS * C_pred = K_ref
We want to know the vector C_pred of new charge values that preserves the module and orientation of vector K_ref, and also obeys the constraints of lower and upper bounds for each charge and keeps the sum of all charges = mol_charge.
We also added a coefficient to multiply the K_ref in cases we want a slightly different vector module but still the same direction.
In the end the script reads the .mol2 file and change its charges to the new charges in C_pred, saving the new results in a -lsql.mol2 file.
Marcelo D. Polêto, Bruno Iochins Grisci, Marcio Dorn, Hugo Verli
Centro de Biotecnologia, Universidade Federal do Rio Grande do Sul
Institute of Informatics, Federal University of Rio Grande do Sul, Porto Alegre, RS, Brazil
E-mail: mdorn@inf.ufrgs.br, bigrisci@inf.ufrgs.br, mdorn@inf.ufrgs.br, hverli@cbiot.ufrgs.br
If you use the dipole charges calculator in a publication, we would appreciate citations to the following papers:
- Pablo R. Arantes, Marcelo D. Polêto, Elisa B. O. John, Conrado Pedebos, Bruno I. Grisci, Marcio Dorn, and Hugo Verli. "Development of GROMOS-Compatible Parameter Set for Simulations of Chalcones and Flavonoids" J. Phys. Chem. B, 2019, 123 (5), pp 994–1008 DOI: https://doi.org/10.1021/acs.jpcb.8b10139
Bibtex entry:
@article{arantes2019development,
title={Development of GROMOS-Compatible Parameter Set for Simulations of Chalcones and Flavonoids},
author={Arantes, Pablo Ricardo and Pol{\^e}to, Marcelo Dep{\'o}lo and John, Elisa Beatriz de Oliveira and Pedebos, Conrado and Grisci, Bruno I and Dorn, Marcio and Verli, Hugo},
journal={The Journal of Physical Chemistry B},
year={2019},
volume={123},
pages={994--1008},
publisher={ACS Publications}
}
- Marcelo D. Polêto, Victor H. Rusu, Bruno I. Grisci, Marcio Dorn, Roberto D. Lins and Hugo Verli. "Aromatic Rings Commonly Used in Medicinal Chemistry: Force Fields Comparison and Interactions With Water Toward the Design of New Chemical Entities" Frontiers in pharmacology, v. 9, 2018. DOI: https://doi.org/10.3389/fphar.2018.00395
Bibtex entry:
@article{poleto2018aromatic,
title={Aromatic Rings Commonly Used in Medicinal Chemistry: Force Fields Comparison and Interactions With Water Toward the Design of New Chemical Entities},
author={Pol{\^e}to, Marcelo D and Rusu, Victor H and Grisci, Bruno I and Dorn, Marcio and Lins, Roberto D and Verli, Hugo},
journal={Frontiers in pharmacology},
volume={9},
year={2018},
publisher={Frontiers Media SA}
}