alchemlyb: the simple alchemistry library

alchemlyb is a library for doing alchemical free energy calculations more easily.

It seeks to provide flexible building blocks covering functions for parsing data from formats common to existing MD engines, subsampling these data, fitting these data with an estimator to obtain free energies, and plotting the results.

These functions are simple in usage and pure in scope, and can be chained together to build customized analyses of data. General and robust workflows following best practices are also provided, which can be used as reference implementations and examples.

alchemlyb seeks to be as boring and simple as possible to enable more complex work. Its components allow work at all scales, from use on small systems using a single workstation to larger datasets that require distributed computing using libraries such as dask.

The library is under active development. However, it is used by multiple groups in a production environment. We use semantic versioning to indicate clearly what kind of changes you may expect between releases. Within any major release (1.x, 2.x, …), the API is stable and is guaranteed to remain backwards-compatible.

Note

The current 2.x release of alchemlyb only supports pymbar releases >= 4.0. (Previous 1.x releases only support pymbar >= 3.0.5, <4.) See discussion #205 and issue #207.

See Getting involved for how to get in touch if you have questions or find problems.

Core philosophy

With its goal to remain simple to use, alchemlyb’s design philosophy follows the following points:

  1. Use functions when possible, classes only when necessary (or for estimators, see (2)).

  2. For estimators, mimic the scikit-learn API as much as possible.

  3. Aim for a consistent interface throughout, e.g. all parsers take similar inputs and yield a common set of outputs.

For more details, see the Roadmap.

Development model

This is an open-source project, the hope of which is to produce a library with which the community is happy. To enable this, the library is a community effort. Development is done in the open on GitHub.

Software engineering best-practices are used throughout, including continuous integration testing via Github Actions, up-to-date documentation, and regular releases.

Note

With release 0.5.0, the alchemlyb project adopted NEP 29 to determine which versions of Python and NumPy will be supported. When we release a new major or minor version, alchemlyb will support at least all minor versions of Python introduced and released in the prior 42 months from the release date with a minimum of 2 minor versions of Python, and all minor versions of NumPy released in the prior 24 months from the anticipated release date with a minimum of 3 minor versions of NumPy.

The pandas package (one of our other primary dependencies) also follows NEP 29 so this support policy will make it easier to maintain alchemlyb in the future.

Getting involved

Contributions of all kinds are very welcome.

If you have questions or want to discuss alchemlyb please post in the alchemlyb Discussions.

If you have bug reports or feature requests then please get in touch with us through the Issue Tracker.

We also welcome code contributions: have a look at our Developer Guide. Open an issue with the proposed fix or change in the Issue Tracker and submit a pull request against the alchemistry/alchemlyb GitHub repository.

For Developers