This page answers the questions users ask about CASINO, in the forum, by e-mail and at the summer schools, as they stand at version 3.2 (October 2026). The answers are short and link to the places that say more: the manual, whose chapters are named in the text, and the pages of this site. The sections “From 3.0 to 3.2” and “Is CASINO right?” are new, and are the ones to read if you have used an earlier version.

1. The program

What is CASINO?

CASINO is a program for quantum Monte Carlo calculations of the electronic structure of atoms, molecules and solids: variational Monte Carlo (VMC), diffusion Monte Carlo (DMC) and reptation Monte Carlo (RMC), for finite systems and for systems periodic in one, two or three dimensions, with all-electron atoms or pseudopotentials. It also treats model systems of interacting particles, electron and electron-hole gases, excitons, positrons and cold atoms, with the same methods. It has been developed since the early 1990s and first released in 1999; the page What is CASINO? says more, and Chapter 1 of the manual explains the methods.

What can it calculate, and what can it not?

Its central result is the total energy of a many-electron ground state, with a statistical error bar, in VMC with a trial wave function and in DMC, which recovers most of the correlation energy that a single determinant misses. Energy differences follow: binding and cohesive energies, reaction energies, defect formation energies, quasiparticle and excitonic gaps, equations of state. Beyond the energy it accumulates densities and spin densities, pair-correlation functions and structure factors, density matrices and momentum densities, the dipole moment, the localisation tensor and atomic forces, and, since version 3.2, the probabilities of finding n electrons in a region and the exchange-correlation hole of a molecule (Section 10). The manual’s Chapter 1 has tables of every capability with its status.

What it is not for: molecular dynamics on a QMC energy surface, since every energy along a trajectory costs a full calculation; finite temperature; excited states beyond those a trial wave function of the right symmetry or occupation can describe; and systems whose fixed-node error is likely to be as large as the effect sought and for which no better nodes can be built. The manual’s section “When QMC is the right tool, and when it is not” says more.

How accurate is it, and what does it cost?

A QMC result carries a statistical error, which the program reports, and systematic errors it does not: the error of the trial wave function (in DMC, the fixed-node error alone, or the fixed-phase error for a complex wave function), the time-step and population-control biases of DMC, the pseudopotential and its localisation error, and finite-size errors in a periodic cell. Each is checked by a further calculation, and the manual’s tutorial (Chapter 3) shows the three checks of a DMC result. For a fixed error bar on the total energy the computer time grows as the cube of the number of electrons, and as its fourth power with backflow; for an error bar on the energy per electron it grows as N, or N² with backflow. The cost of an all-electron calculation grows as Z⁵ to Z^6.5 with the atomic number, which is why heavier atoms are treated with pseudopotentials. A QMC calculation costs far more than a density-functional one of the same system; what it buys is an energy whose errors are controlled, and a reference against which cheaper methods can be tested.

Why is my QMC energy higher than my DFT energy?

Because a DFT energy is not an energy of the many-electron Hamiltonian but the value of an approximate functional, which need not lie above the exact energy; it can lie below the exact energy and often does. VMC and fixed-node DMC energies are expectation values of the true Hamiltonian, so for a local potential they lie above the exact energy, DMC’s in the limit of zero time step and infinite population; a better trial wave function lowers the VMC energy and usually, not always, the DMC energy. The number to compare with is the Hartree-Fock energy from the same orbitals and basis: a VMC run with no Jastrow factor and no cusp correction should reproduce it, and the correlation energy recovered is measured from there (see why the two may differ).

Who wrote CASINO, and who maintains it?

Its principal authors are Richard Needs, Mike Towler, Neil Drummond and Pablo López Ríos, with contributions from many students, postdocs and collaborators, whom the manual’s credits name. It is maintained by Mike Towler, with Neil Drummond and Pablo López Ríos. The DIARY file in the distribution names the author of every change since 1999.

How do I get a copy, and what does the licence allow?

CASINO is free to any academic or individual for use that makes no profit; a company asks for a commercial licence. A first copy is obtained by completing the form on the page How to get a copy, which also gives the CASINO login that later downloads and the forum need. The standard version’s source is deliberately made hard to read; the developer version is the same program with its full source, for those accepted as developers (below). The conditions a user agrees to are listed in the manual’s front matter and on the consent form: the copy is not passed on, the source is not modified or incorporated elsewhere without written permission, which is usually easy to obtain, and publications cite the paper below.

How do I cite it?

A publication of results obtained with CASINO cites R. J. Needs, M. D. Towler, N. D. Drummond, P. López Ríos and J. R. Trail, J. Chem. Phys. 152, 154106 (2020). A paper that discusses a method or algorithm CASINO uses also cites the paper on it; the page How to cite lists them.

Where do I ask for help?

The manual, the examples directory and the descriptions printed by casinohelp are the first sources. Questions are asked and answered on the CASINO forum, which has been the place to ask since 2013 and is where many of the questions on this page were first asked; the page The forum says how to join. A fault in the program, a crash, a wrong result or a statement of the manual that the program contradicts, is reported there too, with the input files that show it, the output, the version (printed at the head of the out file) and the architecture it was built for. A fault that can be reproduced can be fixed.

2. Installing CASINO

What do I need to build it?

A Linux or other Unix system with the bash shell, a Fortran compiler, a C compiler and GNU make; for parallel runs, an MPI library with its compiler wrapper and launcher, such as Open MPI’s mpif90 and mpirun. The BLAS and LAPACK routines CASINO uses come with the distribution and are built with it, so no numerical library is required; an architecture file may link the system’s own OpenBLAS instead, and then its development package is needed. The utilities are mostly bash and Python 3 scripts; a few need tcsh or Perl, the plotting utilities use xmgrace, gnuplot or matplotlib, whichever is present, and the converters for TREXIO, WIEN2k, FHI-aims, QBOX and ADF are Python scripts that need NumPy, ADF’s SciPy too. The file FAQ at the top of the distribution gives, for each common Linux distribution, the one command that installs these packages, and the install script can run it for you. The manual’s Chapter 2 is the full account.

How do I install it?

Unpack the archive in any directory and run ./install in the CASINO directory it makes. The script detects the machine and its compilers, offers the matching architecture, builds the program and the utilities, and saves the configuration in your shell’s start-up file so that runqmc, casinohelp and the rest are on your path in every new interactive shell; a script or a batch job reads ~/.bashrc.casino itself first. Since version 3.2 it can run without a terminal, taking its answers from options, and the new utility casinocheck checks an installation. An installed copy can be moved, or kept beside another version, each in a directory of its own. The page How to install walks through it; Chapter 2 of the manual has the detail, including building by hand with make.

Do I need root, and can I install it for everyone?

No root. CASINO is not designed to be installed system-wide: each user keeps a copy, in any directory, because the distribution holds, besides the program, the utilities, the examples and the documentation the user works with. On a shared machine every user unpacks and builds their own copy, and the licence lets you run it on any computer at your institution.

Which compilers are supported?

The architecture files of the distribution describe builds with gfortran and with the Intel, NVIDIA, Portland, NAG and other compilers, on workstations, clusters with batch systems, macOS, Cygwin and FreeBSD. On a Linux workstation the usual choices are linuxpc-gcc and linuxpc-gcc-parallel for gfortran, serial and with MPI, and linuxpc-ifx and linuxpc-ifx-parallel for Intel’s oneAPI compiler ifx, the parallel one built against the Open MPI that Linux distributions package; both ifx files were added in version 3.2, and the install script detects them. A machine that no architecture file describes needs one, usually a few lines (the manual’s appendix on the architecture system). A compiler that CASINO does not build with is a fault worth reporting, with the compiler’s messages.

Does it run on Windows or a Mac?

On a Mac, yes: the macOS architectures build with the GNU compilers and Open MPI, and the manual’s platform notes say what the shipped bash, which is too old for some of the utilities, needs. On Windows, in the Windows Subsystem for Linux, which is a Linux and takes the Linux build, or in Cygwin, for which the cygwin-gcc and cygwin-gcc-parallel architectures build with Cygwin’s own compilers and Open MPI. The older native Windows build through winwrap is kept but has been superseded since 2014. The platform appendix of the manual collects what a user of Windows or macOS needs beyond Chapter 2.

The build fails. What do I do?

