NetKet 3.22: Neural Quantum States on JAX, and What the README Leaves Out

The gap NetKet fills between a neural network and a quantum expectation value

Writing a neural network that outputs a wave function amplitude is easy. Getting a gradient of the energy expectation value with respect to those parameters is not, because the expectation is an integral over an exponentially large Hilbert space. NetKet exists to close that gap. It is aimed at physicists and graduate students who already know variational Monte Carlo and want to swap the traditional Jastrow or Gutzwiller ansatz for a neural network without rebuilding the surrounding machinery. The README frames it as delivering methods for the study of many-body quantum systems with artificial neural networks and machine learning techniques, and the topic list on the repository names the pieces: neural quantum states, Markov-chain Monte Carlo, Hamiltonian construction, variational methods. That combination is the product. A generic deep learning framework has none of it, and a traditional quantum chemistry package has the Hamiltonian side but not the neural ansatz side.

JAX is the architecture, not an implementation detail

The README states plainly that NetKet is a Python library built on JAX. That single sentence determines most of the library's behaviour and most of its friction. JAX gives you just-in-time compilation and automatic differentiation over functions that are pure, so the variational state, the sampler and the local energy estimator can be traced together into one compiled program. In practice this means the first call on a given shape is slow and later calls are fast, and it means any Python side effect inside a traced function breaks. The data flow the documentation describes is the standard variational Monte Carlo loop: sample configurations from the current state, evaluate local energies on those samples, average to get an energy estimate, differentiate that estimate with respect to the network parameters, and update. NetKet supplies each stage as a composable object rather than a fixed training script. The release history supports the JAX-first reading: 3.22.4 shipped in August 2026, with 3.22.3 and 3.22.2 earlier that summer, a cadence consistent with tracking JAX and its ecosystem rather than a frozen numerical kernel.

Installing NetKet and the conda warning in the README

The README gives three install paths. The standard one is pip install --upgrade pip followed by pip install netket. For GPU work, and only on Linux, pip install 'netket[cuda]'. For the development version, pip install git+https://github.com/netket/netket.git. The constraint that matters most is stated in bold in the README: do not use conda, because JAX has known issues when installed through conda. That is an unusual instruction for a scientific Python package, and it will conflict with existing environment management for many research groups. The README also states NetKet runs on MacOS and Linux and requires Python 3.11 or later. Windows is not listed. If your cluster modules or your lab's standard environment are conda-based, plan to build a separate pip or uv environment rather than trying to make the conda route work. The README recommends pip or uv.

Where NetKet is the wrong tool

NetKet is not a general quantum chemistry package and not a solver you point at a molecule and walk away from. It gives you building blocks and expects you to assemble a variational calculation. The README is candid about the learning material: it points to a tutorials page and to example scripts in the Examples directory, and notes that those examples are not commented. For anyone who does not already understand neural quantum states, that is a real gap. The tutorials are the intended entry point, and the README suggests running them locally or on Google Colaboratory. A second limitation follows from the JAX dependency. If your existing model code is PyTorch, NetKet will not accept it, and porting a nontrivial network is not a mechanical translation. A third is hardware: the README lists MacOS and Linux only, so a Windows workstation is out unless you use a container or WSL, which the README does not discuss. Finally, exact diagonalisation and tensor-network methods remain the better choice for small systems and for one-dimensional gapped chains where they are cheap and deterministic. Sampling introduces statistical error that those methods do not have.

Alternatives and the difference in approach

The closest alternative in spirit is a hand-rolled variational Monte Carlo script: you write your own Metropolis sampler, your own local energy estimator and your own gradient loop on top of JAX, PyTorch or NumPy. That approach wins on transparency and loses on reuse. You will reimplement sampling, operator application and parameter update logic that NetKet already provides, and you will debug them yourself. The other direction is a mature quantum chemistry stack, which handles second quantisation and molecular integrals with well-tested machinery but does not offer neural-network wave functions as a first-class ansatz. NetKet sits between those two: more structure than a bespoke script, less domain coverage than a chemistry package. The practical difference is that NetKet's design assumes you want to change the ansatz and keep the sampler, whereas a bespoke script assumes the opposite.

Maintenance, release cadence and the Apache-2.0 terms

NetKet is released under the Apache License 2.0, and the repository is not archived. The three releases listed in the supplied material span June to August 2026, which indicates an actively maintained project rather than one parked after a paper. Apache-2.0 is a permissive licence with an explicit patent grant, and it permits commercial and academic use, modification and redistribution provided you retain the required notices and state significant changes. It does not require you to publish your own code. This is a description of the licence text, not legal advice; if you are embedding NetKet in a product, have your own counsel review the notice and attribution obligations. The maintenance cost you should budget for is the JAX coupling. A library that tracks JAX closely will occasionally require you to move your environment forward, and JAX itself has moved fast historically. Pin your NetKet and JAX versions together in a lockfile and upgrade them as a pair, because the README's conda warning shows the project already expects environment management to be a source of trouble.

Who should adopt it and what to check first

Adopt NetKet if you are doing research on neural quantum states, you already work in JAX, and you want the sampler, the operator construction and the variational optimisation loop to come from one library instead of three half-finished internal scripts. The NumFOCUS affiliation and the steady release cadence suggest the project will still be there in a few years. Do not adopt it if you need conda, if you are on Windows, if your models live in PyTorch, or if you want a black-box solver. The first thing to verify is not a feature but an environment: confirm Python 3.11 or later on every machine you intend to use, confirm Linux for any GPU run, and build the environment with pip or uv as the README instructs. Then take one tutorial from the documentation, run it unchanged, and only afterwards swap in your own Hamiltonian and your own network. That sequence tells you within an afternoon whether the JAX tracing constraints and the uncommented Examples directory are workable for your group.

Editorial conclusion

Adopt NetKet if you already write JAX and want Markov-chain Monte Carlo sampling, variational state optimisation and operator construction in one library rather than wiring them together yourself. Do not adopt it if your workflow is built on PyTorch or TensorFlow, if you need conda, or if you are on Windows, since the README states MacOS and Linux only. Before committing, verify that Python 3.11 or later is available on your target machines, that your GPU hosts are Linux, and that you can reproduce one tutorial from the documentation end to end on your own Hamiltonian. The install path is pip install netket, or pip install 'netket[cuda]' for Linux GPU support, and the README explicitly says not to use conda because of known JAX issues.

Official sources

1. License: Apache-2.0
2. netket/netket on GitHub
3. Project website
4. README
5. Releases