Arrays, Geometry, Math, and Grids

A scalar grid (TakoScriptScalarGrid) is a plain, JSON-serializable object { origin: [x, y, z], axes: [v0, v1, v2], shape: [nx, ny, nz], values: number[] }, plus optional title, comment, metadata, role, and atoms carried through from a cube file. origin is the Cartesian position of grid point [0, 0, 0]; axes are the three voxel-step vectors (not the full cell — each is the Cartesian displacement for one increment along that axis), so a grid point at index [ix, iy, iz] sits at origin + ix*axes[0] + iy*axes[1] + iz*axes[2]. values is a flat array in x-major order — flat offset (ix * shape[1] + iy) * shape[2] + iz — the same layout Gaussian cube files use. A TakoScriptGridIndex is simply [ix, iy, iz], always integers within shape. Vector- and tensor-valued grids (tako.grid.gradient/tako.grid.hessian output) reuse origin/axes/shape but store 3 or 9 numbers per grid point back-to-back in that same point order.

Grids produced by tako.cube.parse carry origin, axes, and atoms[].x/y/z in Angstrom — the parser converts the cube file’s native Bohr coordinates on read, and tako.cube.writeLike converts back to Bohr on write. Scalar values are passed through unconverted in both directions (whatever units the source cube used, typically e/Bohr³ for densities). Derivative helpers (gradient, hessian, laplacian) differentiate with respect to the grid axes, so their output units are “value unit” per axis-length-unit (per Å, for a cube-derived grid) — they do not know about tako.units and never rescale. tako.units.constants/convert are separate, explicit helpers for Bohr/Å, Hartree/eV, and force/pressure conversions elsewhere in a script.

tako.array, tako.linalg, tako.geometry, and tako.grid are small, synchronous, ase.rs-aligned primitives, not a physics or file API on their own — scripts compose them (parse a cube, take a gradient, eigendecompose a Hessian, threshold with a histogram) to build RDG/NCI-style or other density-derived analyses instead of hand-rolling one-off numeric shortcuts.

tako.array.from

tako.array.from(data: number[] | number[][] | ... | ArrayLike<number>, options?: { shape?: number[]; stride?: number[]; offset?: number; dtype?: 'float64' }) => TakoScriptNdArray

Wraps flat or nested numeric data in a strided float64 n-dimensional array view.

Returns: TakoScriptNdArray: { dtype: ‘float64’, data: Float64Array, shape: number[], stride: number[], offset: number, size: number, get(index: number[]): number, set(index: number[], value: number): void, toArray(): unknown[], toJSON(): { dtype, shape, data: number[] } }. toArray() rebuilds a nested plain array matching shape; toJSON()/data walk the array in logical (shape) order, not raw storage order.

• Nested data must be rectangular at every depth (equal length at each level) or this throws.
• If data has fewer values than shape requires (accounting for stride/offset), this throws; if it has more, the extras are silently ignored.
• Non-numeric or non-finite entries throw immediately.

const a = tako.array.from([[1, 2], [3, 4]]);
a.get([1, 0]); // 3

tako.array.zeros

tako.array.zeros(shape: number[], options?: { dtype?: 'float64' }) => TakoScriptNdArray

Allocates a zero-filled float64 n-dimensional array of the given shape.

Returns: TakoScriptNdArray with the same shape/contiguous-stride/get/set/toArray/toJSON contract as tako.array.from, all values initialized to 0.

• Any zero, negative, or non-integer shape entry throws.

tako.cube.parse

tako.cube.parse(text: string) => TakoScriptParsedCube

Parses Gaussian cube file text into a scalar grid plus atom and metadata records.

Returns: TakoScriptParsedCube: { title: string, comment: string, metadata: Record<string,string>, role: CubeScalarRole, origin: [x,y,z], axes: [v0,v1,v2], shape: [nx,ny,nz], atoms: Array<{ atomicNumber, charge, x, y, z }>, values: number[], min: number, max: number, periodic: boolean }. origin, axes, and every atom x/y/z are converted from the file’s native Bohr to Angstrom; values, min, and max are the raw scalar values from the file, unit-converted. role is inferred from a tako_cube_role= comment tag or from title/comment text (e.g. ‘electron_density’, ‘nci_rdg’, ‘unknown’, …).

