Change Log#

0.5.0#

Added#

L-BFGS optimizer: Added an L-BFGS geometry optimizer with Warp, PyTorch, and JAX bindings for fixed-cell and variable-cell relaxation.
Trust-region step control: L-BFGS bounds step sizes with a trust region without energy evaluations.
Batch state management: Added LBFGSState and LBFGSCellState structures with preparation functions that allocate and validate optimizer state.
Precision preservation: L-BFGS matches coordinate precision end-to-end and selects curvature thresholds for float32 and float64.
Fourier DFT-D3 dispersion: Added periodic fourier_dftd3 in PyTorch and JAX for energy, forces, and optional virial on batched neighbor lists.
Fourier DFT-D3 caching: Added FourierD3Parameters for reusable C6 coefficients and FourierD3Setup for optional cell and mesh preprocessing caches.
Prepared cluster-tile execution: PyTorch prepare_neighbor_list accepts cluster-tile methods, preparing reusable neighbor list storage for repeated calls.
Compiled cluster-tile lists: PyTorch cluster-tile neighbor lists support torch.compile and torch.cuda.CUDAGraph replay with selective rebuilds.
Reciprocal Miller topology: Added generate_ewald_miller_indices and k_vectors_from_miller_indices in PyTorch and JAX to cache reciprocal grids.
Buffer overflow detection: Added the TileBufferOverflow exception and max_tiles_per_group parameter to detect undersized cluster-tile buffers.
JAX compilation boundaries: Added fixed-capacity jax.jit support for naive and cell-list neighbor lists through coo_capacity.
JAX D3 parameters: JAX dftd3 accepts D3Parameters directly under jax.jit without manual array unpacking.
Precision-selective erfc: Added wp_erfc_f32_fast (an explicitly float32-grade approximation) and wp_erfc_input_precision (dispatches by input dtype) in nvalchemiops.math.
Squared-magnitude PME grids: Added generate_k_squared_pme in the Torch and JAX electrostatics namespaces for reciprocal paths that use squared magnitudes.
Legacy electrostatics mode query: Added electrostatics_uses_legacy_fp32() to report whether the legacy float64-core path is forced.

Changed#

Minimum Warp version: Raised the minimum warp-lang requirement to 1.16.0.
Minimum PyTorch version: PyTorch extras now require PyTorch 2.10 or newer for compiled matrix-to-COO conversions.
JAX dual-cutoff validation: JAX dual-cutoff neighbor functions now require the second cutoff to be greater than or equal to the first.
Segmented index types: PyTorch segmented operations now accept int64 indices whose values fit in int32.
Fourier DFT-D3 coordination numbers: Fourier DFT-D3 tapers coordination numbers to zero at the cutoff radius. This produces small numerical differences from standard DFT-D3.
PME mesh sizing: PME mesh estimation now covers the requested spline support and prefers FFT-smooth dimensions. The default spline order is now 5 (previously 4), which can change numerical results; pass spline_order=4 and the previous mesh_dimensions to reproduce the old configuration.
Reduced PME peak memory: PME energy and force paths generate only the squared reciprocal grid when Cartesian reciprocal vectors are unused; virial and cell-gradient paths still generate them.
float32 electrostatics fast path: Monopole Ewald and PME now evaluate in float32 for float32 CUDA inputs instead of promoting to float64; float32 results change at the ~1e-07 level, double-backward still uses the float64 formulation, and Torch CPU execution is unchanged (JAX does not yet gate on device and also uses float32 on CPU). Set NVALCHEMIOPS_ELECTROSTATICS_LEGACY_FP32=1 to evaluate float32 inputs in float64 as before. Independently of this flag, float64 real-space pair evaluation now uses the native erfc, so float64 results can differ from 0.4.x at the ~1e-07 relative level.
Opt-in grid_policy="adaptive" selects pair-centric cell grids from geometry and atom populations to reduce estimated search work in Torch and eager JAX full-list CUDA calls. The model assumes approximately uniform occupancy; performance depends on the workload. "configured" remains the default.
Eager JAX naive tile and cell-list queries reuse compiled inner calls.
Torch naive_neighbor_list checks the shape, dtype, and device of caller-provided output buffers and raises ValueError instead of writing past an undersized buffer.

