Python API

qupled is a hybrid Python/C++ package designed to simulate and analyze dielectric response schemes, both classical and quantum. Python orchestrates the workflow: setting up simulations, managing input/output, and storing results in an SQLite database. C++ performs the heavy numerical computations, accessed via pybind11 bindings.

To run a simulation, users configure input parameters through Python classes (e.g., qupled.schemes.hf.Input) and launch the computation using the corresponding solver class (e.g., qupled.schemes.hf.HF). Results are returned in dedicated result objects (e.g., qupled.schemes.hf.Result) and automatically written to an SQLite database for post-processing or analysis.

The database is implemented in standard SQLite format and can be accessed using any compatible external tool (e.g., sqlite3, DB Browser for SQLite). For convenience, the package provides a dedicated Python interface in the qupled.postprocess.output.Database class, which includes helper methods to query, inspect, and extract stored simulation data programmatically.

The sections below describe the supported schemes in more detail, including their respective input, solver, and result classes.

Classic schemes

HF scheme

The qupled.schemes.hf module is used to setup and perform all the necessary calculations for the solution of the Hartree-Fock approximation. The solution parameters are specified with a dedicated class called qupled.schemes.hf.Input. After the solution is completed the results are stored in an object qupled.schemes.hf.Result and written to the output database.

class qupled.schemes.hf.Solver

Class used to solve the HF scheme.

inputs: Input: The inputs used to solve the scheme. Default = None

results: Result: The results obtained by solving the scheme

property run_id

Property that retrieves the run ID from the database handler.

Returns: The run ID associated with the current database handler.
Return type: str

compute_rdf(rdf_grid: ndarray = None)

Computes the radial distribution function (RDF) using the provided RDF grid.

Parameters: rdf_grid – A numpy array representing the RDF grid. If not provided, a default grid will be used.

compute_itcf(tau: numpy.ndarray | None = None)

Computes the imaginary-time correlation function (ITCF) using the provided imaginary-time grid.

Parameters: tau – A numpy array representing the imaginary-time grid. If not provided, a default grid will be used.

get_solver_status() → RunStatus

Retrieves the current status of the solver based on the native scheme status.

Returns: The corresponding run status from the
Return type: RunStatus

class qupled.schemes.hf.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: ~qupled.util.dimension.Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'HF', database_info: ~qupled.schemes.hf.DatabaseInfo = None)

Class used to store the inputs for the qupled.hf.HF class.

coupling: float: Coupling parameter.

degeneracy: float: Degeneracy parameter.

chemical_potential: list[float]: Initial guess for the chemical potential. Default = [-10, 10]

cutoff: float = 10.0: Cutoff for the wave-vector grid. Default = 10.0

dimension: Dimension = 'D3': Dimesionality of the system. Default = 'Dimension._3D'

frequency_cutoff: float = 10.0: Cutoff for the frequency (applies only in the ground state). Default = 10.0

integral_error: float = 1e-05: Accuracy (relative error) in the computation of integrals. Default = 1.0e-5

integral_strategy: str = 'full'

Scheme used to solve two-dimensional integrals allowed options include:

full: the inner integral is evaluated at arbitrary points selected automatically by the quadrature rule
segregated: the inner integral is evaluated on a fixed grid that depends on the integrand that is being processed

Segregated is usually faster than full but it could become less accurate if the fixed points are not chosen correctly. Default = 'full'

matsubara: int = 128: Number of Matsubara frequencies. Default = 128

resolution: float = 0.1: Resolution of the wave-vector grid. Default = 0.1

threads: int = 1: Number of OMP threads for parallel calculations. Default = 1

processes: int = 1: Number of MPI processes for parallel calculations. Default = 1

class qupled.schemes.hf.Result(chemical_potential: float = None, idr: ndarray = None, itcf: ndarray = None, lfc: ndarray = None, rdf: ndarray = None, rdf_grid: ndarray = None, sdr: ndarray = None, ssf: ndarray = None, tau: ndarray = None, uint: float = None, wvg: ndarray = None)

Class used to store the results for the qupled.hf.HF class.

chemical_potential: float = None: Chemical potential

idr: ndarray = None: Ideal density response

itcf: ndarray = None: Imaginary-time correlation function

lfc: ndarray = None: Local field correction

