SPAR: operator representations
SPAR (Summed Product Analytic Representation) describes molecular operators through one-dimensional basic functions, numerical coefficients, and a mapping between them [26SmMeYu]. It provides a common representation for kinetic energy operators (KEOs), potential energy functions (PEFs), and dipole moment functions (DMFs). The representation can be exact, approximate, or hybrid.
The pages below describe the input reader in TROVE revision 7831d55
(7 September 2026). Published examples and older inputs can use different
constructor syntax; see SPAR input syntax and migration before adapting them. The XY3
page, PH3: 1D-based and 2D-based SPAR kinetic energy operators, describes the R-SYMPHI-BETA coordinates and the
two-dimensional KEO factors added on the xy3-exact-2d-keo branch
(commit a3902fd, 23 October 2026).
From an operator to one-dimensional integrals
For a scalar function, or one component of a tensor-valued function, write
Here \(D\) is the number of vibrational coordinates, \(L\) labels a product term, and \(\ell_k(L)\) selects a basic function for mode \(k\). A zero mode index represents the constant function 1 in the KEO mapping. The coefficient and the complete index tuple belong together: reordering the functions without updating the tuples changes the operator.
The operator basic functions \(f^{(k)}_\ell\) are distinct from the variational basis functions \(\phi^{(k)}_n\). For a multiplication operator in a product basis, the matrix element factors as
KEO matrix elements also contain derivatives and angular-momentum operators. Their placement and the associated pseudopotential must follow the chosen Hamiltonian convention; specifying a set of scalar functions alone does not define a KEO. TROVE stores separate vibrational, rotational, Coriolis, and pseudopotential contributions (see SPAR operator files and conventions).
One- and two-dimensional factors
In Eq. (1) every factor depends on one coordinate. We call such an operator 1D-based. In some coordinate systems a pair of coordinates enters the exact operator only through functions that do not factorise. The pair can then be Taylor-expanded, which keeps the 1D-based form, or it can be kept as a single two-dimensional factor:
We call this form 2D-based. The matrix elements of \(\Phi\) in the
product basis of the two modes are no longer products of 1D integrals.
They are computed outside TROVE and read from a table. The current
implementation supports this for modes 4 and 5, which must form their own
contracted class with a harmonic-oscillator basis. The table file is
keo_2d_s4s5.chk. The KEO file keeps its column layout, but
\(\ell_4,\ell_5\) then label 2D functions instead of 1D functions. See
PH3: 1D-based and 2D-based SPAR kinetic energy operators for the XY3 operators that use both forms.
Accuracy and convergence
An exact analytic KEO avoids an expansion error in that operator. It does not remove errors from a fitted potential, numerical quadrature, a finite variational basis, or contracted-state truncation. A calculation can combine an exact KEO with an approximate PEF or DMF. Record the origin and approximation of each component separately.
For a Taylor representation, a mode index may coincide with a power. For a
general SPAR representation it is a function label: increasing KinOrder
does not automatically improve an exact finite function library. Convergence
still requires systematic changes to the basis, integration grids, and
contraction settings. See Basis sets and TROVE Quick start.
Mass dependence
BASIC-FUNCTION MASS selects the KEO reader with an additional mass index
\(\ell_0\). Each term then contains an inverse nuclear mass selected from
the input ZMAT order. This permits coefficients with the mass factors
separated from their coordinate dependence. BASIC-FUNCTION KINETIC uses
coefficients with the masses already incorporated.
These two checkpoint conventions have different columns and unit conversion behaviour. They cannot be interchanged by changing the block heading alone. Furthermore, a frame or coordinate definition may itself depend on masses. Check that definition before transferring a model to another isotopologue.
Singular coordinates
Factors such as \(1/\sin\rho\) require a compatible basis and integration
scheme at a linear geometry. TROVE recognises CSC_ and COT_ markers
for special matrix-element treatment, but they are not general replacements
for CSC and COT. The basis, operator, and pseudopotential must be derived
and used together. The paper’s supplementary material describes these cases.
The bent H2S tutorial stays away from linear configurations and uses ordinary
CSC and COT functions. It does not validate singular-coordinate models.
Preparing a transferable model
Keep the following information with every operator file:
Coordinate definitions, order, units, and reference geometry.
Body-fixed axes, atom order, masses, and symmetry conventions.
Function libraries and index mappings for each operator or property.
Coefficient units, mass convention, differential ordering, integration measure, and pseudopotential convention.
Potential and dipole parameters, their source, and their range of validity.
TROVE revision, build choices, input files, and numerical comparison data.
An external operator does not supply a missing molecular coordinate transformation, symmetry implementation, or dipole-frame transformation. These remain prerequisites for the calculation.
Sources and examples
The methodological reference is [26SmMeYu]. The associated
supplementary archive contains
InputsAndFrames.pdf, derivations, function definitions, and operator files.
The public SPAR repository contains
further examples and conversion tools. Record the repository commit when
using them; the input conventions must be reconciled with the TROVE revision.
The generators of the PH3 operators on PH3: 1D-based and 2D-based SPAR kinetic energy operators are distributed with
this manual and in inputs/PH3.
The constructor description in this manual was checked against FLReadInput
in fields.f90 and the current HOPO input in inputs/HOPO. The compact
XY2 example was checked against MLkinetic_compact_xy2_bisect_EKE_rigid in
kin_xy2.f90. The scientific interpretation of a new molecular model still
requires validation of its coordinates, operators, and observables.