Enable retrieving alkalinity from phreeqc2026 engine

[jjstickel]

Summary

Major changes:

• creates infrastructure for Solution.engine.get_alkalinity()
• retrieve alkalinity for the phreeqc2026 engine
• use the engine's alkalinity, if available; otherwise fall-back to alkalinity calculated within pyEQL class

Todos

• review overall approach
• determine whether the changed test conditions are generally appropriate
• also fix pyEQL's alkalinity calculation(?) see alkalinity of seawater is too high for phreeqc engines #458

Checklist

• Google format doc strings added.
• Code linted with ruff. (For guidance in fixing rule violates, see rule list)
• Type annotations included. Check with mypy.
• Tests added for new features/fixes.
• I have run the tests locally and they passed.

Tip: Install pre-commit hooks to auto-check types and linting before every commit:

pip install -U pre-commit
pre-commit install

[jjstickel]

Disclosure: I used Claude to help, but the changes are few and make sense to me.

Sorry about lumping removal of docs/examples/.ipynb_checkpoints in with this PR. I can figure out how to unroll that if the PR is invited to proceed.

[rkingsbury]

Thanks very much @jjstickel ; this is a helpful contribution! I'd like to proceed but with a few structural changes:

1. If not too much trouble, can you split the .gitignore changes into another PR? That is a very helpful change; I'd just prefer to keep it separate
2. The changes to expose ALK to the underlying PHREEQC solution (pyEQL/phreeqc/core.py and solution.py) are very helpful; I'm happy with those as-is
3. I'm not (yet) ready to make get_alkalinity an engine method, so can you please revert the changes in pyEQL/engines.py and pyEQL/solution.py? In general, I we try to use engine-specific methods only for those quantities that do not have an unambiguous definition, and rely on pyEQL.Solution native methods for everything else.

Regarding 3 - you have highlighted an important discrepancy between the pyEQL.Solution alkalinity and the underlying PHREEQC one which I want to instead treat as a bug in get_alkalinity. We recently implemented the weak acid-base definition of alkalinity (see #299 and #398 ) and perhaps that introduced a bug we weren't aware of. OR perhaps it isn't appropriate to rely on the Stumm and Morgan definition as the default (which is our current approach). Maybe it's more appropriate to use the proton condition as default.

I welcome additional thoughts!

[jjstickel]

Thanks for the feedback. I'll work on these as I have time (likely later this week or next week).

[rkingsbury]

FYI, I (actually Claude Code) took care of the .gitignore issue in #460 and I updated your branch here, so that part is all done.

[jjstickel]

3. I'm not (yet) ready to make get_alkalinity an engine method, so can you please revert the changes in pyEQL/engines.py and pyEQL/solution.py? In general, I we try to use engine-specific methods only for those quantities that do not have an unambiguous definition, and rely on pyEQL.Solution native methods for everything else.

I added a keyword argument to select between returning the alkalinity calculated by the engine vs. by pyEQL, and set it to be pyEQL by default.

I work with geochemists who have been using PHREEQC for years and trust it a great deal. It is, and will continue to be, necessary for me in my work to report the alkalinity that PHREEQC calculates. Also, from the current bug in alkalinity, it seems that alkalinity calculations are not always straightforward, and so having a feature to calculate it a couple different ways could be useful. (I am not a geochemist, and so I am not able to suggest how to improve pyEQL's alkalinity calculation without performing some literature research).

Does the keyword approach work for you? If this all gets sorted and everyone is convinced that pyEQL is doing the correct calculation [1], then the keyword argument could be removed in the future.

[1] If the "correct" alkalinity calculation ends up being different from PHREEQC, even by a small fraction, it would be important to document why the calculations are different.