Mutual Information I(𝒶, 𝒷) and improving doctests/documentation in `entanglement.jl`

[Fe-r-oz]

This PR aims to introduce Mutual Information I(A,B) along with improving the doctests and documentation in the entanglement.jl .

In the future, if you like, it would be better to have a entanglement introduced in the manual of either "algebra" or upcoming "circuit simulation" manual.

In the papers, there were many graphs, I think based on entanglement entropy that could be reproduced in a tutorial fashion. Hopefully, this sounds interesting. .... If you want to submit an unfinished piece of work in order to get comments and discuss, please mark the pull request as a draft and ping the repository maintainer.

Please address only one topic or issue per pull request! Many small PRs are much easier to review and merge than one large PR.

Before merging, all changes and new functionality should be marked in the CHANGELOG file, but feel free to just leave your CHANGELOG notes in the PR description, to avoid merge conflicts with other requests modifying that file. The maintainer will add these CHANGELOG notes for you if you do so.

Before considering your pull request ready for review and merging make sure that all of the following are completed (please keep the clecklist as part of your PR):

• [x] The code is properly formatted and commented.
• [x] Substantial new functionality is documented within the docs.
• [x] All new functionality is tested.
• [x] All of the automated tests on github pass.

If possible, keep your git history not too wild (rebase and squash commits, keep commits small and semantically separated) so that review is easier.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 85.71429% with 3 lines in your changes missing coverage. Please review.

Project coverage is 83.47%. Comparing base (0035c32) to head (92c96ec). Report is 6 commits behind head on master.

Files with missing lines	Patch %	Lines
src/entanglement.jl	85.71%	3 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #338      +/-   ##
==========================================
- Coverage   83.48%   83.47%   -0.02%     
==========================================
  Files          72       72              
  Lines        4802     4834      +32     
==========================================
+ Hits         4009     4035      +26     
- Misses        793      799       +6     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Fe-r-oz]

Please help review this PR, thank you!

My apologies for the delay in adding code review suggestions. I had initially planned to work on the generalized code paper for some time, but I got caught up in them as they seemed quite exciting to read.

Thank you so much for your helpful suggestions! I especially found the suggestion to add QuantumOpticsBase tests in https://github.com/QuantumSavory/QuantumClifford.jl/pull/338#discussion_r1894183567 very helpful and wonderful! I have reduced the code repetition that I did before (my bad) and also added the QuantumOpticsBase tests. I hope that the PR is now polished thanks to your helpful codereview suggestions!

There is now warning that using QOpticsBase.entanglement_entropy conflicts withQC.entanglement_entropy 😅 in the tests!

[Fe-r-oz]

why did the test fail to catch the mistake with union of ranges with a large gap between them? Is something missing from the tests

Thank you so much for your insights! I’ve fixed an issue where the tests weren’t properly checking for large gaps in the system. The clipped gauge now ensures stabilizers have well-defined left/right endpoints, and the entanglement entropy calculation now correctly errors when non-contiguous regions (e.g., subsystem_rangeA = 1:2, subsystem_rangeB = 5:6) are provided. Additionally, I addressed the out-of-memory errors by using more moderate system sizes, as ket{} becomes computationally expensive for larger systems. The previous implementation was faulty. My bad 🙏🏼