• Throws on too few lines, non-finite header/atom/value tokens, a non-positive axis count, or a value count that does not match shape[0]*shape[1]*shape[2].
• metadata is every tako_key=value token found in the comment line (quoted values are unescaped); periodic: true specifically means the comment carries tako_periodic="true".
• The returned object is a plain TakoScriptScalarGrid-compatible shape (origin/axes/shape/values) and can be passed directly to any tako.grid.* function.

const cube = tako.cube.parse(tako.read('density.cube'));
const grad = tako.grid.gradient(cube);

tako.cube.writeLike

tako.cube.writeLike(template: TakoScriptScalarGrid, values: ArrayLike<number>, options?: { title?: string; comment?: string; role?: CubeScalarRole }) => string

Serializes new scalar values into cube file text, reusing a template grid’s geometry and atoms.

Returns: string: a complete cube file (title, comment, atom-count+origin line, 3 axis lines, atom lines, value block, trailing newline). Origin, axes, and atom coordinates are converted back from the template’s Angstrom to Bohr; values are written as-is, unconverted.

• Throws if values.length does not exactly equal the template voxel count.
• Atom count in the header line comes from template.atoms?.length ?? 0; if the template has no atoms, the cube is written with zero atom records.

const logRho = tako.grid.map(cube, (rho) => Math.log10(Math.abs(rho) + 1e-12));
tako.write('log-density.cube', tako.cube.writeLike(cube, logRho.values, { comment: 'log10 electron density' }));

tako.grid.offset

tako.grid.offset(grid: { shape: [nx,ny,nz] }, index: [ix,iy,iz]) => number

Computes the flat x-major offset of a grid index into its values array.

Returns: number: (ix * shape[1] + iy) * shape[2] + iz.

• Throws if shape is not a 3-tuple of positive integers, or if index is out of bounds for it.

tako.grid.point

tako.grid.point(grid: { origin: [x,y,z]; axes: [v0,v1,v2]; shape: [nx,ny,nz] }, index: [ix,iy,iz]) => [x,y,z]

Computes a grid index’s Cartesian position from the grid’s origin and axes.

Returns: [number,number,number]: origin + ix*axes[0] + iy*axes[1] + iz*axes[2], in whatever length unit origin/axes use (Angstrom for cube-derived grids).

• Throws on an out-of-bounds index or malformed origin/axes/shape.

tako.grid.at

tako.grid.at(grid: { shape: [nx,ny,nz]; values: ArrayLike<number> }, index: [ix,iy,iz]) => number

Reads one scalar value out of a grid at the given index.

Returns: number: values[offset(grid, index)].

• Throws if the index is out of bounds or the resolved value is missing/non-finite.

tako.grid.vectorAt

tako.grid.vectorAt(grid: TakoScriptVectorGrid, index: [ix,iy,iz]) => [number,number,number]

Reads the 3-component vector stored at one grid point of a vector grid.

Returns: [number,number,number]: values[offset*3 .. offset*3+2] for the scalar-grid flat offset of index.

• Throws on an out-of-bounds index or a non-finite stored component.

tako.grid.tensor3At

tako.grid.tensor3At(grid: TakoScriptTensor3Grid, index: [ix,iy,iz]) => TakoScriptMat3

Reads the 3x3 tensor stored at one grid point of a tensor grid, as a row-major matrix.

Returns: [[number,number,number],[number,number,number],[number,number,number]]: the 9 stored components at that point, unpacked row-major into a 3x3 matrix.

• Throws on an out-of-bounds index or a non-finite stored component.

tako.grid.gradient

tako.grid.gradient(grid: TakoScriptScalarGrid) => TakoScriptVectorGrid

Computes the Cartesian gradient of a scalar grid at every grid point.

Returns: TakoScriptVectorGrid ({ kind: ‘vector’, origin, axes, shape, components: 3, values: number[] }) with 3 values per grid point in the same point order as the input, units of [value] per [axes length unit] (per Å for a cube-derived grid).

