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:

The classical schemes

RPA

STLS

STLS-IET

VS-STLS

The quantum schemes

QSTLS

QSTLS-IET

QVS

The hybrid ESA scheme

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 the Python packages that are necessary for running qupled. Depending on your platform and installation method, you may also need the Runtime Dependencies.

Install from source

If you want full control over your qupled installation, clone the repository:

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

Then install the Source-Build Dependencies for your platform. Once they are available, install the package from the repository root:

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx foga install --target qupled

Install with MPI support

MPI support is built from source. After installing the Source-Build Dependencies, including the MPI dependencies, run from the repository root:

uvx foga install --target qupled --profile mpi

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.