tako.stda Settings

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

On this page

tako.stda

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.stda

Runs sTDA vertical excitations with the selected GFN2-xTB or g-xTB ground-state route and folds the requested roots into a sampled energy-domain UV–visible curve.

Signature: await tako.stda(structure, { calculator, properties, nstates, includeTransitionVectors, spectrumEminEv, spectrumEmaxEv, spectrumSpacingEv, spectrumSigmaEv })

Theory

Tamm–Dancoff response couples occupied-to-virtual promotions in a Hermitian eigenproblem. The dedicated sTDA-xTB implementation uses a selected transition space, parameterized transition-charge interactions, and separate closed/open-shell paths.
Oscillator strength is dimensionless and follows f=(2/3)E|mu|^2 in atomic units. Optional dominant-transition records are the four largest signed eigenvector coefficients, not squared populations or percentages.
The UV–visible array is the sum of normalized energy-domain Gaussians, f/[sigma sqrt(2pi)] exp[-(E-Estate)^2/(2 sigma^2)]. Sigma is a standard deviation; FWHM is about 2.35482 sigma.
GFN2 uses the established standalone xtb4stda ground-state and response path. The selected GFN2 calculator authorizes routing, but its dispersion, solvent, SCF, and mixer options do not enter that dedicated solve.
g-xTB instead solves and retains its normal ground state, then passes the accepted orbitals, energies, and occupations into the sTDA response without reconstruction or fallback. The cached density is preserved unchanged, while response dipole integrals are evaluated in the calculator-owned q-vSZP basis. Its SCF controls therefore affect whether and how that accepted state converges; implicit solvation remains unavailable.
The frozen experimental panel supports GFN2 as the accuracy-first default for listed absorption bands. g-xTB is an explicit faster alternative, not an automatic replacement or per-molecule fallback.

Usage Notes

Use a GFN2-family calculator and preserve the integral charge/unpaired-electron definition with the result. MLIP input is normalized away by the workspace or rejected by raw WASM.
Converge nstates independently of spectrum bounds: the energy interval samples only roots already calculated.
Treat dominant transition weights as signed coefficients and raw orbital indices as authoritative; viewer HOMO/LUMO labels and percentages are heuristic.
Keep grid, Sigma, geometry/conformer protocol, and environment assumptions fixed for comparisons. The curve is not molar absorptivity or an experimental line-shape model.

Settings

Setting	Type	Default	Values	Unit	Validation	Description
`calculator`	calculator				A GFN2-xTB or g-xTB calculator is required. New sTDA work defaults to GFN2; an explicit g-xTB selection is preserved. MLIP and DFT input is rejected.	Selects the ground-state route. GFN2 invokes the standalone xtb4stda solve; g-xTB reuses its accepted calculator wavefunction directly.
`properties`	properties	`calculator defaults`	`energy`, `forces`, `stress`, `dos`, `pdos`, `charges`, `electronDensity`, `chargeDensity`, `nci`, `wfn`, `orbitals`, `spinDensity`, `esp`, `densityDerivatives`, `fukui`, `elf`		Accepted and normalized by the shared calculation option parser. The sTDA path does not use this list to add returned property channels.	Compatibility option shared with other calculator operations. It does not add energy, forces, stress, charges, DOS/PDOS, density, NCI, WFN, orbitals, spin density, ESP, density derivatives, Fukui, or ELF fields to the public sTDA result.
`nstates`	integer	`16`			Positive integer clamped to 1–256; the backend must find exactly this many positive roots or rejects	Number of lowest positive response roots. It is independent of the folded-spectrum energy interval.
`includeTransitionVectors`	boolean	`true`				When true, retain at most four largest-absolute signed response-vector coefficients per state. It does not change energies, dipoles, oscillator strengths, or folding.
`spectrumEminEv`	number	`0`		eV	Finite; normalized and runtime-clamped to at least zero	Lower energy of the Gaussian curve grid.
`spectrumEmaxEv`	number	`10`		eV	Finite and repaired to exceed effective minimum; equal bounds become a 1 eV interval	Upper requested grid bound. It is present as a point only when the interval is exactly divisible by spacing.
`spectrumSpacingEv`	number	`0.02`		eV	Positive finite value; TypeScript falls back on invalid input and runtime floors at 0.0001 eV	Energy grid spacing. There is no point-count cap, so tiny spacing over a large range can exhaust memory.
`spectrumSigmaEv`	number	`0.15`		eV	Positive finite value; invalid input falls back to 0.15 eV	Gaussian standard deviation, not FWHM. Finite windows truncate Gaussian tails.