• Per axis, uses a central difference in index space (one-sided forward/backward difference at the first/last plane along that axis), then transforms the index-space gradient into Cartesian coordinates by solving against the grid axes — so accuracy near the domain edges is lower than in the interior.

const rho = tako.cube.parse(cubeText);
const grad = tako.grid.gradient(rho);

tako.grid.hessian

tako.grid.hessian(grid: TakoScriptScalarGrid) => TakoScriptTensor3Grid

Computes the Cartesian Hessian (3x3 second-derivative matrix) of a scalar grid at every grid point.

Returns: TakoScriptTensor3Grid ({ kind: ‘tensor3’, origin, axes, shape, components: 9, values: number[] }) with 9 values (row-major 3x3) per grid point, units of [value] per [axes length unit]².

• Diagonal terms use a 3-point second-derivative stencil; off-diagonal (mixed) terms use a 4-point cross-difference stencil, both computed in index space and then transformed into Cartesian coordinates via the grid axes.
• Near an edge, the stencil center is clamped inward by one plane rather than shrinking the stencil, so edge-adjacent values are an approximation, not a reduced-order derivative.
• Any axis with fewer than 3 planes (shape[axis] < 3) contributes 0 for every second/mixed derivative along that axis.

tako.grid.derivatives

tako.grid.derivatives(grid: TakoScriptScalarGrid, options?: { order?: 1 | 2 }) => { gradient: TakoScriptVectorGrid; hessian?: TakoScriptTensor3Grid }

Computes the gradient (and optionally the Hessian) of a scalar grid in one call.

Returns: { gradient: TakoScriptVectorGrid } when order === 1; otherwise { gradient: TakoScriptVectorGrid, hessian: TakoScriptTensor3Grid } — identical values to calling tako.grid.gradient/tako.grid.hessian separately, computed from one validated copy of grid.

• Equivalent to, but cheaper than, calling tako.grid.gradient and tako.grid.hessian separately when both are needed.

tako.grid.laplacian

tako.grid.laplacian(grid: TakoScriptScalarGrid) => TakoScriptScalarGrid

Computes the scalar Laplacian (trace of the Hessian) of a scalar grid at every grid point.

Returns: TakoScriptScalarGrid with the same origin/axes/shape/title/comment/metadata/role/atoms as the input and values[i] = Hessian_xx + Hessian_yy + Hessian_zz at each point, units of [value] per [axes length unit]².

• Internally computes the full Hessian grid and sums its diagonal, so it inherits the same edge-stencil and degenerate-axis caveats as tako.grid.hessian.

tako.grid.map

tako.grid.map(grid: TakoScriptScalarGrid, mapper: (value: number, point: TakoScriptGridPoint) => number) => TakoScriptScalarGrid

Builds a new scalar grid by applying a function to every value of an existing grid.

Returns: TakoScriptScalarGrid: same origin/axes/shape/title/comment/metadata/role/atoms as the input, with values replaced by the mapper output for every point, in the same x-major order.

• Throws if the mapper returns a non-finite value for any point.

const shifted = tako.grid.map(cube, (rho) => rho - 1e-3);

tako.grid.zip

tako.grid.zip(grids: TakoScriptScalarGrid[], mapper: (values: number[], point: TakoScriptGridPoint) => number) => TakoScriptScalarGrid

Combines multiple scalar grids sharing the same domain into one, point by point.

Returns: TakoScriptScalarGrid: geometry/metadata copied from grids[0], values set to the mapper’s output at every point.

• Throws if grids is empty or not an array, or if any grid after the first has a mismatched shape/origin/axes (“grid domains must have matching shapes/origin and axes”).

const rdgLikeSign = tako.grid.zip([rho, signLambda2], ([r, s]) => s * r);

tako.grid.integrate

tako.grid.integrate(grid: TakoScriptScalarGrid) => number

Integrates a scalar grid over its domain (sum of values times voxel volume).

Returns: number: sum(values) * |det(axes)| — axes are the per-voxel step vectors, so |det(axes)| is the volume of one voxel (in [axes length unit]³, e.g. ų for a cube-derived grid). The result is in [value] * [axes length unit]³.