Read the first error, not the last: a build that stops in one file stops the rest, and the later messages are consequences. The things to check are a missing package from the list above, a compiler that does not support Fortran 2008, and MPI compiler wrappers that call a different Fortran compiler from the one the architecture expects. Since version 3.2 the install script names the OpenBLAS package the .openblas architectures need, and reports a failed build as failed rather than done. If the cause is not plain, post the compiler’s messages, the architecture and the compiler’s version on the forum.

How do I update, and can I keep several versions?

Later versions are downloaded with your CASINO login from Update CASINO: the latest release, or the current beta, which is rebuilt each time a change is published. Keep several versions each in a directory of its own; commands typed by name run the copy whose configuration was last saved by the install script. A developer with access to the git repository updates with git, as the file doc/GIT_GUIDE describes.

3. Running calculations

How do I run a calculation?

With one command, runqmc, in a directory holding the input file of keywords, the orbital file from the program that computed them, any pseudopotential files and, once there is one, the Jastrow factor in correlation.data. The script is the same on a laptop and on a national facility: it learns the machine from its architecture file, checks the calculation for the common mistakes before anything runs, so that they are reported at once rather than after a day in a queue, and starts the program, or on a cluster writes the submission script and submits it. runqmc -p 4 runs four processes; runqmc --help lists the options. The run writes out, the account of the calculation, a history file of the energies of every step, and config.out, the state at the end. A typical project is a chain: orbitals from another program, VMC with them alone, optimisation of a Jastrow factor, and DMC with the optimised trial wave function; Chapter 3 of the manual works through one from start to finish with every number shown.

How many processes should I use?

In VMC, as many as you have: each process makes a random walk of its own and nothing is communicated while the walks run, so a run on P processes gives as much data as a run P times as long on one. Optimisation is nearly as parallel. In DMC the walkers are divided among the processes and redistributed after every step, so each process must have enough walkers to keep it busy between the exchanges; the run warns when more than a quarter of each step is spent communicating and suggests fewer processes or more walkers. With that satisfied, DMC statistics accumulation scales almost perfectly: CASINO has run on more than a hundred thousand cores, and on up to 524,288 cores of Japan’s K computer. What more processes do not shorten is the equilibration, once each process holds a few walkers. On a workstation with simultaneous multithreading, one process per physical core is right, and runqmc, which runs one process on each hardware thread by default, is given --nproc with the number of cores. The manual’s section “Parallel runs in practice” says what to look at in the output.

How do I run on a cluster with a queue?

runqmc writes the submission script from the templates in the machine’s architecture file and submits it; do not call it from a script written by hand, since writing that script is its job. The command line says what to ask the queue for: processes (--nproc), nodes (--nnode) or processes per node (--ppn), the wall-clock time (--walltime), and whatever the architecture file defines, usually an account to charge and a queue. runqmc --check-only writes the script without submitting it. A machine that no architecture file describes needs one, usually a few lines following an existing one; the manual’s appendix on the architecture system says how, and a new file is welcome back in the distribution.

The queue killed my run. How do I continue it?

Set max_cpu_time or max_real_time so that the run stops before the queue does: it then ends at a block boundary, writes config.out and prints the advice a continuation needs. To continue, set newrun to F, rename config.out to config.in, which runqmc does itself when no config.in exists, and set runtype to the stage being continued, dmc_stats for the statistics accumulation of a DMC run. The continuation appends to out, carries the random-number sequence and the reblocking data on, so that the error bars are those of all the data since accumulation began, and in 3.2 works for RMC as well. runqmc --continue and --auto-continue do the continuation for you; the manual’s section “Continuing a run” has the cases that cannot be continued.

Can a run stop by itself when the error bar is small enough?

Yes, in DMC statistics accumulation: at a target error bar since version 3.0, and on a time budget since 3.1.22.stop_method target_error runs until the error bar of the total energy reaches target_error; small_error makes the error bar as small as the computer time stop_time allows, stopping when the rest of the budget would buy too little. The obvious rule, stopping the first time the reblocked error bar falls below the target, is biased in the dangerous direction, since the error bar is itself a fluctuating estimate and a run that stops on its first crossing stops on a downward fluctuation; CASINO’s rule has three guards against that, a validity gate on the reblocking, a margin held while the sample grows by 30 per cent, and a drift band on the mean, and the manual’s section “Stopping on the error bar” states what they guarantee and what they do not.

How much memory does a run need, and what is shared memory?

What usually sets the memory is the orbital data, which are the same on every process and never change: the blip coefficients of a plane-wave wave function, the coefficients of a Gaussian one. In a plain MPI run every process holds a copy, so a node running 64 processes on a 2 GB blip file needs 128 GB for the coefficients alone. A build with shared memory, make Shm, or 1:Shm in the install script’s menu, keeps one copy on each node, and the run is started with runqmc --shm that all its processes read, and the node needs 2 GB. Localised orbitals (the localizer utility) reduce the memory and the time of a blip calculation further. A long RMC reptile holds every configuration along it, and takes memory in proportion.

Does it run on GPUs?

Experimentally. The OpenACC build moves two parts of a calculation to a graphics processor, for systems large enough for the device to pay: the p term of the Jastrow factor of a periodic system, and the Ewald sums of the two- and three-dimensional Coulomb interaction. The rest runs on the processor, so the gain depends on how much of a run those parts are. It is built with make Openacc and run with runqmc --acc; the manual’s section on it names whom to contact. A second level of parallelism, OpenMP threads within each MPI process, is an option where the architecture file allows it (make Openmp).

4. Trial wave functions from other programs

Which programs can CASINO take trial wave functions from?

Any of these, through the file named, written by the program itself or by a converter distributed with CASINO and, with the few exceptions the manual names, installed besiderunqmc. The manual’s chapter “Trial wave functions from other programs” has a section for each, with the versions tested, how the program is run and how its converter is used; the page Interfaces is the summary. The first five routes are new in 3.2.

Program	Orbitals	File CASINO reads	Written by
FHI-aims	numeric atom-centred	naowfn.data	aims2qmc, from the TREXIO file FHI-aims exports (3.1.1239)
WIEN2k	LAPW, all-electron	lapwfn.data and pwfn.data	w2k2casino, from WIEN2k’s own output files (3.1.1162)
Elk	LAPW, all-electron	lapwfn.data and pwfn.data	a writer compiled into Elk, had from the CASINO developers on request (3.1.1243)
exciting	LAPW, all-electron	lapwfn.data and pwfn.data	a writer compiled into exciting, had from the CASINO developers on request (3.1.1243)
FLEUR	LAPW, all-electron	lapwfn.data and pwfn.data	a writer compiled into FLEUR, had from the CASINO developers on request (3.1.1243)
MCEXX	plane waves, exact-exchange Kohn-Sham orbitals among them	pwfn.data	MCEXX itself (3.1.1102)
TREXIO files, from a program whose TREXIO file holds the orbitals and the basis set, which not every program’s does	Gaussian	gwfn.data, and the MDET block of a CI or CASSCF expansion	trexio2qmc (3.1.342)
QBOX	plane waves	pwfn.data	qbox2pwfn; casino2qso gives QBOX the pseudopotential (3.1.315)
PWSCF (Quantum ESPRESSO)	plane waves or blips	pwfn.data, bwfn.data or bwfn.data.b1	pw.x with -pw2casino; runpwscf runs it, twistav_pwscf twist-averages, runqmcmd runs coupled DFT and DMC dynamics
CASTEP	plane waves	pwfn.data	castep2casino, part of CASTEP; runcastep runs the two in one command
ABINIT	plane waves	pwfn.data	ABINIT itself, since its version 4.4.3
CRYSTAL	Gaussian, for molecules and for systems periodic in 1, 2 and 3 dimensions	gwfn.data	crysgen06 to crysgen23; runcrystal runs CRYSTAL and the converter
GAUSSIAN	Gaussian	gwfn.data	gaussiantoqmc (GAUSSIAN 94 to 09)
GAMESS-US	Gaussian	gwfn.data	gamess2qmc and getdet, s to g functions
MOLPRO, OPENMOLCAS	Gaussian	gwfn.data	molden2qmc, code 5
ORCA	Gaussian	gwfn.data	molden2qmc, code 3
PSI4, PySCF	Gaussian	gwfn.data	molden2qmc, code 1; PySCF also through TREXIO
TURBOMOLE	Gaussian	gwfn.data	molden2qmc, code 0
CFOUR	Gaussian	gwfn.data	molden2qmc, code 2
DALTON	Gaussian	gwfn.data	molden2qmc, code 4
NWCHEM	Gaussian	gwfn.data	molden2qmc, code 6
Q-CHEM	Gaussian	gwfn.data	molden2qmc, code 7, from Q-Chem’s own output (3.1.1047)
ADF	Slater-type	stowfn.data	adf2stowf, by Vladimir Konjkov, distributed with CASINO
ATSP2K	numerical, atoms	awfn.data	extractdet, with the multiconfiguration expansion
2DHF (x2dhf)	numerical, diatomic molecules	dwfn.data	uf2dwfn
GP, JEEP	plane waves	pwfn.data	jeep_to_pwfn (not used for many years)

