cuEST Release Notes#
v0.3.0#
New Features#
Adds support for direct density fitted Coulomb integrals and derivatives:
Setting
CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT= 1 when thecuestDFIntPlan_tis constructed activates direct DF-J for compute calls using that handle.
Adds grid-based exchange (Grid-K), which forms the AO exchange (K) matrix and its nuclear gradient by numerical quadrature on a molecular grid:
cuestGridKSymmetricExchangeCompute()andcuestGridKNonsymmetricExchangeCompute()compute AO exchange matrices for a batch of density matrices. The nonsymmetric routine accepts general densities (i.e., for response or excited-state methods).cuestGridKSymmetricExchangeDerivativeCompute()computes the nuclear gradients of the Grid-K exchange energy at fixed densities, one gradient per density matrix.The initial implementation of the Grid-K algorithm is intended for datacenter GPUs with full-rate FP64 compute.
Adds direct four-center Coulomb (J) and exchange (K) matrices and their nuclear derivatives, evaluated from four-center electron repulsion integrals:
cuestDirectCoulombCompute()andcuestDirectSymmetricExchangeCompute()compute AO Coulomb and symmetric exchange matrices for a batch of density matrices.cuestDirectCoulombDerivativeCompute()andcuestDirectSymmetricExchangeDerivativeCompute()compute the nuclear gradients of the corresponding energies at fixed density coefficients, one gradient per density matrix.cuestDirectCoulombBilinearDerivativeCompute()andcuestDirectSymmetricExchangeBilinearDerivativeCompute()compute the nuclear gradients of the bilinear forms Tr(D J[D’]) and Tr(D K[D’]) at fixed density coefficients for a batch of density-matrix pairs; only symmetric density matrices are supported for the exchange form.The initial implementation of the integral-direct algorithm is intended for datacenter GPUs with full-rate FP64 compute.
Adds second nuclear derivatives of the overlap (S) and kinetic energy (T) integrals, providing the one-electron terms needed to assemble an analytic SCF Hessian:
cuestOverlapHessianSkeletonCompute()andcuestKineticHessianSkeletonCompute()contract the second derivatives of the AO overlap and kinetic energy matrices against a density-like matrix to form a skeleton Hessian block.cuestOverlapHessianRHSCompute()andcuestKineticHessianRHSCompute()compute the first derivatives of the same matrices and transform them into the MO basis, giving the integral-derivative input consumed by a coupled-perturbed Hartree-Fock (CPHF) response solve.
Adds the XC terms for the \(\omega\mathrm{B97X\text{-}D}\) and \(\omega\mathrm{B97X\text{-}D3}\) range separated hybrid GGA functionals. The caller is responsible for computing the classical
-D2/-D3corrections required by these functionals, respectively.Adds fixed-point emulation support to the following API functions:
The following exchange-correlation compute routines now have emulation support:
cuestXCPotentialRKSCompute(),cuestXCPotentialUKSCompute(),cuestXCDensityCompute(),cuestXCPotentialCompute(),cuestXCNonsymmetricDensityCompute(),cuestXCDerivativeRKSCompute(),cuestXCDerivativeUKSCompute(),cuestXCDerivativeCompute(),cuestXCNonsymmetricDerivativeCompute(). Matrix multiplication operations in the density collocation, potential formation and gradient evaluation may be emulated.The nonlocal exchange-correlation compute routines now have emulation support:
cuestNonlocalXCPotentialRKSCompute(),cuestNonlocalXCPotentialUKSCompute(),cuestNonlocalXCDerivativeRKSCompute(),cuestNonlocalXCDerivativeUKSCompute(). Matrix multiplication operations in the density collocation, potential formation and gradient evaluation may be emulated.The ECP compute routines now have emulation support:
cuestECPCompute(),cuestECPDerivativeCompute(). Formation of the potential matrix and gradient evaluation contain emulated matrix multiplication operations.The density-fitted integral plan has emulation support:
cuestDFIntPlanCreate(). The fitting of the three-center integrals may be emulated.The density-fitted Coulomb and exchange gradients have emulation support:
cuestDFSymmetricDerivativeCompute(). Numerous operations performed by this function may be emulated.For every type of matrix multiplication operation where fixed-point emulation may be used, a pair of parameters is provided to give the user control to change the precision or optionally disable emulation for those terms.
Changes#
The cuEST library provides support for basis sets including functions up to g orbitals (L=4 angular momentum). This limit is now strictly enforced. Calls to create integral plans with basis sets including L>4 angular momentum will return
CUEST_STATUS_EXCEEDS_MAX_L.The
cuestDFIntPlan_tsupports up to g orbitals in the primary basis and up to L=8 in the auxiliary basis.This change affects only integral plans. Primitive data structures such as
cuestAOShell_t,cuestAOBasis_tandcuestAOPairList_tcan still be created with arbitrary angular momentum.
Changed the behavior of the
cuestAOPairList_tto avoid screening same-center primitive pairs. Only primitive pairs on different centers are subject to thethresholdPQscreening threshold.The
variableBufferSizecan now be specified without consideration of system size (with reasonable values in the 2GB to 8GB range).This change affects all XC and nonlocal XC compute routines.
The workspace buffer sizes (i.e. those returned by workspace query calls) remain dependent on system size and will deviate noticably from the
variableBufferSizefor large molecules.
Improved error handling in some API functions.
Certain API functions will now return
CUEST_STATUS_INVALID_PLANif handles to required plans are destroyed too early.cuestDFIntPlanCreate()will now returnCUEST_STATUS_INVALID_ARGUMENTfor invalidCUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHMparameter arguments.cuestXCIntPlanCreate()andcuestXCIntPlanCreateWorkspaceQuery()will now returnCUEST_STATUS_INVALID_ARGUMENTifCUEST_XCINTPLAN_PARAMETERS_NUM_THREADSis less than 1.
If the
cuestDFSymmetricDerivativeCompute()function does not returnCUEST_STATUS_SUCCESS, thecuestDFIntPlan_tused to make the call may be marked as invalid. In those cases, subsequent calls using thatcuestDFIntPlan_twill returnCUEST_STATUS_INVALID_PLAN.
Bug Fixes#
Fixed a bug where calls to
cuestXCPotentialUKSCompute()could return incorrect results if a density matrix filled with zeros was passed to the routine.The
cuestECPDerivativeCompute()function requires a symmetric input density matrix. This is now clarified in the documentation.
v0.2.2#
Enhancements#
Improves efficiency on compute capability 8.6, 8.9 and 12.1 GPUs in default math mode (
CUEST_DEFAULT_MATH_MODE).Density fitted exchange will use emulation in the default math mode.
Bug Fixes#
Fixed a bug in
cuestDFSymmetricDerivativeComputewhere it returned a spuriousCUEST_STATUS_EXCEPTIONin cases where the computation should have completed successfully. The bug was localized tocuestDFSymmetricDerivativeComputeand did not affect numerical results of any function calls that returnedCUEST_STATUS_SUCCESS.
Changes#
Numerical results for density-fitted exchange obtained with compute capability 8.6, 8.9 and 12.1 GPUs will change relative to v0.2.1. These emulated numerical results will be similar to those obtained on other default-emulated GPUs CCs like 9.0 (H100, H200), 10.0 (B200), and 12.0 (RTX PRO 6000 Blackwell). The precision of these results can be controlled by adjusting the emulation parameters.
Calls to
cuestSetComputeCapabilityTarget()setting unsupported or nonexistent compute capability major/minor versions will disable emulation in subsequent density-fitted exchange calls.
v0.2.1#
Enhancements#
Improves efficiency of the caching of just-in-time (JIT) compiled kernels.
Modifies the JIT compilation stack to be loaded on demand. This removes a hard dependency on the libcuda.so.1 CUDA driver library, which is usually absent on machines that lack a CUDA-capable GPU.
v0.2.0#
New Features#
Adds support for polarizable continuum model (PCM) derivatives with respect to each atomic cavity radius:
cuestPCMRadiiDerivativeCompute()for radius-rescaling solvent models such as DRACO.
Adds support for range-separated hybrid exchange and its nuclear derivatives.
The
cuestDFIntPlan_tcan be configured to use the full-range \(1/r\) operator, the long-range \(\mathrm{erf}(\omega r)/r\) operator and linear combinations thereof.
Adds native support for new exchange-correlation functionals:
\(\mathrm{LC\mbox{-}}\omega\mathrm{PBE}\)
\(\mathrm{LC\mbox{-}}\omega\mathrm{PBEh}\)
\(\omega\mathrm{B97X}\)
\(\omega\mathrm{B97X\mbox{-}V}\)
\(\omega\mathrm{B97M\mbox{-}V}\)
\(\mathrm{CAM\mbox{-}B3LYP}\)
\(\mathrm{HSE06}\)
\(\mathrm{M06}\)
\(\mathrm{M06\mbox{-}2X}\)
Adds support for general multipole integrals and their nuclear derivatives:
cuestMultipoleCompute()evaluates AO multipole matrices for arbitrary Cartesian orders \(x^l y^m z^n\) about a specified origin.cuestMultipoleDerivativeCompute()computes nuclear gradients of the multipole integrals contracted with a user-supplied density matrix.
Adds support for one-electron angular momentum integrals and their nuclear derivatives:
cuestAngularMomentumCompute()computes atomic orbital (AO) angular momentum matrices (\(L_x\), \(L_y\), \(L_z\)) about a user-defined origin.cuestAngularMomentumDerivativeCompute()computes nuclear gradients of angular momentum expectation integrals contracted with a user-supplied input density matrix.
Introduces nabla integrals and their nuclear derivatives:
cuestNablaCompute()evaluates AO nabla operator matrices (\(\nabla_x\), \(\nabla_y\), \(\nabla_z\)).cuestNablaDerivativeCompute()computes nuclear gradients of the nabla integrals contracted with a user-supplied density matrix.
Adds density-fitted nonsymmetric exchange (K) matrix computation:
cuestDFNonsymmetricExchangeCompute()computes AO exchange (K) matrices with nonsymmetric density matrices (e.g., for response or excited-state methods) within a density fitting (DF) framework.Supports batched evaluation over multiple density matrices. Densities are specified as a single left coefficient matrix and multiple right coefficient matrices.
Adds AO-to-MO transformation for density-fitted integrals:
cuestDFMOIntegralsCompute()transforms three-index DF AO tensors \((A|mn)\) into MO-space tensors \((A|ia)\) using pairs of left/right coefficient matrices.Supports batched transformations with variable numbers of left and right orbitals per matrix pair.
Applies the fitting metric (and, when configured, long-range corrected operators) as part of the transformation.
Adds detailed inspection of polarizable continuum model (PCM) calculations:
cuestPCMIntegrationGridCompute()allows the user to obtain the PCM grid.cuestPCMIntegrationWeightCompute()allows the user to obtain the PCM weights.
Adds support for float-float FP64 emulation:
Accelerates VV10 nonlocal correlation, potential, Coulomb, and PCM computations on GPUs with reduced native FP64 throughput, such as the GeForce and workstation-class architectures (compute capabilities 8.6, 8.9, and 12.0).
Defaults to using float-float emulation when beneficial based on the active hardware.
Adds just-in-time (JIT) compilation of specialized GPU kernels for select compute routines:
cuestPotentialCompute(),cuestPotentialDerivativeCompute(),cuestDFCoulombCompute(),cuestDFSymmetricDerivativeCompute(),cuestPCMPotentialCompute(),cuestPCMDerivativeCompute(), andcuestPCMRadiiDerivativeCompute().Requires CUDA Toolkit 13.x or newer (13.0.2 or later); on CUDA 12.x, affected routines run their precompiled kernels instead.
Compiled kernels are cached to disk (default
~/.cuest_cache/cuest-cuda<cuda_major>-v<cuest_version>/) and reused across runs, so the compile cost is paid once per machine.Configurable via
CUEST_HANDLE_PARAMETERS_JIT_CACHE_DIRandCUEST_HANDLE_PARAMETERS_JIT_COMPILE_THREADSon the handle parameters, and per-routine via each routine’s*_JIT_USAGE_MODEparameter.See Just-In-Time (JIT) Compilation in cuEST for details.
Changes#
To improve efficiency in the
cuestDFSymmetricDerivativeCompute(), thecuestDFSymmetricDerivativeComputeMemoryPolicy_toptions have been changed.The
CUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_FULLandCUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_BLOCKEDmemory policies have been deprecated.The
CUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_DEVICECACHEpolicy replacesCUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_FULL.If the new
CUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_OVERWRITEmemory policy is used whencuestDFSymmetricDerivativeCompute()is called, thecuestDFIntPlan_twill be placed in a “dirty” state and cannot continue to be used. Calls using acuestDFIntPlan_tin a dirty state return theCUEST_STATUS_INVALID_PLANstatus code.
The
cuestDFIntPlan_tcan now be constructed in an “integral direct” mode by settingCUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT.Currently, this option is only supported during calls to
cuestDFMOIntegralsCompute().Calls to other compute functions using a
cuestDFIntPlan_tbuilt in “integral direct” mode will fail with theCUEST_STATUS_INVALID_PLANstatus code.
The
cuestDFIntPlan_tnow only accepts values ofCUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTIONthat are greater than or equal to zero.The
CUEST_STATUS_INVALID_ARGUMENTstatus will be returned if this condition is violated.
The
cuestDFSymmetricDerivativeComputefunctions accept NULL pointers for the MO coefficients if no exchange calculation will be performed.This behavior is now consistent for both the C and Python APIs.
Python bindings now use nanobind and the 3.12 stable ABI. This means that Python 3.11 is deprecated and all 3.12+ versions are supported (free threaded Python is not currently supported). While regular usage is unchanged, nanobind introduces some extra type safety preventing, e.g., creation of enum variables from integers that do not correspond to a valid enumerator value.
The libcuest, libcuest-static, and libcuest-dev C packages are deployed only through the conda-forge channel from 0.2.0 onwards. Previous versions are still available on both conda-forge and the nvidia channel.
v0.1.1#
Bug Fixes#
Fixes a possible corruption bug in symmetrizing Vxc and VV10 potential matrices, in cases with large numbers of atomic orbitals. The bug can be observed for medium-sized problems using the
compute-sanitizertool, but is not known to be observable for matrices involving fewer than 10,000 atomic orbitals withoutcompute-sanitizer. Matrices computed by the following API calls are potentially impacted:This change does not modify the signature of any APIs and does not impact performance.
Disclaimer#
cuEST is in a pre-release state. Pre-release products may not be fully functional, may contain errors or design flaws, and may be changed at any time without notice. We appreciate your feedback to improve and iterate on our products.