Skip to main content

Torch Autodiff implementation of charge models

Project description

Torch Autodiff Multicharge

Compatibility: Python Versions PyTorch Versions
Availability: Release PyPI Conda Version Apache-2.0
Status: Test Status Ubuntu Test Status macOS (x86) Test Status macOS (ARM) Test Status Windows Build Status Documentation Status pre-commit.ci Status Coverage

PyTorch implementation of the electronegativity equilibration (EEQ) model for atomic partial charges. This module allows to process a single structure or a batch of structures for the calculation of atom-resolved dispersion energies.

For details on the EEQ model, see

  • \S. A. Ghasemi, A. Hofstetter, S. Saha, and S. Goedecker, Phys. Rev. B, 2015, 92, 045131. DOI: 10.1103/PhysRevB.92.045131

  • \E. Caldeweyher, S. Ehlert, A. Hansen, H. Neugebauer, S. Spicher, C. Bannwarth and S. Grimme, J. Chem. Phys., 2019, 150, 154122. DOI: 10.1063/1.5090222

For alternative implementations, also check out

  • multicharge: Implementation of the EEQ model in Fortran.

Installation

pip

tad-multicharge can easily be installed with pip.

pip install tad-multicharge

conda

tad-multicharge is also available from conda.

conda install tad-multicharge

From source

This project is hosted on GitHub at tad-mctc/tad-multicharge <https://github.com/tad-mctc/tad-multicharge>__. Obtain the source by cloning the repository with

git clone https://github.com/tad-mctc/tad-multicharge
cd tad-multicharge

We recommend using a conda environment to install the package. You can setup the environment manager using a mambaforge installer. Install the required dependencies from the conda-forge channel.

mamba env create -n torch -f environment.yaml
mamba activate torch

Install this project with pip in the environment

pip install .

The following dependencies are required

Compatibility

PyTorch \ Python 3.8 3.9 3.10 3.11 3.12
1.11.0 :white_check_mark: :white_check_mark: :x: :x: :x:
1.12.1 :white_check_mark: :white_check_mark: :white_check_mark: :x: :x:
1.13.1 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :x:
2.0.1 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :x:
2.1.2 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :x:
2.2.2 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:
2.3.1 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:
2.4.1 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:

Note that only the latest bug fix version is listed, but all preceding bug fix minor versions are supported. For example, although only version 2.2.2 is listed, version 2.2.0 and 2.2.1 are also supported.

On macOS and Windows, PyTorch<2.0.0 does only support Python<3.11.

Development

For development, additionally install the following tools in your environment.

mamba install black covdefaults mypy pre-commit pylint pytest pytest-cov pytest-xdist tox
pip install pytest-random-order

With pip, add the option -e for installing in development mode, and add [dev] for the development dependencies

pip install -e .[dev]

The pre-commit hooks are initialized by running the following command in the root of the repository.

pre-commit install

For testing all Python environments, simply run tox.

tox

Note that this randomizes the order of tests but skips "large" tests. To modify this behavior, tox has to skip the optional posargs.

tox -- test

Examples

The following example shows how to calculate the EEQ partial charges and the corresponding electrostatic energy for a single structure.

import torch
from tad_multicharge import eeq

numbers = torch.tensor([7, 7, 1, 1, 1, 1, 1, 1])

# coordinates in Bohr
positions = torch.tensor(
    [
        [-2.98334550857544, -0.08808205276728, +0.00000000000000],
        [+2.98334550857544, +0.08808205276728, +0.00000000000000],
        [-4.07920360565186, +0.25775116682053, +1.52985656261444],
        [-1.60526800155640, +1.24380481243134, +0.00000000000000],
        [-4.07920360565186, +0.25775116682053, -1.52985656261444],
        [+4.07920360565186, -0.25775116682053, -1.52985656261444],
        [+1.60526800155640, -1.24380481243134, +0.00000000000000],
        [+4.07920360565186, -0.25775116682053, +1.52985656261444],
    ]
)

total_charge = torch.tensor(0.0)
cn = torch.tensor([3.0, 3.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0])

