# 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 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. 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 the lower triangle to the upper triangle 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). Converts serialized data to the correct Psi4 data type 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. 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)

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

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.

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)

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

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)

Creates exact copy of the matrix and returns it

coldim(self: psi4.core.Matrix)

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:
Returns:

Returns the given (self) Psi4 object.

Return type:

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

Parameters:
Return type:
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)

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)

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

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

Loads a matrix from an ASCII file in MPQC format

nirrep(self: psi4.core.Matrix) int

Returns the number of irreps

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

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:
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:
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)

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)

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)

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)

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)

Returns the rows per irrep array

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

Returns the rows in irrep h

save(*args, **kwargs)

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)

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)

Returns the sum of the squares of this matrix

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:
Returns:

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

Return type:

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)

Returns the trace of the matrix

transform(*args, **kwargs)

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)

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)

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