// this matrix_h05.h file has the matrix eigenvalue, eignevector, etc. for symmetric matrices
// each of the routines is complex-aware.
//		that is, it will operate upon the real-isomorph of a Hermitian matrix.




//  Jacobi algorithm for the eigenvalue-eigenvector pairs.
//	will error-out with a return-code of 64 if the matrix is neither symmetric nor of at least size two.
//  will return an error-code of 128; if the algorithm fails to converge.
//	the array is the input symmetric array to be factored.  the array becomes the diagonal of eigenvalues.
//		the bra is the output set of horizontal eigenvectors, which correspond to the eigenvalues.
//		the bra matrix is a proper ortho-normal matrix.
MATRIX_DLL_API
int matrix_insitu_Jacobi(MAT *bra, MAT *array, MAT *scratch);


//  factors a symmetric 1x1 matrix array into a bra, a diag, and an implied ket.
//  will error-out with a return of 64 if the matrix is larger or not symmetric.
MATRIX_DLL_API
int matrix_trivial_factor(MAT *array, MAT *bra, MAT *diag);


//  factors a Hermitian 1x1 complex (2x2 real isomorph) matrix array into
//		a bra, a diag, and an implied ket.
//  will error-out with a return of 64 if the matrix is larger or not Hermitian.
MATRIX_DLL_API
int matrix_trivial_factor_cmplx(MAT *array, MAT *bra, MAT *diag);


//   WARNING:  does not check anything.
//	 reconstructs the right-half of a complex matrix.  It is a no-op for a real matrix.
MATRIX_DLL_API
void matrix_right_half_complex(MAT *array);


//   WARNING:  does not check anything.
//	 reconstructs the bottom-half of a complex matrix.  It is a no-op for a real matrix.
MATRIX_DLL_API
void matrix_bottom_half_complex(MAT *array);

	
//	sorts the elements of the diagonal matrix in decresing order of absolute-values and permutes the bra accordingly.
//	such that :  bra_in diag_in bra_intr = bra diag bratr.
//	purpose:  to be employed as the penultimate step of the factorization of a symmetric-matrix.
MATRIX_DLL_API
int matrix_insitu_sort(MAT *bra, MAT *diag);


//  factors a symmetric array into its bra, diag, and ket.
MATRIX_DLL_API
int matrix_factor_symmetric(MAT *array, MAT *bra, MAT *diag, MAT *ket, unsigned long sort, MAT *scratch);


//	the following four routines are variations upon a common theme:

//	factors the positive symmetric matrix array_in into its bra, diag, and ket.
//		optionally, sorts the eigenvalues.
//	then, computes the square-root and its inverse, of the array_in.
//	if the matrix array_in is not positive symmetric, will error-out with a return of 16.
MATRIX_DLL_API
int matrix_square_root(MAT *array_in, unsigned long sort, MAT *bra, MAT *diag, MAT *ket,
					MAT *array_sqrt, MAT *array_sqrt_inv, MAT *scratch_1, MAT *scratch_2);


//	computes the square-root of the positive-symmetric array_in.
//		optionally, sorts the eigenvalues.
//	if the matrix array_in is not positive symmetric, will error-out with a return of 16.
MATRIX_DLL_API
int	matrix_square_root0(MAT *array_in, unsigned long sort, MAT *array_sqrt, MAT *scratch_1,
						MAT *scratch_2, MAT *scratch_3, MAT *scratch_4);


//	computes the inverse of the square-root of the positive-symmetric array_in.
//		optionally, sorts the eigenvalues.
//	if the matrix array_in is not positive symmetric, will error-out with a return of 16.
MATRIX_DLL_API
int	matrix_square_root1(MAT *array_in, unsigned long sort, MAT *array_sqrt_inv, MAT *scratch_1,
						MAT *scratch_2, MAT *scratch_3, MAT *scratch_4, MAT *scratch_5);


//	multiplies the inverse of the square-root of the positive-symmetric array_a by
//	the square-root of the positive-symmetric array_b.
//		optionally, sorts the eigenvalues.
//	if either array_a or array_b is not positive symmetric, will error-out with a return of 16.
MATRIX_DLL_API
int	matrix_square_root2(MAT *array_a, MAT *array_b, unsigned long sort, MAT *array,
						MAT *scratch_1, MAT *scratch_2, MAT *scratch_3, MAT *scratch_4,
						MAT *scratch_5, MAT *scratch_6);



//  copyright (c) 2003,4 by R.I. 'Scibor-Marchocki.  last modified Monday 26-th April 2004.

// eof