Geometry Optimization with Tako Script

tako.optimize changes atomic coordinates and, when requested, selected cell degrees of freedom until its force-based convergence condition is met or its step budget is exhausted. It returns a promise and creates an Opt-<N>-calc workspace.

The algorithmic theory is in Geometry Optimization. This chapter defines Script construction, branching, and output handling.

Operation contract

const result = await tako.optimize(structure, {
  calculator,
  properties,
  optimizer,
  maxSteps,
  fmaxEvPerAngstrom,
  maxstepAngstrom,
  alpha,
  trajectoryFrameInterval,
  cellRelaxation,
});

The generated tako.optimize settings reference is authoritative for accepted values and validation.

Fixed-cell molecular relaxation

const input = await tako.input("input/structure.extxyz");
const calculator = tako.calculator.gfn2({
  levelOfTheory: "gfn2",
  dispersion: "d4",
  charge: 0,
  unpaired: 0,
});

const properties = ["energy", "forces"];
const check = calculator.validate("optimization", { properties });
if (!check.ok) throw new Error(check.reasons.join("; "));

const result = await tako.optimize(input, {
  calculator,
  properties,
  optimizer: "bfgs",
  maxSteps: 300,
  fmaxEvPerAngstrom: 0.01,
  maxstepAngstrom: 0.04,
});

if (!result.converged) {
  throw new Error(
    `Optimization stopped unconverged after ${result.steps} steps; ` +
    `final fmax=${result.final_fmax_ev_per_angstrom} eV/A`,
  );
}

const finalStructure = tako.analysis.finalStructure(input, result);
await tako.output("output/final.extxyz", finalStructure);
await tako.output("output/result.json", result);

The explicit convergence branch is part of the scientific contract. A normally resolved promise can contain converged: false after the step budget is exhausted.

Variable-cell relaxation

const input = await tako.input("input/crystal.extxyz");
const calculator = tako.calculator.mlip({ levelOfTheory: "nequix" });
const properties = ["energy", "forces", "stress"];

const check = calculator.validate("optimization", { properties });
if (!check.ok) throw new Error(check.reasons.join("; "));

const result = await tako.optimize(input, {
  calculator,
  properties,
  optimizer: "bfgs",
  maxSteps: 300,
  fmaxEvPerAngstrom: 0.02,
  maxstepAngstrom: 0.04,
  cellRelaxation: {
    mode: "custom",
    relaxLengths: [true, true, false],
    relaxAngles: [false, false, false],
  },
});

if (!result.converged) throw new Error("Variable-cell relaxation did not converge.");
await tako.output("output/relaxed.extxyz", tako.analysis.finalStructure(input, result));
await tako.output("output/cell-summary.json", {
  cell: result.cell,
  stressEvPerAngstrom3: result.stress_ev_per_angstrom3,
  finalFmaxEvPerAngstrom: result.final_fmax_ev_per_angstrom,
});

relaxLengths and relaxAngles contain three booleans each. They define the released cell subspace; they are not post-processing filters. A nonperiodic structure cannot be cell-relaxed.

Selective dynamics

Apply Cartesian mobility flags to a new structure before calling the optimizer:

let constrained = tako.structure.fix(input, [0, 1, 2, 3]);
constrained = tako.structure.fix(constrained, [4], {
  move: [false, false, true],
});

Omitting move freezes all components of the listed atoms. In move, true means that component is free. Retain the constrained input artifact: the final coordinates alone do not reveal which degrees of freedom were excluded.

The current optimization convergence trace can include raw force on frozen atoms, so a plateau can reflect anchor forces rather than genuine convergence. Report the constrained-force convention and inspect free-atom motion.

Result schema

tako.analysis.energyEv(result) refuses an explicitly unconverged result. tako.analysis.finalStructure(input, result) reconstructs the final structure without asserting convergence; call it only inside an explicit branch whose purpose is clear.

Staged continuation

async function optimizeStage(input, settings) {
  const result = await tako.optimize(input, settings);
  return {
    result,
    structure: tako.analysis.finalStructure(input, result),
  };
}

const coarse = await optimizeStage(input, {
  calculator,
  properties: ["energy", "forces"],
  optimizer: "fire",
  maxSteps: 300,
  fmaxEvPerAngstrom: 0.05,
  maxstepAngstrom: 0.02,
});

if (!coarse.result.converged) {
  throw new Error("Coarse stage did not reach its declared gate.");
}

const fine = await optimizeStage(coarse.structure, {
  calculator,
  properties: ["energy", "forces"],
  optimizer: "bfgs",
  maxSteps: 300,
  fmaxEvPerAngstrom: 0.01,
  maxstepAngstrom: 0.04,
});

if (!fine.result.converged) throw new Error("Fine stage did not converge.");
await tako.output("output/final.extxyz", fine.structure);
await tako.output("output/stages.json", {
  coarse: coarse.result,
  fine: fine.result,
});

The second call begins from the first geometry but starts a new optimizer workspace and curvature state. Retaining both results prevents the staged history from being mistaken for one uninterrupted BFGS trajectory.

Failure handling

Cancellation rejects with Canceled by user and is not a numerical checkpoint. A later optimization can begin from an explicitly saved structure, but it does not resume the cancelled optimizer’s internal state.