Add AlchemicalArchive

[ianmkenney]

This PR introduced the AlchemicalArchive for serializing an AlchemicalNetwork along with it's transformation results. Closes #323.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.82%. Comparing base (25c818a) to head (fe1033c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #687      +/-   ##
==========================================
+ Coverage   98.79%   98.82%   +0.02%     
==========================================
  Files          40       41       +1     
  Lines        2498     2555      +57     
==========================================
+ Hits         2468     2525      +57     
  Misses         30       30              

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

[ianmkenney]

Commit 1772aa6 replaces the use of dataclasses with subclassing GufeTokenizable. While the simplicity from dataclasses is appealing, the performance benefits from using the GufeTokenizable subclass leaves little room for debate.

Implementation	compression algorithm	size (MB)	to_json (ms)	from_json, string (ms)
dataclass	None	222	113000	~8500
dataclass	zstandard	117	--	--
Tokenizable	None	5	0.0014	0.0013

If anyone has thoughts on this, please share!

[jthorton]

Great job @ianmkenney. Is there any substantial benefit to adding compression to the Tokenizable implementation as well? If these objects are intended for long term storage, minimising the footprint at the cost of inspectability might be okay if there is a large difference. Or what about a msgpack option?

[ianmkenney]

@jthorton at least for the network I've tested, compressing with zstandard reduced the size to about 1 MB. MessagePack would probably be a good option. From what I see currently implemented, compression needs to be done manually. We would want to add a compress keyword arg in to_msgpack for ease of use.

edit: I think as protocols start producing and collecting more artifacts, compression will be much more valuable and should probably be the default.

[ianmkenney]

A quick test using MessagePack, with the new compression kwarg.

from gufe.archival import AlchemicalArchive
from gufe.compression import zst_compress, zst_decompress

from sys import getsizeof

archive = AlchemicalArchive.from_json(file="archive.json")

payload = archive.to_msgpack(compress=False)
print("msgpack, uncompressed (bytes):", getsizeof(payload))

payload = archive.to_msgpack(compress=True)
print("msgpack, compressed (bytes):", getsizeof(payload))

payload = archive.to_json()
print("JSON, uncompressed (bytes):", getsizeof(payload))
print("JSON, compressed (bytes):", getsizeof(zst_compress(payload.encode())))

msgpack, uncompressed (bytes): 2494841
msgpack, compressed (bytes): 762852
JSON, uncompressed (bytes): 5544757
JSON, compressed (bytes): 1032531

[ianmkenney]

pre-commit.ci autofix

[github-actions]

No API break detected ✅