Of the plane-wave programs, PWSCF alone writes the blip form itself; the others write pwfn.data, which CASINO reads as it is or converts to blips in a preliminary run (below). The writers of lapwfn.data for Elk, exciting and FLEUR are compiled into those programs and are had from the CASINO developers on request until the programs include them. For the Gaussian-basis programs the test every interface must pass is in examples/generic/gauss_dfg: a methane with only d functions in its basis, one with only f and one with only g, for each of which VMC on the converted file must reproduce the program’s Hartree-Fock energy and, in the tests of 2026, its electron density; its RESULTS file records, for each program, the version tested and the energies obtained, and is the record behind the word “supported”.

How do I check that a converted wave function is right?

Three ways, in order of cost. At start-up CASINO checks that a molecule’s Gaussian or Slater-type orbitals are orthonormal as it reads the basis set (orb_overlap_check, 3.1.518 and 3.1.590), which catches most converters that have the normalisation or the ordering of the basis functions wrong. It then compares the analytic kinetic energy of the wave function with a numerical one at a test configuration, and a run that prints “Wave function failed kinetic energy check” has a fault in the wave function, its parameters or its derivatives, unless the failure is narrow; ke_verbose prints every step of the check. And a VMC run with use_jastrow set to F, and cusp_correction too, should reproduce the generating program’s Hartree-Fock energy within its error bar, when both use the same pseudopotential; this is the first run of the manual’s tutorial.

My VMC energy without a Jastrow factor does not match the SCF energy. Why?

Check, in turn: the two programs are not using the same pseudopotential, or one is all-electron and the other not; the reference is a DFT energy, which a determinant of DFT orbitals does not reproduce, its expectation value of the Hamiltonian lying above the Hartree-Fock energy; the basis-function conventions are not those CASINO expects, the ordering or normalisation of the d, f or g functions or Cartesian functions written as spherical, which is a converter fault and which the orthonormality check now reports; the wave function is spin-polarised or multideterminant and the converter did not carry that; or, in an all-electron calculation, the cusp correction has altered the orbitals near the nuclei, which changes the energy slightly, and the VMC error bar is optimistic (Section 8). A persistent mismatch with everything else excluded is worth a post on the forum, with the files.

Can I use multideterminant wave functions, from CI, CASSCF or CIPSI?

Yes. The expansion goes in the MDET block of correlation.data, each determinant described by its changes from the ground-state occupation, and the coefficients can be optimised under opt_det_coeff. trexio2qmc writes the block from a TREXIO file that holds a CI or CASSCF expansion, which is the route from PySCF, Quantum Package (its CIPSI expansions among them) and the other programs that write TREXIO files; getdet writes a det.data block from a GAMESS-US calculation, which is pasted into gwfn.data; for a multiconfiguration ATSP2K atom extractdet writes the determinants into awfn.data and the MDET block carries their coefficients alone. Long expansions are compressed into fewer determinants of modified orbitals (mdet.casl and cmdet.casl), and since 3.2 an expansion that ends in zero coefficients compresses to the same wave function. In QMC the Jastrow factor describes most of the dynamic correlation, so short expansions do much of what long ones do elsewhere; the manual’s section “Multideterminant expansions” says what each program’s expansion can and cannot contain.

Why are plane waves converted to blips, and why is the file so large?

CASINO can use plane-wave orbitals as they are, but every plane wave then contributes to every orbital value. Re-expanded in blips, localised cubic splines on a regular grid, each orbital value is a sum of 64 terms whatever the size of the basis, a gain in speed of the order of the number of plane waves divided by 64, and the cost of a move then scales with system size as that of a localised basis. The price is memory and disk: a blip grid holds more coefficients than the plane-wave basis it replaces, which is why the files are large and why shared memory exists (Section 3). A run with runtype gen_blip writes the blip file from pwfn.data; PWSCF writes it itself.

My program is not on the list. Can I still use it?

A program that works in Gaussian, plane-wave, Slater-type or blip functions, or tabulates orbitals on a grid for an atom or a diatomic molecule, needs no change to CASINO: a converter that writes its output in the matching file format of the manual’s chapter on files is all it takes, and any Gaussian-basis program that writes MOLDEN files, or TREXIO files, can be served by molden2qmc or trexio2qmc, a new MOLDEN code being a small addition. The page Interface development is written for the author of such a converter, and the gauss_dfg test above is the test it must pass.

5. Pseudopotentials

Which pseudopotentials should I use?

Those of the CASINO pseudopotential library, pplib, which were made for quantum Monte Carlo, the Dirac-Fock pseudopotentials of Trail and Needs among them. For each the library gives the tabulated form CASINO reads, the expansions in Gaussian functions that the Gaussian-basis programs need, Gaussian basis sets optimised for them where they exist, and awfn.data files for the atoms. A pseudopotential is an approximation to the effect of the core electrons, and with a non-local one DMC adds the error of localising it (below); both are checked by comparison with another pseudopotential or with an all-electron result. The manual’s chapter on Hamiltonians describes what CASINO reads from a pseudopotential file and how the non-local energy is integrated.

Must the orbital program use the same pseudopotential as CASINO?

Yes: the orbitals should be those of the Hamiltonian CASINO samples, and the comparison with the generating program’s energy needs it. The library gives each pseudopotential in CRYSTAL’s and GAUSSIAN’s formats, and for the other programs the converters of utils/pseudo_converters translate the tabulated file into the form the program reads; each program’s section of the manual names the one it needs.

Can I compute all-electron orbitals and then use a pseudopotential in CASINO?

No, for the same reason: the determinant would be built from orbitals of a different Hamiltonian. The pseudopotential calculation gives the orbitals for a pseudopotential run, and an all-electron calculation, with the cusp correction for Gaussian orbitals, gives them for an all-electron run.

Can I use pseudopotentials from other libraries?

If they are in a form CASINO reads or can be converted to it. The converters in utils/pseudo_converters go both ways between CASINO’s tabulated format and UPF (casino2upf, upf2casino), and from the Gaussian-expanded effective core potentials of NWChem’s format, the ccECPs among them (nwchem_pp_convert, corrected for every ccECP with an f channel or a spin-orbit block in 3.1.450 and 3.1.466), from ABINIT’s, CHAMP’s and JEEP’s formats, and to QBOX’s and CASTEP’s; ptm transforms the channels of a pseudopotential, for one whose local channel is not the one CASINO expects. A converted potential must still be used in both programs, and the pplib’s potentials were made for QMC where most others were not.

Can I mix all-electron and pseudopotential atoms?

Yes. An element whose pseudopotential file is absent is treated as all-electron, and the out file says so for each element; the hydrogen atoms of the manual’s silane example are treated this way. An element that the orbital file describes as a pseudo-ion, by its valence charge, stops the run if its file is missing. Two pseudopotentials for one element, as for an atom in a surface and another adsorbed on it, are read from a second file.

What are T-moves, the locality approximation and the determinant locality approximation?

Three ways of handling a non-local pseudopotential in DMC, where its action on the DMC wave function cannot be evaluated. The locality approximation applies the non-local operator to the trial wave function and divides by it, which makes the DMC energy no longer an upper bound, dependent on the Jastrow factor, and liable to population explosions, since the localised potential diverges at the nodes. T-moves, the default since 2018, split the matrix elements by sign, apply those of one sign as random moves of the electrons and localise the others: the energy is again an upper bound and the instability is gone, at the price of a larger time-step bias. The determinant locality approximation (use_detla) localises by the antisymmetric part of the trial wave function alone, so that the energy at zero time step no longer depends on the Jastrow factor and results from different Jastrow factors, or different programs, are comparable. The manual’s DMC chapter sets out all three and their errors.

6. Optimising the wave function

What is the Jastrow factor, and which form should I use?