rdf: ndarray = None: Radial distribution function

rdf_grid: ndarray = None: Radial distribution function grid

sdr: ndarray = None: Static density response

ssf: ndarray = None: Static structure factor

tau: ndarray = None: Imaginary-time grid

uint: float = None: Internal energy

wvg: ndarray = None: Wave-vector grid

compute_itcf(inputs: Input, tau: numpy.ndarray | None = None)

Compute the imaginary-time correlation function (ITCF) for the system.

The imaginary-time grid is in absolute units [0, 1/theta], where theta is the degeneracy parameter. For ground-state calculations (theta = 0), tau is unbounded and defaults to np.arange(0.0, 10.1, 0.1). For finite-temperature calculations, tau is clipped to [0, 1/theta] and defaults to np.arange(0.0, 1.1, 0.1) / theta.

Parameters

inputs – Input parameters used for the ITCF computation.
tau (np.ndarray | None, optional) – A 1D array of imaginary-time points in absolute units [0, 1/theta]. If None, a default grid is generated based on the degeneracy parameter.

Raises

ValueError – If the wave-vector grid (wvg) or the local field correction (lfc) is not available.

Returns

The computed ITCF and imaginary-time grid are stored in the self.itcf: and self.tau attributes respectively.

Return type

None

Rpa scheme

The qupled.schemes.rpa module is used to setup and perform all the necessary calculations for the solution of the Random-Phase Approximation. The solution parameters are specified with a dedicated class called qupled.schemes.rpa.Input. After the solution is completed the results are stored in an object qupled.schemes.hf.Result and written to the output database.

class qupled.schemes.rpa.Solver

Bases: Solver

Class used to solve the RPA scheme.

class qupled.schemes.rpa.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'RPA', database_info: DatabaseInfo = None)

Bases: Input

Class used to manage the input for the qupled.rpa.Rpa class.

Stls scheme

The qupled.schemes.stls module is used to setup and perform all the necessary calculations for the solution of the Stls scheme. The solution parameters are specified with a dedicated class called qupled.schemes.stls.Input. After the solution is completed the results are stored in an object qupled.schemes.stls.Result and written to the output database.

class qupled.schemes.stls.Solver

Bases: Solver

Class used to solve the Stls scheme.

static get_initial_guess(run_id: int, database_name: str | None = None) → Guess

Constructs an initial guess object by extracting the information from a database.

Parameters

run_id – The unique identifier for the run whose data is to be retrieved.
database_name – The name of the database to query. If None, the default database will be used.

Returns

An instance of Guess containing the initial guess data.

class qupled.schemes.stls.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'STLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>)

Bases: Input

Class used to manage the input for the qupled.stls.Stls class.

error: float = 1e-05: Minimum error for convergence. Default = 1.0e-5

mixing: float = 1.0: Mixing parameter. Default = 1.0

iterations: int = 1000: Maximum number of iterations. Default = 1000

guess: Guess: Initial guess. Default = stls.Guess()

class qupled.schemes.stls.Result(chemical_potential: float = None, idr: ndarray = None, itcf: ndarray = None, lfc: ndarray = None, rdf: ndarray = None, rdf_grid: ndarray = None, sdr: ndarray = None, ssf: ndarray = None, tau: ndarray = None, uint: float = None, wvg: ndarray = None, error: float = None)

Bases: Result

Class used to store the results for the qupled.stls.Stls class.

error: float = None: Final error of the scheme. Default = None

class qupled.schemes.stls.Guess(wvg: 'np.ndarray' = None, ssf: 'np.ndarray' = None)

wvg: ndarray = None: Wave-vector grid. Default = None

ssf: ndarray = None: Static structure factor. Default = None

Stls-IET schemes

The qupled.schemes.stlsiet module is used to setup and perform all the necessary calculations for the solution of the Stls-IET schemes. The solution parameters are specified with a dedicated class called qupled.schemes.stlsiet.Input. After the solution is completed the results are stored in an object qupled.schemes.stlsiet.Result and written to the output database.

class qupled.schemes.stlsiet.Solver

Bases: Solver

Class used to solve the StlsIet schemes.

static get_initial_guess(run_id: str, database_name: str | None = None) → Guess

Retrieves the initial guess for a computation based on a specific run ID from a database.

Parameters

