Skip to content

Commit

Permalink
Clarified and re-structured installation doc page
Browse files Browse the repository at this point in the history
  • Loading branch information
@lorenaacuna
lorenaacuna authored Nov 5, 2024
1 parent aeb597c commit 37e3a4d
Show file tree
Hide file tree
Showing 4 changed files with 207 additions and 190 deletions.
211 changes: 21 additions & 190 deletions docs/source/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,225 +11,54 @@ To install GASTLI, you need to:
- have a fortran compiler, for example ``gfortran``,
- download the zip file for the input data `here <https://www.dropbox.com/scl/fi/p2kawqp8gtzh5psn21tjc/gastli_input_data.zip?rlkey=fc0mfxvpck5mukkqhk1f8hkad&st=ggsa4zmk&dl=0>`_, and place it in a directory in your computer that is easy to find

If you do not have the first two requirements, we offer an installation guide below.
If you do not have either of the first two requirements, we offer an installation guide for different OS below:

.. toctree::
linux_install
macos_intel_install
macos_arm64_install

.. important::

The latest stable version is 0.9.1, which corresponds to the main branch. Version 0.9.2 is the development branch. We recommend users to make sure that the install version 0.9.1 if they use pip ``pip install gastli==0.9.1``


Fortran and Python installation
-------------------------------

Linux
~~~~~

On Linux, you can install Python and the fortran compiler with:

.. code-block:: bash
sudo apt-get install python python-pip gfortran
Depending on the distribution, ``python`` may need to be replaced with ``python3``.

Mac OS (all)
~~~~~~~~~~~~

For Mac OS, we recommend to use `homebrew <https://brew.sh>`_. Trying to install gfortran (or gcc) from source can be complicated, and setup-related errors can be easily introduced.
.. warning::

For a safe installation, start executing in your terminal:

.. code-block:: bash
brew update
brew upgrade
brew doctor
The command ``brew doctor`` may show a list of fixes. We recommend to go through this list before moving on to the next step.

Finally, the fortran compiler can be installed by running in the terminal:

.. code-block:: bash
brew install gcc
Mac OS (Apple Silicon M1/M2/M3)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your Mac OS has an Apple Silicon chip, and you follow the steps above for Mac OS, you may encounter the following error when trying to access any variable, class or function of the package:

.. code-block:: bash
Mac OS with Apple Silicon processors (M1, M2 and M3) have ARM64 as the native architecture. These systems have shown problems when installing
a Python package that compiles a fortran backend because Python's default fortran compiler uses Intel architecture. One way to recognise this is
to try installing GASTLI's with pip (or from source) anfd testing the installation as indicated below. If you get a message such as the following,
you need to follow the instructions for Apple Silicon in the :doc:`macos_arm64_install` section:

.. code-block:: python
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: dlopen(/Users/acuna/anaconda3/envs/GASTLI_norosetta/lib/python3.10/site-packages/gastli/dimensions.cpython-310-darwin.so, 0x0002): symbol not found in flat namespace (_f2pyinitdimensions_)
There are two options to fix this error: 1) using an Intel emulation with Rosetta, or 2) using a disk image. We explain both options below.

**1) Installation with Rosetta**

The installation of GASTLI on Apple machines with the M1/M2/M3 chip requires Intel emulation with Rosetta.

.. code-block:: bash
softwareupdate --install-rosetta
Now go to the Applications folder and find the iTerm icon. Make a copy of this application and name the new copy as something like "iTerm_Rosetta". Right click iTerm_Rosetta, choose "Get Info", and select the "Open using Rosetta" box. To test that you are indeed using the Intel emulator, type the following in your iTerm_Rosetta:

.. code-block:: bash
arch
This command should return ``i386``.

Next, install homebrew with Rosetta:

.. code-block:: bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
With the Intel emulation, Homebrew should be installed at ``/usr/local/bin/brew``. Add the following to your ``.bash_profile``

.. code-block:: bash
alias brew_i386="/usr/local/bin/brew"
In the future, you will use `brew_i386` as an alternative of `brew` with the Intel emulation.

For completeness only, you might also install Homebrew in your M1/M2/M3 terminal, which should be then installed at ``/opt/homebrew/bin/brew``. Add the following to your ``.bash_profile``

.. code-block:: bash
alias brew="/opt/homebrew/bin/brew"
Now we will install ``miniconda3`` in Rosetta, but before that, we will have to modify ``.bash_profile`` so we could handle the ``conda`` between M1/M2/M3 and Rosetta separately. Here I assume you already installed ``anaconda`` in your M1/M2/M3 terminal, so the following block should be in your ``.bash_profile``:

