Installation

Installing koopmans takes three steps: the electronic-structure codes, the Python package, and then one command that sets up the engine that runs your calculations.

The electronic-structure codes

koopmans does not do any of the electronic-structure work itself. It writes the inputs, runs Quantum ESPRESSO and Wannier90, and reads the outputs back. Their executables must be on your PATH before you set up the engine.

Which executables you need depends on what you want to calculate:

pw.x is needed by everything.
kcp.x computes screening parameters from total-energy differences, and evaluates the corrected functional. On a periodic system that route also uses wann2kcp.x and merge_evc.x.
kcw.x computes the screening parameters from linear response instead, and interpolates the final band structure.
wannier90.x and pw2wannier90.x construct the localized orbitals that periodic systems use as variational orbitals.
projwfc.x is optional, and gives you a projected density of states alongside a Wannierization.
ph.x computes dielectric constants.

Choosing the blocks of a Wannierization automatically additionally needs Wannier.jl and a Julia interpreter. Everything else works without them.

The Python package

koopmans requires Python 3.12 or 3.13. Install the most recent code from GitHub with uv:

$ uv pip install git+https://github.com/elinscott/koopmans.git

or with pip:

$ python3 -m pip install git+https://github.com/elinscott/koopmans.git

The engine

Calculations are dispatched, run and recorded by a background engine, which keeps track of what has already been computed so that an interrupted workflow can be resumed and a repeated calculation is not run twice. Set it up once, with

$ koopmans install

This creates the database that records your calculations, installs and starts the job scheduler, finds those executables on your PATH and registers them, and starts the background engine. It reports which executables it found; if one you need is missing, put it on your PATH and run the command again, or point at it explicitly:

$ koopmans install --code pw=/opt/qe/bin/pw.x

By default each calculation is given as many MPI processes as your machine has physical cores. Use --procs-per-calc to change that, and --max-procs to cap how many processes may run at once across all concurrent calculations.

Not every executable is compiled with MPI, and running a serial build under mpirun starts several copies of it in one directory, where they overwrite each other’s files. koopmans install therefore looks for a call to MPI_Init in each executable it registers, and in the shared libraries that executable links, and reports what it decided:

MPI:
  pw         parallel  (links libqe_modules.so.7, which calls mpi_init_)
  wannier90  serial    (no MPI_Init call in the binary or the libraries it links)

Merely linking an MPI runtime does not count: a build produced by mpif90 records libmpi whether or not any MPI call survives compilation. An executable in which no MPI call can be found is registered serial, which is slower but always correct. If the answer is wrong for one of your executables, overrule it:

$ koopmans install --parallel wannier90
$ koopmans install --serial pw

Rerunning koopmans install also re-inspects codes registered earlier and replaces any that runs the wrong way. A replacement code node is a new node, so calculations cached against the old one are no longer reused and will run again; the install reports which codes it replaced, and --no-migrate skips the step entirely.

To check on the engine at any point:

$ koopmans backend status

The engine runs in the background between calculations. If you reboot, or if it stops for any other reason, start it again with

$ koopmans backend daemon start

and stop it with koopmans backend daemon stop.

The scheduler that hands your calculations onto the machine’s cores has its own worker process, managed the same way:

$ koopmans backend hq status
HyperQueue server is running.
  worker 3: pool of 24 CPU(s)
  each calculation is given 4 MPI rank(s) by default

Start it with koopmans backend hq start if it is not running. To change the pool without reinstalling, restart the worker with a new size:

$ koopmans backend hq restart --max-procs 28

Keep the pool at least as large as the ranks one calculation is given — the second number above. A calculation asking for more ranks than the pool holds can never be scheduled, so it waits indefinitely rather than failing. To make each calculation smaller instead, rerun koopmans install --procs-per-calc.

koopmans backend hq stop stops the worker but leaves the scheduler running, so the queue is not discarded. Check hq job summary before stopping a worker with work in flight: a task whose worker disappears may be retried on the next one, in the same directory as the interrupted run. koopmans backend uninstall removes the whole setup, database included.

Installing for development

To install in development mode with uv:

$ git clone git+https://github.com/elinscott/koopmans.git
$ cd koopmans
$ uv pip install -e .

or with pip:

$ python3 -m pip install -e .