Skip to main content

​
Overview

The OPT task relaxes atomic positions and (optionally) the unit cell of an Atoms object using an ASE optimizer. It is registered as a Prefect task with the name OPT and uses a TASK_SOURCE + INPUTS cache policy so that identical inputs reuse previously computed results.

​
Function signature

from mlip_arena.tasks.optimize import run as OPT

result = OPT(
    atoms,
    calculator,
    optimizer=BFGSLineSearch,
    optimizer_kwargs=None,
    filter=None,
    filter_kwargs=None,
    criterion=None,
    symmetry=False,
)

​
Parameters

​
body.atoms
ase.Atoms
required
The input atomic structure. A copy is made internally so the original object is not mutated.
​
body.calculator
ase.calculators.calculator.BaseCalculator
required
The ASE-compatible calculator used to evaluate energies and forces.
​
body.optimizer
Optimizer | str
default:"BFGSLineSearch"
Optimizer class or string name. Supported string values: "MDMin", "FIRE", "FIRE2", "LBFGS", "LBFGSLineSearch", "BFGS", "BFGSLineSearch", "QuasiNewton", "GPMin", "CellAwareBFGS", "ODE12r".
​
body.optimizer_kwargs
dict | None
default:"None"
Extra keyword arguments forwarded to the optimizer constructor.
​
body.filter
Filter | str | None
default:"None"
ASE filter (cell/strain wrapper) applied around atoms before passing to the optimizer. Supported string values: "Filter", "UnitCell", "ExpCell", "Strain", "FrechetCell". Set to None to optimize atomic positions only.
​
body.filter_kwargs
dict | None
default:"None"
Extra keyword arguments forwarded to the filter constructor.
​
body.criterion
dict | None
default:"None"
Convergence criteria passed to optimizer.run(). Defaults to {"steps": 1000} when None. Common keys include fmax (force threshold in eV/Å) and steps (maximum number of steps).
​
body.symmetry
boolean
default:"false"
When True, applies an ASE FixSymmetry constraint so that the crystal symmetry is preserved throughout the relaxation.

​
Return value

{
    "atoms": Atoms,   # relaxed structure
    "steps": int,     # number of optimizer steps taken
    "converged": bool # whether convergence criterion was met
}
​
atoms
ase.Atoms
The relaxed atomic structure with the calculator attached.
​
steps
int
Total number of optimizer steps performed.
​
converged
bool
True if the optimizer reached the convergence criterion before exhausting the step budget.

​
Prefect task behavior

  • Task name: OPT
  • Run name: generated as OPT: <formula> - <calculator>.
  • Cache policy: TASK_SOURCE + INPUTS — results are cached based on the task source code and all input values. Identical calls return the cached result without re-running.
  • Retries: none by default (use OPT.with_options(retries=N) to add retries).
  • Submittable: call OPT.submit(...) to run asynchronously inside a Prefect flow.

​
Example

from ase.build import bulk
from mlip_arena.models import MLIPEnum
from mlip_arena.tasks.optimize import run as OPT
from mlip_arena.tasks.utils import get_calculator

# Build a simple FCC copper cell
atoms = bulk("Cu", "fcc", a=3.6)

# Get calculator for MACE-MP(M)
calculator = get_calculator(MLIPEnum["MACE-MP(M)"])

# Relax atomic positions AND cell shape with FrechetCell filter
result = OPT(
    atoms=atoms,
    calculator=calculator,
    optimizer="BFGS",
    filter="FrechetCell",
    criterion={"fmax": 0.01, "steps": 500},
    symmetry=True,
)

print(result["converged"])  # True / False
print(result["steps"])      # steps taken
print(result["atoms"])      # relaxed Atoms