Metadata-Version: 2.1
Name: openmm-nonbonded-slicing
Version: 0.4.0.post1
Summary: An OpenMM plugin for slicing nonbonded interactions
Home-page: https://github.com/craabreu/openmm-nonbonded-slicing
Author: Charlles Abreu
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openmm<8.6,>=8.5.2
Provides-Extra: cuda12
Requires-Dist: openmm-nonbonded-slicing-cuda-12==0.4.0.post1; platform_system == "Linux" and extra == "cuda12"
Provides-Extra: cuda13
Requires-Dist: openmm-nonbonded-slicing-cuda-13==0.4.0.post1; platform_system == "Linux" and extra == "cuda13"

OpenMM Nonbonded Slicing Plugin
===============================

[![Linux](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/Linux.yml/badge.svg)](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/Linux.yml)
[![MacOS](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/MacOS.yml/badge.svg)](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/MacOS.yml)
[![Doc](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/Doc.yml/badge.svg)](https://github.com/craabreu/openmm-nonbonded-slicing/actions/workflows/Doc.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

This [OpenMM] plugin contains the **SlicedNonbondedForce** class, a variant of OpenMM's [NonbondedForce].
By partitioning all particles among $`n`$ disjoint subsets, the total potential energy becomes a linear
combination of contributions from pairs of subsets like

```math
E = \sum_{I=0}^{n-1} \sum_{J=I}^{n-1} \left( \lambda^{vdW}_{I,J}E^{vdW}_{I,J}+\lambda^{elec}_{I,J}E^{elec}_{I,J} \right)
```

where each slice is defined by subsets $`I`$ and $`J`$, superscripts _vdW_ and _elec_ denote van
der Waals and electrostatic contributions, $`E_{I,J}`$ is the potential energy of all particle pairs
formed by one particle in subset $`I`$ and one in subset $`J`$, and $`\lambda_{I,J}`$ is a scaling parameter.

By default, all scaling parameters are constant and equal to 1. However, the user can turn selected
scaling parameters into variables and store their values in [Context] global parameters. Derivatives
with respect to these variables can be requested and used, for instance, to report individual energy
slice contributions or sums thereof via [getState] with options `getEnergy=True` and
`getParameterDerivatives=True`. Derivatives are only computed along with the energy: without
`getEnergy=True`, they are NaN.

A global parameter can scale the electrostatic contributions, the van der Waals contributions, or
both, of any number of slices. Since the energy is linear in the scaling parameters, the derivative
with respect to a parameter $`\lambda`$ is the sum of the unscaled contributions it multiplies:

```math
\frac{\partial E}{\partial \lambda} = \sum_{(I,J) \in S^{elec}_\lambda} E^{elec}_{I,J} + \sum_{(I,J) \in S^{vdW}_\lambda} E^{vdW}_{I,J}
```

where $`S^{elec}_\lambda`$ and $`S^{vdW}_\lambda`$ are the sets of slices whose electrostatic and van der
Waals contributions are scaled by $`\lambda`$. This derivative does not depend on the values of the
scaling parameters. For instance, a parameter that scales both contributions of a single slice $`I, J`$
yields its full energy $`E^{vdW}_{I,J}+E^{elec}_{I,J}`$, while one that scales the electrostatic
contributions of several slices yields their sum.

Documentation
=============

Documentation for this plugin is available at [Github Pages](https://craabreu.github.io/openmm-nonbonded-slicing/).
It includes the Python API and the theory for slicing lattice-sum energy contributions.

Installation
============

The plugin is distributed on [conda-forge]:

```bash
mamba install -c conda-forge openmm-nonbonded-slicing
```

and on [PyPI], for Linux x86_64 and macOS (Apple Silicon and Intel) with Python 3.10–3.14:

```bash
pip install openmm-nonbonded-slicing            # Reference and OpenCL platforms
pip install openmm-nonbonded-slicing[cuda12]    # plus the CUDA platform (Linux, CUDA 12)
pip install openmm-nonbonded-slicing[cuda13]    # plus the CUDA platform (Linux, CUDA 13)
```

Each PyPI release is published once per supported OpenMM version. pip installs the newest one,
upgrading OpenMM if needed; to keep an older OpenMM, pin it in the same command, for example
`pip install "openmm==8.5.*" openmm-nonbonded-slicing`:

| PyPI release  | OpenMM |
|---------------|--------|
| `X.Y.Z`       | 8.4    |
| `X.Y.Z.post1` | 8.5    |
| `X.Y.Z.post2` | 8.6    |

On Intel Macs, OpenMM 8.6 from PyPI only works with Python 3.10, so pip installs the OpenMM 8.5
release there for Python 3.11 and later.

Instructions for building from source are in the [documentation](https://craabreu.github.io/openmm-nonbonded-slicing/).

Usage
=====

```py
import openmm as mm
import nonbondedslicing as nbs
system = mm.System()
force = nbs.SlicedNonbondedForce(2)
system.addForce(force)
```


[NonbondedForce]:       http://docs.openmm.org/latest/api-python/generated/openmm.openmm.NonbondedForce.html
[Context]:              http://docs.openmm.org/latest/api-python/generated/openmm.openmm.Context.html
[getState]:             http://docs.openmm.org/latest/api-python/generated/openmm.openmm.Context.html#openmm.openmm.Context.getState
[OpenMM]:               https://openmm.org
[conda-forge]:          https://anaconda.org/conda-forge/openmm-nonbonded-slicing
[PyPI]:                 https://pypi.org/project/openmm-nonbonded-slicing
