tako.optimize Settings

Page type: Reference · Generated from src/script/takoScriptDocs.ts · Verified 2026-07-11T00:00:00.000Z

On this page

tako.optimize

This page is generated from code-owned Doxygen-style metadata in src/script/takoScriptDocs.ts. Update that file first, then regenerate this page so runtime capability descriptions, docs, and agent guidance stay aligned.

tako.optimize

Relaxes atomic positions, and optionally the periodic cell, through the normal Tako calculation workspace.

Signature: await tako.optimize(structure, { calculator, properties, optimizer, maxSteps, fmaxEvPerAngstrom, maxstepAngstrom, alpha, trajectoryFrameInterval, cellRelaxation })

Theory

Geometry optimization searches for a local minimum on the selected model potential-energy surface by iteratively using energies and forces. Fixed-cell convergence is judged by the largest per-atom force-vector norm, reported through fmaxEvPerAngstrom; variable-cell optimization extends the optimizer array with three scaled cell rows.
BFGS builds an approximate Hessian and is efficient near smooth minima. FIRE is often robust for rough starts and large force relaxation. MDMin is a simple damped-dynamics fallback. For fixed cells, maxstepAngstrom limits atomic displacement; variable-cell runs apply it to the augmented atomic-and-cell optimizer array.
Cell relaxation adds lattice degrees of freedom. It requires stress support and changes the physical question from fixed-cell relaxation to variable-cell relaxation; do not mix fixed-cell and variable-cell energies without noting that difference.

Usage Notes

Start with fixed-cell atom relaxation for imported crystals unless the task explicitly asks for cell relaxation.
Use trajectoryFrameInterval greater than 1 for long relaxations when only coarse history is needed.
After optimization, use tako.analysis.finalStructure(input, result) and write it to output/final.extxyz for reproducibility.

Settings

Setting	Type	Default	Values	Unit	Validation	Description
`calculator`	calculator				Required for calculator-backed operations; validate the operation, structure element coverage, and requested properties before execution	Calculator object from `tako.calculator.gxtb(...)`, `gfn2(...)`, `mlip(...)`, or `dft(...)`. It controls the level of theory, charge/spin where supported, runtime assets, property availability, and the synchronous supported-element list used by TakoScript and the UI.
`properties`	properties	`['energy', 'forces']`	`energy`, `forces`, `stress`		Unknown names are removed; energy and forces are reinserted. Stress is meaningful only for a periodic structure and a calculator that supplies it. Optimization performs no DOS, PDOS, charge, density, NCI, or WFN post-processing stage.	Optimization result channels. The operation returns energy and force-derived convergence data; request `stress` for a supported periodic final-state stress evaluation and for variable-cell relaxation.
`optimizer`	enum	`bfgs`	`bfgs`, `fire`, `mdmin`			Geometry optimizer. `bfgs` is the default quasi-Newton optimizer, `fire` is robust for poor starting geometries, and `mdmin` is a damped-dynamics fallback.
`maxSteps`	integer	`500`			Positive integer; the WASM execution path clamps the effective budget to 1–500 even if a larger value was supplied	Requested optimizer iteration budget. The returned settings record currently retains the requested value, while execution uses at most 500 steps; use 500 or less to keep recorded and effective budgets identical.
`trajectoryFrameInterval`	integer	`1`				Write one trajectory frame every N optimization steps. Increase it to reduce output size for long relaxations.
`fmaxEvPerAngstrom`	number	`0.01`				Force convergence threshold in eV/A. Smaller values are stricter but can expose model noise or greatly increase runtime.
`maxstepAngstrom`	number	`0.04`				Fixed-cell: maximum atomic displacement per optimizer step in Å. Variable-cell: limiter on the combined N+3 generalized optimizer rows, so the trace maximum may come from a scaled cell row rather than an atom.
`alpha`	number	`70`		eV/Å²		BFGS initial Hessian scale. Larger values make the initial BFGS steps more conservative; it mainly matters for BFGS.
`cellRelaxation`	object	`{ mode: 'fixed' }`	`fixed`, `full`, `lengths`, `angles`, `custom`			`fixed` relaxes atoms only. `full` relaxes lengths and angles. `lengths` changes lattice vector lengths while preserving angles. `angles` changes angles while preserving lengths. `custom` uses explicit `relaxLengths: [a,b,c]`, `relaxAngles: [alpha,beta,gamma]`, and optional `cellFactor` scaling for cell degrees of freedom.

