Matrix

class psi4.core.Matrix

Bases: pybind11_object

Class for creating and manipulating matrices

Attributes Summary

name

The name of the Matrix.

np

View with single irrep.

nph

View with irreps.

shape

Shape of the Psi4 data object.

Methods Summary

absmax(self)

Returns the absolute maximum value

accumulate_product(self, arg0, arg1)

Multiplies two arguments and adds the result to this matrix

add(*args, **kwargs)

Overloaded function.

add_and_orthogonalize_row(self, v)

Expands the row dimension by one, and then orthogonalizes vector v against the current rows before setting the new row to the orthogonalized copy of v

apply_denominator(self, Matrix)

Apply matrix of denominators to this matrix

array_interface(self)

axpy(self, a, X)

Add to this matrix another matrix scaled by a

back_transform(*args, **kwargs)

Overloaded function.

chain_dot(**kwargs)

Chains dot products together from a series of Psi4 Matrix classes.

cholesky_factorize(self)

Computes the Cholesky factorization of a real symmetric positive definite matrix

clone(self)

Creates exact copy of the matrix and returns it

coldim(self)

Returns the columns per irrep array

cols(self[, h])

Returns the columns in irrep h

copy(self, arg0)

Copy another Matrix into this.

copy_lower_to_upper(self)

Copy the lower triangle to the upper triangle

copy_upper_to_lower(self)

Copy the upper triangle to the lower triangle

diagonalize(self, eigvectors, eigvalues, order)

Diagonalizes this matrix, space for the eigvectors and eigvalues must be created by caller.

doublet(A, B, transA, transB)

Multiply two matrices together.

from_array([name, dim1, dim2])

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

from_list(x)

from_serial()

Converts serialized data to the correct Psi4 data type :rtype: Union[Matrix, Vector]

gemm(self, transa, transb, alpha, a, b, beta)

Generalized matrix multiplication argument transa Transpose the left matrix? argument transb Transpose the right matrix? argument alpha Prefactor for the matrix multiplication argument A Left matrix argument B Right matrix argument beta Prefactor for the resulting matrix

general_invert(self)

Computes the inverse of any nonsingular matrix using LU factorization

get(*args, **kwargs)

Overloaded function.

get_block(self, rows, cols)

Get a matrix block

hermitivitize(self)

Average off-diagonal element in-place

hermitize(self)

Makes a real matrix symmetric by averaging the matrix and its transpose.

identity(self)

Sets the matrix to the identity

invert(self)

Computes the inverse of a real symmetric positive definite matrix

load(*args, **kwargs)

Overloaded function.

load_mpqc(self, filename)

Loads a matrix from an ASCII file in MPQC format

nirrep(self)

Returns the number of irreps

np_read([prefix])

Reads the data from a NumPy compressed or uncompressed file using numpy.load().

np_write([filename, prefix])

Writes the irrepped matrix to a NumPy uncompressed file using numpy.savez().

partial_cholesky_factorize(self[, delta, ...])

Computes the fully pivoted partial Cholesky factorization of a real symmetric positive semidefinite matrix, to numerical precision delta

power(self, alpha[, cutoff])

Takes the matrix to the alpha power with precision cutoff

print_atom_vector(self[, RMRoutfile])

Print the matrix with atom labels, assuming it is an natom X 3 tensor

print_out(self)

Prints the matrix to the output file

pseudoinverse(self, condition, nremoved)

Computes the matrix which is the conditioned pseudoinverse of this matrix

remove_symmetry(self, a, transformer)

Remove symmetry from a matrix A with PetiteList::sotoao()

rms(self)

Returns the rms of this matrix

rotate_columns(self, h, i, j, theta)

Rotates columns i and j in irrep h by angle theta

rowdim(self)

Returns the rows per irrep array

rows(self[, h])

Returns the rows in irrep h

save(*args, **kwargs)

Overloaded function.

scale(self, a)

Scales the matrix by the floating point value a

scale_column(self, h, n, a)

Scales column n of irrep h by a

scale_row(self, h, m, a)

Scales row m of irrep h by a

schmidt(self)

Calls the libqt schmidt function

set(*args, **kwargs)

Overloaded function.

set_block(self, rows, cols, block)

Set a matrix block

subtract(self, arg0)

Substract a matrix from this matrix

