Electrostatics

Compute screened Coulomb pair energies and electrostatic potential.

from proteinmotion import Electrostatics

Constructor

Electrostatics(
    protein,
    charges='formal',
    *,
    dielectric=80,
    screening_length=8,
    cutoff=12,
    min_energy=0.05,
    exclude_same_residue=True,
    exclude_bonded=True,
)

Parameters

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`charges`	`'formal'`	"formal" side-chain templates or one charge per atom, in elementary charge units.
`dielectric`keyword only	`80`	Positive relative dielectric constant.
`screening_length`keyword only	`8`	Positive exponential screening length in ångströms; None disables screening.
`cutoff`keyword only	`12`	Distance cutoff in ångströms.
`min_energy`keyword only	`0.05`	Minimum absolute pair energy to include, in kcal/mol.
`exclude_same_residue`keyword only	`True`	Exclude pairs within the same residue.
`exclude_bonded`keyword only	`True`	Exclude directly bonded pairs.

Notes

Energy units are kcal/mol; potential units are kcal/mol per elementary charge. Formal charge templates illustrate charged side chains. Import atom charges for a prepared protonation state. This model uses a uniform dielectric and exponential screening.

Example and output

This excerpt runs inside a scene’s construct() method. The full example file includes imports, structure loading, and camera setup. Run it from a repository checkout.

Code Scene excerpt

p = ubiquitin().ball_and_stick()
field = Electrostatics(
    p,
    charges="formal",
    dielectric=80,
    screening_length=8,
    cutoff=6,
    min_energy=0.08,
)
pair = field.pairs[0]
endpoints = Region(p, [pair.a, pair.b])
residues = [p.topology.atoms[i].resid for i in (pair.a, pair.b)]
selected = p.select(residues=residues)
other = Region(p, np.setdiff1d(np.arange(len(p.topology.atoms)), selected.atom_indices))
other.set_opacity(0.06)
frame(self, p, endpoints, margin=4.5)
contacts = field.highlight(
    mode="2d",
    max_pairs=1,
    show_distances=True,
    font_size=42,
    style="solid",
    line_width=2,
)
self.play(Write(contacts), run_time=1.5)
self.play(self.camera.animate.orbit(0.5), run_time=3)
self.wait(1)

Output Preview · 5.5 s · 60 fps

Electrostatic contact

Screened Coulomb estimate using example formal charges.

Full source: ChargeContacts Download MP4

Methods and properties

Name	Description
from_pqr()class method	Load exact-identity PQR charges and create an electrostatic analysis.
pair_energy()method	Evaluate screened Coulomb energy for two atom indices.
potential()method	Sum the electrostatic potential from all charges at sample points.
pairsproperty · inherited from _Analysis	Tuple of Interaction records recomputed when coordinates or analysis settings change.
highlight()method · inherited from _Analysis	Create styled electrostatic contact lines. Options go to InteractionHighlight.

from_pqr()

View source

Electrostatics.from_pqr(protein, path, *, allow_extra=False, **kwargs)

Load exact-identity PQR charges and create an electrostatic analysis.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`path`	Required	Input or output file path, as specified by the operation.
`allow_extra`keyword only	`False`	Permit additional PQR records after every protein atom has an exact match.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Returns: Electrostatics

pair_energy()

View source

Electrostatics.pair_energy(a, b)

Evaluate screened Coulomb energy for two atom indices.

Parameter	Default	Description
`a`	Required	Zero-based first atom index.
`b`	Required	Zero-based second atom index.

Returns: Energy in kcal/mol.

potential()

View source

Electrostatics.potential(points, *, softening=1.0, chunk_size=2048)

Sum the electrostatic potential from all charges at sample points.

Parameter	Default	Description
`points`	Required	Coordinates with shape (points, 3), in model ångströms.
`softening`keyword only	`1.0`	Plummer softening length in ångströms.
`chunk_size`keyword only	`2048`	Number of potential sample points processed together.

Returns: Array in kcal/mol per elementary charge.

Uses Plummer softening and includes all charges, independently of the pair cutoff.

pairs

View source

Inherited from interactions._Analysis.

Electrostatics.pairs

Tuple of Interaction records recomputed when coordinates or analysis settings change.

highlight()

View source

Inherited from interactions._Analysis.

Electrostatics.highlight(**kwargs)

Create styled electrostatic contact lines. Options go to InteractionHighlight.

Parameter	Default	Description
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Returns: InteractionHighlight