Installing

Use a conda environment

We highly recommend installing python in an isolated environment using conda (or its speedier, backward-compatible successor, mamba). In particular, we recommend the miniforge or mambaforge distributions of Python, which are lightweight distributions of conda that automatically activate the conda-forge channel for up-to-date scientific packages.

Note

If you are on a Windows machine, we recommend you install the Windows Subsystem for Linux (WSL) and set up your conda environments inside the WSL environment.

After installing conda / mamba, follow their instructions to create an environment. The steps should be similar to the following:

  1. Open your terminal (or “Anaconda prompt” or “Miniforge prompt” on Windows)

  2. Pick a name for your environment (note: you can create many environments if you want)

  3. type conda create -n <name-you-picked> python=3.10 (if you install miniforge) or mamba create -n <name-you-picked> python=3.10 (if you installed mambaforge) and press enter

  4. After the environment is installed, type conda activate <name-you-picked> / mamba activate <name-you-picked> and press enter

pip install

Once Python is installed and your environment is activated you can install pyEQL from PyPi by typing the following command:

pip install pyEQL

This should automatically pull in the required dependencies as well.

Important

If you are NOT using a conda environment, may have to run ‘pip3’ rather than ‘pip’. This will be the case if Python 2.x and Python 3.x are installed side-by-side on your system. You can tell if this is the case by typing the following command:

$ python --version
Python 2.7.12

This means Python 2.x is installed. If you run ‘pip install’ it will point to the Python 2.7 installation, but pyEQL only works on Python 3. So, try this:

$ python3 --version
Python 3.9.7

To get to Python 3.x, you have to type ‘python3’. In this case, you would run ‘pip3 install’

Warning

If you are using a Mac with an Apple M1, M2, etc. chip (i.e., Arm64 architecture), some features of pyEQL will be unavailable. Specifically, anything which depends on PHREEQC (e.g., the equilibrate method in the native engine and the entire phreeqc engine) will not work. This is because phreeqpython is currently not available for this platform. All other functions of pyEQL should work as expected.

Feel free to post your experiences or proposed solutions at https://github.com/KingsburyLab/pyEQL/issues/109

NOTE: Some users have reported being able to use phreeqpython functions by installing an x86 version of conda/miniconda. See the issue report for more details.

Other dependencies

pyEQL also requires the following packages:

  • pint - for automated unit conversion

  • pymatgen - used to interpret chemical formulas

  • iapws - used to calculate the properties of water

  • monty - used for saving and loading Solution objects to files

  • maggma - used by the internal property database

  • scipy

  • numpy

If you use pip to install pyEQL (recommended), they should be installed automatically.

Installing the development branch

If you want to use the bleeding edge version before it is released to PyPi instead of the latest stable release, you can substitute the following for the above ‘pip install’ command:

pip install git+https://github.com/KingsburyLab/pyEQL.git@main

Manually install via Git

Simply navigate to a directory of your choice on your computer and clone the repository by executing the following terminal command:

git clone https://github.com/KingsburyLab/pyEQL

Then install by executing:

pip install -e pyEQL

Note

You may have to run ‘pip3’ rather than ‘pip’. See the note in the pip install section.