Deprecated#

nvalchemiops.math.wp_erfc is deprecated in favor of wp_erfc_input_precision or wp_erfc_f32_fast; it keeps its original behavior for existing callers.

Fixed#

Fixed PyTorch bindings to execute Warp kernels on the active CUDA stream across all modules.
Corrected the uniform background neutralizing term in multipole Ewald and PME for charged systems.
Fixed PyTorch segmented operations to avoid retaining CUDA graph pool allocations during cached launches.
Corrected JAX ewald_reciprocal_space derivatives to include reciprocal cell gradient contributions.
Changed neighbor_list keyword argument type annotations from dict to Any in PyTorch and JAX.
Fixed PyTorch matrix-to-COO conversions for variable output edge counts under torch.compile.
Registered FIRE2 custom operators with PyTorch library dispatch to support compilation.
Fixed symbolic shape tracing for PyTorch electrostatics and multipole operations under torch.compile.
Prevented host synchronization during cell matrix inversion inside CUDA graph capture.
Corrected cluster-tile neighbor periodic image selection for skewed triclinic cells.
Pair-centric grid sizing accounts for estimated neighbor-loop work in dense systems.
Targeted Torch cell-list calls refresh search radii when reusing workspaces, preventing missed neighbors after a full-list adaptive call.
Loaded the benchmark dataset cache with weights_only=True.

v0.4.1 - 2026-08-03#

Added#

Monopole Torch and JAX Ewald, PME, and slab entry points accept keyword-only energy_reduction="atom" | "system" (default "atom"). "atom" returns per-atom energies (N,); "system" returns per-system totals (B,). Direct-output fields (forces, charge gradients, virials) keep their existing shapes. Torch eager atom mode may synchronize once per participating component when a materialized uniform cotangent is proven by value inspection; system mode is structurally sync-free for arbitrary (B,) loss weights. JAX adds API/layout parity only; underlying Warp kernels remain atom-buffer-oriented.
PyTorch cluster-tile selective calls can append caller-owned tile state with return_state=True, without changing the default neighbor-list return arity.

Changed#

Improved JAX neighbor-list import performance by deferring dtype-specific direct naive and cell-list Warp wrapper registration until first use. Cluster-tile graph callbacks now use bundled callback/preload registrations with lazy direct kernels for naive and cell-list paths. Public behavior is unchanged.

Fixed#

Fixed Torch PME and Ewald energy gradients for connected charge, position, and cell inputs. Non-uniform or weighted energy losses and create_graph=True higher-order derivatives no longer double-count upstream chain-rule terms.
Torch ewald_reciprocal_space now preserves graph-connected reciprocal vectors for cell/strain autograd, restoring the physical reciprocal Ewald virial when vectors are regenerated from the differentiable cell.
Torch Ewald, PME, and slab backward paths now compile when an explicit single-system batch (batch_idx=zeros(N)) is supplied. Reciprocal PME compiled gradients are also correct when a compiled function is reused across mesh sizes.
Torch DFT-D3 custom operators now zero caller-owned energy, forces, coordination-number, and virial buffers before empty-system or zero-edge early returns, so reused output tensors cannot retain stale values.
JAX DFT-D3 CSR calls with atoms but no edges return zero-filled per-atom forces and coordination numbers with shapes (N, 3) and (N,), matching the neighbor-matrix contract and preserving per-system energy and virial axes.
JAX cell-list builds now derive search radii from their realized grids, preventing missed neighbors when static capacity changes the constructed grid. Batched capacity_strategy="geometry" preserves promoted grids for all non-empty systems by reserving an equal per-system capacity; volume-based sizing remains the default. Fused Warp graph calls with explicit max_total_cells now require an explicit neighbor_search_radius.
Unbatched JAX naive dual-cutoff PBC neighbor lists now populate both cutoff outputs when using the default wrap_positions=True. Previously this path wrapped positions but skipped the fill kernel, leaving zero counts and padded matrices.
Batched PyTorch cluster-tile segmented COO validates fixed topology, offsets, counts, and tile-state capacities before launching Warp kernels.
Single-system Torch and JAX segmented cluster-tile COO now require one exact physical interval, bound writes by output capacity, fail closed for malformed offsets, and cap compiled/JIT active counts to writable capacity. Batched per-system physical subsegments remain supported.
Compiled unified PyTorch cluster-tile dispatch now rejects tensor-valued PBC rather than treating it as fully periodic. Eagerly validate PBC and compile the direct single-system fixed-state route instead.
JAX cluster-tile empty selective rebuilds now preserve false-flag state and clear true-flag pair and tile counts while retaining fixed-capacity storage.

