Installation

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’

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 (and potentially unstable!) development branch instead of the latest stable release, you can substitute the following for the above ‘pip install’ command:

pip install git+https://github.com/rkingsbury/pyEQL.git@develop

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/rkingsbury/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.