run_id – The unique identifier for the run whose data is to be retrieved.
database_name – The name of the database to query. If None, the default database is used.

Returns

An object containing the initial guess values, including results and inputs extracted from the database.

Return type

Guess

class qupled.schemes.stlsiet.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'STLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>, mapping: str = 'standard')

Bases: Input

Class used to manage the input for the qupled.stlsiet.StlsIet class. Accepted theories: STLS-HNC, STLS-IOI and STLS-LCT.

mapping: str = 'standard'

Mapping for the classical-to-quantum coupling parameter \(\Gamma\) used in the iet schemes. Allowed options include:

standard: \(\Gamma \propto \Theta^{-1}\)
sqrt: \(\Gamma \propto (1 + \Theta)^{-1/2}\)
linear: \(\Gamma \propto (1 + \Theta)^{-1}\)

where \(\Theta\) is the degeneracy parameter. Far from the ground state (i.e. \(\Theta\gg1\)) all mappings lead identical results, but at the ground state they can differ significantly (the standard mapping diverges). Default = standard.

guess: Guess: Initial guess. Default = stls.Guess()

class qupled.schemes.stlsiet.Result(chemical_potential: float = None, idr: ndarray = None, itcf: ndarray = None, lfc: ndarray = None, rdf: ndarray = None, rdf_grid: ndarray = None, sdr: ndarray = None, ssf: ndarray = None, tau: ndarray = None, uint: float = None, wvg: ndarray = None, error: float = None, bf: ndarray = None)

Bases: Result

Class used to store the results for the qupled.stlsiet.StlsIet class.

bf: ndarray = None: Bridge function adder

class qupled.schemes.stlsiet.Guess(wvg: 'np.ndarray' = None, ssf: 'np.ndarray' = None, lfc: 'np.ndarray' = None)

lfc: ndarray = None: Local field correction. Default = None

VSStls scheme

The qupled.schemes.vsstls module is used to setup and perform all the necessary calculations for the solution of the VSStls scheme. The solution parameters are specified with a dedicated class called qupled.schemes.vsstls.Input. After the solution is completed the results are stored in an object qupled.schemes.vsstls.Result and written to the output database.

class qupled.schemes.vsstls.Solver

Bases: Solver

Class used to solve the VSStls scheme.

compute(inputs: Input)

Solves the scheme and saves the results.

Parameters: inputs – Input parameters.

class qupled.schemes.vsstls.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 9, processes: int = 1, theory: str = 'VSSTLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>, alpha: list[float] = <factory>, coupling_resolution: float = 0.1, degeneracy_resolution: float = 0.1, error_alpha: float = 0.001, iterations_alpha: int = 50, free_energy_integrand: FreeEnergyIntegrand = <factory>)

Bases: Input

Class used to manage the input for the qupled.vsstls.VSStls class.

alpha: list[float]: Initial guess for the free parameter. Default = [0.5, 1.0]

coupling_resolution: float = 0.1: Resolution of the coupling parameter grid. Default = 0.1

degeneracy_resolution: float = 0.1: Resolution of the degeneracy parameter grid. Default = 0.1

error_alpha: float = 0.001: Minimum error for convergence in the free parameter. Default = 1.0e-3

iterations_alpha: int = 50: Maximum number of iterations to determine the free parameter. Default = 50

free_energy_integrand: FreeEnergyIntegrand: Pre-computed free energy integrand.

threads: int = 9: Number of threads. Default = 9

class qupled.schemes.vsstls.Result(chemical_potential: float = None, idr: ndarray = None, itcf: ndarray = None, lfc: ndarray = None, rdf: ndarray = None, rdf_grid: ndarray = None, sdr: ndarray = None, ssf: ndarray = None, tau: ndarray = None, uint: float = None, wvg: ndarray = None, error: float = None, free_energy_grid: ndarray = None, free_energy_integrand: ndarray = None, alpha: float = None)

Bases: Result

Class used to store the results for the qupled.vsstls.VSStls class.

free_energy_grid: ndarray = None: Free energy grid

free_energy_integrand: ndarray = None: Free energy integrand

alpha: float = None: Free parameter

class qupled.schemes.vsstls.FreeEnergyIntegrand(grid: 'np.ndarray' = None, integrand: 'np.ndarray' = None)