sum_of_squares(self)

Returns the sum of the squares of this matrix

symmetrize_gradient(self, mol)

Symmetrizes a gradient-like matrix (N,3) using information from a given molecule

symmetry(self)

Returns the overall symmetry of the matrix

to_array([copy, dense])

Converts a PSI4 Matrix or Vector to a NumPy array.

to_serial()

Converts an object with a .nph accessor to a serialized dictionary

trace(self)

Returns the trace of the matrix

transform(*args, **kwargs)

Overloaded function.

transpose(self)

Creates a new matrix that is the transpose of this matrix

transpose_this(self)

Transpose the matrix in-place

triplet(A, B, C, transA, transB, transC)

Multiply three matrices together.

vector_dot(self, rhs)

Returns the vector dot product of this with rhs

zero(self)

Zero all elements of the matrix

zero_diagonal(self)

Zero the diagonal of the matrix

zero_lower(self)

Zero the lower triangle

zero_upper(self)

Zero the upper triangle

Attributes Documentation

name

The name of the Matrix. Used in printing.

np

View with single irrep.

nph

View with irreps.

shape

Shape of the Psi4 data object.

Methods Documentation

absmax(self: psi4.core.Matrix) float

Returns the absolute maximum value

accumulate_product(self: psi4.core.Matrix, arg0: psi4.core.Matrix, arg1: psi4.core.Matrix) None

Multiplies two arguments and adds the result to this matrix

add(*args, **kwargs)

Overloaded function.

  1. add(self: psi4.core.Matrix, arg0: psi4.core.Matrix) -> None

Adds a matrix to this matrix

  1. add(self: psi4.core.Matrix, h: int, m: int, n: int, val: float) -> None

Increments row m and column n of irrep h’s block matrix by val.

add_and_orthogonalize_row(self: psi4.core.Matrix, v: psi4.core.Vector) bool

Expands the row dimension by one, and then orthogonalizes vector v against the current rows before setting the new row to the orthogonalized copy of v

apply_denominator(self: psi4.core.Matrix, Matrix: psi4.core.Matrix) None

Apply matrix of denominators to this matrix

array_interface(self: psi4.core.Matrix) list
axpy(self: psi4.core.Matrix, a: float, X: psi4.core.Matrix) None

Add to this matrix another matrix scaled by a

back_transform(*args, **kwargs)

Overloaded function.

  1. back_transform(self: psi4.core.Matrix, transformer: psi4.core.Matrix) -> None

Backtransform this with transformer

  1. back_transform(self: psi4.core.Matrix, a: psi4.core.Matrix, transformer: psi4.core.Matrix) -> None

Backtransform A with transformer

chain_dot(**kwargs)

Chains dot products together from a series of Psi4 Matrix classes. Uses doublet(). :rtype: Matrix

Parameters:
  • args – Arbitrary number of Matrix arguments to be multiplied.

  • trans – Optional iterable of booleans of length number of args to designate transposes, if any.

Return type:

Matrix

cholesky_factorize(self: psi4.core.Matrix) None

Computes the Cholesky factorization of a real symmetric positive definite matrix

clone(self: psi4.core.Matrix) psi4.core.Matrix

Creates exact copy of the matrix and returns it

coldim(self: psi4.core.Matrix) psi4.core.Dimension

Returns the columns per irrep array

cols(self: psi4.core.Matrix, h: int = 0) int

Returns the columns in irrep h

copy(self: psi4.core.Matrix, arg0: psi4.core.Matrix) None

Copy another Matrix into this.

copy_lower_to_upper(self: psi4.core.Matrix) None

Copy the lower triangle to the upper triangle

copy_upper_to_lower(self: psi4.core.Matrix) None

Copy the upper triangle to the lower triangle

diagonalize(self: psi4.core.Matrix, eigvectors: psi4.core.Matrix, eigvalues: psi4.core.Vector, order: psi4.core.DiagonalizeOrder = <DiagonalizeOrder.Ascending: 1>) None

Diagonalizes this matrix, space for the eigvectors and eigvalues must be created by caller. Only for symmetric matrices.

static doublet(A, B, transA, transB)

Multiply two matrices together.

Deprecated since version 1.4: Use psi4.core.doublet() instead.

classmethod from_array(name='New Matrix', dim1=None, dim2=None)

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

