API Reference

High-level drivers

Engines

Core data model

class poraque.core.grid.Grid(shape, cell, pbc=True)

Real-space grid and its dual plane-wave (reciprocal) basis.

Poraquê represents fields (densities, potentials, Kohn-Sham orbitals) on a uniform real-space grid that fills the periodic unit cell. The grid is the primal representation; its discrete Fourier transform spans a plane-wave basis

\[\psi(\mathbf{r}) = \sum_{\mathbf{G}} c_{\mathbf{G}}\, e^{i \mathbf{G}\cdot\mathbf{r}},\]

where the wavevectors \(\mathbf{G}\) are the reciprocal-lattice points sampled by the FFT (see get_g_vectors()). This duality is what lets the kinetic operator be applied exactly (and diagonally) in reciprocal space while local potentials are applied diagonally in real space. The completeness of the basis is controlled by the grid density, i.e. by the plane-wave kinetic-energy cutoff (see from_ecut()).

classmethod from_ecut(cell, ecut, pbc=True, density_factor=2.0)

Build a grid dense enough for a given plane-wave kinetic cutoff.

The wavefunction plane-wave cutoff ecut (Hartree) corresponds to a maximum wavevector g_max = sqrt(2 * ecut). The electron density, being the square of the orbitals, contains components up to density_factor * g_max (2 for an exact product), so the grid spacing must satisfy the Nyquist condition h <= pi / (density_factor * g_max) along each lattice vector.

Parameters:

• cell (array_like) – 3x3 lattice vectors (Bohr).

• ecut (float) – Plane-wave kinetic-energy cutoff for the wavefunctions (Hartree).

• pbc (bool or tuple of bool, optional) – Periodic boundary conditions.

• density_factor (float, optional) – Ratio between the density and wavefunction cutoffs (default 2.0).

Returns:

A grid whose shape resolves the requested cutoff. The attribute ecut records the cutoff used.

Return type:

Grid

kinetic_g2(kpoint_cartesian=None)

Squared shifted reciprocal vectors \(|\mathbf{G} + \mathbf{k}|^2\).

Parameters:

kpoint_cartesian (array_like, optional) – Bloch wavevector in Cartesian reciprocal coordinates (1/Bohr). Defaults to the \(\Gamma\) point, recovering get_g2().

Returns:

Array of shape shape used to build the kinetic operator T = 1/2 |G + k|^2 in reciprocal space.

Return type:

numpy.ndarray

kpoint_to_cartesian(kpoint_fractional)

Convert a fractional k-point to Cartesian reciprocal coordinates.

Parameters:

kpoint_fractional (array_like) – (3,) k-point in fractional reciprocal coordinates (the convention used by ase.dft.kpoints.monkhorst_pack()).

Returns:

(3,) Cartesian wavevector (1/Bohr).

Return type:

numpy.ndarray

get_xyz()

Generate Cartesian coordinates for all grid points.

integrate(field)

Integrate a scalar field over the grid volume.

get_g_vectors()

Build the reciprocal-space grid vectors (Gx, Gy, Gz).

These are the angular wavevectors G = 2*pi*k sampled by the FFT for the current grid spacing, returned as three arrays each shaped like the grid.

Returns:

(Gx, Gy, Gz) arrays of shape self.shape.

Return type:

tuple of numpy.ndarray

get_g2()

Squared magnitude of the reciprocal grid vectors |G|^2.

Returns:

Array of shape self.shape with Gx^2 + Gy^2 + Gz^2.

Return type:

numpy.ndarray

class poraque.core.system.System(positions, atomic_numbers, cell, pbc=True, electrons=None, spin_polarized=False)

Represents the physical system (ions, electrons, cell).

classmethod from_ase(atoms, charge=0)

Create a System object from an ASE Atoms object.

Positions and cell are converted from Ångström (ASE convention) to Bohr (internal atomic units).

Parameters:

• atoms (ase.Atoms) – The atomic structure.

• charge (int, optional) – Net charge; the electron count is sum(Z) - charge.

to_ase()

Export this system to an ASE Atoms object.

Positions and cell are converted from Bohr (internal) back to Ångström (ASE convention). The inverse of from_ase() for neutral systems.

Returns:

The atomic structure in ASE units.

Return type:

ase.Atoms

class poraque.core.density.Density(grid, data=None)

Represents the electron density on the grid.

integrate()

Integrate the density over the grid volume.

normalize(n_electrons)

Normalize the density to a given number of electrons.

check_positivity()

Check if the density is positive everywhere. Returns the minimum value and its position (indices).

class poraque.core.state.State(grid, orbitals, occupations=None)

Represents the electronic state (orbitals, occupations). Mainly used for KS-DFT.

get_density()

Compute the electron density from orbitals and occupations.

\[n(\mathbf{r}) = \sum_i f_i\, |\phi_i(\mathbf{r})|^2\]

orthonormalize()

Orthonormalize orbitals using Gram-Schmidt or similar. Note: For real-space grids, this involves the volume element.

class poraque.core.results.Result(energy, components, density, state=None, converged=False, iterations=0, history=None)

Represents the output of a calculation.

class poraque.core.solver.SolverSettings(max_iter=100, tolerance=1e-06, mixing=0.5, algorithm='scf', max_line_search=20, cg_restart=20)

Generic solver configuration and utilities.

Functionals

Potentials

Pseudopotentials

Backends

ASE interface