Skip to content

molpy.potential

Potential functions for molecular simulations.

This module provides potential functions for bonds, angles, dihedrals, and pair interactions. Each potential class accepts specific parameters (e.g., r, bond_idx, bond_types) rather than Frame objects, making them more flexible and easier to use in different contexts.

For convenience, utility functions are provided to extract data from Frame objects and call potential functions with the extracted data.

Potential

Base class for all potential functions in MolPy.

This class provides a template for defining potential functions that can be used in molecular simulations. Each potential class should implement calc_energy and calc_forces methods with specific parameters.

calc_energy 

calc_energy(*args, **kwargs)

Calculate the potential energy.

Parameters

args: Arguments specific to the potential type *kwargs: Keyword arguments specific to the potential type

Returns

float The potential energy.

Source code in src/molpy/potential/base.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def calc_energy(self, *args, **kwargs) -> float:
    """
    Calculate the potential energy.

    Parameters
    ----------
    *args: Arguments specific to the potential type
    **kwargs: Keyword arguments specific to the potential type

    Returns
    -------
    float
        The potential energy.
    """
    raise NotImplementedError("Subclasses must implement this method.")

calc_forces 

calc_forces(*args, **kwargs)

Calculate the forces.

Parameters

args: Arguments specific to the potential type *kwargs: Keyword arguments specific to the potential type

Returns

np.ndarray An array of forces.

Source code in src/molpy/potential/base.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def calc_forces(self, *args, **kwargs) -> np.ndarray:
    """
    Calculate the forces.

    Parameters
    ----------
    *args: Arguments specific to the potential type
    **kwargs: Keyword arguments specific to the potential type

    Returns
    -------
    np.ndarray
        An array of forces.
    """
    raise NotImplementedError("Subclasses must implement this method.")

Potentials

Bases: UserList[Potential]

Collection of potential functions.

This class provides a way to combine multiple potentials and calculate total energy and forces. However, since different potentials require different parameters, you need to call calc_energy and calc_forces for each potential separately and sum the results.

For a simpler interface, use the helper functions in potential.utils to extract data from Frame objects.

calc_energy 

calc_energy(*args, **kwargs)

Calculate the total energy by summing energies from all potentials.

Note: This assumes all potentials in the collection accept the same arguments. For different potential types, you should call calc_energy on each potential separately.

Parameters

args: Arguments passed to each potential's calc_energy method *kwargs: Keyword arguments passed to each potential's calc_energy method

Returns

float The total energy.

Source code in src/molpy/potential/base.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def calc_energy(self, *args, **kwargs) -> float:
    """
    Calculate the total energy by summing energies from all potentials.

    Note: This assumes all potentials in the collection accept the same
    arguments. For different potential types, you should call calc_energy
    on each potential separately.

    Parameters
    ----------
    *args: Arguments passed to each potential's calc_energy method
    **kwargs: Keyword arguments passed to each potential's calc_energy method

    Returns
    -------
    float
        The total energy.
    """
    return sum(pot.calc_energy(*args, **kwargs) for pot in self)

calc_forces 

calc_forces(*args, **kwargs)

Calculate the total forces by summing forces from all potentials.

Note: This assumes all potentials in the collection accept the same arguments and return forces with the same shape. For different potential types, you should call calc_forces on each potential separately and sum the results.

Parameters

args: Arguments passed to each potential's calc_forces method *kwargs: Keyword arguments passed to each potential's calc_forces method

Returns

np.ndarray An array of total forces.

Source code in src/molpy/potential/base.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def calc_forces(self, *args, **kwargs) -> np.ndarray:
    """
    Calculate the total forces by summing forces from all potentials.

    Note: This assumes all potentials in the collection accept the same
    arguments and return forces with the same shape. For different potential
    types, you should call calc_forces on each potential separately and
    sum the results.

    Parameters
    ----------
    *args: Arguments passed to each potential's calc_forces method
    **kwargs: Keyword arguments passed to each potential's calc_forces method

    Returns
    -------
    np.ndarray
        An array of total forces.
    """
    if not self:
        raise ValueError(
            "Cannot determine force shape: no potentials in collection"
        )

    # Get forces from first potential to determine shape
    first_forces = self[0].calc_forces(*args, **kwargs)
    total_forces = np.zeros_like(first_forces)

    for pot in self:
        forces = pot.calc_forces(*args, **kwargs)
        total_forces += forces

    return total_forces