Add Hermitian symmetry support to public API

[RTChou67]

Export the Hermitian, anti-Hermitian, and conjugate-transpose constants from dbcsr_api.
Define and validate supported scalar type and symmetry combinations: real N/S/A and complex N/H/K.
Clarify dbcsr_dot semantics: bilinear by default, with optional conjugate_a=.TRUE. for the Frobenius inner product. Account for conjugation and sign when reducing compressed H/K matrices.
Add H/K coverage for creation, copying, transpose, filtering, multiplication, norms, dot products, and binary I/O.
Update the API source comments used to generate procedure documentation.

This changes the public API and requires a major release according to CONTRIBUTING.md.

[oschuett]

Why do you need this?

In past we used complex DBCSR matrices only in a few places until I managed to remove the dependency entirely.

[RTChou67]

The motivation is mainly about the k-point code in CP2K, where complex hermitian matrices such as the Hamiltonian and overlap matrices are represented as two real DBSCR matrices: a symmetric real part and an antisymmetric imaginary part. Since DBCSR already has Hermitian/anti-Hermitian matrix types internally, I would like to make this functionality available through the public API and evaluate whether it can simplify these parts of the CP2K k-point code.

[oschuett]

Sorry, I didn't realize this PR was opened on the DBCSR repo. Then I'll leave the review to others.

Just note that, we'll not be re-introducing complex DBCSR matrices to CP2K. We're currently in the process of migrating from DBCSR to DBM. And for DBM I made the conscious decision to only support real matrices to keep complexity low.

So, if you really need complex sparse matrices in CP2K, please build yourself a small helper library that encapsulates two real matrices.

[Growl1234]

I also don't see much added value for this change.

[RTChou67]

Sorry, I didn't realize this PR was opened on the DBCSR repo. Then I'll leave the review to others.

Just note that, we'll not be re-introducing complex DBCSR matrices to CP2K. We're currently in the process of migrating from DBCSR to DBM. And for DBM I made the conscious decision to only support real matrices to keep complexity low.

So, if you really need complex sparse matrices in CP2K, please build yourself a small helper library that encapsulates two real matrices.

Thanks for pointing out. Then I suppose this change is indeed not so useful.