ThermoEngine is the central library in the ENKI ecosystem for thermodynamic modeling of geologic systems, providing a python framework for using, comparing, and developing thermodynamic models. ThermoEngine provides access to the MELTS family of models, as well as providing a generic interface to other thermodynamics database models to facilitate easy comparison. ThermoEngine uses a simple Python interface for accessing phase properties and running equilibrium calculations, with lower level routines implemented within fast C libraries (which are pre-compiled for all standard architectures and distributed through PyPI, see How to use below).
ThermoEngineLite is a work in progress and more abilities, including a User Guide, will be released in the coming months. ThermoEngineLite will become ThermoEngine 2.0 and this repository provides early access to the upgrades that make ThermoEngine easy to install and more performant. To access the legacy ThermoEngine code (the version running on the cloud computer server) see the original ThermoEngine Repo.
This software is released under the GNU Affero General Public License (GNU AGPLv3). This means you are free to use the software and build upon it (through importing thermoengine into your own projects), but we ask that you please give credit via citations for all of the hard work of the ENKI developer team. If you modify the ThermoEngine source code in any way, or if the software is provided via an online interface or cloud server, the license requires that the modified source code (in its entirety) must be available through the same portal. The ENKI developer team is highly collaborative and interested in serving the needs of our community, so please consider working together with us to ensure that your work is distributed to the community as well. We welcome new collaborators, please take a look at our Contributor Guidelines below to find out how you can get involved!
For more information on the ENKI project see enki-portal.org.
To install the latest release of ThermoEngineLite on your own computer you can install from PyPI in a conda environment running python 3.10:
pip install thermoengine
Note that this version is a placeholder version, ready for a stable release. To find out more join our user group.
To see example calculations from the ENKI family of tools, and run lite-weight calculations in the cloud, visit our Examples Gallery.
While we are working towards releasing v2.0.0, you may want to install the latest developer version. These versions can be installed using pip and the GitLab package registry, requiring a different syntax:
pip install thermoengine --index-url https://gitlab.com/api/v4/projects/64726257/packages/pypi/simple
To update an existing installation of the developer version use:
pip install thermoengine --index-url https://gitlab.com/api/v4/projects/64726257/packages/pypi/simple --upgrade
We recommend using conda or miniconda to manage your python environments. Once you have either one installed, create an environment for thermoengine by running (in a terminal):
conda create -n "thermoengine" python==3.10 ipython
then activate the environment:
conda activate thermoengine
then install thermoengine as described above.
This is the version available on PyPI (i.e. pip) and should be used by most users. The next Stable Release will be v2.0.0. We are working towards the first stable release.
The source code for this version will be found on a branch named (for example) v2.0.x.
Before we release a new version of ThermoEngine, it will go through a final testing period as a "release candidate". Built versions can be installed from the Gitlab package registry (see directions above). The next release candidate will be v2.0.0.rc1.
The source code for this version will be found on a branch named (for example) v2.0.x.
While we are adding new features in preparation for the next stable release, we periodically build preview versions so that developers can get early access to new features and do preliminary testing. The built versions can be installed from the Gitlab package registry (see directions above). The next developer version will be v2.0.0.dev9.
The source code for this version will be found on the main branch.
While we are preparing the next developer version release, we accumulate changes in the staging branch (currently named develop) to allow testing and further development. These changes are available only in versions of the code built by the user in the VSCode devcontainer. There is no guarantee that this version will be functional at any given time. We try to push these updates to the main branch (and release a developer version) as frequently as possible.
Information about how to join our mailing list and our Zulip chat portal.
We regularly run workshops (both in-person and virtually), which will be announced on our community portals and the ENKI website.
Additionally, please see our Code of Conduct for expectations on how we can respectfully engage with all current and potential future members of our community and the broader geoscience community as a whole.
Coming soon...
You will require a compiler (probably clang) to be installed in order to compile coder generated code. You may also require the aqueous module to be available to the linker at compile time. We recommend using the preconfigured VSCode development environment, defined in the .devcontainer directory.
You can build ThermoEngine directly from source instead of using the precompiled binaries distributed on PyPI. We aim to provide wheels for all architectures supported by SciPy, but if your architecture is not supported you will need to build both SciPy and ThermoEngine from source. GSL must be installed on your system and we recommend compiling with clang.
Makefiles automate the building of the ThermoEngine libraries, and the quickest way to build and install the entire package is to run:
make devinstall
from the top level directory.
We provide a pre-configured VSCode development environment, defined in the .devcontainer directory.
To run standard tests run pytest in the thermoengine directory. All tests should pass or xfail. To test development features you can run make devtests in the top level directory.