iodata.utils module

Utility functions module.

exception BaseFileError(message, file=None, lineno=None)

Bases: Exception

Base class for all errors related to loading or dumping files.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception BaseFileWarning(message, file=None, lineno=None)

Bases: Warning

Base class for all warnings related to loading or dumping files.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class Cube(origin, axes, data)

Bases: object

The volumetric data from a cube (or similar) file.

__init__(origin, axes, data)

Method generated by attrs for class Cube.

axes: ndarray[Any, dtype[float]]

A (3, 3) array where each row represents the spacing between two neighboring grid points along the first, second and third axis, respectively.

data: ndarray[Any, dtype[float]]

A (K, L, M) array of data on a uniform grid

origin: ndarray[Any, dtype[float]]

A 3D vector with the origin of the axes frame.

property shape

Shape of the rectangular grid.

exception DumpError(message, file=None, lineno=None)

Bases: BaseFileError

Raised when an error is encountered while dumping to a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception DumpWarning(message, file=None, lineno=None)

Bases: BaseFileWarning

Raised when an IOData object is made compatible with a format when dumping to a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception FileFormatError(message, file=None, lineno=None)

Bases: BaseFileError

Raise when a file or input format cannot be identified.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class LineIterator(filename)

Bases: object

Iterator class for looping over lines and keeping track of the line number.

Use this class as a context manager, similar to the built-in open function:

with LineIterator("filename.ext") as lit:
    for line in lit:
        ...

__init__(filename)

Initialize a LineIterator.

Parameters:

filename (str) – The file that will be read.

back(line)

Go back one line in the file and decrease the lineno attribute by one.

exception LoadError(message, file=None, lineno=None)

Bases: BaseFileError

Raised when an error is encountered while loading from a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception LoadWarning(message, file=None, lineno=None)

Bases: BaseFileWarning

Raised when incorrect content is encountered and fixed when loading from a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception PrepareDumpError(message, file=None, lineno=None)

Bases: BaseFileError

Raised when an IOData object is incompatible with a format before dumping to a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception PrepareDumpWarning(message, file=None, lineno=None)

Bases: BaseFileWarning

Raised when an IOData object is made compatible with a format before dumping to a file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception WriteInputError(message, file=None, lineno=None)

Bases: BaseFileError

Raised when an error is encountered while writing an input file.

__init__(message, file=None, lineno=None)

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

check_dm(dm, overlap, eps=0.0001, occ_max=1.0)

Check if the density matrix has eigenvalues in the proper range.

Parameters:

• dm (ndarray[Any, dtype[float]]) – The density matrix shape=(nbasis, nbasis), dtype=float

• overlap (ndarray[Any, dtype[float]]) – The overlap matrix shape=(nbasis, nbasis), dtype=float

• eps (float) – The threshold on the eigenvalue inequalities.

• occ_max (float) – The maximum occupation.

Raises:

ValueError – When the density matrix has wrong eigenvalues.

derive_naturals(dm, overlap)

Derive natural orbitals from a given density matrix.

Parameters:

• dm (ndarray[Any, dtype[float]]) – The density matrix. shape=(nbasis, nbasis)

• overlap (ndarray[Any, dtype[float]]) – The overlap matrix shape=(nbasis, nbasis)

Return type:

tuple[ndarray[Any, dtype[float]], ndarray[Any, dtype[float]]]

Returns:

• coeffs – Orbital coefficients shape=(nbasis, nfn)

• occs – Orbital occupations shape=(nfn, )

set_four_index_element(four_index_object, i0, i1, i2, i3, value)

Assign values to a four index object, account for 8-fold index symmetry.

This function assumes physicists’ notation.

Parameters:

• four_index_object (ndarray[Any, dtype[float]]) – The four-index object. It will be written to. shape=(nbasis, nbasis, nbasis, nbasis), dtype=float

• i0 (int) – The indices to assign to.

• i1 (int) – The indices to assign to.

• i2 (int) – The indices to assign to.

• i3 (int) – The indices to assign to.

• value (float) – The value of the matrix element to store.

strtobool(value)

Interpret string as a boolean.

Return type:

bool

volume(cellvecs)

Calculate the (generalized) cell volume.

Parameters:

cellvecs (ndarray[Any, dtype[float]]) – A numpy matrix of shape (x,3) where x is in {1,2,3}. Each row is one cellvector.

Return type:

float

Returns:

• In case of 3D, the cell volume.

• In case of 2D, the cell area.

• In case of 1D, the cell length.