The Jastrow factor is a positive function of the electron positions that multiplies the Slater determinant and puts the correlation in: it keeps electrons apart, satisfies the cusp conditions where particles meet, and lowers the energy and, above all, the variance of the local energy, which is what sets the cost of every later calculation. It cannot move the nodes, so it does not change the fixed-node DMC energy of a local Hamiltonian; with non-local pseudopotentials it does, through the locality approximation or T-moves (Section 5), but it makes that energy far cheaper to obtain. CASINO has two forms. The Drummond-Towler-Needs Jastrow factor, in correlation.data, is a fixed set of terms each written for a purpose: electron-electron (u), electron-nucleus (chi), electron-electron-nucleus (f), plane-wave terms for crystals, a three-electron term, cylindrical terms for wires and layers, and terms for particular systems. The general Jastrow factor, in parameters.casl, builds terms of any number of electrons and nuclei from a library of basis and cutoff functions, grouped by rules the user writes. Start with the first: its terms have known purposes, the examples and the tutorial use it, and most of the manual’s advice is written for it. The general form is for a term the first cannot express; gen_gjastrow converts one to the other.

Which optimisation method, and in what order?

Every method works on a fixed sample of configurations that a VMC run writes, and a run makes cycles of VMC and optimisation. The route the manual gives: two or three cycles of varmin_linjas, which minimises the variance of the local energy exactly as a quartic in the linear Jastrow parameters and gets nearly the whole gain in its first cycle; then emin, energy minimisation by the linear method, for everything else, the cutoff lengths, the backflow parameters, the determinant coefficients, four cycles being the usual start. Where energy minimisation misbehaves, a cycle of madmin, which minimises the mean absolute deviation of the local energy from its median, or of varmin with its filter on, prepares the wave function for it; reweighted variance minimisation is used rarely, being prone to run away. For silane, started from an empty Jastrow factor, the three variance methods reach the same energy, nearly all of it in the first cycle; energy minimisation from the same start takes three cycles, from the varmin_linjas result one. The manual’s chapter “Optimising the wave function” has the table and the reasons.

How many configurations do I need?

More than 10,000 for a Jastrow factor of a few tens of parameters; energy minimisation is the more stable the more it has, and 10⁵ to 10⁶ are worth using where they can be afforded. A sample so small that the minimiser can fit its noise gives parameters that look good on the sample and bad in the next VMC run. The VMC run of each cycle should be a few times longer than the number of configurations it writes, so that its energy has an error bar small enough to judge by, and the configurations should be nearly independent: the decorrelation period defaults to 15 steps in an optimisation, and the correlation time of a preliminary VMC run says whether that is enough.

Should I optimise the cutoff lengths?

Usually. Too short a cutoff leaves correlation undescribed and too long a one costs time, since every pair within range is evaluated; the best length depends on the system and is found by optimising it with the other parameters. Cutoffs enter the wave function non-linearly, so such an optimisation needs more cycles, and truncation order 3, which keeps the local energy continuous at the cutoff, makes it easier. Since 3.2 the derivatives with respect to the cutoffs of the f term, of the H term and of backflow are analytical, which saves up to nearly half the time of a cycle that optimises the f-term cutoffs and up to a quarter for backflow’s. A cutoff that wanders is held fixed for some cycles with opt_noctf_cycles, and in a periodic system a cutoff is bounded by the cell.

Why do variance and energy minimisation give different energies?

Because they look for different things. The minimum of the variance of the local energy is not where the energy is least, so a variance-optimised wave function has a higher VMC energy than an energy-optimised one, and the energy-optimised one has in practice often a lower DMC energy and better expectation values of other operators too, though no lower VMC energy guarantees either. Variance minimisation is more robust, usually has a single minimum in the linear parameters, and is the right start; the difference between the two is a measure of how much the wave function still has to give.

The optimisation went wrong: the energy rose, the variance exploded, or I got NaN. What now?

The common cause is a measure the minimiser could lower on the sample by making the wave function worse elsewhere: a few configurations dominate the sum, or the sample is nearly indifferent to some parameters and noise sets them. In order: set vm_filter to T in every varmin or madmin run, which gives the few configurations furthest from the mean little weight (in an unreweighted run with standard sampling; the filter is refused otherwise) (unfiltered optimisations of a four-electron molecule failed in about two runs in five, filtered ones in fewer than one in ten); use more configurations, which helps energy minimisation most; use fewer parameters, a lower expansion order or shorter cutoffs; and change the method, a cycle of varmin_linjas, filtered varmin or madmin before emin. Keep the file with the lowest VMC energy, which need not be the last cycle’s; the manual’s section “When an optimisation fails” is the full list.

What is backflow, and is it worth it?

Backflow replaces the electron coordinates in the Slater determinant by quasiparticle coordinates, each electron displaced by a function of the positions of the others and of the nuclei. A Jastrow factor cannot move the nodes; backflow does, and so can lower the fixed-node DMC energy as well as the VMC energy and the variance. It costs more per step, by a factor that grows with the number of electrons, and it helps VMC more than DMC: for the all-electron carbon atom it recovers about 49 per cent of the correlation energy missing in Slater-Jastrow VMC and about 18 per cent of that missing in DMC. Its parameters are optimised under opt_backflow, with analytical derivatives since 3.2 for a real Slater determinant of Gaussian or Slater-type orbitals in a finite system, which make its optimisation six to seven times faster. Worth it when the fixed-node error matters at the precision sought.

How else do I improve the nodes?

With a multideterminant expansion, whose coefficients emin optimises in one or two cycles (Section 4); with a geminal (pairing) wave function, which replaces the orbitals of a determinant by a pairing function of two electrons of opposite spin, expanded in all the orbitals of the file, and which since 3.2 treats open shells; and with backflow on either, open-shell geminals excepted. Orbital optimisation by orbital modifications is in the code but, as Appendix G of the manual says, not to be relied on in any version.

Can an optimisation be restarted?

Yes. The parameters of every stage go to files of their own, correlation.out.0, .1, .2 and so on, or parameters.0.casl and so on for a general Jastrow factor or a geminal. varmin and madmin write them at every accepted step and emin at every iteration, so that a run stopped in the middle of a cycle leaves its best parameters so far; varmin_linjas writes when its minimiser finishes or reaches its time limit; a run that reaches max_cpu_time stops at the next such point. A new run starts from the file with the lowest energy renamed correlation.data, and runtype opt_vmc begins with an optimisation on the configurations of an earlier run’s config.in.

7. Diffusion Monte Carlo

How do I choose the DMC time step?

By checking it. The DMC propagation is exact only at zero time step, and at small time steps the error in the energy is proportional to the time step; the bias is larger in all-electron systems, larger with T-moves, and need not cancel between the two systems of an energy difference. Run at two or more time steps, with the equilibration lengthened in proportion as the step is shortened so that each run covers the same imaginary time, and extrapolate to zero with endmc -x or extrapolate_tau; quote the extrapolated energy, or the energy at a step small enough for the bias to be below the error bar wanted. In the manual’s tutorial, silane with pseudopotentials at 0.005, 0.01, 0.02 and 0.04 hartree^-1 shows a bias below a millihartree, and 0.01 is small enough for that precision. Re-equilibrating a population after a change of time step takes far fewer steps than equilibrating from VMC configurations, which makes a time-step study cheap.

How many walkers?

A thousand is a usual starting population for a small molecule, and whether it is enough is checked afterwards: holding the population near its target biases the energy by an amount inversely proportional to the population, and the bias does not fall as the run grows. Check with a run at a larger population and the same time step, or estimate it from the run itself with popbias, which reads dmc.hist. At a given error bar, and so at a given cost, a larger population and a shorter run have the smaller bias; the bias grows with the number of electrons and with a worse trial wave function. On many processes the population must keep every process busy (Section 3).

How long should the equilibration be, and how do I know?

The walkers start as a sample of the trial wave function squared and must relax to the DMC distribution; the relaxation takes a few multiples of the inverse of the gap to the lowest excited state of the same symmetry, in imaginary time, and the walkers typically take about a thousand steps to diffuse across the system, which the equilibration should cover several times. Judge its end from the plot of the best estimate and the population against step that graphdmc draws, and after the run from equil_diagnostics, which reports where two standard rules would have started the statistics and how far the mean would then move; it is advice and certifies nothing, since no rule can see a transient slower than the series it is given. The check that settles the question is a run with a longer equilibration that gives the same energy. A best estimate still moving when the statistics begin is the sign to look for, and no error bar accounts for the bias it leaves. For a large population on many processes, a preliminary run with a small population can equilibrate instead and write walkers for the main run (dmc_nconf_prelim).

What is a population explosion, and what do I do about it?

