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.

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

Adds a matrix to this matrix

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.

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

Backtransform this with transformer

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.

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

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.

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

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

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

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.

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

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.

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

Sets every element of a matrix to val

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

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.

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

Transform this matrix with transformer

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