• A simple Riemann-sum integral; no interpolation or boundary weighting.

tako.grid.histogram

tako.grid.histogram(grid: TakoScriptScalarGrid, options: { bins: number; range?: [number, number] }) => TakoScriptHistogram

Bins every value of a scalar grid into a 1-D histogram.

Returns: TakoScriptHistogram: { bins: Array<{ min: number; max: number; center: number }>, counts: number[] }, both length options.bins, bins[i] covering [min + i*width, min + (i+1)*width).

• Throws if bins is not a positive integer, or if the (explicit or computed) range is non-finite or not strictly increasing.
• Values strictly outside [min, max] are dropped from every count, not clamped into the edge bins — an explicit range narrower than the data silently excludes out-of-range values.

tako.linalg.dot

tako.linalg.dot(left: [number,number,number], right: [number,number,number]) => number

Computes the dot product of two 3-vectors.

Returns: number: left . right.

• Throws if either argument is not a finite [x,y,z] vector.

tako.linalg.cross

tako.linalg.cross(left: [number,number,number], right: [number,number,number]) => [number,number,number]

Computes the cross product of two 3-vectors.

Returns: [number,number,number]: left x right.

• Throws if either argument is not a finite [x,y,z] vector.

tako.linalg.norm

tako.linalg.norm(vector: [number,number,number]) => number

Computes the Euclidean length of a 3-vector.

Returns: number: Math.hypot(x, y, z).

• Throws if vector is not a finite [x,y,z] vector.

tako.linalg.matVec3

tako.linalg.matVec3(matrix: TakoScriptMat3, vector: [number,number,number]) => [number,number,number]

Multiplies a 3x3 matrix (rows) by a 3-vector.

Returns: [number,number,number]: [row0.vector, row1.vector, row2.vector].

• Throws if matrix is not a 3x3 array of finite [x,y,z] rows or vector is not a finite [x,y,z] vector.

tako.linalg.det3

tako.linalg.det3(matrix: TakoScriptMat3) => number

Computes the determinant of a 3x3 matrix given as rows.

Returns: number: row0 . (row1 x row2).

• Throws if matrix is not a 3x3 array of finite rows.

tako.linalg.inverse3

tako.linalg.inverse3(matrix: TakoScriptMat3) => TakoScriptMat3

Computes the inverse of a 3x3 matrix given as rows.

Returns: TakoScriptMat3: the row-major inverse, such that matVec3(inverse3(m), matVec3(m, v)) ≈ v.

• Throws “matrix is singular.” if |det(matrix)| <= 1e-15.

tako.linalg.solve3

tako.linalg.solve3(matrix: TakoScriptMat3, vector: [number,number,number]) => [number,number,number]

Solves the linear system matrix @ x = vector for a 3x3 matrix.

Returns: [number,number,number]: x such that matrix @ x = vector (computed as inverse3(matrix) @ vector).

• Throws “matrix is singular.” if |det(matrix)| <= 1e-15.

tako.linalg.eigenSymmetric3

tako.linalg.eigenSymmetric3(matrix: TakoScriptMat3) => { values: [number,number,number]; vectors: TakoScriptMat3 }

Computes eigenvalues and eigenvectors of a symmetric 3x3 matrix via cyclic Jacobi rotation.

Returns: { values: [number,number,number]; vectors: TakoScriptMat3 }: values are the three eigenvalues sorted ascending. vectors[i] is the full 3-component eigenvector for values[i] — vectors is an array of 3 discrete eigenvectors indexed the same as values, not a matrix whose columns you index into separately.

• Runs up to 32 Jacobi sweeps, stopping early once the largest off-diagonal magnitude is <= 1e-14; adequate for well-conditioned 3x3 matrices.
• For a Hessian, values[1] is the conventional “lambda2” used in sign(lambda2)*rho NCI analysis.

const hess = tako.grid.tensor3At(hessianGrid, index);
const { values } = tako.linalg.eigenSymmetric3(hess);
const signLambda2 = Math.sign(values[1]);

tako.geometry.distance

tako.geometry.distance(left: [number,number,number], right: [number,number,number]) => number