grid: ndarray = None: Coupling parameter grid. Default = None

integrand: ndarray = None: Free energy integrand. Default = None

Hybrid schemes

ESA scheme

The qupled.schemes.esa module is used to setup and perform all the necessary calculations for the solution of the Effective Static Approximation. The solution parameters are specified with a dedicated class called qupled.schemes.esa.Input. After the solution is completed the results are stored in an object qupled.schemes.hf.Result and written to the output database.

class qupled.schemes.esa.Solver

Bases: Solver

Class used to solve the ESA scheme.

class qupled.schemes.esa.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'ESA', database_info: DatabaseInfo = None)

Bases: Input

Class used to manage the input for the qupled.esa.ESA class.

Quantum schemes

Qstls scheme

The qupled.schemes.qstls module is used to setup and perform all the necessary calculations for the solution of the Qstls scheme. TThe solution parameters are specified with a dedicated class called qupled.schemes.qstls.Input. After the solution is completed the results are stored in an object qupled.schemes.stls.Result and written to the output database.

class qupled.schemes.qstls.Solver

Bases: Solver

Class used to solve the Qstls scheme.

class qupled.schemes.qstls.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'QSTLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>, fixed_run_id: int | None = None)

Bases: Input

Class used to manage the input for the qupled.qstls.Qstls class.

Qstls-IET scheme

The qupled.schemes.qstlsiet module is used to setup and perform all the necessary calculations for the solution of the Qstls-IET schemes. The solution parameters are specified with a dedicated class called qupled.schemes.qstlsiet.Input. After the solution is completed the results are stored in an object qupled.schemes.stlsiet.Result and written to the output database.

class qupled.schemes.qstlsiet.Solver

Bases: Solver

Class used to solve the Qstls-IET schemes.

static get_initial_guess(run_id: str, database_name: str | None = None) → Guess

Constructs an initial guess object by extracting the information from a database.

Parameters

run_id – The unique identifier for the run whose data is to be retrieved.
database_name – The name of the database to query. If None, the default database will be used.

Returns

An instance of Guess containing the initial guess data.

class qupled.schemes.qstlsiet.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 1, processes: int = 1, theory: str = 'STLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>, fixed_run_id: int | None = None, mapping: str = 'standard')

Bases: Input, Input

Class used to manage the input for the qupled.qstlsiet.QStlsIet class. Accepted theories: QSTLS-HNC, QSTLS-IOI and QSTLS-LCT.

QVSStls scheme

The qupled.schemes.qvsstls.QVSStls class is used to setup and perform all the necessary calculations for the solution of the QVStls schemes. The solution parameters are specified with a dedicated class called qupled.schemes.qvsstls.Input. After the solution is completed the results are stored in an object qupled.schemes.vsstls.Result and written to the output database.

class qupled.schemes.qvsstls.Solver

Bases: Solver

Class used to solve the QVStls scheme.

compute(inputs: Input)

Solves the scheme and saves the results.

Parameters: inputs – Input parameters.

class qupled.schemes.qvsstls.Input(coupling: float, degeneracy: float, chemical_potential: list[float] = <factory>, cutoff: float = 10.0, dimension: Dimension = Dimension._3D, frequency_cutoff: float = 10.0, integral_error: float = 1e-05, integral_strategy: str = 'full', matsubara: int = 128, resolution: float = 0.1, threads: int = 9, processes: int = 1, theory: str = 'QVSSTLS', database_info: DatabaseInfo = None, error: float = 1e-05, mixing: float = 1.0, iterations: int = 1000, guess: Guess = <factory>, fixed_run_id: int | None = None, alpha: list[float] = <factory>, coupling_resolution: float = 0.1, degeneracy_resolution: float = 0.1, error_alpha: float = 0.001, iterations_alpha: int = 50, free_energy_integrand: FreeEnergyIntegrand = <factory>)

Bases: Input, Input

Class used to manage the input for the qupled.qvsstls.QVSStls class.

Finite Size Correction

The qupled.postprocess.finite_size_correction.FiniteSizeCorrection class is used to setup and perform all the necessary calculations to compute the finite size correction. The solution parameters are specified with a dedicated class called qupled.postprocess.finite_size_correction.Input. After the solution is completed the results are stored in an object qupled.postprocess.finite_size_correction.Result and written to the output database.

