Overview

Qupled is a package that can be used to compute the properties of quantum one component plasmas via theoretical approaches based on the dielectric formalism. The theoretical approaches which can be solved with qupled include:

Qupled supports both MPI and OpenMP parallelizations to handle the most computationally-intensive calculations in the quantum and in the classical VS-STLS scheme.

Installation

Install with pip

Qupled can be installed as a pip package by running

pip install qupled

This will also install all the python packages that are necessary for running the package.

Install with MPI support

If you need to use qupled with MPI support, first install the External dependencies and then run

USE_MPI=ON pip install --no-binary=:all: qupled

Install from source

If you want full control over your qupled installation, you can install it also directly from the source. Start by cloning the respository

git clone https://github.com/fedluc/qupled.git
cd qupled

Then Install the External dependencies with

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --group dev --no-install-project
.venv/bin/foga install --target dev-env

and then run build and test commands through foga:

foga build
foga test

If you want to run an example or an ad-hoc script during development, prefer uv run so the project uses the synced environment without requiring an extra package installation step.

External dependencies

Installing qupled may require compiling some C++ code, depending on the platform and installation method. The following dependencies must be met before attempting to build the C++ part of qupled

The installation of these dependencies can be done in different ways depending on the platform you are using. For example, on Ubuntu, Debian-based and macOS systems, you can use the following commands:

Ubuntu or Debian-based systems

sudo apt-get install -y cmake libopenmpi-dev libgsl-dev libomp-dev python3-dev libsqlite3-dev libsqlitecpp-dev

Fedora or Red Hat-based system

sudo dnf install -y cmake openmpi openmpi-devel gsl-devel sqlite-devel
cd /tmp
git clone https://github.com/SRombauts/SQLiteCpp.git
cd SQLiteCpp
mkdir build && cd build
cmake ..
make -j$(nproc)
make install
ldconfig
cd / && rm -rf /tmp/SQLiteCpp

macOS

brew install cmake gsl libomp openmpi sqlite sqlitecpp

Architecture

Qupled is a hybrid Python/C++ package. The Python layer handles the user-facing API, input validation, and result storage, while the C++ native library performs the heavy numerical computations. The two layers communicate through pybind11 bindings compiled into the qupled.native extension module.

        %%{init: {'theme': 'default', 'themeVariables': {'primaryColor': '#dbeafe', 'primaryBorderColor': '#2563eb', 'primaryTextColor': '#1e3a5f', 'edgeLabelBackground': '#f0f4ff', 'lineColor': '#2563eb'}}}%%
graph TD
    User(["User"])
    Input["Input class<br/>(qupled.schemes.*)"]
    Solver["Solver class<br/>(qupled.schemes.*)"]
    Bindings["pybind11 bindings<br/>(qupled.native)"]
    Cpp["C++ native library<br/>(schemes / thermo / util)"]
    DB[("SQLite database<br/>qupled.db")]
    Post["Post-processing<br/>(qupled.postprocess)"]

    User -->|"configures"| Input
    User -->|"calls compute()"| Solver
    Solver -->|"passes input to"| Bindings
    Bindings -->|"invokes"| Cpp
    Cpp -->|"returns results"| Bindings
    Bindings -->|"returns"| Solver
    Solver -->|"writes results to"| DB
    DB -->|"read via"| Post

Units

All the calculations are performed in normalized units. The wave vectors are normalized to the Fermi wave-vector and the frequencies are normalized to \(2\pi E_{\mathrm{f}}/h\). Here \(E_{\mathrm{f}}\) is the Fermi energy and \(h\) is Planck’s constant.

Limitations

  • Quantum schemes are currently only available for 3D systems; 2D calculations are not implemented for QSTLS, QSTLS-IET, and QVS.

  • Ground state (zero temperature) calculations are not available for the QSTLS-IET and QVS schemes.