Parameters:
  • self – 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)
classmethod from_list(x)
classmethod from_serial()

Converts serialized data to the correct Psi4 data type :rtype: Union[Matrix, Vector]

Parameters:
  • self – Pointer to which class to be constructed.

  • json_data (Dict[str, Any]) – Serialization of class. See to_serial() for data layout.

Return type:

Matrix | Vector

gemm(self: psi4.core.Matrix, transa: bool, transb: bool, alpha: float, a: psi4.core.Matrix, b: psi4.core.Matrix, beta: float) None

Generalized matrix multiplication argument transa Transpose the left matrix? argument transb Transpose the right matrix? argument alpha Prefactor for the matrix multiplication argument A Left matrix argument B Right matrix argument beta Prefactor for the resulting matrix

general_invert(self: psi4.core.Matrix) None

Computes the inverse of any nonsingular matrix using LU factorization

get(*args, **kwargs)

Overloaded function.

  1. get(self: psi4.core.Matrix, h: int, m: int, n: int) -> float

Returns a single element of a matrix in subblock h, row m, col n

  1. get(self: psi4.core.Matrix, m: int, n: int) -> float

Returns a single element of a matrix, row m, col n

get_block(self: psi4.core.Matrix, rows: psi4.core.Slice, cols: psi4.core.Slice) psi4.core.Matrix

Get a matrix block

hermitivitize(self: psi4.core.Matrix) None

Average off-diagonal element in-place

hermitize(self: psi4.core.Matrix) None

Makes a real matrix symmetric by averaging the matrix and its transpose.

identity(self: psi4.core.Matrix) None

Sets the matrix to the identity

invert(self: psi4.core.Matrix) None

Computes the inverse of a real symmetric positive definite matrix

load(*args, **kwargs)

Overloaded function.

  1. load(self: psi4.core.Matrix, filename: str) -> None

Loads a block matrix from an ASCII file (see tests/mints3 for format)

  1. load(self: psi4.core.Matrix, psio: psi4.core.IO, fileno: int, tocentry: str, nso: int) -> bool

Load a matrix from a PSIO object from fileno with tocentry of size nso

  1. load(self: psi4.core.Matrix, psio: psi4.core.IO, fileno: int, savetype: psi4.core.SaveType = <SaveType.LowerTriangle: 2>) -> None

Load a matrix from a PSIO object from fileno and with toc position of the name of the matrix

load_mpqc(self: psi4.core.Matrix, filename: str) None

Loads a matrix from an ASCII file in MPQC format

nirrep(self: psi4.core.Matrix) int

Returns the number of irreps

classmethod np_read(prefix='')

Reads the data from a NumPy compressed or uncompressed file using numpy.load(). :rtype: Union[Matrix, Vector]

Parameters:
  • self – Pointer to which class to be constructed.

  • filename (str) – File name to read.

  • prefix (str) – Name under which array was saved for NumPy.

Return type:

Matrix | Vector

np_write(filename=None, prefix='')

Writes the irrepped matrix to a NumPy uncompressed file using numpy.savez().

Can return the packed data for saving many matrices into the same file.

Parameters:
  • self (Union[Matrix, Vector]) – Instance to be serialized.

  • filename (Optional[str]) – File name where the data will be saved.

  • prefix (str) – Name of instance prepared for NumPy.

Returns:

When filename given, it and dict serialization passed to numpy.savez(), so .npz file saved and None returned. When filename None, dict serialization returned.

Return type:

None or Dict[str, Any]

partial_cholesky_factorize(self: psi4.core.Matrix, delta: float = 0.0, throw_if_negative: bool = False) psi4.core.Matrix

Computes the fully pivoted partial Cholesky factorization of a real symmetric positive semidefinite matrix, to numerical precision delta

power(self: psi4.core.Matrix, alpha: float, cutoff: float = 1e-12) psi4.core.Dimension

Takes the matrix to the alpha power with precision cutoff

print_atom_vector(self: psi4.core.Matrix, RMRoutfile: str = 'outfile') None

Print the matrix with atom labels, assuming it is an natom X 3 tensor

print_out(self: psi4.core.Matrix) None

Prints the matrix to the output file

pseudoinverse(self: psi4.core.Matrix, condition: float, nremoved: int) psi4.core.Matrix

