Skip to main content

DistancePlan

Compute the distance between centers of two selections.

Constructor

from warp_md import DistancePlan

plan = DistancePlan(
    selection_a,
    selection_b,
    mass_weighted=False,
    pbc="none"
)
selection_a
Selection
required
First group of atoms
selection_b
Selection
required
Second group of atoms
mass_weighted
bool
default:"False"
Use center of mass (True) or center of geometry (False)
pbc
str
default:"none"
Periodic boundary conditions: "none" or "orthorhombic"

run() Method

Returns: 1D array of distances in Å (one per frame)

Example

import warp_md as wmd

system = wmd.System("complex.pdb")
traj = wmd.open_trajectory("md.nc", system)

# Distance between protein and ligand
protein = system.select("protein")
ligand = system.select("resname LIG")

plan = wmd.DistancePlan(protein, ligand, mass_weighted=True)
distances = plan.run(traj, system)

print(f"Min distance: {distances.min():.2f} Å")
print(f"Max distance: {distances.max():.2f} Å")

AnglePlan

Compute the angle between three selections.

Constructor

plan = AnglePlan(
    selection_a,
    selection_b,
    selection_c,
    mass_weighted=False,
    pbc="none",
    degrees=True
)
selection_a
Selection
required
First point
selection_b
Selection
required
Vertex (central point)
selection_c
Selection
required
Third point
mass_weighted
bool
default:"False"
Use centers of mass
pbc
str
default:"none"
Periodic boundary conditions
degrees
bool
default:"True"
Return angles in degrees (True) or radians (False)

Example

# Measure domain bending angle
domain_a = system.select("resid 1:50")
hinge = system.select("resid 51:60")
domain_b = system.select("resid 61:120")

plan = wmd.AnglePlan(domain_a, hinge, domain_b, mass_weighted=True)
angles = plan.run(traj, system)

import matplotlib.pyplot as plt
plt.hist(angles, bins=30)
plt.xlabel("Angle (degrees)")
plt.ylabel("Count")
plt.show()

VectorPlan

Compute unit vectors between two selections.

Constructor

plan = VectorPlan(
    selection_a,
    selection_b,
    mass_weighted=False,
    pbc="none",
    normalize=True
)

run() Method

Returns: 2D array of shape (n_frames, 3) containing (x, y, z) components

Example

# Calculate helix axis vector
n_term = system.select("resid 10 and name CA")
c_term = system.select("resid 30 and name CA")

plan = wmd.VectorPlan(n_term, c_term, normalize=True)
vectors = plan.run(traj, system)

# Compute angle with z-axis
import numpy as np
z_axis = np.array([0, 0, 1])
angles = np.arccos(np.dot(vectors, z_axis)) * 180 / np.pi

CenterOfMassPlan

Compute the center of mass for a selection.

Constructor

plan = CenterOfMassPlan(selection)
selection
Selection
required
Atoms to analyze

run() Method

Returns: 2D array of shape (n_frames, 3) with (x, y, z) coordinates in Å

Example

# Track protein center of mass
protein = system.select("protein")
plan = wmd.CenterOfMassPlan(protein)
com_trajectory = plan.run(traj, system)

# Calculate displacement
import numpy as np
displacement = np.linalg.norm(
    com_trajectory - com_trajectory[0], axis=1
)

print(f"Total displacement: {displacement[-1]:.2f} Å")
For center of geometry (unweighted), use the center() helper function from warp_md.analysis.

PrincipalAxesPlan

Calculate principal axes of inertia for a molecular selection. Constructor:
from warp_md import PrincipalAxesPlan

plan = PrincipalAxesPlan(
    selection,          # Selection: atoms for axes calculation
    mass_weighted=True, # bool: use mass-weighted axes
    device="auto"       # str: execution device
)
selection
Selection
required
Atoms for principal axes calculation
mass_weighted
bool
default:"True"
Whether to use mass-weighted inertia tensor
Returns: ndarray[frames, 3, 3] — Principal axes (eigenvectors) for each frame Example:
from warp_md import System, Trajectory, PrincipalAxesPlan

system = System.from_pdb("protein.pdb")
traj = Trajectory.open_xtc("traj.xtc", system)
protein = system.select("protein")

plan = PrincipalAxesPlan(protein, mass_weighted=True)
axes = plan.run(traj, system)

# Analyze alignment of principal axis over time
first_axis = axes[:, 0, :]  # First principal axis
z_alignment = first_axis[:, 2]  # z-component

import matplotlib.pyplot as plt
plt.plot(z_alignment)
plt.xlabel("Frame")
plt.ylabel("z-component of principal axis")
plt.title("Protein Orientation")
plt.show()

DistanceToPointPlan

Calculate distances from a selection to a fixed point in space. Constructor:
from warp_md import DistanceToPointPlan

plan = DistanceToPointPlan(
    selection,          # Selection: atoms to measure from
    point=(0, 0, 0),   # tuple: fixed point coordinates (Å)
    device="auto"       # str: execution device
)
selection
Selection
required
Atoms to measure distances from
point
tuple
default:"(0, 0, 0)"
Fixed point coordinates in Ångströms
Returns: ndarray[frames, atoms] — Distances to point in Ångströms Example:
from warp_md import System, Trajectory, DistanceToPointPlan

system = System.from_pdb("membrane.pdb")
traj = Trajectory.open_xtc("traj.xtc", system)
lipid_heads = system.select("name P")

# Measure distance from membrane center (z=0)
plan = DistanceToPointPlan(lipid_heads, point=(0, 0, 0))
distances = plan.run(traj, system)

# Analyze membrane thickness
upper_leaflet = distances[distances[:, 2] > 0]
lower_leaflet = distances[distances[:, 2] < 0]
thickness = upper_leaflet.mean() + lower_leaflet.mean()
print(f"Membrane thickness: {thickness:.2f} Å")

Additional Geometry Plans

Additional geometry plans are available. Check the complete API list or use warp-md list-plans to see all available Plans with their parameters.Other geometry plans include:
  • LowestCurvePlan — Find trajectory path with minimum curvature
  • CenterOfGeometryPlan — Geometric (unweighted) center
  • DistanceToReferencePlan — Distances to a reference structure
  • RotationMatrixPlan — Calculate rotation matrices between frames

Build docs developers (and LLMs) love