Interface to NumPy

Code author: Daniel G. A. Smith

Section author: Daniel G. A. Smith

Module: psi4/psi4/driver/p4util/numpy_helper.py

Basics

Converting between the PSI4 Data classes and a NumPy array is easy through various helper functions as detailed in this section. A quick overview NumPy functionality can be found here. In addition, numerous example of hybrid NumPy and Psi4 can be found at the Psi4Numpy project. Currently only the Matrix and Vector objects support NumPy interfacing. Let us begin with a simple conversion from these objects to a NumPy array:

>>> import psi4
>>> import numpy as np

# Build the Psi4 data objects
>>> mat = psi4.core.Matrix(3, 3)
>>> vec = psi4.core.Vector(3)

# Convert to a NumPy array
>>> numpy_mat = np.array(mat)
>>> numpy_vec = np.array(vec)

Here the data is copied into new NumPy arrays. NumPy arrays can be converted back to PSI4 objects using the from_array interface:

>>> new_mat = psi4.core.Matrix.from_array(mat)
>>> new_vec = psi4.core.Vector.from_array(vec)

NumPy Views

Copying the data between NumPy and Psi4 objects can lead to excessive data movement and convoluted code. Here we introduce the idea of “Views” where the same data can be viewed by multiple objects. However, this can lead to very subtle errors if used incorrectly and care needs to be taken when using these views. Views can be created in two ways:

>>> numpy_mat_view = np.asarray(mat)

# Access the NumPy object and set all values to 1 through broadcasting
>>> numpy_mat_view[:] = 1

>>> print(np.array(mat))
[[ 1.  1.  1.]
 [ 1.  1.  1.]
 [ 1.  1.  1.]]

Secondly, these objects have a .np attribute for easy access to the underlying data:

>>> mat.np[:] = 1

this operation is identical to the above.

PSI4 Data Objects with Irreps

PSI4 data objects natively support multiple irreducible representations which is quite useful for Quantum Chemistry. However, this is not fundamental to NumPy and some work around are required to natively support these operations. Take the following irreped Matrix:

>>> dim = psi4.core.Dimension.from_list([1, 2, 3])
>>> irreped_mat = psi4.core.Matrix("New Matrix", dim, dim)

# Create a list of Psi4 arrays
>>> list_of_arrays = irreped_mat.to_array()

# Or, use the .nph irreped accessor
>>> irreped_mat.nph[0][:] = 1

Where .nph is the irreped accessor form. If .np or np.array are called on irreped Matrices or Vectors an error will be thrown; however, the irreped form is always valid for non-irreped matrices.

Array to Matrix

A general function that converts PSI4 data objects to NumPy arrays.

psi4.driver.p4util.numpy_helper.array_to_matrix(self, arr, name='New Matrix', dim1=None, dim2=None)[source]

Converts a NumPy array or list of NumPy arrays into a PSI4 Matrix or Vector (irrepped if list).

Parameters:
  • self (Union[Matrix, Vector]) – Matrix or Vector class.

  • arr (Union[ndarray, List[ndarray]]) – NumPy array or list of arrays to use as the data for a new Matrix or Vector.

  • name (str) – Name to give the new Matrix.

  • dim1 (Union[List, Tuple, Dimension, None]) – If a single dense NumPy array is given, a dimension can be supplied to apply irreps to this array. Note that this discards all extra information given in the matrix besides the diagonal blocks determined by the passed dimension.

  • dim2 (Optional[Dimension]) – Same as dim1 only if using a Dimension object.

Returns:

Returns the given (self) Psi4 object.

Return type:

Matrix or Vector

Notes

This is a generalized function to convert a NumPy array to a Psi4 object

Examples

>>> data = np.random.rand(20,1)
>>> vector = psi4.core.Matrix.from_array(data)
>>> irrep_data = [np.random.rand(2, 2), np.empty(shape=(0,3)), np.random.rand(4, 4)]
>>> matrix = psi4.core.Matrix.from_array(irrep_data)
>>> print(matrix.rowdim().to_tuple())
(2, 0, 4)

Matrix to Array

A general function that converts NumPy arrays to PSI4 data objects.

psi4.driver.p4util.numpy_helper._to_array(matrix, copy=True, dense=False)[source]

Converts a PSI4 Matrix or Vector to a NumPy array. Either copies the data or simply constructs a view.

Parameters:
  • matrix (Union[Matrix, Vector]) – Pointers to which Psi4 core class should be used in the construction.

  • copy (bool) – Copy the data if True, return a view otherwise

  • dense (bool) – Converts irrepped Psi4 objects to diagonally blocked dense arrays if True. Returns a list of arrays otherwise.

Returns:

Returns a single or list of NumPy arrays depending on options.

Return type:

ndarray or List[ndarray]

Notes

This is a generalized function to convert a Psi4 object to a NumPy array

Examples

>>> data = psi4.core.Matrix(3, 3)
>>> data.to_array()
[[ 0.  0.  0.]
 [ 0.  0.  0.]
 [ 0.  0.  0.]]