Example

const molecule = await tako.input("input/chromophore.extxyz");
const calculator = tako.calculator.gfn2({ charge: 0, unpaired: 0 });
const result = await tako.stda(molecule, {
  calculator,
  nstates: 32,
  includeTransitionVectors: true,
  spectrumEminEv: 1.5,
  spectrumEmaxEv: 6.5,
  spectrumSpacingEv: 0.01,
  spectrumSigmaEv: 0.15,
});
await tako.output("output/stda-result.json", result);

Result

Returned sTDA result containing duplicated discrete state arrays, one Gaussian-folded curve, and effective controls. The workspace separately extracts excitations.json and uv_vis.json; viewer peaks and assignments are not returned fields.

Field	Type	Unit	Availability	Description
`kind`	”stda”		Every successful result	Runtime operation discriminator.
`level_of_theory`	string		Every successful result	Normalized GFN2 routing level. Dispersion is reported separately and does not enter the dedicated response solve.
`engine`	”gfn2”		Every successful result	Stable engine-family label.
`method`	”stdaXtb” \| “stdaGxtb”		Every successful result	Stable response label identifying the actual selected ground-state route.
`states`	StdaState[]		Every successful result	Requested positive roots in eigensolver energy order.
`states[].index`	integer		Every state	Zero-based sequential state index; it does not encode multiplicity.
`states[].energy_ev`	number	eV	Every state	Vertical excitation energy.
`states[].oscillator_strength`	number		Every state	Dimensionless electric-dipole oscillator strength, clamped nonnegative.
`states[].transition_dipole_au`	[number, number, number]	e a0	Every state from the current dedicated backend	Electronic transition-dipole vector, not the permanent dipole.
`states[].dominant_transitions`	StdaTransition[]		Every state; empty when includeTransitionVectors is false	At most four retained response-vector components.
`states[].dominant_transitions[].spin`	null \| “alpha” \| “beta”		Every retained component	Unrestricted orbital channel; null for closed shell. It is not an excited-state multiplicity.
`states[].dominant_transitions[].occupied`	integer		Every retained component	Zero-based occupied model-MO index.
`states[].dominant_transitions[].virtual_orbital`	integer		Every retained component	Zero-based virtual model-MO index.
`states[].dominant_transitions[].weight`	number		Every retained component	Signed eigenvector coefficient, selected by absolute magnitude; not a percentage or squared population.
`excitations.method`	”stdaXtb” \| “stdaGxtb”		Every successful result	Method label in the artifact-compatible nested envelope.
`excitations.states`	StdaState[]		Every successful result	Duplicate of top-level states, not a second solve.
`uv_vis.kind`	”uv_vis”		Every successful result	Folded-curve discriminator.
`uv_vis.x_unit`	”eV”		Every successful result	Energy-axis unit.
`uv_vis.energies_ev`	number[]	eV	Every successful result	Uniform grid beginning at effective minimum; endpoint may be below effective maximum.
`uv_vis.intensities`	number[]	oscillator strength eV^-1	Every successful result	Normalized-Gaussian sum; not absorbance or molar absorptivity.
`uv_vis.sigma_ev`	number	eV	Every successful result	Effective Gaussian standard deviation.
`settings.nstates`	integer		Every successful result	Effective root count.
`settings.include_transition_vectors`	boolean		Every successful result	Effective coefficient-output switch.
`settings.spectrum_emin_ev`	number	eV	Every successful result	Effective lower grid bound.
`settings.spectrum_emax_ev`	number	eV	Every successful result	Effective requested upper bound; not necessarily an included grid point.
`settings.spectrum_spacing_ev`	number	eV	Every successful result	Effective grid spacing.
`settings.spectrum_sigma_ev`	number	eV	Every successful result	Effective Gaussian standard deviation.

Errors and Promise Behavior

Rejects raw MLIP routing, nonintegral charge, inconsistent charge/spin occupation, missing embedded element parameters, or invalid periodic lattice.
Rejects rather than returning fewer states when the selected transition space or positive eigenvalue set cannot provide the exact requested root count.
Eigensolver failure and memory pressure fail the whole operation. There is no state-by-state partial result, convergence/accuracy flag, or restart checkpoint.
Cancellation terminates the shared calculation worker and a later call restarts ground-state, transition-space, eigenproblem, and folding work.