v0.4.0 - 2026-07-13#

Added#

Full Torch Ewald/PME APIs support energy-derived forces, charge gradients, and strain-first virials, including second-order force/stress losses.
Full JAX Ewald/PME energy-only calls support first-order gradients for positions, charges, and row-vector displacement virials. JAX PME reciprocal higher-order support is limited to tested position and charge scalar losses; PME cell/stress/strain higher-order derivatives remain unsupported.
2D slab correction is exposed through compute_slab_correction and the high-level Ewald/PME slab_correction= keyword in Torch and JAX.
Higher-order multipole electrostatics for charges, dipoles, and quadrupoles (l = 0, 1, 2) are available through Torch/Warp direct-k Ewald, PME, feature extraction, and SCF cache/step APIs.
Differentiable segment operations are available through nvalchemiops.torch.segment_ops and nvalchemiops.jax.segment_ops.
Neighbor-list APIs now include inline pair_fn potentials, optional per-pair vectors/distances, a cluster-pair tile strategy, partial rebuild flags, and public strategy cost/suggestion helpers.
compute_bspline_moduli_1d is exported from the top-level Torch and JAX electrostatics namespaces for PME precompute workflows.

Changed#

Direct-output flags on full Ewald/PME APIs remain functional but are deprecated for differentiable training. Use energy-only calls plus framework autograd for forces, charge gradients, and virials in training workflows.
neighbor_list(method=None) now uses a geometry cost model and can select fine-grained strategies such as naive_tile, cell_list_pair_centric, and cluster_tile when eligible.
The nvalchemiops.neighbors package was restructured into per-strategy subpackages (naive/, cell_list/, cluster_tile/, rebuild/). Flat compatibility modules continue to re-export with DeprecationWarning.
DFT-D3 dispersion kernels were optimized for improved performance.
PyTorch version requirements were loosened and CUDA backend extras were updated for CUDA 12/13 install workflows.
The minimum warp-lang requirement is now >= 1.13.

Fixed#

