# GauXC

[GauXC](https://github.com/wavefunction91/GauXC) provides an external exchange-correlation (XC)
integrator for Quickstep. It can evaluate selected conventional functionals and GauXC Skala models
through the [GAUXC](#CP2K_INPUT.FORCE_EVAL.DFT.XC.XC_FUNCTIONAL.GAUXC) section.

The CP2K interface currently provides two distinct paths:

- The default molecular-quadrature path evaluates the XC contribution through GauXC's atom-centered
  molecular grid. It is intended primarily for isolated calculations.
- The experimental native-grid path (`NATIVE_GRID T`) evaluates SKALA TorchScript models from the
  CP2K GPW real-space grid. It has a different support scope and should be treated separately from
  the molecular-quadrature path.

## Basic Input

GauXC is selected as the only XC functional in the
[XC_FUNCTIONAL](#CP2K_INPUT.FORCE_EVAL.DFT.XC.XC_FUNCTIONAL) section. The following fragment selects
a conventional functional evaluated by GauXC:

```text
&XC
  &XC_FUNCTIONAL
    &GAUXC
      FUNCTIONAL PBE
    &END GAUXC
  &END XC_FUNCTIONAL
&END XC
```

A non-`NONE` model selects a GauXC Skala model. The model can be a `.fun` file or an installed model
name. The underlying functional is optional in this case and defaults to `PBE`:

```text
&XC
  &XC_FUNCTIONAL
    &GAUXC
      MODEL path/to/model.fun
    &END GAUXC
  &END XC_FUNCTIONAL
&END XC
```

The `.fun` format and available model checkpoints are defined by GauXC rather than CP2K. `.fun`
files use TorchScript serialization. The official Skala 1.1 checkpoint can be downloaded together
with GauXC in toolchain, or from Hugging Face with the `hf` command provided by the
`huggingface_hub` package:

```bash
hf download microsoft/skala-1.1 skala-1.1.fun --local-dir .
```

Select the downloaded checkpoint with `MODEL ./skala-1.1.fun`. Alternatively, set
`GAUXC_SKALA_MODEL` to its path and use `MODEL SKALA`. See the
[GauXC/Skala model documentation](https://microsoft.github.io/skala/gauxc/c-library.html#download-checkpoint-from-huggingface)
for the model interface and available checkpoints. Obtain `.fun` files only from trusted sources.

The molecular-quadrature Skala path defaults to `GRID SUPERFINE` and `PRUNING_SCHEME UNPRUNED`
unless these settings are provided explicitly. These settings are recommended for force checks;
coarser grids are accuracy settings and should be converged for the target calculation.

## Molecular-Quadrature Path

The default path uses GauXC's molecular quadrature. It is the established interface for isolated
Quickstep calculations, including energy, XC potential, and nuclear-gradient calculations within its
supported scope.

### Periodic Reference Calculations

Periodic inputs are not a compact periodic GauXC implementation. To use the molecular path in a
periodic input as an isolated-cell reference calculation, explicitly set `PERIODIC_REFERENCE` to
`T`:

```text
&GAUXC
  PERIODIC_REFERENCE T
&END GAUXC
```

This reference path is restricted to all of the following:

- `PERIODIC XYZ`;
- Gamma-point calculations with one AO image;
- `METHOD GPW` with GTH pseudopotentials.

It uses a molecular quadrature and must not be used to validate compact periodic materials. Periodic
neighbor-cell AO blocks, k-points, compact-cell quadrature, and periodic stress tensors require a
dedicated periodic GauXC interface.

### Skala Runtime Controls

`MODEL_ATOM_CHUNK_SIZE` controls atom-blocked Torch inference. A positive value selects the number
of atoms per block, zero disables chunking, and the default lets GauXC or the
`GAUXC_ONEDFT_ATOM_CHUNK_SIZE` environment variable choose the policy.

For MPI calculations, `SKALA_RUNTIME` controls the communicator used for Skala energy and potential
evaluation. `AUTO` uses the force-evaluation communicator for closed-shell calculations and a
replicated rank-local runtime for open-shell calculations. The corresponding
`MODEL_GRADIENT_RUNTIME` setting defaults to a conservative replicated runtime for nuclear
gradients. Select `MPI` only with a GauXC installation that supports distributed Skala gradients.

### GAPW and Other Restrictions

- Conventional GauXC with `METHOD GAPW` requires all-electron potentials. With pseudopotentials,
  `METHOD GAPW` is available only for Skala-style models and evaluates the molecular
  AO/valence-density XC term directly.
- Skala with `METHOD GAPW` and GTH/ECP pseudopotentials currently supports energies only; forces and
  molecular virials are unavailable. CP2K's GAPW one-center XC correction is not used on this path.
- `METHOD GAPW_XC`, NLCC pseudopotentials with Skala, and non-local `VDW_POTENTIAL` corrections are
  not supported by the molecular GauXC path.
- Higher-XC-derivative response and kernel properties are not available through GauXC. Real-time
  propagation is also unsupported.

`MOLECULAR_VIRIAL` is a finite-system diagnostic constructed from GauXC nuclear gradients; it is not
a periodic stress tensor.

## Experimental Native-Grid SKALA Path

`NATIVE_GRID T` bypasses GauXC's molecular quadrature and evaluates a SKALA TorchScript model from
CP2K's GPW real-space grid. It is an experimental path for energy, XC potential, and
nuclear-gradient/stress calculations with one GAUXC functional. Unlike the molecular path, it can
cover selected isolated and periodic GPW/GAPW calculations, including k-point density matrices.

A minimal native-grid input is:

```text
&XC
  &XC_FUNCTIONAL
    &GAUXC
      MODEL SKALA
      NATIVE_GRID T
      NATIVE_GRID_DIAGNOSTICS T
    &END GAUXC
  &END XC_FUNCTIONAL
&END XC
```

`NATIVE_GRID_DIAGNOSTICS T` prints the electron count, spin moment, and summed grid weights of the
feature block supplied to Torch. This is useful when validating a model or a periodic setup.

### CUDA and MPI

The CPU TorchScript path is limited to non-k-point calculations. K-point calculations require a
CUDA-capable LibTorch installation and:

```text
&GAUXC
  NATIVE_GRID T
  NATIVE_GRID_USE_CUDA T
  NATIVE_GRID_CUDA_DEVICE -1
&END GAUXC
```

A negative `NATIVE_GRID_CUDA_DEVICE` assigns the MPI-local rank to a visible CUDA device. A
non-negative value selects that visible device explicitly. CUDA TorchScript exports containing
hard-coded device constants may still require a rank-local `CUDA_VISIBLE_DEVICES` setting.

`NATIVE_GRID_ATOM_CHUNKS T` distributes the model evaluation in atom blocks for MPI calculations and
can reduce peak CUDA memory. `NATIVE_GRID_ATOM_CHUNK_MAX_ROWS` further limits the number of
atom-grid rows handled by one Torch call when needed.

### Current Scope

The native-grid path supports regular-grid GPW/GTH calculations and selected GAPW calculations. For
GAPW with GTH/ECP pseudopotentials, only regular-grid feature kinds are supported; PAW and
one-center GAPW pseudopotential contributions are not implemented. `METHOD GAPW_XC`, ROKS, ADMM, and
non-k-point multiple-image calculations are also outside the current scope.

Because this is an experimental interface, validate energies, forces, and stresses for the chosen
model and system before using it for production calculations.

## Troubleshooting

- `CP2K_GAUXC_STATUS_STDERR=1` mirrors GauXC status messages to standard error. This can be useful
  when a launcher or CI system does not retain the CP2K output file after an external-library
  failure.
- TorchScript models require a LibTorch installation compatible with CP2K's BLAS and OpenMP runtime.
  Pre-built LibTorch bundles can conflict with a CP2K build using oneMKL; use a compatible BLAS
  stack or build LibTorch against the selected dynamic stack when this occurs.
- `OUTPUT_PATH` writes GauXC molecule and basis-set diagnostics to an existing directory. It
  requires GauXC to have been built with HDF5 support.

## See Also

- [](../../technologies/libraries)
- [](gpw)
- [](gapw)