.. code-block:: bash
# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/Users/xxxx/anaconda3/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
eval "$__conda_setup"
else
if [ -f "/Users/xxxx/anaconda3/etc/profile.d/conda.sh" ]; then
. "/Users/xxxx/anaconda3/etc/profile.d/conda.sh"
else
export PATH="/Users/xxxx/anaconda3/bin:$PATH"
fi
fi
unset __conda_setup
# <<< conda initialize <<<
Note that the "xxxx" here should be your username. Let's cut these few lines and paste them into a separate file ``.init_conda_arm64.sh`` in the home directory. We will come back to handle this file later.

Now let's install ``miniconda3`` in Rosetta. First, type the following line in iTerm_Rosetta:

.. code-block:: bash
curl -L https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh > Miniconda3-latest-MacOSX-x86_64.sh
Then type the following and follow instructions to proceed with the installation:

.. code-block:: bash
bash Miniconda3-latest-MacOSX-x86_64.sh
Once the installation succeed, you will see that the following several new lines have been added to ``.bash_profile``:

.. code-block:: bash
# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/Users/xxxx/miniconda3/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
eval "$__conda_setup"
else
if [ -f "/Users/xxxx/miniconda3/etc/profile.d/conda.sh" ]; then
. "/Users/xxxx/miniconda3/etc/profile.d/conda.sh"
else
export PATH="/Users/xxxx/miniconda3/bin:$PATH"
fi
fi
unset __conda_setup
# <<< conda initialize <<<
Let's cut these few lines again and paste them into a separate file ``.init_conda_x86_64.sh`` in the home directory. In the same iTerm_Rosetta, type the following:

.. code-block:: bash
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
Okay, now we are ready to go ahead mofify ``.bash_profile`` to handle two versions of ``conda`` between M1 and Rosetta terminals. Add the following lines to your ``.bash_profile``:

.. code-block:: bash
# <<<<<< Added by TR 20220405 <<
arch_name="$(uname -m)"
if [ "${arch_name}" = "x86_64" ]; then
echo "Running on Rosetta using miniconda3"
source ~/.init_conda_x86_64.sh
elif [ "${arch_name}" = "arm64" ]; then
echo "Running on ARM64 using anaconda"
source ~/.init_conda_arm64.sh
else
echo "Unknown architecture: ${arch_name}"
fi
# <<<<<<<< end <<<<<<<
Now, when you open iTerm / iTerm_Rosetta, you will instantly know which ``conda`` version is being used.

Next, we should install the following packages in ``miniconda3``:

.. code-block:: bash
conda install ipython
conda install numpy
conda install jupyter
Then, we install ``gfortran`` in iTerm_Rosetta:

.. code-block:: bash
brew_i386 install gfortran
Everything is ready now, so we should simply install GASTLI with pip

**2) Installation with disk image**

`François-Xavier Coudert’s github repository <https://github.com/fxcoudert/gfortran-for-macOS>`_ provides gfortran disk images (.dmg) that can be used to install gfortran through an installation wizard for the Apple Silicon (M1, M2, M3) chips.
Installation of GASTLI's Python package
=======================================

Conda environment
-----------------

Once Python and the fortran compiler are installed, our recommendation is to use a Python virtual environment such as `venv <https://docs.python.org/3/library/venv.html>`_ or `conda <https://docs.anaconda.com/anaconda/install/index.html>`_, to prevent potential conflicts.
Our recommendation is to use a Python virtual environment such as `venv <https://docs.python.org/3/library/venv.html>`_ or `conda <https://docs.anaconda.com/anaconda/install/index.html>`_, to prevent potential conflicts.

We can create a new conda environment (for example, "GASTLI_env") by running in the terminal:
If you decide to create a new conda environment (for example, "GASTLI_env"), run in the terminal:

.. code-block:: bash
conda create -n GASTLI_env python=3.10
Activate the environment:
Then activate the environment:

.. code-block:: bash
conda activate GASTLI_env
After activating the environment, we will be ready to install GASTLI with pip:
After activating the environment, we will be ready to install GASTLI with pip, ``pip install gastli==0.9.1``

.. code-block:: bash
.. warning::

The latest stable version is 0.9.1, which corresponds to the main branch. Version 0.9.2 is the development branch. We recommend users to make sure that the install version 0.9.1 if they use pip ``pip install gastli==0.9.1``

pip install gastli==0.9.1


Installation from source
Expand Down Expand Up @@ -260,3 +89,5 @@ The output should be:
3
0.13
12 changes: 12 additions & 0 deletions docs/source/linux_install.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@

Fortran installation in Linux
-------------------------------

On Linux, you can install Python and the fortran compiler with:

.. code-block:: bash
sudo apt-get install python python-pip gfortran
Depending on the distribution, ``python`` may need to be replaced with ``python3``.

Loading

0 comments on commit 37e3a4d

Please sign in to comment.