A walker whose local energy is far below the reference energy for many steps, usually because an electron is trapped near a node or a singularity of the trial wave function, branches at every step until its copies fill the population and the reference energy, driven down to contain them, kills every other walker: an explosion, or a collapse if the trapped walkers then die. With dmc_trip_weight set above the target weight, the run returns to the start of the previous block and draws new random numbers, up to max_rec_attempts times; a run without it stops when the weight reaches five times the target or falls to zero. The cures are a better Jastrow factor, T-moves rather than the locality approximation, whose localised potential diverges at the nodes, and after a collapse a larger population. The manual’s section “Population catastrophes and automatic block resetting” describes the mechanism and the options.

What does “Stat inefficiency” in the output mean?

Branching makes copies of walkers, and copies stay correlated for a while, so a DMC population behaves, for the error bar, like a smaller number of independent walkers, the effective population; the statistical inefficiency is the ratio of the average population to the effective one. With popstats set the run prints both, an estimate from the correlation time and a measurement, following Nemec’s analysis, and warns when the run holds fewer than 32 blocks of its chosen length, too few for the figures to be reliable, or when either inefficiency reaches 2 beyond its own error. The effective population comes from the difference of two nearly equal estimates of a variance, which can be negative; the estimator has then failed, not the walk, and since 3.2 it prints as unavailable instead of as a negative number. The energies are not affected either way.

Why is my DMC energy below the exact energy?

For a local Hamiltonian fixed-node DMC gives an upper bound, so a DMC energy below an exact one means the two are not energies of the same Hamiltonian, or one of the biases is at work. The usual reasons: a pseudopotential, whose energy is not comparable with an all-electron reference; the locality approximation, under which the DMC energy is not variational, where T-moves restore the bound; a time-step bias, which is of either sign, and is removed by extrapolation; an “exact” value that is an estimate, or non-relativistic where the comparison is not; or a statistical fluctuation, which two or three error bars cover. A DMC energy that stays below a true exact energy of the same Hamiltonian after these are excluded is a fault worth reporting.

What is reptation Monte Carlo, and should I use it?

RMC samples a path of configurations in imaginary time, the reptile, instead of a branching population, and so gives pure expectation values, free of the mixed-estimator bias of DMC and of the population-control bias, with the energy at both ends of the reptile. In 3.2 it was rebuilt: each new configuration is accepted or rejected against the trial wave function, as DMC does, which cuts its time-step error to DMC’s size and changes every RMC number; pure estimates of the potential and kinetic energies and of the density and other expectation values come from the middle of the reptile with reblocked error bars; the error bars are taken at block lengths of at least four renewal times of the reptile, and print as a lower bound, starred, when the stage is too short for one; parallel runs average every process’s reptile; a run can be continued; and a move is 30 per cent faster for a lithium atom with 252 determinants at 8 processes. The manual’s RMC chapter, and the reptation run in its tutorial, say how to set it up. Its status in the capability tables is intermediate: use it for expectation values that DMC estimates with a bias, and check its energy against DMC’s.

8. Error bars

Which error bar do I quote, and do I need to run reblock?

CASINO reblocks on the fly: the error bars the out file prints for the energy and its components are already corrected for the correlation of successive steps when the file says the reblocking converged; otherwise it prints the unreblocked error and says so. A VMC run prints three, uncorrected, by the correlation-time method and by reblocking; the last two should agree within their own uncertainty and either is the one to quote. A DMC run prints the reblocked one. The reblock utility is for two things the run does not do: reblocked error bars on other quantities stored in the history file, and, for a VMC run or a quantity other than the DMC energy, the full curve of error against block length when the plateau itself is what you want to see.

Are VMC error bars reliable in all-electron systems?

Not at the default settings. With a common time step the core electrons are seldom moved, so the local energy keeps a slowly decaying correlation that the error-bar estimate can miss: for all-electron atoms and small molecules with Hartree-Fock wave functions and the cusp correction, the spread of independent runs exceeded the quoted error bars by 8 per cent on average, and the mean of twelve runs of argon missed the exact Hartree-Fock energy by 0.4 hartree, 2.7 times the error estimated from their spread. Set vmc_step_profile to T, which gives the core electrons smaller steps and with which the seven systems tested agreed with the exact energies within 2.5 standard errors, keep the cusp correction, and check the error bar against the spread of a few independent runs. DMC is not affected.

How do I tell whether two results differ?

By their combined error bar, the square root of the sum of the squares of the two: a difference under twice it is not resolved, and a run long enough to resolve it is planned from the error bar’s scaling, which falls as the inverse square root of the run length. The systematic errors do not cancel by themselves between two runs: the time-step and population checks are made for each, and an energy difference between systems is only as good as the balance of the trial wave functions that describe them.

9. Periodic systems

What is the difference between the simulation cell and the primitive cell?

A one-electron theory of a solid reduces the problem to the primitive cell and integrates over the Brillouin zone. A many-body calculation cannot, because the correlation between the electrons is long ranged: it is done in a simulation cell of several primitive cells, repeated periodically, and the energy per particle of the infinite solid is approached as the cell grows. The block npcell gives the number of primitive cells along each lattice vector, the orbital file holds the orbitals at the k points that fold into the supercell, and the utility supercell finds the cell shapes that reduce the finite-size error for a given number of atoms.

What are the finite-size errors, and how are they corrected?

Two. The electron momenta sample the Brillouin zone at the points the cell allows, which twist averaging reduces (below). And the interaction is artificially periodic: the exchange-correlation hole is confined to the cell, so the interaction and kinetic energies of the cell differ from the infinite system’s. CASINO offers the model periodic Coulomb (MPC) interaction in place of the Ewald one for the interaction energy, and with finite_size_corr T evaluates, in VMC and DMC, corrections to the kinetic and interaction energies, the interaction one alone with a general Jastrow factor from the Jastrow factor and from the structure factor of the run, printing the corrected energies; the corrections exist in two and three dimensions. The remaining error is removed by extrapolation in cell size, and the utility finsize works the corrections out from a run’s output. The manual’s chapter on Hamiltonians sets out the theory.

What is twist averaging, and how do I do it?

A twist is a non-zero Bloch vector of the simulation cell, a phase the wave function picks up when an electron crosses the cell; averaging the energy over twists samples the Brillouin zone as a dense k-point grid does in a one-electron theory, and removes most of the momentum part of the finite-size error. It needs a complex wave function and orbitals at each twist: with PWSCF the script twistav_pwscf runs the DFT and QMC calculations for a set of twists, DMC re-equilibrates its population after each change of twist, and twistanalysis averages the results and gives the error bar of the average. The manual’s chapter on kinds of system describes twisted boundary conditions, and the electron-gas utilities do the same for homogeneous systems.

Can I compute band gaps and excited states?

Yes, as energy differences. An excited state is described by promoting an electron from one orbital to another, or adding or removing one, through neu and ned or, for plane-wave and blip orbitals, the MDET block’s PL and MI lines, so that its determinant has the symmetry or the occupation of the state wanted; DMC then gives its energy to the fixed-node accuracy of that trial wave function. The quasiparticle gap of a solid comes from DMC runs of the ground state and of the states with an electron added and removed, which get_qp_gap combines, and the excitonic gap and binding energy from the promoted state, with get_exciton_binding; neither applies a finite-size correction, which a gap needs as much as a total energy does. Excited states of the same symmetry as the ground state are harder, since the fixed-node energy is a bound for the lowest state of each symmetry only.

Does CASINO handle one- and two-dimensional systems?

Yes: polymers, slabs and crystals periodic in one, two and three dimensions, and systems that live in one or two dimensions, layers, bilayers, wires and biwires, electron and electron-hole gases among them, with the Ewald interaction written for each case. The finite-size corrections above exist in two and three dimensions, and are refused for a system periodic in one dimension; in 3.2 the one-dimensional Coulomb sum is accurate to about 10^-10 hartree per pair by default. A facility that does not apply in a given dimension refuses at input with a message rather than running wrong.

10. Beyond the energy

What can CASINO compute besides the energy?

