Skip to content

kups.potential.classical.coulomb

Coulomb electrostatic potential for vacuum/non-periodic systems.

This module provides a simple pairwise Coulomb potential for charged systems without periodic boundary conditions. For periodic systems with long-range electrostatics, use Ewald summation instead.

Potential: \(U = \frac{1}{4\pi\epsilon_0} \sum_{i<j} \frac{q_i q_j}{r_{ij}}\)

coulomb_vacuum_energy(inp)

Compute Coulomb electrostatic energy for vacuum systems.

Calculates pairwise electrostatic energy using Coulomb's law over all charge pairs in each (vacuum) system. Accounts for double counting.

Parameters:

Name Type Description Default
inp CoulombVacuumInput

Graph potential input.

 required

Returns:

Type Description
WithPatch[Table[SystemId, Energy], IdPatch[Any]]

Total electrostatic energy per system.
Source code in src/kups/potential/classical/coulomb.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def coulomb_vacuum_energy(
    inp: CoulombVacuumInput,
) -> WithPatch[Table[SystemId, Energy], IdPatch[Any]]:
    """Compute Coulomb electrostatic energy for vacuum systems.

    Calculates pairwise electrostatic energy using Coulomb's law over all
    charge pairs in each (vacuum) system. Accounts for double counting.

    Args:
        inp: Graph potential input.

    Returns:
        Total electrostatic energy per system.
    """
    return _pairwise_coulomb_energy(inp)

make_coulomb_vacuum_potential(particles_view, systems_view, neighborlist_view, probe, gradient_lens, hessian_lens, hessian_idx_view, patch_idx_view=None, out_cache_lens=None)

Create simple Coulomb potential for non-periodic systems.

Computes pairwise electrostatic interactions using Coulomb's law. Suitable for gas-phase or cluster systems. For periodic/bulk systems, use Ewald summation for proper treatment of long-range electrostatics.

Parameters:

Name Type Description Default
particles_view View[State, Table[ParticleId, IsCoulombGraphParticles]]

Extracts indexed particle data (positions, charges, system index)

 required
systems_view View[State, Table[SystemId, HasCell[Vacuum]]]

Extracts indexed system data (cell)

 required
neighborlist_view View[State, NeighborList[Literal[2]]]

Extracts a cutoff-bound neighbor list

 required
probe Probe[State, Ptch, IsGraphProbe[IsCoulombGraphParticles, Literal[2]]] | None

Grouped probe for incremental updates (particles, neighborlist_after, neighborlist_before)

 required
gradient_lens Lens[CoulombVacuumInput, Gradients]

Specifies gradients to compute

 required
hessian_lens Lens[Gradients, Hessians]

Specifies Hessians to compute

 required
hessian_idx_view View[State, Hessians]

Hessian index structure

 required
patch_idx_view View[State, PotentialOut[Gradients, Hessians]] | None

Cached output index structure (optional)

 None
out_cache_lens Lens[State, PotentialOut[Gradients, Hessians]] | None

Cache location lens (optional)

 None

Returns:

Type Description
Potential[State, Gradients, Hessians, Ptch]

Coulomb potential for vacuum.
Source code in src/kups/potential/classical/coulomb.py 
 96
 97
 98
 99
100
101
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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def make_coulomb_vacuum_potential[
    State,
    Ptch: Patch[Any],
    Gradients,
    Hessians,
](
    particles_view: View[State, Table[ParticleId, IsCoulombGraphParticles]],
    systems_view: View[State, Table[SystemId, HasCell[Vacuum]]],
    neighborlist_view: View[State, NeighborList[Literal[2]]],
    probe: Probe[State, Ptch, IsGraphProbe[IsCoulombGraphParticles, Literal[2]]] | None,
    gradient_lens: Lens[CoulombVacuumInput, Gradients],
    hessian_lens: Lens[Gradients, Hessians],
    hessian_idx_view: View[State, Hessians],
    patch_idx_view: View[State, PotentialOut[Gradients, Hessians]] | None = None,
    out_cache_lens: Lens[State, PotentialOut[Gradients, Hessians]] | None = None,
) -> Potential[State, Gradients, Hessians, Ptch]:
    """Create simple Coulomb potential for non-periodic systems.

    Computes pairwise electrostatic interactions using Coulomb's law. Suitable for
    gas-phase or cluster systems. For periodic/bulk systems, use
    [Ewald summation][kups.potential.classical.ewald] for proper treatment of
    long-range electrostatics.

    Args:
        particles_view: Extracts indexed particle data (positions, charges, system index)
        systems_view: Extracts indexed system data (cell)
        neighborlist_view: Extracts a cutoff-bound neighbor list
        probe: Grouped probe for incremental updates (particles, neighborlist_after, neighborlist_before)
        gradient_lens: Specifies gradients to compute
        hessian_lens: Specifies Hessians to compute
        hessian_idx_view: Hessian index structure
        patch_idx_view: Cached output index structure (optional)
        out_cache_lens: Cache location lens (optional)

    Returns:
        Coulomb potential for vacuum.
    """
    radius_graph_fn = GraphConstructor(
        particles=particles_view,
        systems=systems_view,
        neighborlist=neighborlist_view,
        probe=probe,
    )
    composer = LocalGraphSumComposer(
        graph_constructor=radius_graph_fn,
        parameter_view=lambda _: None,
    )
    potential = PotentialFromEnergy(
        composer=composer,
        energy_fn=coulomb_vacuum_energy,
        gradient_lens=gradient_lens,
        hessian_lens=hessian_lens,
        hessian_idx_view=hessian_idx_view,
        cache_lens=out_cache_lens,
        patch_idx_view=patch_idx_view,
    )
    return potential