Phreeqc wrapper

[vineetbansal]

WIP.

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

[codecov]

Codecov Report

❌ Patch coverage is 56.25000% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.46%. Comparing base (c46f935) to head (5540bd1).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
src/pyEQL/engines.py	53.33%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #291      +/-   ##
==========================================
- Coverage   84.89%   84.46%   -0.44%     
==========================================
  Files           9        9              
  Lines        1476     1493      +17     
  Branches      257      258       +1     
==========================================
+ Hits         1253     1261       +8     
- Misses        193      201       +8     
- Partials       30       31       +1     

☔ 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.

[vineetbansal]

@rkingsbury - this is ready to be reviewed from my end. The wrapper is a work in progress of course, and will remain so for a few iterations, but since there is quite a bit of mechanical stuff and glue code to review here, we can do this in stages - merge now with the assurance that nothing breaks with this PR, and develop the wrapper in functionality over the next few PRs. This would be my recommendation. Or we can do a single PR for a "good-enough" phreeqc wrapper for pyEQL purposes.

Here's what's happening:

• The phreeqc wrapper package is called pyEQL-phreeqc.
• pyEQL-phreeqc code is part of this repo (in src/pyEQL/pyEQL-phreeqc) but gets built (and will eventually get uploaded to pypi) as its own package called pyEQL-phreeqc, independent of pyEQL.
• pyEQL-phreeqc would remain a way for client code to interact with phreeqc directly, whether or not they use pyEQL:

from pyEQL_phreeqc import Phreeqc

phreeqc = Phreeqc("phreeqc.dat")
phreeqc.run_string("...")
assert phreeqc.get_component_count() == 5
assert phreeqc.get_log_string() == "..."

• pyEQL will be able to use pyEQL-phreeqc internally as a supported engine (if installed using the phreeqc extra, and called using Solution(volume="2 L", engine="pyeql").

• None of the engine code is actually written so far, and raises a NotImplementedError. This engine is not being tested by pytest.

• Tests for pyEQL-phreeqc are in the tests/phreeqc folder.

Rationale for this two-packages-in-a-repo:

• Since pyEQL-phreeqc results in a compiled wheel, users on exotic platforms (or platforms that we haven't tested for), will still be able to use pyEQL using its sdist or its pure-python wheel. pyEQL-phreeqc's sdist will still be available of course, but entails compilation on the user's machine in these cases.
• This should allow us to merge this PR sooner and get going with collaborative development without disrupting any existing behavior of pyEQL drastically.

That said, tests for pyEQL-phreeqc currently pass on Win/Mac/Linux and will continue to do so as we tweak it, so users on all these platforms are covered. Given that this is the case, it is possible to remove this dual-package distinction and just have pyEQL generate platform specific wheels. Users will just have to pip install pyEQL.

I suppose the choice depends on whether pyEQL is still a generally useful package without all the phreeqc integration (and will continue to be) or whether we see it as tightly integrated with phreeqc.

Some other points:

• Versioning of pyEQL-phreeqc is independent of that of pyEQL (and just comes from its pyproject.toml). If the two are going to remain separate packages, then their versions should be bumped independently anyway. We can reserve the git-tag approach for pyEQL while manually bumping up pyEQL-phreeqc when we need to.
• The CI runs the tests with pyEQL-phreeqc installed from the repo itself. This should aid in faster development as we're brainstorming how we want to integrate with phreeqc in these PRs.
• I've modified the CI workflow to build both packages and release both on pypi. However, the trigger is still the same - the marketplace action rymndhng/release-on-push-action@v0.28.0. I'm not 100% sure what it does, but if its some variant of "release-on-git-tag" approach, then we'll just have to be careful that we do tag any commits where we bump up the version of pyEQL-phreeqc. We can refine this behavior over time.
• I realize that the naming of packages may not be ideal here. We can change this.

[rkingsbury]

Thanks for this @vineetbansal . I appreciate the detailed rationale you provided to help me understand what's happening here!

I'm happy to merge now. Here are a list of items / comments I want to follow up on as we continue to refine the new wrapper:

1. Will it generally be necessary to include the entire contents of IPHREEQC in our repo, or is that just a convenience for the time being? I'm thinking about the implications for future updates as new versions of IPHREEQC come out.
2. I am 99+% sure that IPHREEQC is public domain code and hence should be no problem to include in our repo, which is LGPL licensed, but I want to verify this. I'm having trouble finding an explicit license declaration anywhere on the USGS websites.
3. Great point re: source vs. binary wheels. I had never thought of that. There is definitely value in pyEQL without the PHREEQC wrapper
4. I like keeping both pyEQL and pyEQL-phreeqc in the same repo to facilitate development and maintenance (one fewer repo to maintain is a good thing), even if we release the packages separately
5. Re: package name - I'm not sure yet what the ideal strategy is; I think pyEQL-phreeqc is a very sensible place to start
6. rymndhng/release-on-push-action@v0.28.0 is just an action I copied from another repo that enables "release on tag". I'd love to talk to you about a better or cleaner way to accomplish this (perhaps using an "official" github action instead)
7. Let's circle back to how the engine kwarg will activate the new wrapper. My intention is for this new wrapper to completely replace phreeqpython and I don't plan to maintain that support for very long. So I'd like to see your work become the default in the native and phreeqc engines, but we should also have a transitional period over a few releases where a separate engine argument is used to activate your wrapper.