gpr_optim

Python bindings for GPR atomic dimer saddle point searches.

Classes

GPRCalculator

ASE-compatible calculator with GPR surrogate acceleration.

Functions

default_parameters()

Return a dict of all InputParameters with their C++ defaults.

default_gpr_parameters()

Return a dict of GP-relevant parameters with sensible defaults.

preset_parameters([name])

Return a parameter dict with preset values for common use cases.

run_dimer(params, initial_obs, mid_point_obs, ...)

Run an atomic dimer saddle point search.

ase_potential(atoms)

Create a potential callback from an ASE Atoms object.

atoms_config_from_ase(atoms[, frozen_indices])

Create an AtomsConfiguration from an ASE Atoms object.

observation_from_ase(atoms_list)

Create an Observation from a list of ASE Atoms objects.

Package Contents

gpr_optim.default_parameters()

Return a dict of all InputParameters with their C++ defaults.

Modify the returned dict and pass it to run_dimer().

The keys correspond directly to the InputParameters struct fields in the C++ code. Array-valued parameters (R_init, G_init, orient_init, param_trans, dist_sp, cell_dimensions) must be numpy arrays of the correct size.

Returns

paramsdict

A dictionary with all default parameter values.

gpr_optim.default_gpr_parameters()

Return a dict of GP-relevant parameters with sensible defaults.

This is the minimal parameter set needed to construct and train a GaussianProcessRegression model without running a dimer search. Modify the returned dict and pass it to GaussianProcessRegression.initialize().

Returns

paramsdict

Dictionary with GP-specific default parameter values.

gpr_optim.preset_parameters(name='default')

Return a parameter dict with preset values for common use cases.

Presets override specific keys of default_parameters():

  • "default" – same as default_parameters()

  • "fast" – fewer iterations, looser convergence

  • "accurate" – more iterations, tighter convergence

Parameters

namestr

Preset name.

Returns

params : dict

gpr_optim.run_dimer(params, initial_obs, mid_point_obs, orientation, atoms_config, potential_fn)

Run an atomic dimer saddle point search.

This is a convenience wrapper that creates the C++ objects and executes the GPR dimer algorithm in a single call.

Parameters

paramsdict

Parameter dictionary. Start from default_parameters() and override the keys you need. At a minimum you should set:

  • dimer_sep – dimer separation distance

  • T_dimer – force convergence threshold

  • num_bigiter – max outer iterations

  • num_iter – max inner iterations

  • method_rot – rotation method ("LBFGS_alg")

  • method_trans – translation method ("LBFGS_alg")

  • param_trans – [step_length, max_step_length]

  • cell_dimensions – 3x3 cell as flat 9-element array

initial_obsObservation

Initial observation data. Set R to the initial coordinates (shape (N_obs, 3*N_atoms)), E to energies (shape (N_obs, 1)), and G to gradients (shape (N_obs, 3*N_atoms)).

mid_point_obsObservation

Observation at the dimer mid-point (same field layout as initial_obs but with a single row).

orientationnumpy.ndarray

Initial dimer orientation, shape (1, 3*N_moving).

atoms_configAtomsConfiguration

Atomic configuration. Set positions (shape (1, 3*N_atoms)), is_frozen (shape (1, N_atoms), dtype uint8), id (shape (1, N_atoms), dtype uint32), and atomic_nrs (shape (1, N_atoms), dtype int32).

potential_fncallable

A potential energy callback. Use ase_potential() to create one from an ASE calculator, or provide a function with signature fn(positions, atomic_numbers, forces, box) -> energy.

Returns

dimerAtomicDimer

The converged dimer object. Retrieve results with:

  • dimer.get_final_energy()

  • dimer.get_final_coord_of_mid_point()

  • dimer.get_final_force_at_mid_point()

  • dimer.get_final_curvature()

  • dimer.get_total_force_calls()

  • dimer.get_iterations()

gpr_optim.ase_potential(atoms)

Create a potential callback from an ASE Atoms object.

The returned callable has the signature expected by PotentialWrapper:

fn(positions, atomic_numbers, forces, box) -> energy

The Atoms object is updated in-place on every call (positions and cell are overwritten), so the same object can be inspected after the search completes.

Parameters

atomsase.Atoms

An ASE Atoms object with a calculator attached. The calculator must support get_potential_energy() and get_forces().

Returns

potential_fncallable

A function suitable for passing to PotentialWrapper or run_dimer().

Raises

ImportError

If ASE is not installed.

ValueError

If atoms has no calculator attached.

Examples

>>> from ase.build import molecule
>>> from ase.calculators.emt import EMT
>>> h2 = molecule("H2")
>>> h2.calc = EMT()
>>> pot_fn = ase_potential(h2)
gpr_optim.atoms_config_from_ase(atoms, frozen_indices=None)

Create an AtomsConfiguration from an ASE Atoms object.

Parameters

atomsase.Atoms

ASE Atoms object.

frozen_indicesarray-like of int, optional

Indices of atoms to mark as frozen. If None, all atoms are treated as moving.

Returns

atoms_config : AtomsConfiguration

gpr_optim.observation_from_ase(atoms_list)

Create an Observation from a list of ASE Atoms objects.

Each Atoms object must have energy and forces already computed (e.g. via atoms.get_potential_energy() / atoms.get_forces()).

Parameters

atoms_listlist of ase.Atoms

Atoms objects with calculators that have been evaluated.

Returns

obs : Observation

class gpr_optim.GPRCalculator(inner_calc, variance_threshold=0.0001, max_training_points=100, gpr_params=None, retrain_interval=5)

ASE-compatible calculator with GPR surrogate acceleration.

Wraps an inner calculator (e.g. EMT, VASP) and trains a Gaussian process model on observed energy/force evaluations. When the GP prediction variance is below a threshold, returns the GP prediction instead of calling the inner calculator.

This integrates transparently with ASE’s dimer method:

from ase.mep import DimerControl, MinModeAtoms, MinModeTranslate

atoms.calc = GPRCalculator(inner_calc=EMT(), variance_threshold=1e-4)
d_atoms = MinModeAtoms(atoms, DimerControl(...))
MinModeTranslate(d_atoms).run(fmax=0.01)

Parameters

inner_calcase.calculators.calculator.Calculator

The expensive calculator to accelerate.

variance_thresholdfloat

Maximum acceptable GP variance. If the predicted variance exceeds this, the inner calculator is called instead.

max_training_pointsint

Maximum number of training points to keep in the GP model.

gpr_paramsdict, optional

Parameters for the GP model. Defaults to default_gpr_parameters().

retrain_intervalint

Retrain hyperparameters every N inner calculator calls.

property total_inner_calls

Number of times the inner calculator was called.

property total_gpr_calls

Number of times the GP surrogate was used.

calculate(atoms=None, properties=None, system_changes=None)

Compute energy and forces, using GP when confident.

Parameters

atomsase.Atoms

Atoms object to evaluate.

propertieslist of str

Properties to compute (ignored, always computes energy+forces).

system_changeslist of str

What changed since last call (ignored).