Installation

Install from conda-forge

Recommended approach!

New environment:

mamba create -n isofit_env -c conda-forge isofit
mamba activate isofit_env

or

conda create -n isofit_env -c conda-forge isofit
conda activate isofit_env

Within an existing environment:

mamba install -c conda-forge isofit

or

conda install -c conda-forge isofit

Install with pip

Note

The commands below use $ pip, however $ python -m pip or is often a safer choice. It is possible for the $ pip executable to point to a different version of Python than the $ python executable. Using $ python -m pip at least ensures that the package is installed against the Python interpreter in use. The issue is further compounded on systems that also have $ python3 and $ pip3 executables, or executables for specific versions of Python like $ python3.11 and $ pip3.11.

ISOFIT can be installed from the Python Package Index with:

$ pip install isofit

In order to support a wide variety of environments, ISOFIT does not overly constrain its dependencies, however this means that in some cases pip can take a very long time to resolve ISOFIT’s dependency tree. Some users may need to provide constraints for specific packages, or install ISOFIT last. pip also supports installing from a remote git repository – this installs against the main branch:

$ pip install "git+https://github.com/isofit/isofit.git@main"

Install from github

git clone https://github.com/isofit/isofit
mamba env create -f isofit/recipe/environment_isofit_basic.yml
mamba activate isofit_env
pip install -e ./isofit

Downloading Extra Files

Once ISOFIT is installed, the CLI provides an easy way to download additional files that may be useful. These can be acquired via the isofit download command, and the current list of downloads we support is available via isofit download –help.

> _NOTE:_ The default location for downloading extra files will be the isofit.root path, which is the installation path of the package. This path may not be writeable. In these cases, use the –output [path] flag to control where the downloads will occur. If the output path is different than the default, many of the provided configuration files may not work.

Setting environment variables

Depending on the selected RTM, specific environment variables pointing to the RTM’s base directory have to be set prior to running ISOFIT. In the following, general instructions on how to set these variables on MacOS, Linux and Windows are provided.

MacOS

  • Most MacOS systems load environment variables from the user’s .bash_profile configuration file. Open this file with your preferred text editor, such as vim:

vim ~/.bash_profile

  • Add this line to your .bash_profile:

export VARIABLE_NAME=DIRECTORY (use your actual path)

  • Save your changes and run:

source ~/.bash_profile

Linux

  • Most Linux profiles use either bash or csh/tcsh shells. These shells load environment variables from the user’s .bashrc or .cshrc configuration files.

  • (BASH) Add this parameter to the .bashrc (see MacOS description):

export VARIABLE_NAME=DIRECTORY (use your actual path)

  • (T/CSH) Add this parameter to the .cshrc (see MacOS description):

setenv VARIABLE_NAME=DIRECTORY (use your actual path)

Windows

  • Using a command prompt, type one of the following:

setx /M VARIABLE_NAME "DIRECTORY" (use your actual path)

setx VARIABLE_NAME "DIRECTORY" (use your actual path)

Quick Start using MODTRAN 6.0

This quick start presumes that you have an installation of the MODTRAN 6.0 radiative transfer model. This is the preferred radiative transfer option if available, though we have also included interfaces to the open source LibRadTran RT code as well as to neural network emulators.

  1. Create an environment variable MODTRAN_DIR pointing to the base MODTRAN 6.0 directory.

  2. Run the following code

cd examples/20171108_Pasadena
./run_examples_modtran.sh

  1. This will build a surface model and run the retrieval. The default example uses a lookup table approximation, and the code should recognize that the tables do not currently exist. It will call MODTRAN to rebuild them, which will take a few minutes.

  2. Look for output data in examples/20171108_Pasadena/output/.

Quick Start with LibRadTran 2.0.x

This quick start requires an installation of the open source LibRadTran radiative transfer model (LibRadTran). A few important steps have to be considered when installing the software, which are outlined below. We have tested with the latest 2.0.4 release.

  1. Download and unpack the latest version of LibRadTran:

wget -nv http://www.libradtran.org/download/libRadtran-2.0.4.tar.gz
tar -xf libRadtran-2.0.4.tar.gz

  1. Download and unpack the “REPTRAN” absorption parameterization:

wget -nv http://www.meteo.physik.uni-muenchen.de/~libradtran/lib/exe/fetch.php?media=download:reptran_2017_all.tar.gz -O reptran-2017-all.tar.gz
tar -xf reptran-2017-all.tar.gz

  1. Unpacking REPTRAN will create a folder called ‘data’ with a subfolder ‘correlated_k’. Copy this subfolder to the LibRadTran data directory:

cp -r data/correlated_k libRadtran-2.0.4/data

  1. Go to the LibRadTran base directory, configure and compile the software. It’s important to set python2 as interpreter and ‘ignore-errors’ when running the ‘make’ command:

cd libRadtran-2.0.4
PYTHON=$(which python2) ./configure --prefix=$(pwd)
make --ignore-errors

  1. Create an environment variable LIBRADTRAN_DIR pointing to the base libRadTran directory.

  2. Run the following code

cd examples/20171108_Pasadena
./run_example_libradtran.sh

  1. This will build a surface model and run the retrieval. The default example uses a lookup table approximation, and the code should recognize that the tables do not currently exist. It will call LibRadTran to rebuild them, which will take a few minutes.

  2. Look for output data in examples/20171108_Pasadena/output/.

Additional Installation Info for Mac OSX

  1. Install the command-line compiler

xcode-select --install

  1. Download the python3 installer from https://www.python.org/downloads/mac-osx/

Known Incompatibilities

Ray may have compatability issues with older machines with glibc < 2.14.

Additional Installation Info for Developers

Be sure to read the Contributing page as additional installation steps must be performed.