qstack.equio

Equilibrium geometry and molecular structure I/O utilities.

qstack.equio.array_to_tensormap(mol, v)

Transform an array into a tensor map.

Wrapper for vector_to_tensormap and matrix_to_tensormap.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• v (numpy.ndarray) – Array to transform. Can be a vector (1D) or matrix (2D).

Returns:

Tensor map representation of the array.

Return type:

metatensor.TensorMap

Raises:

ValueError – If array dimension is not 1 or 2.

qstack.equio.join(tensors)

Merge two or more tensors with the same label names avoiding information duplication.

Parameters:

tensors (list) – List of metatensor.TensorMap objects.

Returns:

Merged tensor containing information from all input tensors.

Return type:

metatensor.TensorMap

Raises:

RuntimeError – If tensors have different label names.

qstack.equio.matrix_to_tensormap(mol, dm)

Transform a matrix into a tensor map.

Each element of the matrix corresponds to a pair of atomic orbitals.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• dm (numpy.ndarray) – matrix to transform.

Returns:

Tensor map representation of the matrix.

Return type:

metatensor.TensorMap

qstack.equio.split(tensor)

Split a tensor based on the molecule information stored within the input TensorMap.

Parameters:

tensor (metatensor.TensorMap) – Tensor containing several molecules.

Returns:

Collection of metatensor.TensorMap objects, one per molecule. Returns list if molecule indices are continuous, dict otherwise.

Return type:

list or dict

Raises:

RuntimeError – If tensor does not contain multiple molecules.

qstack.equio.tensormap_to_array(mol, tensor)

Transform a tensor map into an array.

Wrapper for tensormap_to_vector and tensormap_to_matrix.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• tensor (metatensor.TensorMap) – Tensor to transform.

Returns:

Array representation (1D vector or 2D matrix).

Return type:

numpy.ndarray

Raises:

RuntimeError – If tensor key names don’t match expected format.

qstack.equio.tensormap_to_matrix(mol, tensor)

Transform a tensor map into a matrix.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• tensor (metatensor.TensorMap) – tensor to transform.

Returns:

2D array (matrix) representation.

Return type:

numpy.ndarray

Raises:

RuntimeError – If tensor size does not match mol.nao * mol.nao.

qstack.equio.tensormap_to_vector(mol, tensor)

Transform a tensor map into a vector.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• tensor (metatensor.TensorMap) – tensor to transform.

Returns:

1D array (vector) representation.

Return type:

numpy.ndarray

Raises:

RuntimeError – If tensor size does not match mol.nao.

qstack.equio.vector_to_tensormap(mol, c)

Transform an vector into a tensor map.

Each element of the vector corresponds to an atomic orbital of the molecule.

Parameters:

• mol (pyscf.gto.Mole) – pyscf Mole object.

• c (numpy.ndarray) – vector to transform.

Returns:

Tensor map representation of the vector.

Return type:

metatensor.TensorMap