Example

const input = await tako.input("input/slab.extxyz");
const calculator = tako.calculator.mlip({ levelOfTheory: "nequix-phono" });
const result = await tako.optimize(input, {
  calculator,
  properties: ["energy", "forces", "stress"],
  optimizer: "fire",
  maxSteps: 300,
  fmaxEvPerAngstrom: 0.02,
  cellRelaxation: { mode: "fixed" },
});
await tako.output("output/final.extxyz", tako.analysis.finalStructure(input, result));

Result

Returned optimization result with convergence state, final energy and force diagnostic, sampled frames, serialized trajectory text, normalized settings, final structure, optional stress, and calculator provenance. Workspace logs and persisted artifacts are separate from this object.

Field	Type	Unit	Availability	Description
`kind`	”optimization”		Every resolved result	Runtime result discriminator.
`converged`	boolean		Every resolved result	Whether the optimizer met its gate before exhausting the effective step budget. Fixed cell uses maximum per-atom force norm; variable cell uses the maximum norm over augmented atomic and scaled cell-force rows.
`steps`	integer		Every resolved result	Accepted optimization steps; may be zero for an initially converged structure.
`final_energy_hartree`	number	Eh	Every resolved result	Final calculator energy.
`final_energy_ev`	number	eV	Every resolved result	Final calculator energy converted to electronvolts.
`final_fmax_hartree_per_bohr`	number	Eh/bohr	Every resolved result	Fixed cell: final maximum per-atom force norm. Variable cell: final maximum over the augmented atomic and scaled cell-force rows.
`final_fmax_ev_per_angstrom`	number	eV/Å	Every resolved result	The same final optimizer-array norm converted to eV/Å; not guaranteed to be an atomic force in a variable-cell run.
`frames`	object[]		Every resolved result	Sampled optimization frames; the first emitted frame and final frame are retained even when the interval skips intermediate steps.
`frames[].step`	integer		Every stored frame	Optimizer step index.
`frames[].energy_hartree`	number	Eh	Every stored frame	Frame potential energy.
`frames[].energy_ev`	number	eV	Every stored frame	Frame potential energy converted to electronvolts.
`frames[].fmax_hartree_per_bohr`	number	Eh/bohr	Every stored frame	Fixed cell: frame maximum per-atom force norm. Variable cell: maximum augmented-row norm.
`frames[].fmax_ev_per_angstrom`	number	eV/Å	Every stored frame	The same frame optimizer-array norm converted to eV/Å.
`frames[].maxstep_bohr`	number	bohr	Every stored frame	Fixed-cell: maximum accepted atomic displacement. Variable-cell: maximum over the N+3 generalized optimizer rows, which may be a scaled cell row.
`frames[].maxstep_angstrom`	number	Å	Every stored frame	The same optimizer-trace maximum converted with the length convention; in variable-cell runs it is not guaranteed to be an atomic displacement.
`frames[].cell.vectors`	3×3 number array	Å	Periodic stored frames only	Frame lattice vectors.
`frames[].atoms`	object[]		Every stored frame	Frame atoms in input order.
`frames[].atoms[].id`	integer		Every frame atom	Stable input atom identifier.
`frames[].atoms[].element`	string		Every frame atom	Element symbol.
`frames[].atoms[].x`	number	Å	Every frame atom	Frame Cartesian x coordinate.
`frames[].atoms[].y`	number	Å	Every frame atom	Frame Cartesian y coordinate.
`frames[].atoms[].z`	number	Å	Every frame atom	Frame Cartesian z coordinate.
`frames[].atoms[].selective`	[boolean, boolean, boolean]		Frame atoms whose input carried selective-dynamics flags	Per-axis mobility flags copied from the input.
`trajectory_xyz`	string		Every resolved result	Stored frames serialized as an XYZ trajectory.
`settings.optimizer`	”bfgs” \| “fire” \| “mdmin”		Every resolved result	Normalized optimizer name.
`settings.max_steps`	integer		Every resolved result	Requested step budget retained in the payload. Execution clamps it to 1–500; values above 500 therefore do not describe the effective budget.
`settings.trajectory_frame_interval`	integer		Every resolved result	Stored-frame interval.
`settings.fmax_ev_per_angstrom`	number	eV/Å	Every resolved result	Requested force gate.
`settings.maxstep_angstrom`	number	Å	Every resolved result	Requested fixed-cell atomic step limit or variable-cell augmented-row step limit.
`settings.alpha`	number	eV/Å²	Every resolved result	BFGS initial Hessian scale retained in the normalized settings.
`settings.cell_relaxation.mode`	”fixed” \| “full” \| “lengths” \| “angles” \| “custom”		Every resolved result	Normalized cell-relaxation mode.
`settings.cell_relaxation.relax_lengths`	[boolean, boolean, boolean]		Every resolved result	Enabled a, b, and c length strain components.
`settings.cell_relaxation.relax_angles`	[boolean, boolean, boolean]		Every resolved result	Enabled α, β, and γ angle strain components.
`settings.cell_relaxation.cell_factor`	number \| null		Every resolved result	Requested positive cell-degree scaling factor, or null when omitted. At execution, null, zero, nonfinite, and nonpositive values use the engine default factor based on atom count; the payload records the request rather than the resolved effective factor.
`settings.scf`	object		Every resolved result	Normalized GFN SCF settings record; retained with empty/default GFN fields for MLIP runs.
`settings.scf.energy_threshold`	number	Eh	Every resolved result	Normalized SCF energy threshold.
`settings.scf.density_threshold`	number		Every resolved result	Normalized SCF density threshold.
`settings.scf.max_iterations`	integer		Every resolved result	SCF iteration limit.
`settings.scf.electronic_temperature_kelvin`	number	K	Every resolved result	Electronic temperature.
`settings.scf.mixer_damping`	number		Every resolved result	SCF mixer damping.
`settings.scf.output_interval`	integer		Every resolved result	SCF log/output interval.
`settings.scf.temperature_schedule_kelvin`	number[]	K	Every resolved result	Explicit electronic-temperature schedule.
`settings.scf.temperature_annealing.policy`	string		Every resolved result	Effective annealing policy.
`settings.scf.temperature_annealing.start_kelvin`	number	K	Every resolved result	Annealing start temperature.
`settings.scf.temperature_annealing.stages`	integer		Every resolved result	Annealing stage count.
`settings.scf.temperature_annealing.stage_iterations`	integer		Every resolved result	Iterations allocated to each annealing stage.
`settings.scf.initial_guess`	string		Every resolved result	Normalized initial-guess mode.
`settings.scf.mixer`	string		Every resolved result	Normalized SCF mixer name.
`settings.scf.allow_unconverged`	boolean		Every resolved result	Whether an unconverged electronic state was permitted by settings.
`stress_ev_per_angstrom3`	3×3 number array \| null	eV/Å³	Every resolved result; populated only when stress was requested and the final calculator evaluation returned it	Final stress tensor in the backend convention.
`cell`	object \| null		Every resolved result	Final periodic cell or null for a nonperiodic structure.
`cell.vectors`	3×3 number array	Å	Periodic final structure only	Final lattice vectors.
`atoms`	object[]		Every resolved result	Final atoms in input order.
`atoms[].id`	integer		Every final atom	Stable input atom identifier.
`atoms[].element`	string		Every final atom	Element symbol.
`atoms[].x`	number	Å	Every final atom	Final Cartesian x coordinate.
`atoms[].y`	number	Å	Every final atom	Final Cartesian y coordinate.
`atoms[].z`	number	Å	Every final atom	Final Cartesian z coordinate.
`atoms[].selective`	[boolean, boolean, boolean]		Final atoms whose input carried selective-dynamics flags	Per-axis mobility flags copied from the input.
`level_of_theory`	string		Every resolved result	Normalized level-of-theory identifier.
`engine`	”gfn2” \| “mlip”		Every resolved result	Calculation engine family.
`mlip_runtime`	string		Every resolved result; empty for GFN2	MLIP inference runtime identifier.
`mlip_model`	string		Every resolved result; empty for GFN2	MLIP model-weight identifier.

Errors and Promise Behavior

Validate calculator support before execution. Variable-cell relaxation additionally requires a periodic cell and stress-capable calculator; invalid combinations reject rather than falling back to fixed-cell optimization.
The promise resolves with converged: false when the step budget ends before the force gate. This is a numerical nonconvergence result, not a rejected promise and not an accepted optimized structure.
Validation, asset preparation, calculator execution, serialization, worker reset, done without a result, and cancellation reject the promise. Cancellation rejects with Canceled by user and exposes no restartable optimizer state.
Frames streamed or persisted before rejection are partial execution evidence. They must not be presented as a completed optimization result.