class qupled.postprocess.finite_size_correction.FiniteSizeCorrection

Post-processing FSC solver. It computes and writes results into the scheme run at (rs=target_rs, theta, dimension).

property run_id

Property that retrieves the run ID from the database handler.

Returns: The run ID associated with the current database handler.
Return type: str

compute(solver: Solver, inputs: Input)

Compute the finite size correction and store the results in the database.

Parameters: inputs – Input parameters.

class qupled.postprocess.finite_size_correction.Input(number_of_particles: int, drs: float = 0.1, scheme: Input = None)

Class used to store the inputs for the qupled.finite_size_correction.FiniteSizeCorrection class.

number_of_particles: int: Number of particles.

drs: float = 0.1: Coupling parameter resolution. Default = 0.1

scheme: Input = None: Scheme inputs. Default = None

class qupled.postprocess.finite_size_correction.Result(uint: 'float | None' = None, fxc: 'float | None' = None)

uint: float | None = None: Internal energy

fxc: float | None = None: Free energy

Output database

The output generated by qupled is stored in an SQL database named qupled.db, which is created in the directory where qupled is executed. If the database doesn’t already exist, it will be created automatically; otherwise, new results are added to the existing database. The qupled.postprocess.output.DataBase class provides functionality for accessing the data stored in the database.

class qupled.postprocess.output.DataBase

Class to read and delete data from a database generated by qupled

static inspect_runs(type: OutputType = OutputType.SCHEME, database_name: str | None = None) → dict

Reads runs from the database and returns the content in the form of a dictionary.

Parameters

type – The type of output to inspect. Defaults to OutputType.SCHEME.
database_name – Name of the database to read from. Defaults to None.

Returns

A dictionary whose keys are the run IDs and values are the corresponding run information.

Return type

dict

static read_run(run_id: int, type: OutputType = OutputType.SCHEME, database_name: str | None = None, input_names: list[str] | None = None, result_names: list[str] | None = None) → qupled.database.base_tables.RunData | None

Reads a specific run from the database.

Parameters

run_id – The ID of the run to read.
type – The type of output to read. Defaults to OutputType.SCHEME.
database_name – The name of the database to read from. Defaults to None.
input_names – A list of input names to retrieve. Defaults to None.
result_names – A list of result names to retrieve. Defaults to None.

Returns

Object containing the run data, or None if not found.

Return type

RunData

static read_inputs(run_id: int, type: OutputType = OutputType.SCHEME, database_name: str | None = None, names: list[str] | None = None) → dict

Reads inputs from the database and returns the content in the form of a dictionary.

Parameters

run_id – Identifier of the run to read inputs for.
type – The type of output to read inputs for. Defaults to OutputType.SCHEME.
database_name – Name of the database to read from. Defaults to None.
names – A list of quantities to read. Defaults to None, which reads all available quantities.

Returns

A dictionary whose keys are the quantities listed in names and values are the corresponding inputs.

Return type

dict

static read_results(run_id: int, type: OutputType = OutputType.SCHEME, database_name: str | None = None, names: list[str] | None = None) → dict

Reads results from the database and returns the content in the form of a dictionary.

Parameters

type – The type of output to read results for.
run_id – Identifier of the run to read results for. Defaults to OutputType.SCHEME.
database_name – Name of the database to read from. Defaults to None.
names – A list of quantities to read. Defaults to None, which reads all available quantities.

Returns

A dictionary whose keys are the quantities listed in names and values are the corresponding results.

Return type

dict

static delete_run(run_id: int, type: OutputType = OutputType.SCHEME, database_name: str | None = None)

Deletes a run entry from the database based on the provided run ID.

Parameters

run_id – The unique identifier of the run to be deleted.
type – The type of output to delete. Defaults to OutputType.SCHEME.
database_name – The name of the database to connect to. Defaults to None.

class qupled.postprocess.output.OutputType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

An enumerator representing the output types.

Values:

SCHEME: Output from a scheme calculation.

FINITE_SIZE_CORRECTION: Output from a finite size correction calculation.

Dimenions

class qupled.util.dimension.Dimension(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

An enumerator representing spatial dimensions.

Values:

_2D: Represents a two-dimensional space.

_3D: Represents a three-dimensional space.