Fixed an issue with JAX naive PBC pair-output paths that dropped non-zero periodic images. The JAX naive_neighbor_list pair-output path (return_distances / return_vectors, and now pair_fn) launched its periodic kernel with the shift axis pinned to 1, so when cutoff exceeded half the cell width (R>1) every non-zero periodic image was silently dropped — yielding too few neighbors and incorrect per-pair distances/vectors/forces relative to the PyTorch binding. The launch now enumerates all shifts (max_shifts), matching PyTorch and the analytic neighbor set in the multi-image regime. The single-cutoff cutoff < half-cell (R==1) case is unchanged.
Fixed an issue with JAX per-pair distance/vector higher-order gradients. The JAX neighbor-list autograd returned the detached Warp-kernel distances/vectors and re-attached only a first-order gradient via a custom_vjp, so the Hessian / Hessian-vector-product was incorrect (~45% off) whenever the downstream loss was nonlinear in the returned distances (e.g. (distances**2).sum()); first-order gradients (forces) were unaffected. The geometry is now reconstructed as a live, differentiable pure-JAX function of positions/cell, so gradients of all orders are exact (matching PyTorch and the analytic Hessian). Affects all JAX return_distances/return_vectors bindings (naive, cell_list, cluster_tile, batched).
Fixed DFT-D3 forces and virials with S5 smoothing. When smoothing was active, the CN-chain dE/dCN used the unswitched pair energy, so CN-chain forces and virials did not exactly match the gradient of the switched energy. Only runs with S5 smoothing enabled were affected; the default (smoothing disabled) was already correct and is unchanged.
Naive PBC neighbor wrapping now leaves non-periodic axes unwrapped when per-axis pbc flags are supplied.
Fixed Torch Ewald gradients for non-uniform per-atom energy cotangents.
JAX electrostatics no longer imports the removed jax.custom_transpose; transpose rules use stable jax.custom_vjp paths.
FIRE2 variable-cell updates now advance positions and cell degrees of freedom consistently during constrained/variable-cell relaxation.
Neighbor-list launchers now reject unbatched methods when batch metadata is supplied.
MTK NPT/NPH cell propagation, velocity half-step coupling, and barostat half-step thermostat coupling now match the intended strain-rate formulation.
JAX naive PBC pair-output paths enumerate all periodic images in the multi-image regime.
JAX per-pair distance/vector outputs are reconstructed as live differentiable geometry, fixing higher-order gradients for nonlinear distance losses.

Deprecated and Removed#

compute_forces, compute_virial, compute_charge_gradients, and hybrid_forces direct-output flags on full Ewald/PME APIs are deprecated for differentiable training.
nvalchemiops.neighbors.zero_array is deprecated; call array.zero_() directly.
cells_inv and volumes dynamics arguments listed in CHANGELOG.md are deprecated.
cell_velocities now stores the strain rate ε̇ = p_g/W, not ḣ = dh/dt.
npt_barostat_half_step{,_aniso,_triclinic} drop the eta_dots argument.
The internal make_outer_neigh_offsets helper was removed.

Version 0.3.0 - 2026-03-16#

Breaking Changes#

PyTorch is now an optional dependency: Core codebase consists of framework-agnostic warp-lang kernels with PyTorch bindings in separate namespace (nvalchemiops.torch.*). You can install the minimum supported version of PyTorch via uv pip install nvalchemiops[torch].
Naive PBC cached metadata changed: public Torch and JAX naive neighbor-list workflows now cache shift_range_per_dimension, num_shifts_per_system, and max_shifts_per_system. shift_offset and total_shifts are no longer part of the public API for cached naive-PBC inputs.

Migration Guide#

Tip

If PyTorch is detected in the environment, existing imports will continue to work for the next few minor version increments, but will emit warnings to remind users to update import paths (shown below).

Core modules comprise the pure warp-lang kernels and launchers.
PyTorch neighbor lists: Change nvalchemiops.neighborlist.neighbor_list to nvalchemiops.torch.neighbors.neighbor_list
DFT-D3: Change from nvalchemiops.interactions.dispersion import dftd3 to from nvalchemiops.torch.interactions.dispersion import dftd3
Coulomb: Change from nvalchemiops.interactions.electrostatics import coulomb_energy to from nvalchemiops.torch.interactions.electrostatics import coulomb_energy
Ewald: Change from nvalchemiops.interactions.electrostatics import ewald_summation to from nvalchemiops.torch.interactions.electrostatics import ewald_summation
PME: Change from nvalchemiops.interactions.electrostatics import particle_mesh_ewald to from nvalchemiops.torch.interactions.electrostatics import particle_mesh_ewald
Utility functions: estimate_cell_list_sizes and estimate_batch_cell_list_sizes are now imported directly from nvalchemiops.torch.neighbors (previously nvalchemiops.neighborlist.neighbor_utils)

Version 0.2.0#

Bug fixes associated with neighbor list computation.
Added electrostatics interface.

Version 0.1.0#

Initial public beta release of nvalchemiops.