DeepQMC: neural network wave functions for molecules, configured through Hydra
Deep learning quantum Monte Carlo for electrons in real space
At a glance
- What is it?
- DeepQMC is a JAX and Haiku suite for variational Monte Carlo over deep-learning molecular wave functions, with penalty-based excited states and transferable ansatz training. It is a research instrument for computational chemistry groups, not a drop-in quantum chemistry package.
- Who is it for?
- Adopt DeepQMC if you are a computational chemistry or machine learning research group that already works with JAX and needs variational Monte Carlo over neural network ansatzes, including excited states or transferable training across molecular configurations. Do not adopt it if you need a general-purpose quantum chemistry workflow with basis-set selection and analytic gradients; this is a research code for a specific class of ansatz.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap DeepQMC fills between neural network ansatzes and runnable simulations
Publishing a neural network wave function ansatz and shipping a reproducible optimization pipeline are different jobs. DeepQMC takes the second one. The README describes it as an open-source software suite for variational optimization of deep-learning molecular wave functions, solving the molecular Hamiltonian with support for effective core potentials. The intended user is not someone who wants a molecular energy by Thursday. It is a researcher who has read the Psiformer, PauliNet, FermiNet or DeepErwin papers and wants to run that family of methods without reimplementing the sampler, the local energy estimator, and the training loop from scratch. The repository ships config files for variants of all of those architectures, plus LapNet and a transferable extension called TransPsiformer, under src/deepqmc/conf/ansatz. That directory is effectively the catalogue of what the package can instantiate. If your target architecture is not represented there, you are writing a new config and possibly new modules rather than picking an option.
JAX, Haiku and Hydra: the three-layer stack and what each layer owns
The dependency choices determine how you will actually work with the code. JAX supplies the array programming and automatic differentiation that make the variational optimization tractable, and it is also the reason GPU setup is a manual step rather than an install flag. Haiku provides the neural network module abstraction, which is why the ansatz configs map onto named architectures rather than onto raw parameter trees. Hydra, in its CLI build, owns configuration composition, so experiments are assembled from config groups instead of from long argument lists. That last choice has a practical consequence: reproducing someone else's run means reproducing their config tree, and the ansatz directory is the part of that tree the README points at explicitly. The README also names the mechanisms the code implements: a penalty-based approach for excited states, a spin penalty that targets states in a fixed spin sector, and geometric transferability, where a single ansatz is optimized across multiple configurations of a set of atoms. Transferability can be done on a fixed set of molecular configurations or by dynamically sampling configurations during optimization, and the README states it can be combined with excited-state optimization. Those three mechanisms are the substance of the package. Everything else is plumbing around them.
Installing DeepQMC and the GPU step the README makes your problem
The release install is one command: pip install -U deepqmc. For a local checkout, the README gives git clone, cd deepqmc, then pip install -e .[dev]. It notes that if Pip complains about setup.py not being found, you should update Pip. That is a small but telling detail about the packaging era the project targets. The more consequential instruction is about hardware. The README states plainly that the standard installation results in the CPU version of JAX and that running on GPU is highly recommended. Enabling it means upgrading JAX yourself to match your system's CUDA and cuDNN versions, with the README offering pip install "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html as the common CUDA 12 path, and pointing to the JAX install guide for everything else. There is no DeepQMC-specific GPU installer and no version matrix in the README. Validation is a single bare command: run deepqmc. That entry point exists to confirm the installation and its dependencies, not to launch a meaningful calculation. Treat the CUDA matching step as the real installation work, because a JAX build compiled against the wrong CUDA version fails at runtime rather than at install time.
Where DeepQMC is the wrong tool
The README's own framing sets the boundary. This is a suite for variational optimization of deep-learning molecular wave functions, and the methods it implements are stochastic and iterative. If your problem is a routine ground-state energy for a modest molecule, a conventional quantum chemistry package will give you an answer in seconds with analytic gradients and well-understood error behaviour. DeepQMC will give you a distribution of local energy estimates whose quality depends on how well the ansatz was optimized, and the README does not promise convergence criteria, error bars, or comparison tables against coupled cluster. The excited-state path is explicitly penalty-based, which is a specific methodological choice with known trade-offs in the literature the README cites, not a general excited-state solver. Transferable training across configurations increases the optimization problem's scope, and the README does not discuss cost scaling or memory behaviour for large configuration sets. There is also a hardware floor: the README calls GPU use highly recommended, which for practical purposes means a CPU-only machine is a debugging environment, not a production one. And because configuration runs through Hydra, a miscomposed config can silently train an architecture you did not intend. Nothing in the supplied material describes config validation or a dry-run mode that would catch this before the optimization starts.
How this differs from a conventional quantum chemistry code
The contrast worth drawing is not against another neural network VMC package but against the deterministic electronic structure stack most chemistry groups already run. A conventional code expands the wave function in a fixed basis and solves for coefficients, so the error is controlled by basis set choice and the result is reproducible to numerical precision. DeepQMC replaces the fixed expansion with a neural network whose parameters are optimized stochastically against the variational energy, and the README's architecture list shows what that buys: a single ansatz can be trained across multiple molecular configurations, and excited states can be targeted through penalties rather than through state-averaged orbital optimization. The cost is that you inherit a training loop. You need to reason about optimization schedules, sampler behaviour and the penalty weights, none of which have a counterpart in a basis-set calculation. The README's own citation list reflects this: the implementation paper, a dedicated excited-state paper, and a transferable-simulation paper are presented as the references for methodology and experiments. That is the reading load you take on before you can interpret a DeepQMC result. If you are not prepared to engage with those papers, the tool will produce numbers you cannot defend.
Version history, maintenance and licensing
The release cadence visible in the repository metadata is uneven. Version 1.1.2 landed in November 2023, 1.2.0 in September 2024, and 1.3.0 in July 2026, with the last push to master in August 2026. That is roughly one substantive release per year, with a long gap between 1.2.0 and 1.3.0. For a research package this is normal, but it means you should expect to track master or pin a specific tag rather than assume frequent patch releases. The README's installation section does not mention a supported Python version range beyond the PyPI badge, and the upgrade path between minor versions is not documented in the material provided. The licence is MIT, which the README also records in the Zenodo citation block. MIT is permissive: it allows use, modification and redistribution with the copyright notice preserved, and it comes with no warranty. That last point matters more here than in a typical library, because a silent numerical error in a wave function optimization produces a plausible number rather than a crash. The README asks users to cite the implementation paper, the excited-state paper and the transferable-simulation paper depending on which features are used, plus the Zenodo record for the repository itself. Citation is an academic norm rather than a licence term, but for a package whose value is concentrated in published methods, treating it as optional is a poor fit for the community it serves.
Who should install it, and what to check first
The fit is narrow and the README is honest about it. You should adopt DeepQMC if you are in a group that already runs JAX on GPU hardware, you want to optimize neural network trial wave functions for electrons in real space, and your interest includes at least one of the features that distinguish this package: penalty-based excited states, fixed-spin-sector targeting, or transferable optimization across molecular configurations. You should not adopt it if you need a general electronic structure workflow, if you have no GPU available, or if you are unwilling to read the three associated papers before trusting an output. The verification sequence before any real calculation is short and specific. Confirm your JAX build matches your CUDA and cuDNN versions, since the README makes that your responsibility. Run the deepqmc entry point to confirm the installation resolves. Then open src/deepqmc/conf/ansatz and confirm that the config matching your target architecture is the one you think it is, because that directory is the only place the README identifies where the shipped ansatzes live. If the architecture you need is absent from that directory, budget for implementation work, not configuration work.
Editorial conclusion
Adopt DeepQMC if you are a computational chemistry or machine learning research group that already works with JAX and needs variational Monte Carlo over neural network ansatzes, including excited states or transferable training across molecular configurations. Do not adopt it if you need a general-purpose quantum chemistry workflow with basis-set selection and analytic gradients; this is a research code for a specific class of ansatz. Before committing, verify three things: that your JAX build matches your CUDA and cuDNN versions, that the deepqmc entry point runs cleanly after installation, and that the ansatz config under src/deepqmc/conf/ansatz actually corresponds to the architecture you intend to reproduce.
Community notes