Charge and spin densities, binned or on a grid, with error bars at every point; the conditional density about a held electron, the exchange-correlation hole and the on-top pair density of a molecule; pair-correlation functions and structure factors; one- and two-body density matrices, momentum densities and the condensate fraction of homogeneous systems; the momentum density of annihilating electron-positron pairs; the localisation tensor; the electric dipole moment and, from a run in a uniform electric field, polarisabilities; ionic populations and the contact density; the probability of finding n electrons in each of a set of domains, Voronoi cells, spheres, half-spaces or Bader basins, with variances and covariances; and atomic forces. The expectation values go to expval.data, which plot_expval plots, except the dipole moment and the forces, which go to the hist files and are reblocked like the energy. In DMC an expectation value that does not commute with the Hamiltonian is a mixed estimate, biased at first order in the error of the trial wave function; the extrapolation 2 DMC minus VMC, pure estimates, by future walking for the forces or by RMC for quantities that depend on positions alone, reduce or remove the bias. The manual’s chapter “Expectation values” has the list with each quantity’s status.

Can I see the density, the nodes or the walkers?

Yes, and 3.2 added most of the ways. expval2cube writes densities and spin densities, with their error cubes, as Gaussian cube files for VESTA, critic2, VMD and the like; hole2html draws the exchange-correlation hole as a page in which the electron can be dragged. nodeview draws the nodal surface of a finite system’s wave function as one electron sees it with the others held; nodecells counts the nodal cells and tests Ceperley’s tiling property, so that a node’s topology can be checked before DMC; wfnscope lets you drag the electrons of a molecule’s wave function in a browser and watch the conditional density, the nodal slice and the local energy follow. walker_film films the walkers of a DMC or VMC run, drifting, diffusing, branching and dying, and walkerfilm turns the film into a trajectory for OVITO or Blender or a web page that plays it; and dmcsound turns a DMC run into sound, each excited state a fit resolves a tone fading at its own rate. The chapter “The wave function outside QMC” describes them.

Does CASINO compute forces?

For finite systems with Gaussian orbitals, in VMC and DMC, with pure estimates by future walking; molecular forces with pseudopotentials have been right throughout the code’s record, apart from the exceptions Appendix G lists, every one fixed or refused by 3.2, and forces in periodic systems, which were never right, have been refused since 3.1.123. A QMC force carries a statistical error of its own, which is why a geometry optimisation or a molecular-dynamics run is usually not what QMC is for; the manual’s chapter “Pure estimates and forces” says what the forces include and what they cost, and Appendix G notes that nothing has yet compared them with an independent force.

11. From 3.0 to 3.2

What happened between version 3.0 and version 3.2?

Version 3.0 was released in August 2026 and the development series behind 3.2 opened on 16 August, the date of its first version. By 26 October it had reached version 3.1.1243, in 356 numbered versions and 1,257 entries in the DIARY, the file that has recorded every change since 1999: 40 entries in August, 318 in September and 899 in the first 26 days of October. The series searched the program’s history and its code for faults, fixed those it found in what it computed going back to before 2008 (Section 12), removed waste of time where it was measured, added facilities, pilot-wave trajectories in its own wave functions among them, and gave the code a new manual. In rough order:

• August and the first days of September. Geminal (pairing) wave functions for open shells (3.1.17), automatic stopping on a time budget, small_error, made to work (3.1.22), nine faults of the trajectory program LOUIS fixed, seven of them by 3.1.59 and the last by 3.1.679, and a sixteen-year-old fault in the diffusion constant printed by parallel VMC (3.1.23).
• September, into the first of October. The build: Intel ifx architectures (3.1.92, 3.1.279), an MPI build that compiles under a compiler other than the one that built the MPI library (3.1.90 to 3.1.100), non-zero exit statuses when a run fails (3.1.70 to 3.1.100), ten utilities that gave wrong numbers under a decimal-comma locale (3.1.68). The converters: CRYSTAL23 (3.1.178 to 3.1.193), ADF (3.1.205), QBOX (3.1.315), TREXIO files (3.1.342), 2DHF (3.1.347). Speed, measured at 8 to 64 MPI ranks: the Ewald sums (3.1.112 to 3.1.115, 3.1.203), Gaussian orbitals (3.1.146), Slater-type orbitals (3.1.148, 3.1.238, 3.1.313), T-moves (3.1.133). And the first of the DMC faults: parallel DMC with dmc_method 2 had carried uninitialised Jastrow values from 2014 to 2017 and again from 2019 (3.1.202).
• The first week of October. Wave-function optimisation: analytical derivatives for the backflow parameters, by Vladimir Konjkov (3.1.345), the analytical derivatives of the standard Jastrow factor corrected (3.1.354), analytical derivatives for the f-term and backflow cutoff lengths (3.1.429, 3.1.455), a guard against runaway reweighted variance minimisation (3.1.407). The cusp corrections of virtual and periodic Gaussian orbitals, and periodic Gaussian backflow, which could be wrong by tens of hartrees a cell (3.1.402, 3.1.465, 3.1.510). The three-electron backflow term made antisymmetric (3.1.502). Smaller VMC steps for the core electrons of all-electron atoms (3.1.551).
• The second week of October. Densities with error bars at every point, as cube files (3.1.538, 3.1.561, 3.1.600); the exchange-correlation hole of a molecule, drawn in a browser (3.1.613, 3.1.645); the localisation tensor of a correlated state (3.1.722). De Broglie-Bohm trajectories in superpositions of CASINO wave functions (3.1.562, 3.1.595). The nodal surface drawn (3.1.680), the nodal cells counted (3.1.913), the wave function explored by hand (3.1.935). Reptation Monte Carlo rebuilt, from the walk to the error bars (3.1.253 to 3.1.1235). Derivatives of the DMC energy with respect to the determinant coefficients (3.1.802), the population-control bias estimated after the fact (3.1.969), equations of state fitted (3.1.1054), a uniform electric field (3.1.1060), films of the walkers (3.1.1074), optimisation and DMC in one run (3.1.1092), the probability of n electrons in a domain (3.1.1133).
• From mid-October. The manual rewritten (3.1.1029), the old one kept beside it (3.1.998). Trial wave functions from MCEXX (3.1.1102), WIEN2k (3.1.1162) and FHI-aims (3.1.1239). An installer that works without a terminal, and casinocheck (3.1.1157). The appendix on faults of earlier versions (3.1.1221). The GPU build’s Jastrow factor corrected (3.1.1227).

What is new in 3.2, in one list?

• Wave functions and optimisation. Open-shell geminals; analytical parameter derivatives for backflow, which make an optimisation of the backflow parameters of a Slater determinant in a finite system six to seven times faster, and for the cutoff lengths of the f term and of backflow, which save up to nearly half the time of optimising the one and up to a quarter of the other; reweighted variance minimisation much less prone to run away; the filter recommended in every unreweighted variance minimisation; a check at start-up that converted Gaussian orbitals are orthonormal, which catches most converter faults at once; Cartesian d, f and g functions read directly; the exponential tail of the UHARM term.
• DMC and RMC. Automatic stopping at the smallest error bar a time budget allows, beside the target error bar of 3.0; equilibration diagnostics; popbias; the reweighting of Anderson, Per and Umrigar (limdmc 7 and 8); nodal derivatives (dmc_node_deriv); RMC with accept-reject moves, pure estimates from the middle of the reptile, continuation and error bars taken at block lengths of at least four renewal times; runtype vmc_opt_dmc.
• Beyond the energy. Zero-variance densities on a grid with error bars, cube files for VESTA and its like, the conditional density and the exchange-correlation hole, the on-top pair density, the localisation tensor, probabilities of electron numbers in domains, the dipole moment’s polarisabilities from an electric field, forces refused where they had no meaning.
• Seeing the wave function. nodeview, nodecells, wfnscope, walker films for OVITO and Blender, and dmcsound.
• Pilot waves. The pilot_eval run type, pilotdrive, and LOUIS’s ensemble mode (Section 13).
• Programs. FHI-aims, WIEN2k, MCEXX, QBOX and any program that writes TREXIO files; CRYSTAL23; Q-Chem converted directly; GAMESS with f and g functions; TURBOMOLE tested to g; CASTEP run in one command (Section 4).
• Running and installing. ifx architectures, an installer that needs no terminal, casinocheck, exit statuses, runqmc that refuses to overwrite a run, walkers shared by the speed of each processor where that pays, and the Hartree-Fock utility mcta_hf, whose error bar on the total energy is no longer understated.
• The manual. Rewritten as a narrative for new users, with a reference part generated from the code where it can be, and new appendices on the faults of earlier versions and on changes of behaviour.

The file CHANGES in the distribution lists each of these with its version, and the DIARY gives every one in full.

How much faster is 3.2?

