Feature: Saturation Index Retrieval and Plotting

[SuixiongTay]

Summary

This PR adds support for querying saturation indices (SI) through a new get_saturation_index method on the Solution class. The method retrieves SI from the active backend engine. This PR addresses #58.

• Added a def phases(self) function in solution.py to access the PHREEQC wrapper to retrieve the equilibrium phase data collected in pyEQL/phreeqc/core.py
• Implemented the get_saturation_index so it can retrieve saturation index (SI) keys and values from the backend engine
• Added get_plot feature within the get_saturation_index(get_plot=True) method to visualize the SI of solid and gas phases using plotly based on the phases returned from the defined engine.

Below is an example for seawater:

s1 = Solution.from_preset("seawater")
s1.equilibrate()
si = s1.get_saturation_index(get_plot=True)

Below is another example for a custom engine and solution:

custom_eos = PhreeqcEOS(phreeqc_db="vitens.dat")
s1 = Solution({'Na+': '10 mol/L', 'K+': '10 mol/L', 'Cl-': '10 mol/L'}, pH=9, temperature= '25 degC', engine=custom_eos)
si = s1.get_saturation_index(get_plot=True)

Todos

• Compile Ksp values across the commonly-encountered scalants, defined under pyEQL_db.dat. (Suggestions?)
• Additional pytest

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.42%. Comparing base (7c49fa5) to head (992bb32).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #395      +/-   ##
==========================================
+ Coverage   86.23%   86.42%   +0.19%     
==========================================
  Files          14       14              
  Lines        1853     1879      +26     
  Branches      323      326       +3     
==========================================
+ Hits         1598     1624      +26     
  Misses        209      209              
  Partials       46       46              

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

🚀 New features to boost your workflow:

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

[YitongPan1]

Hi Shaun, I updated some tests for the saturation index, please let me know if there is anything not covered yet, thank you!

[SuixiongTay]

Thanks Yitong, the coverage looks quite comprehensive.

I noticed the test is failing for test_multi_mineral_si because carbonate species are missing. Adding that in should solve the problem. Thanks!

[rkingsbury]

Thanks both! This looks pretty good. See small comments.

[rkingsbury]

Looking good; apologies I missed some of the comments from a few weeks ago. I think it just needs:

1. Some clarification about how the SI is calculated in the docstring, and
2. some edits to the unit tests

And will be good to go.

[rkingsbury]

Thanks @SuixiongTay ! Nice job with the additional documentation in the docstring. I've always felt that adding extra explanation makes a huge difference for making a package usable and understandable.

[rkingsbury]

@SuixiongTay looks like we're still failing due to the ** error