Computes the Euclidean distance between two Cartesian points.

Returns: number: |right - left|, in whatever length unit the inputs use.

• Throws if either argument is not a finite [x,y,z] vector.

tako.geometry.angle

tako.geometry.angle(left: [number,number,number], center: [number,number,number], right: [number,number,number]) => number

Computes the angle at center between rays to left and right.

Returns: number: angle in degrees, in [0, 180].

• Throws if any point is not a finite [x,y,z] vector, or if left/right coincide with center (zero-length ray).

tako.geometry.dihedral

tako.geometry.dihedral(a: [number,number,number], b: [number,number,number], c: [number,number,number], d: [number,number,number]) => number

Computes the dihedral (torsion) angle of four points a-b-c-d.

Returns: number: signed dihedral angle in degrees, in (-180, 180].

• Throws if any point is not a finite [x,y,z] vector, or (via normalize3) if b and c coincide.

tako.geometry.fracToCart

tako.geometry.fracToCart(fractional: [number,number,number], cell: TakoScriptCellVectors) => [number,number,number]

Converts fractional (crystal) coordinates to Cartesian using explicit cell vectors.

Returns: [number,number,number]: fx*cell[0] + fy*cell[1] + fz*cell[2], in the same length unit as cell.

• Throws if fractional is not a finite [x,y,z] vector or cell is not 3 finite row vectors.

tako.geometry.cartToFrac

tako.geometry.cartToFrac(cartesian: [number,number,number], cell: TakoScriptCellVectors) => [number,number,number]

Converts Cartesian coordinates to fractional (crystal) coordinates using explicit cell vectors.

Returns: [number,number,number]: fractional coordinates such that fracToCart(cartToFrac(v, cell), cell) ≈ v. Not wrapped into [0, 1).

• Throws if cell vectors are degenerate (zero cell volume) or inputs are not finite [x,y,z] vectors.

tako.geometry.minimumImageDelta

tako.geometry.minimumImageDelta(left: [number,number,number], right: [number,number,number], cell: TakoScriptCellVectors) => [number,number,number]

Computes the shortest periodic-image displacement from left to right under a given cell.

Returns: [number,number,number]: the Cartesian delta right - left, wrapped into the minimum-image convention by rounding its fractional components to the nearest integer cell and re-subtracting (each fractional component of the wrapped delta lies in [-0.5, 0.5]).

• Throws if cell vectors are degenerate or inputs are not finite [x,y,z] vectors.

tako.geometry.wrapFractional

tako.geometry.wrapFractional(value: number) => number

Wraps a single fractional coordinate into [0, 1).

Returns: number: value - Math.floor(value), in [0, 1); a result of -0 is normalized to 0.

• Throws if value is not a finite number. Apply per-component for a full fractional vector.

tako.units.constants

tako.units.constants: { BOHR_TO_ANGSTROM: number; ANGSTROM_TO_BOHR: number; HARTREE_TO_EV: number; EV_TO_HARTREE: number; HARTREE_PER_BOHR_TO_EV_PER_ANGSTROM: number }

Plain object of the numeric conversion factors backing tako.units.convert.

Returns: Object with fields BOHR_TO_ANGSTROM = 0.52917721092, ANGSTROM_TO_BOHR = 1/BOHR_TO_ANGSTROM, HARTREE_TO_EV = 27.211386245988, EV_TO_HARTREE = 1/HARTREE_TO_EV, HARTREE_PER_BOHR_TO_EV_PER_ANGSTROM = HARTREE_TO_EV / BOHR_TO_ANGSTROM.

• A data property, not a function — read the fields directly (e.g. tako.units.constants.BOHR_TO_ANGSTROM).

tako.units.convert

tako.units.convert(value: number, from: string, to: string) => number

Converts a number between named length, energy, force, or pressure units.

Returns: number: value rescaled from from to to.

• Throws “Unsupported unit: …” if either name is not one of the listed strings.
• Throws “Cannot convert … to …” if from and to belong to different dimensions (e.g. length to energy).

const evPerA = tako.units.convert(forceHartreePerBohr, 'hartree/bohr', 'ev/angstrom');

Return to the Tako Script API index.