Description

This is something I have been working on as part of the upcoming Psi4-GauXC interface; but it seems to be of interest for other use cases, so I will be adding it here as a separate PR.

What this change does, is it adds two new member functions to the Psi4::Matrix class, eigen_map() and eigen_maps() . Both of these functions serve the same purpose - take the Psi4 matrix in question and return a representation of said matrix through Eigen's Map objects. The Eigen::Map class acts the same way as a normal Eigen::Matrix object, but uses an external array as its data buffer rather than an internal data buffer. The eigen_map() and eigen_maps() functions, then, return Eigen matrix-like objects that directly link with the Psi4 matrix data buffer of the Psi4 matrix for which the function was called. This provides an efficient fashion by which to utilize Psi4 matrices in contexts which require Eigen constructs, with no data deepcopying or Eigen-to-Psi4 back-conversions required.

There is a key difference between the two functions. eigen_map() assumes that the matrix has a single irrep, and returns a single Eigen::Map object. eigen_maps() , on the other hand, is used for matrices with multiple irreps, and returns a std::vector of Eigen::Map objects, each Map in the vector corresponding to one irrep of the Psi4 matrix.

User API & Changelog headlines

• Adds two new functions, eigen_map() and eigen_maps(), usable in Psi4 plugins and downstream programs, that return a formulation of the calling Psi::Matrix object, that is usable in contexts where Eigen::Matrix objects are required/desired.

Dev notes & details

• Adds two new member functions to Psi4::Matrix, eigen_map() and eigen_maps(), that return Eigen::Map representations of the Psi4 matrix object.

Questions

• N/A

Notes

• I did look into forward declaring the necessary Eigen classes, but forward declaring Eigen::Map turns out to be a bit ugly, as it is a class template that, to forward declare, ends up requiring forward declarations for other Eigen classes and enums (such as Stride and AlignmentType) that aren't specifically necessary for the Psi4 use case. Therefore, I have skipped forward declarations here.
• I can confirm the correctness of the eigen_map() function, as I have implemented these PR changes into my Psi-GauXC interface, wherein eigen_map() replaces the original formulation I used for the equivalent result. eigen_maps(), however, is currently untested as there is no current use case for it yet, and should thus be considered experimental.

Checklist

• Tests added for any new features
• All or relevant fraction of full tests run

Status

• Ready for review
• Ready for merge