mnt: changed spin_squared name to other name

[zerothi]

The correct name is a contamination of the spin states. This change adheres so that it is more correct.

@tfrederiksen @sofiasanz could you please review this name change?
I think this is more correct, no? You have it used in hubbard, but just wanted to clear it out.

• Tests added
• Documentation for functionality
• User visible changes (including notable bug fixes) are documented in CHANGELOG

[codecov]

Codecov Report

Attention: Patch coverage is 94.11765% with 2 lines in your changes are missing coverage. Please review.

Project coverage is 86.76%. Comparing base (2334b58) to head (e34dd38).

Files	Patch %	Lines
src/sisl/physics/electron.py	91.30%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #497      +/-   ##
==========================================
- Coverage   86.76%   86.76%   -0.01%     
==========================================
  Files         399      399              
  Lines       50548    50544       -4     
==========================================
- Hits        43860    43854       -6     
- Misses       6688     6690       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[zerothi]

Hmm, I stumbled upon this one: https://arxiv.org/pdf/1508.02058.pdf

There seems to be more terms that could be useful?

[tfrederiksen]

I agree to choose the standard name of spin_contamination. However, the returned quantity is not exactly the single number that some people may be used to. For instance, this is the typical spin contamination block reported by ORCA:

UHF SPIN CONTAMINATION
----------------------

Warning: in a DFT calculation there is little theoretical justification to
         calculate <S**2> as in Hartree-Fock theory. We will do it anyways
         but you should keep in mind that the values have only limited relevance

Expectation value of <S**2>     :     0.767859
Ideal value S*(S+1) for S=0.5   :     0.750000
Deviation                       :     0.017859

Anyways, as long as the documentation is clear what is calculated, I guess the user can figure things out from there.

[tfrederiksen]

Maybe one could have an optional keyword to take the calculation one step further to compute the three values above?

[zerothi]

Maybe one could have an optional keyword to take the calculation one step further to compute the three values above?

Yes, I think that perhaps it should default to all terms given in the article I reference, then options could be used to query them individually. However the current form returns all contamination values for a single state, whereas the article (and orca) seems to only return single numbers, what are your thoughts about that? Should we have a keyword for sum=true/false?

[tfrederiksen]

I think sum=True would be a reasonable default. While the state-resolved quantity may be of some relevance for expert users, I think the general idea of spin contamination is to characterize with a single number how the calculated many-electron state, i.e., the single Slater determinant in mean-field approaches, deviates from a true eigenstate of the S^2 operator. Hence, the sum over filled states would be natural.

Regarding the terms in your reference (which I didn't study), they are only relevant for noncollinear and spin-orbit calculations, right? I think what you already have is the "standard" expression for spin contamination (up to the exact S^2 value and N_beta).

[zerothi]

Thanks, yes it covers nc/soc, but also discusses the collinear term.

[zerothi]

I think sum=True would be a reasonable default. While the state-resolved quantity may be of some relevance for expert users, I think the general idea of spin contamination is to characterize with a single number how the calculated many-electron state, i.e., the single Slater determinant in mean-field approaches, deviates from a true eigenstate of the S^2 operator. Hence, the sum over filled states would be natural.

Regarding the terms in your reference (which I didn't study), they are only relevant for noncollinear and spin-orbit calculations, right? I think what you already have is the "standard" expression for spin contamination (up to the exact S^2 value and N_beta).

Could you remind me here, should sum=True sum everything, both, so sum(Sa) + sum(Sb)?
I will leave the rest for a later round.

[zerothi]

I think it was obvious once I looked into it, will now default to return the sum (sum(Sa)).