eeq_model = eeq.EEQModel.param2019()
energy, qat = eeq_model.solve(numbers, positions, total_charge, cn)

print(torch.sum(energy, -1))
# tensor(-0.1750)
print(qat)
# tensor([-0.8347, -0.8347,  0.2731,  0.2886,  0.2731,  0.2731,  0.2886,  0.2731])

The next example shows the calculation of the electrostatic energy with a simpler API for a batch of structures.

import torch
from tad_multicharge import eeq
from tad_mctc.batch import pack
from tad_mctc.convert import symbol_to_number

# S22 system 4: formamide dimer
numbers = pack(
    (
        symbol_to_number("C C N N H H H H H H O O".split()),
        symbol_to_number("C O N H H H".split()),
    )
)

# coordinates in Bohr
positions = pack(
    (
        torch.tensor(
            [
                [-3.81469488143921, +0.09993441402912, 0.00000000000000],
                [+3.81469488143921, -0.09993441402912, 0.00000000000000],
                [-2.66030049324036, -2.15898251533508, 0.00000000000000],
                [+2.66030049324036, +2.15898251533508, 0.00000000000000],
                [-0.73178529739380, -2.28237795829773, 0.00000000000000],
                [-5.89039325714111, -0.02589114569128, 0.00000000000000],
                [-3.71254944801331, -3.73605775833130, 0.00000000000000],
                [+3.71254944801331, +3.73605775833130, 0.00000000000000],
                [+0.73178529739380, +2.28237795829773, 0.00000000000000],
                [+5.89039325714111, +0.02589114569128, 0.00000000000000],
                [-2.74426102638245, +2.16115570068359, 0.00000000000000],
                [+2.74426102638245, -2.16115570068359, 0.00000000000000],
            ]
        ),
        torch.tensor(
            [
                [-0.55569743203406, +1.09030425468557, 0.00000000000000],
                [+0.51473634678469, +3.15152550263611, 0.00000000000000],
                [+0.59869690244446, -1.16861263789477, 0.00000000000000],
                [-0.45355203669134, -2.74568780438064, 0.00000000000000],
                [+2.52721209544999, -1.29200800956867, 0.00000000000000],
                [-2.63139587595376, +0.96447869452240, 0.00000000000000],
            ]
        ),
    )
)

# total charge of both system
charge = torch.tensor([0.0, 0.0])

# calculate electrostatic energy in Hartree
energy = torch.sum(eeq.get_energy(numbers, positions, charge), -1)

torch.set_printoptions(precision=10)
print(energy)
# tensor([-0.2086755037, -0.0972094536])
print(energy[0] - 2 * energy[1])
# tensor(-0.0142565966)

Contributing

This is a volunteer open source projects and contributions are always welcome. Please, take a moment to read the contributing guidelines.

License

This project is licensed under the Apache License, Version 2.0 (the "License"); you may not use this project's files except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tad_multicharge-0.3.0.tar.gz (20.2 kB view details)

Uploaded Source

Built Distribution

tad_multicharge-0.3.0-py3-none-any.whl (23.8 kB view details)

Uploaded Python 3

File details

Details for the file tad_multicharge-0.3.0.tar.gz.

File metadata

  • Download URL: tad_multicharge-0.3.0.tar.gz
  • Upload date:
  • Size: 20.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for tad_multicharge-0.3.0.tar.gz
Algorithm Hash digest
SHA256 815655a7dc2e732e334703b4db87b306ca8394d11569ebc9797b36216bd48283
MD5 0903a5acdf327f3bf7d74485b9b99d82
BLAKE2b-256 bdd736dc5563908b9d8a36b679af8b16b408e1a8fcfc03a1cb0e257b368a53db

See more details on using hashes here.

File details

Details for the file tad_multicharge-0.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for tad_multicharge-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9962000308da3090663e655a761138d7c8c39a1c120bcd83c9233043df9f8761
MD5 9c1302aee487688da583383d27713dac
BLAKE2b-256 685a72337d2819f8271c6f44f3f1e0e06239fd70d2fb70361691f17f3fc78f14

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page