Computes the matrix which is the conditioned pseudoinverse of this matrix

remove_symmetry(self: psi4.core.Matrix, a: psi4.core.Matrix, transformer: psi4.core.Matrix) None

Remove symmetry from a matrix A with PetiteList::sotoao()

rms(self: psi4.core.Matrix) float

Returns the rms of this matrix

rotate_columns(self: psi4.core.Matrix, h: int, i: int, j: int, theta: float) None

Rotates columns i and j in irrep h by angle theta

rowdim(self: psi4.core.Matrix) psi4.core.Dimension

Returns the rows per irrep array

rows(self: psi4.core.Matrix, h: int = 0) int

Returns the rows in irrep h

save(*args, **kwargs)

Overloaded function.

  1. save(self: psi4.core.Matrix, filename: str, append: bool = True, saveLowerTriangle: bool = True, saveSubBlocks: bool = False) -> None

Saves the matrix in ASCII format to filename, as symmetry blocks or full matrix

  1. save(self: psi4.core.Matrix, psio: psi4.core.IO, filename: int, savetype: psi4.core.SaveType = <SaveType.LowerTriangle: 2>) -> None

Saves the matrix in ASCII format to filename, as symmetry blocks or full matrix

scale(self: psi4.core.Matrix, a: float) None

Scales the matrix by the floating point value a

scale_column(self: psi4.core.Matrix, h: int, n: int, a: float) None

Scales column n of irrep h by a

scale_row(self: psi4.core.Matrix, h: int, m: int, a: float) None

Scales row m of irrep h by a

schmidt(self: psi4.core.Matrix) None

Calls the libqt schmidt function

set(*args, **kwargs)

Overloaded function.

  1. set(self: psi4.core.Matrix, val: float) -> None

Sets every element of a matrix to val

  1. set(self: psi4.core.Matrix, m: int, n: int, val: float) -> None

Sets a single element of a matrix to val at row m, col n

  1. set(self: psi4.core.Matrix, h: int, m: int, n: int, val: float) -> None

Sets a single element of a matrix, subblock h, row m, col n, with value val

set_block(self: psi4.core.Matrix, rows: psi4.core.Slice, cols: psi4.core.Slice, block: psi4.core.Matrix) None

Set a matrix block

subtract(self: psi4.core.Matrix, arg0: psi4.core.Matrix) None

Substract a matrix from this matrix

sum_of_squares(self: psi4.core.Matrix) float

Returns the sum of the squares of this matrix

symmetrize_gradient(self: psi4.core.Matrix, mol: psi::Molecule) None

Symmetrizes a gradient-like matrix (N,3) using information from a given molecule

symmetry(self: psi4.core.Matrix) int

Returns the overall symmetry of the matrix

to_array(copy=True, dense=False)

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.]]
to_serial()

Converts an object with a .nph accessor to a serialized dictionary

Parameters:

self (Union[Matrix, Vector]) – Matrix or Vector instance.

Returns:

Serialized dictionary with keys:

  • shape

  • data : List[str]

  • type : {‘matrix’, ‘vector’}

Return type:

Dict[str, Any]

trace(self: psi4.core.Matrix) float

Returns the trace of the matrix

transform(*args, **kwargs)

Overloaded function.

  1. transform(self: psi4.core.Matrix, transformer: psi4.core.Matrix) -> None

Transform this matrix with transformer

  1. transform(self: psi4.core.Matrix, a: psi4.core.Matrix, transformer: psi4.core.Matrix) -> None

Transform A with transformer

transpose(self: psi4.core.Matrix) psi4.core.Matrix

Creates a new matrix that is the transpose of this matrix

transpose_this(self: psi4.core.Matrix) None

Transpose the matrix in-place

static triplet(A, B, C, transA, transB, transC)

Multiply three matrices together.

Deprecated since version 1.4: Use psi4.core.triplet() instead.

vector_dot(self: psi4.core.Matrix, rhs: psi4.core.Matrix) float

Returns the vector dot product of this with rhs

zero(self: psi4.core.Matrix) None

Zero all elements of the matrix

zero_diagonal(self: psi4.core.Matrix) None

Zero the diagonal of the matrix

zero_lower(self: psi4.core.Matrix) None

Zero the lower triangle

zero_upper(self: psi4.core.Matrix) None

Zero the upper triangle