Skip to content

Optimization

Geometry optimization using potential energy functions.

Quick reference

Symbol Summary Preferred for
Optimizer Base class driving any calc_energy(frame) / calc_forces(frame) potential Custom optimizers
OptimizationResult Result record (final frame, energy, convergence info) Inspecting outcomes
LBFGS Limited-memory BFGS optimizer Geometry relaxation of small/medium structures
ForceFieldPotential Wraps a molrs ForceField (via ff.to_potentials(frame)) as an optimizer potential Optimizing with force-field energies/forces
  • Potential -- energy/force implementations used by optimizers

Full API

Base

base

Base classes for geometry optimization.

The optimizer operates directly on a :class:molrs.Frame — the universal coordinate-plus-topology container. run(frame, ...) reads and writes the frame's "atoms" coordinate columns in place and returns an :class:OptimizationResult carrying the optimized frame. The potential (:class:~molpy.optimize.ForceFieldPotential) is the Frame-consuming layer, so both the optimizer and the potential share the same Frame object.

OptimizationResult dataclass 

OptimizationResult(
    frame, energy, fmax, nsteps, converged, reason
)

Result of a geometry optimization.

Attributes:

Name Type Description
frame Frame

Final optimized molrs.Frame (same object when inplace=True).
energy float

Final potential energy (force-field units, e.g. kcal/mol).
fmax float

Final maximum force component (energy units / angstrom).
nsteps int

Number of optimization steps taken.
converged bool

Whether the convergence criterion was met.
reason str

Human-readable termination reason.

Optimizer 

Optimizer(potential, *, entity_type=Entity)

Bases: ABC

Base class for Frame-native geometry optimizers.

The optimizer reads/writes the coordinate columns of a molrs.Frame's "atoms" block and evaluates energy/forces by calling the potential on the same frame (potential.calc_energy(frame) / calc_forces(frame)). The frame is the optimized state — there is no structure-to-frame conversion.

Parameters:

Name Type Description Default
potential PotentialLike

Potential exposing calc_energy(frame) / calc_forces(frame).

 required
entity_type type[Entity]

Retained for backward-compatible construction; unused (the frame's atom block is the single source of coordinates).

 Entity
Example

from molpy.optimize import LBFGS, ForceFieldPotential

potential = ForceFieldPotential(forcefield) # molrs ForceField opt = LBFGS(potential, maxstep=0.04, memory=20) result = opt.run(frame, fmax=0.01, steps=500) # frame: molrs.Frame

attach 
attach(func, interval=1, **kwargs)

Attach a callback func(optimizer, frame, **kwargs) called every interval steps.

get_energy 
get_energy(frame)

Return the potential energy of the frame.

get_energy_and_forces 
get_energy_and_forces(frame)

Evaluate energy and forces by calling the potential on the frame.

get_forces 
get_forces(frame)

Return the forces on the frame's atoms.

get_positions 
get_positions(frame)

Return the frame's atom positions as an (N, 3) array.

run 
run(frame, fmax=0.01, steps=1000, *, inplace=True)

Optimize frame until convergence or steps is reached.

Parameters:

Name Type Description Default
frame Frame

molrs.Frame to optimize.

 required
fmax float

Convergence threshold on the maximum force component.

 0.01
steps int

Maximum number of steps.

 1000
inplace bool

If True, mutate frame; if False, optimize a frame.copy().

 True

Returns:

Type Description
OptimizationResult

class:OptimizationResult whose frame is the optimized frame.
set_positions 
set_positions(frame, positions)

Write an (N, 3) (or flat 3N) position array into the frame.

Uses Block.insert (an upsert), which both molrs Block variants support — the rich molrs.frame.Block (from Atomistic.to_frame) and the raw core Block (from MMFFTypifier.typify) — so the optimizer is agnostic to how the frame was built.

step abstractmethod 
step(frame)

Perform one optimization step, mutating the frame's coordinates.

Parameters:

Name Type Description Default
frame Frame

molrs.Frame to optimize (modified in-place).

 required

Returns:

Type Description
tuple[float, float]

(energy, fmax) after the step.

PotentialLike

Bases: Protocol

Protocol for potential functions evaluated on a :class:molrs.Frame.

LBFGS

lbfgs

L-BFGS geometry optimizer.

LBFGS 

LBFGS(
    potential,
    *,
    maxstep=0.04,
    memory=20,
    damping=1.0,
    entity_type=None,
)

Bases: Optimizer

Limited-memory BFGS geometry optimizer.

Implements the L-BFGS algorithm for quasi-Newton optimization with limited memory storage. Uses two-loop recursion to compute search directions efficiently.

Parameters:

Name Type Description Default
potential Potential

Potential with calc_energy/calc_forces methods.

 required
maxstep float

Maximum step size (as displacement norm).

 0.04
memory int

Number of previous steps to store for Hessian approximation.

 20
damping float

Damping factor for step size.

 1.0
entity_type type[Entity]

Type of entity to optimize.

 None

Attributes:

Name Type Description
maxstep

Maximum allowed step size
memory

LBFGS memory size
damping

Step damping factor
s_history list[ndarray]

Position difference history
y_history list[ndarray]

Gradient difference history
rho_history list[float]

Curvature history (1 / y·s)
Example

from molpy.optimize import LBFGS, ForceFieldPotential

potential = ForceFieldPotential(forcefield) # molrs ForceField opt = LBFGS(potential, maxstep=0.04, memory=20) result = opt.run(frame, fmax=0.01, steps=500) # frame: molrs.Frame

step 
step(frame)

Perform one L-BFGS optimization step on a frame.

Parameters:

Name Type Description Default
frame Frame

molrs.Frame to optimize (coordinate columns modified in-place).

 required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: (energy, fmax) where energy is the potential energy after the step and fmax is the maximum force component.

ForceField Potential

forcefield_potential

Adapter exposing a molrs ForceField as an optimizer potential.

The optimizer base (:class:molpy.optimize.base.Optimizer) drives any object that answers calc_energy(frame) / calc_forces(frame). molrs's native :class:molrs.Potentials instead consumes flat coordinate vectors and must be recompiled against the current frame each step (geometry changes while the topology/types stay fixed). This thin adapter bridges the two: it compiles the force field against the live frame and evaluates energy/forces from the frame's coordinates.

ForceFieldPotential 

ForceFieldPotential(forcefield)

Evaluate a molrs :class:~molrs.ForceField from a :class:~molrs.Frame.

Parameters:

Name Type Description Default
forcefield ForceField

A molrs ForceField whose styles/types are fully defined. The frame passed to :meth:calc_energy / :meth:calc_forces must carry type columns whose values match the force field's type names (e.g. a bond labelled "OW-HW").

 required
calc_energy 
calc_energy(frame)

Return the total potential energy for frame.

calc_forces 
calc_forces(frame)

Return the per-atom forces for frame as an (N, 3) array.