Faster where it was measured, and the measurements are in the DIARY, each with its system. DMC on a 4x4x4 NiO supercell, 1024 electrons in a Gaussian basis at 64 MPI ranks, gained about 9 and then 2 per cent from the Ewald sums (3.1.112, 3.1.115), 8.5 per cent from the T-moves (3.1.133), 10 per cent from the handling of rejected moves (3.1.201) and 7 per cent more from the Ewald sum again (3.1.203). A cluster of 64 water molecules, 512 electrons, gained 33 per cent in DMC and 28 per cent in VMC from the Gaussian evaluation (3.1.146); a 2x2x2 diamond supercell with pseudopotentials 13 per cent (3.1.668). VMC with Slater-type orbitals runs 1.6 to 1.7 times as fast for C₁₆H₃₄ and C₃₂H₆₆ (3.1.313), and leaving out distant Slater functions makes a 98-atom alkane 2.5 times as fast (3.1.238). A geminal wave function that uses 4 of silane’s 116 orbitals takes a DMC step about 2.7 times faster (3.1.1214); an RMC move is 30 per cent faster for a lithium atom with 252 determinants (3.1.1220). In optimisation, the backflow parameters of a Slater determinant in a finite system are optimised six to seven times faster (3.1.345), reweighted variance minimisation of a general Jastrow factor 2.7 times faster and energy minimisation 1.3 times for a water molecule with pseudopotentials (3.1.1093), and a VMC energy of given error bar costs two to five times less for all-electron atoms and small molecules heavier than helium with vmc_step_profile (3.1.551). And one set-up that took about three weeks on a long cell now takes fifteen seconds (3.1.1080). Where a change moves a printed number, the DIARY entry says so.

Who did the work?

Of the DIARY’s 1,257 entries from 3.0 to 26 October, all but 17 are Mike Towler’s. Neil Drummond added the Tersoff bond-order potential, the starting configurations of Wigner crystals and the repairs that keep the code building under the NAG and ifx compilers, and fixed the parallel VMC diffusion constant. Vladimir Konjkov wrote the analytical backflow derivatives, extended the geminal wave functions to open shells, and maintains the ADF converter that CASINO now distributes. Pablo López Ríos removed the broken “virtual parallel” optimisation feature and improved the library build.

Is the manual new?

Yes. The manual was rewritten in October 2026 (3.1.1029) as a narrative for a new user, from the methods through installation, a first calculation, running, optimisation, DMC and the rest, with a reference part, the keywords and the files, generated from the code where it can be. It has the appendices this page leans on: F, “Changes of behaviour”, which tells a user of an earlier version what now behaves differently; G, “Faults of earlier versions”; and, in the chapter on trial wave functions, a section on CRYSTAL basis sets, with measurements of how much optimising a basis gains and how little of it reaches DMC; and one on the test suite. The previous manual is kept in the distribution, in manual/OLD, as it stood before the rewrite.

I used version 3.0 or 2.13. What behaves differently now?

Appendix F of the manual is the list. The ones most likely to touch a running project: reptation Monte Carlo accepts or rejects each new configuration of the reptile, as DMC does, so every RMC number changes and the old walk is an option (3.1.1075); parallel DMC shares walkers equally by default, so a run repeats itself at a given seed, with speed-weighted sharing an option (3.1.301); runqmc refuses a new run in a directory holding an earlier run’s out file instead of appending to it (3.1.477); Gaussian shells are screened on what they can contribute rather than on their exponent alone, which moves energies that had mHa-per-cell errors from large-coefficient d shells (3.1.155); the virtual orbitals of a multideterminant expansion are cusp-corrected as themselves (3.1.402); a run that fails ends its out file with “Job failed” and a non-zero exit status; and the architecture files for retired hardware, Blue Gene, Knights Landing and the old Cray machines among them, are kept only as patterns for their successors.

How is a version tested?

Every change is run through the test suite in examples/TEST before it is contributed: some three hundred small decks for eighty systems, chosen to exercise most of the program in minutes, run in serial and in parallel, with the numbers each run prints compared, times and version lines apart, with a reference library made by a trusted build, so that a change that alters a result anywhere is seen. A converter is tested against the generating program’s own Hartree-Fock energy and, in the tests of 2026, its electron density, on molecules with only d, only f and only g functions in the basis, which catches a mis-scaled shell at once. The appendix on the test suite says how, and a user checks a new build the same way.

12. Is CASINO right?

Was CASINO wrong before version 3.2?

In many places, yes. Appendix G of the manual, “Faults of earlier versions”, compiled in October 2026 from the DIARY and the repository’s history, records every fault found in what CASINO computed: wrong energies, derivatives, expectation values and error bars, files written wrongly, and inputs that should have been refused. Its table has 321 rows, each with the version that introduced the fault, where the record fixes it, and the version that fixed it, or the word open. 251 of them were fixed in the 2026 series: 185 faults that predate version 3.0, some of them from before 2008, 14 whose date is not established, and 52 first seen within the series, 19 of them introduced there and 33 present by some version of it and possibly older. Most were in terms and options that few calculations use: in the manual’s words, the plainest uses of CASINO, a Slater-Jastrow wave function with the standard u, chi and f terms, optimised by variance minimisation and run through VMC and DMC, were wrong in few versions. The rule the appendix states is the one to apply: a result computed with a version in which a feature it used was wrong cannot be relied on, whatever it agreed with, and is to be computed again with a version in which the fault is fixed.

Were plain calculations affected?

Rarely. The standard Jastrow factor in VMC, and in DMC with dmc_method 1 in three dimensions, has been right throughout the record except in OpenMP builds before 2.11.176 (November 2012), in skewed or large periodic cells whose lists of lattice vectors were incomplete, until 3.1.212 (September 2026), and for the chi term’s cusp flag with cusp-corrected Slater-type orbitals, until 3.1.1068 (October 2026). DMC with dmc_method 1 and electrons alone has been right throughout, except for a catastrophe reset that did not always remove the moves it discarded, until 3.1.478, and blocks run under block_time, until 3.1.356, a geminal with backflow, until 3.1.1115, and three options the appendix names: the renormalisation copy of dmc_poprenorm and nc_dmc until 3.1.150, and dmc_reweight_conf until 3.1.761 for configurations read from a file and 3.1.909 at a change of twist. The faults that touched common practice are in the next answer.

Which results should I compute again?

Appendix G lists twelve kinds, with the versions concerned. In brief:

• parallel DMC with dmc_method 2, which carried uninitialised Jastrow values and was biased low, from March 2014 to July 2017 and from February 2019 to 3.1.202 (September 2026);
• all-electron DMC with dmc_method 2 at a finite time step, which under T-moves with branching, the defaults, branched with the T-move factor, from January 2018 to 3.1.259;
• energy minimisation of the standard Jastrow factor, and variance minimisation with optimisable cutoffs, whose analytical derivatives were wrong from May 2025 to 3.1.354 (October 2026);
• energy minimisation with a pseudopotential and opt_fixnl F, its default, and variance or MAD minimisation with it set, whose derivatives left out the change in the non-local energy: with the general Jastrow factor from 2012, the standard one from May 2025 and backflow from 3.1.345, until 3.1.1205;
• any geminal calculation with Gaussian, plane-wave or blip orbitals before 2.13.1309 (July 2026), which had faults in the orbital count and the kinetic energy, and DMC with dmc_method 1, a geminal and backflow before 3.1.1115, which used stale gradients;
• Gaussian g functions, whose derivatives were wrong, with a Jastrow factor before 2.13.679 (January 2018), and with molgscreening or backflow before 3.1.557 and 3.1.589;
• periodic Gaussian backflow and the general-purpose cusp correction in a periodic system before 3.1.510, both wrong by up to tens of hartrees a cell, and periodic Gaussian backflow on an atom with f functions and no d, or with f functions reaching further than its d, before 3.1.589;
• CRYSTAL06 and CRYSTAL09 conversions with f functions before 2.13.172 (November 2013), which zeroed their coefficients, and of spin-polarised molecules before 2.11.5 (February 2012), which copied the up-spin orbitals into the down-spin set;
• DMC expectation values other than the energy with tpdmc above zero from parallel runs before 3.1.1112, which came from the master process’s walkers alone;
• parallel RMC before 3.1.316, which reported one process’s reptile, and RMC error bars before 3.1.1208, which were too small, by up to about a factor of two in the shipped examples;
• Slater-type orbitals with f shells before 2.13.1105 (March 2024), whose normalisation was wrong;
• atomic forces read from the hist file before 2.13.592 (October 2016), whose columns named the wrong atom or axis, and non-local forces with T-moves before 2.13.1039 (March 2023), which summed the wrong matrix elements.

