macrodensity.io module#

Module Description#

Module containing functions to read output files from VASP, GULP and FHI-AIMS.

macrodensity.io.get_band_extrema(input_file: str) → list#

Get the valence band maximum and conduction band minimum from VASP OUTCAR.

This function reads the VASP OUTCAR file and extracts the valence band maximum (VBM) and conduction band minimum (CBM). It also checks for partial occupancy and prints a warning message if found.

Args:

input_file (str): The path to the VASP OUTCAR file.

Returns:
list: A list containing the valence band maximum (VBM) and conduction band minimum (CBM).

list[0] = VBM, list[1] = CBM.

Example:
>>> input_file = 'path/to/OUTCAR'
>>> band_extrema = get_band_extrema(input_file)
>>> print("Valence Band Maximum (VBM):", band_extrema[0])
>>> print("Conduction Band Minimum (CBM):", band_extrema[1])
macrodensity.io.read_gulp_potential(gulpfile: str = 'gulp.out') → tuple#

Read electrostatic potential data from a GULP output file.

Parameters:

gulpfile (str, optional): Path to the GULP output file (gulp.out). Default is ‘gulp.out’.

Returns:
tuple: A tuple containing:

  • np.ndarray: 1D array representing the electrostatic potential data.

  • int: Number of grid points along the x-axis (NGX).

  • int: Number of grid points along the y-axis (NGY).

  • int: Number of grid points along the z-axis (NGZ).

  • np.ndarray: 3x3 array representing the Cartesian lattice vectors.

Example:
>>> gulpfile = 'path/to/gulp.out'
>>> potential, NGX, NGY, NGZ, lattice = read_gulp_potential(gulpfile)
>>> print("Electrostatic potential Data:", potential)
>>> print("Number of Grid Points (NGX, NGY, NGZ):", NGX, NGY, NGZ)
>>> print("Lattice Vectors:")
>>> print(lattice)
macrodensity.io.read_vasp_density(FILE: str, use_pandas: bool = None, quiet: bool = False) → tuple#

Read density data from a VASP CHGCAR-like file.

Parameters:

FILE (str): Path to the CHGCAR-like file.

use_pandas (bool or None, optional): If True, use Pandas to read 3D data (recommended for large files). If False, use np. If None, automatically use Pandas if available. Default is None.

quiet (bool, optional): If True, suppress print statements during reading. Default is False.

Returns:
tuple:

  • np.ndarray: 1D array representing the potential data.

  • int: Number of grid points along the x-axis (NGX).

  • int: Number of grid points along the y-axis (NGY).

  • int: Number of grid points along the z-axis (NGZ).

  • np.ndarray: 3x3 array representing the lattice vectors.

Example:
>>> FILE = "path/to/your/CHGCAR_file"
>>> potential_data, NGX, NGY, NGZ, lattice = read_vasp_density(FILE)
>>> print("potential Data:")
>>> print(potential_data)
>>> print("Number of grid points along x, y, z axes:", NGX, NGY, NGZ)
>>> print("Lattice Vectors:")
>>> print(lattice)
macrodensity.io.read_vasp_density_classic(FILE: str) → tuple#

Read density data from a classic VASP-style file.

Parameters:

FILE (str): Path to the density file.

Returns:
tuple: A tuple containing:

  • np.ndarray: 1D array representing the potential data.

  • int: Number of grid points along the x-axis (NGX).

  • int: Number of grid points along the y-axis (NGY).

  • int: Number of grid points along the z-axis (NGZ).

  • np.ndarray: 3x3 array representing the lattice vectors.

Example:
>>> FILE = "path/to/classic-VASP-density-file"
>>> potential, NGX, NGY, NGZ, lattice = read_vasp_density_classic(FILE)
>>> print("potential Data:", potential)
>>> print("Number of Grid Points (NGX, NGY, NGZ):", NGX, NGY, NGZ)
>>> print("Lattice Vectors:")
>>> print(lattice)
macrodensity.io.read_vasp_parchg(FILE: str, use_pandas: bool = None, quiet: bool = False, spin: bool = False) → tuple#

Read density data or spin-polarized partial density data from a VASP PARCHG-like file.

Parameters:

FILE (str): Path to the PARCHG-like file.

use_pandas (bool or None, optional): If True, use Pandas to read 3D data (recommended for large files). If False, use np. If None, automatically use Pandas if available. Default is None.

quiet (bool, optional): If True, suppress print statements during reading. Default is False.

spin (bool, optional): If True, read spin-polarized partial densities. Default is False.

Returns:
tuple: A tuple containing:

  • list or np.ndarray: List containing arrays representing the density data

for each spin channel, or np.ndarray for the total density if spin is False. - int: Number of grid points along the x-axis (NGX). - int: Number of grid points along the y-axis (NGY). - int: Number of grid points along the z-axis (NGZ). - np.ndarray: 3x3 array representing the lattice vectors.

Example:
>>> FILE = "path/to/PARCHG-like-file"
>>> density, NGX, NGY, NGZ, lattice = read_vasp_parchg(FILE)
>>> if isinstance(density, list):
        print("Spin-polarized Partial Densities:")
        for i, spin_density in enumerate(density):
            print(f"Spin {i+1} density Data:", spin_density)
>>> else:
        print("Total density Data:", density)
>>> print("Number of Grid Points (NGX, NGY, NGZ):", NGX, NGY, NGZ)
>>> print("Lattice Vectors:")
>>> print(lattice)