The version a calculation used is printed at the head of its out file.

What is still open?

The faults that no version has fixed are listed at the end of Appendix G, each with what it touches. They are: the Laplacian of the two-dimensional f term in layered systems, which is unsettled off the particles’ plane; the cylindrical Jastrow terms exactly on their axis, where a walk does not go; a one-channel electron-electron term of the general Jastrow factor with an Only rule, which still counts the same-spin pairs it excludes; the analytical derivatives of the general Jastrow factor’s W term; a geminal constraint group left out of the file, which takes the value zero; an unreweighted variance minimisation that ran away in 32 of 60 seeds on a set of H₄ inputs, by a mechanism not located; varmin_linjas’s reference energy, never updated within a cycle; an ill-conditioned choice of eigenvector in energy minimisation at extreme manipulation constants; the molecular orbital modifications, reported broken in 2012 and not repaired; and the cusp corrections for an electron exactly at a nucleus, a point a walk never reaches. Three faults of the experimental GPU build’s Jastrow factor are listed too; the DIARY records their fix at 3.1.1227.

How do I tell whether a result of mine was affected?

Take the version from the head of the out file, and read the entries of Appendix G for each feature the calculation used: the appendix is written feature by feature, “right throughout the record except…”, with the versions in which each was wrong, and its table gives the effect on results where it was measured. The DIARY entry of each fix, named by version, says what was wrong and what changed. If a feature you used was wrong in your version, the result is to be computed again; if the appendix records no fault, that means the record holds none, not that the use has been checked against an independent result.

How were the faults found, and what keeps new ones out?

By reading the code against the manual and against the DIARY, which has recorded every change since 1999, feature by feature; where a fault’s effect was measured, by calculations on builds before and after the fix, the row says so. Against new faults: every change is tested in serial and parallel before it is contributed; the program checks at start-up that converted orbitals are orthonormal (orb_overlap_check) and, with check_aderivs set, that analytical derivatives agree with finite differences; and a facility works in every dimension, orbital type and method or refuses at input with a message, rather than running silently wrong. Faults found after this writing are added to Appendix G as they are fixed.

13. Pilot waves

What is pilot-wave theory?

The pilot-wave theory of de Broglie (1927) and Bohm (1952) is quantum mechanics in which the particles have positions at all times and the wave function guides them, each moving, in atomic units, with the velocity v_i = Im ∇_i ln Ψ / m_i. The wave function obeys the Schrödinger equation as usual; what the theory adds is a definite trajectory for every particle, so that an atom, a molecule or a crystal is a set of electrons moving along paths determined by the wave function. An ensemble of such systems whose configurations are distributed as |Ψ|² stays so distributed, and gives exactly the predictions of quantum mechanics; the measurement problem does not arise, since outcomes are where the particles are. The page de Broglie-Bohm theory sets out the theory, its history and its literature.

What is quantum non-equilibrium?

An ensemble whose configurations are not distributed as |Ψ|². In this picture the Born rule is not a postulate but a state of statistical equilibrium, as a Maxwell distribution is in a gas; a distribution that differs from it is possible in principle, and Valentini showed that for a wave function that is a superposition of several energy eigenstates the flow can stir such an ensemble towards |Ψ|² on a coarse-grained scale, as a classical gas relaxes, with a coarse-grained H-function as the measure of the distance from equilibrium. Whether, and how fast, this relaxation happens for the correlated states of real atoms, molecules and solids, rather than for particles in a box, is the question CASINO’s pilot-wave facility was built to answer.

What is Nelson’s stochastic mechanics?

A variant, due to Bohm and Vigier and to Nelson (1966), in which the particles’ motion has an osmotic drift and a random component besides the pilot-wave velocity, with a diffusion constant that Nelson set at one half for an electron and that the utility takes as a parameter, with the Born distribution as the equilibrium the process relaxes to. The two theories make the same predictions in equilibrium and differ out of it: under the deterministic dynamics an ensemble relaxes only on a coarse-grained scale, under the stochastic one it relaxes outright. CASINO’s trajectory utility integrates either, the stochastic dynamics when a diffusion constant is given.

What does CASINO’s pilot-wave facility do?

Three things, all shipped in version 3.2. The run type pilot_eval evaluates a trial wave function, the gradient of its logarithm and its local and per-particle kinetic energies at configurations read from a file, or fed through a pipe, which is what a trajectory calculation needs. The utility pilotdrive forms a superposition of CASINO wave functions, each a state computed in a directory of its own, estimates their norms, overlaps and Hamiltonian matrix from their own VMC samples and diagonalises the Hamiltonian in the space they span, then integrates the de Broglie-Bohm trajectories of ensembles of systems, started in equilibrium or out of it, and follows the coarse-grained H-function of each ensemble on one or several marginals, with the floors and the null distribution against which a value is judged. The states can be any wave function pilot_eval accepts (not one in a magnetic field, with non-collinear spins, with transverse_method 1 or with a held particle), for a finite system or a periodic one in two or three dimensions, all-electron or with pseudopotentials, real or complex; with a diffusion constant the trajectories follow Nelson’s dynamics instead. It also computes, for a molecule from which an electron is removed suddenly, the state the cation is left in (pilotdrive dyson). The third is LOUIS (below); beside them, the utility wfnscope draws the velocity field of a superposition as the electrons are dragged about in a browser. The manual’s section “Pilot-wave trajectories” gives the route and the cost; for the helium example, three states and 500 trajectories over 75 atomic units of time take about three minutes on three cores.

Why is this in a quantum Monte Carlo program?

Because a QMC program already has everything a trajectory calculation of a real system needs: accurate correlated wave functions of atoms, molecules and solids, the machinery to evaluate them and the gradient of their logarithm at any configuration of the electrons, and samples of |Ψ|² from which ensembles are drawn. The trajectory work on particles in a box, which LOUIS does, has been distributed with CASINO since 2013 because the study of quantum trajectories bears on proposed QMC algorithms; the step to real atoms needed the wave functions, and CASINO had them. The facility is a run type and a utility of its own and touches no VMC or DMC result.

What is it good for?

The relaxation to quantum equilibrium can now be studied in the correlated states of real atoms and molecules, which is the question the route exists to answer. What the helium work established is in the manual: two real states never relax, since every trajectory retraces itself after one beat period; a superposition of states with commensurate frequencies is periodic too, so the three lowest ¹S states of helium stir an ensemble from an H of 0.99 down to 0.69 and back to 0.95 after one period, nearly every trajectory where it started; relaxation needs incommensurate beats, states of two or three symmetries, or the phase slips of thousands of atomic units of time. Beyond that question the trajectories give a picture of what the electrons of a molecule do in a superposition, the response of a molecule to the sudden removal of an electron, and a test of the states themselves: a trial state is not an eigenstate, and the spread of the continuity defect along the trajectories measures how far it is from one in the sense the dynamics needs (with non-local pseudopotentials a part of the defect belongs to exact eigenstates too). The film “Towards quantum equilibrium: beryllium” on this site’s Videos and simulations page shows such an ensemble, 4,000 beryllium atoms in a superposition of twelve states, started out of equilibrium and followed for 200 atomic units of time.

What is LOUIS?

A separate program of Mike Towler’s, distributed with CASINO since 2013, that propagates quantum particles in a two- or three-dimensional box by de Broglie-Bohm dynamics and its generalisations, following single trajectories, the time-dependent density and the H-function; since version 3.2 it carries a forward ensemble of walkers in two dimensions, with or without Nelson’s stochastic noise, and computes the coarse-grained H-function from it, and it has a manual of its own in utils/louis/manual.

14. Getting involved

How do I contribute, or become a developer?

A user accepted as a developer, as the page How to become a developer describes, downloads the version with the full source and can be given read access to the git repository. A change is sent to the maintainer as a git-formatted patch, with the evidence that it passed the test suite in serial and in parallel; the manual’s appendix on contributing says how a change is written, tested and described, and the page Things to do lists what is wanted. A converter for a program not on the list in Section 4 is a self-contained contribution, and the page Interface development is written for its author.

Where do I learn QMC itself?

Start with the manual’s first chapter, which explains VMC and DMC, the errors in a result and what a calculation costs in the terms a user needs, and with the tutorial of Chapter 3, which takes a molecule from trial wave function to DMC with every number shown. The page Introductory and review material lists the reviews, the lectures of the summer schools and the books. The forum’s archive, back to 2013, holds the answers to most of what a new user meets.

Contents