fenics-with-spyder.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "aggregate-beatles",
   "metadata": {},
   "source": [
    "# About this notebook\n",
    "\n",
    "This notebook documents a procedure to install FEniCS using Anaconda. The [first step](#Step-1:-install-Anaconda) in the notebook (installing Anaconda itself) needs to be completed from a terminal window. You can then continue to install manually by following [Method 1](#Method-1:-manual-installation-from-terminal), or, once you have a working Anaconda installation, you can launch this notebook using Jupyter and install automatically by running the commands in [Method 2](#Method-2:-automatic-installation-from-this-notebook) (not yet implemented). An optional [final step](#Step-4-(optional):-Spyder-desktop-shortcut) is to create shortcuts for the desktop and the application launcher for convenient booting of Spyder.\n",
    "\n",
    "## Requirements\n",
    "\n",
    "This procedure has been tested on:\n",
    "* a 64-bit laptop with an Intel Core i3 processor running Ubuntu 20.04.2 LTS\n",
    "* a 64-bit miniserver (Meerkat) with i7 processor running Ubuntu 20.04.2 LTS\n",
    "\n",
    "\n",
    "## Last Updated\n",
    "\n",
    "This document last updated on 2021-06-18."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3023412c",
   "metadata": {},
   "source": [
    "# Step 0: removing a pre-existing FEniCS installation\n",
    "\n",
    "If you have arrived here after discovering that your installation of FEniCS is dysfunctional, you may want to remove your previous FEniCS installation to prevent any conflicts with the Anaconda installation you are about to install.\n",
    "\n",
    "## `apt` installation\n",
    "\n",
    "If you installed FEniCS using `apt`, the `purge` option with auto remove should clear FEniCS and all its configuration and dependent packages so that you can create a fresh installation using the instructions in this document.\n",
    "\n",
    "In a fresh terminal window (Ctrl+Shift+t), type:\n",
    "```\n",
    "sudo apt-get purge --auto-remove fenics\n",
    "```\n",
    "\n",
    "If you used a PPA to install the software, you may need to also run:\n",
    "```\n",
    "sudo ppa-purge ppa:fenics-packages/fenics\n",
    "```\n",
    "\n",
    "## Anaconda installation\n",
    "\n",
    "If the previous installation is in Anaconda you can remove by FEniCS installation by removing the entire conda environment containaing FEniCS. With the terminal (base) environment active, you can remove the FEniCS environment using:\n",
    "```\n",
    "conda env remove -n fenicsproject\n",
    "```\n",
    "or\n",
    "```\n",
    "conda remove -n fenicsproject --all\n",
    "```\n",
    "will have the same effect. If you installed FEniCS to a different conda environment than `fenicsproject`, replace `fenicsproject` with the environment name.\n",
    "\n",
    "However, since Spyder is within Anaconda, you may be able to skip to step 2b and associate Spyder without removing FEniCS.\n",
    "\n",
    "If you plan to plot FEniCS objects directly from Python, you'll need the `matplotlib` module. In this case, removing the existing environment and creating a fresh enivronment may be the best idea before moving to step 2a."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "registered-little",
   "metadata": {},
   "source": [
    "# Step 1: install Anaconda\n",
    "\n",
    "This step must be completed manually from the terminal, regardless of whether you plan to use the manual [Method 1](#Method-1:-manual-installation-from-terminal) or the automatic [Method 2](#Method-2:-automatic-installation-from-this-notebook). (This is obvious, since you cannot execute this notebook without an Anaconda installation!) To install Anaconda:\n",
    "\n",
    "1. Download the Anaconda installer from https://www.anaconda.com/products/individual#Downloads. As of the time of this writing (2021-05-19), the current version is Python 3.8.\n",
    "2. Open a terminal window and `cd` to the location of the downloaded shell script.\n",
    "3. From the terminal, run the install script. For me, this was achieved with the command:\n",
    "   \n",
    "   ```\n",
    "   ./Anaconda3-2021.05-Linux-x86_64.sh\n",
    "   ```\n",
    "\n",
    "4. Accept the terms of the license agreement when prompted.\n",
    "5. Accept the default installation location (or choose another location if you must). For me, this was\n",
    "\n",
    "   ```\n",
    "   /home/connor/anaconda3\n",
    "   ```\n",
    "\n",
    "6. The installation proceeds. It may take a while.\n",
    "7. When prompted \"Do you wish the installer to initialize Anaconda3 by running conda init? [yes|no]\", choose yes. This will set up your terminal by prepending the Anaconda installation to your `PATH`, making the Anaconda Python interpreter the first Python interpreter found by the shell.\n",
    "\n",
    "## Verify Anaconda installation\n",
    "\n",
    "To verify that Anaconda installation succeeded, start a new terminal window. First you will notice that the currently-active conda environment has been prepended to the prompt, e.g.\n",
    "\n",
    "```\n",
    "connor@connor-Vostro-1540: ~/Downloads$\n",
    "```\n",
    "\n",
    "has been replaced by\n",
    "\n",
    "```\n",
    "(base) connor@connor-Vostro-1540: ~/Downloads$\n",
    "```\n",
    "\n",
    "The string `(base)` indicates that the conda environment `base` is currently active. To check that the Anaconda setup worked correctly, run the command\n",
    "\n",
    "```\n",
    "which python\n",
    "```\n",
    "The terminal should display the path to the Python executable in the Anaconda environment, e.g.\n",
    "```\n",
    "/home/connor/anaconda3/bin/python\n",
    "```\n",
    "\n",
    "If you run\n",
    "```\n",
    "which -a python3\n",
    "```\n",
    "you will see a list of all installed Python versions, e.g.\n",
    "```\n",
    "/home/connor/anaconda3/bin/python3\n",
    "/usr/bin/python3\n",
    "/bin/python3\n",
    "```\n",
    "The Anaconda version is listed first, meaning that all calls to `python3` will be directed to the Python interpreter in your Anaconda installation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d4d5e44",
   "metadata": {},
   "source": [
    "# Option A: manual installation from terminal\n",
    "\n",
    "## Step 2: Install FEniCS\n",
    "In this section, we go through a sequence of commands that can be typed one-by-one into the terminal to set up FEniCS with Spyder. Note that the conda commands used in this method include the `--yes` option to suppress the prompt to install packages. If you'd like to be prompted during each step, remove the `--yes`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "robust-culture",
   "metadata": {},
   "source": [
    "### Step 2.1: Set up conda environments\n",
    "\n",
    "In this section, we set up a new conda environment in which FEniCS will be installed. First, we will set up a conda environment called \"fenicsproject\". I recommend using the Python version from the official Anaconda channels (currently 3.8 as of 2021-05-19), since I've had issues when using the Python 3.9 interpreter from the \"conda-forge\" channel. I also like to install packages from the official Anaconda channel when possible. Therefore, rather than use the `-c conda-forge` option from the [standard installation instructions](https://fenicsproject.org/download/) (which seems to prompt all packages to be installed from conda-forge) when creating my environment, I first create the environment without installing FEniCS, configure my conda environment with \"conda-forge\" as my second-priority channel, and then install FEniCS in the last step. Stepwise, this looks like this:\n",
    "\n",
    "1. Create the conda environment named \"fenicsproject\" and install Python 3.8. From the terminal, run \n",
    "   \n",
    "   ```\n",
    "   conda create -n fenicsproject --yes python=3.8.*\n",
    "   ```\n",
    "   * If you wish to install `matplotlib`, it is best to install it at this point to avoid dependency conflicts that may arise after you install `fenics`. To install `matplotlib`, use instead:\n",
    "      ```\n",
    "      conda create -n fenicsproject --yes python=3.8 matplotlib\n",
    "      ```\n",
    "2. Activate the fenicsproject environment:\n",
    "   \n",
    "   ```\n",
    "   conda activate fenicsproject\n",
    "   ```\n",
    "3. Set \"conda-forge\" as an alternate package source:\n",
    "\n",
    "   ```\n",
    "   conda config --append channels conda-forge\n",
    "   ```\n",
    "\n",
    "### Step 2.2: Install FEniCS and optional packages\n",
    "\n",
    "You are now ready to install FEniCS:\n",
    "```\n",
    "conda install --yes fenics\n",
    "```\n",
    "\n",
    "__Optional__: FEniCS contains a select few simple built-in meshes. For more complicated problems, you will need to install another meshing package. A comparison of several free meshing packages can be found here: [https://github.com/nschloe/meshgen-comparison](https://github.com/nschloe/meshgen-comparison). You may also wish to install the `mshr` and `meshio` packages. `mshr` is no longer maintained, but is tightly integrated with FEniCS and provides a useful extension of the FEniCS built-in meshes. In addition, `mshr` may be helpful for new FEniCS users because it is used in many of the FEniCS tutorials. The mesh format converter, `meshio`, is a very helpful tool that enables FEniCS to work with meshes generated by a variety of meshing packages.\n",
    "\n",
    "To install `meshio` and `mshr`, run the following commands:\n",
    "```\n",
    "conda install meshio\n",
    "conda install mshr\n",
    "```\n",
    "\n",
    "### Step 2.3: Verify conda environments\n",
    "\n",
    "If we run\n",
    "```\n",
    "conda list fenics\n",
    "conda list spyder\n",
    "```\n",
    "we see that the \"fenics\" package (and several associated packages) are installed in the \"fenicsproject\" environment, but Spyder is not. On the other hand, if we then run the following:\n",
    "```\n",
    "conda activate base\n",
    "conda list fenics\n",
    "conda list spyder\n",
    "```\n",
    "we see that Spyder is installed in the \"base\" environment but FEniCS is not. I set up my installation like this in order to:\n",
    "\n",
    "1. Minimize the number of FEniCS and Spyder installations\n",
    "2. Separate the FEniCS and Spyder dependencies (whether or not they clash at all, I don't know)\n",
    "\n",
    "Finally, if we run\n",
    "```\n",
    "which spyder\n",
    "```\n",
    "from the base environment, we see that Spyder will be run from the Anaconda installation (and not from somewhere else on our system)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acknowledged-genre",
   "metadata": {},
   "source": [
    "## Step 3: Spyder console interpreter\n",
    "\n",
    "If we try to run a FEniCS code from our current setup, we will get an error when we try to\n",
    "```python\n",
    "import fenics as fe\n",
    "```\n",
    "This is because Spyder's default setting is to open the console using the same Python interpreter that was used to run Spyder. To run FEniCS codes, we must tell Spyder to open the console using the Python interpreter found in the \"fenicsproject\" environment. In order for this to succeed, we must have the \"spyder-kernels\" package installed in the \"fenicsproject\" environment. It's important to install the correct version of \"spyder-kernels\" that is compatible with our Spyder installation (Spyder seems to be picky about this, we'll get an error if we have the wrong version). Above, when I ran the command:\n",
    "```\n",
    "conda list spyder\n",
    "```\n",
    "I saw that \"spyder-kernels\" version 1.10.2 was installed in the base environment (e.g. yours may be 2.0.1). Use the version you found to install in the \"fenicsproject\" environment if your machine gave a different version (e.g. replacing `1.10.2` with `2.0.1`):\n",
    "```\n",
    "conda activate fenicsproject\n",
    "conda install --yes spyder-kernels=1.10.2\n",
    "```\n",
    "To instruct Spyder to open consoles using the Python interpreter from the \"fenicsproject\" environment, launch Spyder:\n",
    "```\n",
    "conda activate base\n",
    "spyder\n",
    "```\n",
    "\n",
    "In __Tools > Preferences > Python Interpreter > Python Interpreter__, select the radio button for \"Use the following Python interpreter:\". In the box below the radio button, select the Python interpreter in the \"fenicsproject\" environment, using the path from the first part of 2b. For example, mine was:\n",
    "```\n",
    "/home/connor/anaconda3/envs/fenicsproject/bin/python\n",
    "```\n",
    "Click OK. In the status bar at the bottom of the Spyder window (if you're using Spyder 4.2.5 like I am), you'll see \"conda: fenicsproject (Python 3.8.X)\", which tells you that your consoles will now be running from the \"fenicsproject\" environment.\n",
    "\n",
    "At this point, you should be all set up to run FEniCS with Spyder.\n",
    "\n",
    "### (Optional) Enabling plotting in separate window\n",
    "\n",
    "If you prefer to see figures in a separate window rather than inline in the Spyder \"Plots\" pane, you will need to install the \"pyqt\" module in the \"fenicsproject\" environment:\n",
    "```\n",
    "conda activate fenicsproject\n",
    "conda install --yes pyqt\n",
    "```\n",
    "\n",
    "To enable plotting in a separate window, go to __Tools > Preferences > IPython console > Graphics > Graphics backend__ and choose \"Qt5\" for the backend. When you click \"OK\", Spyder will probably prompt you to restart the kernel. I have found that this often produces a warning, an error, or the console simply \"hangs\". Opening a new console seems to fix this and cause the changes to take effect."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "baa8ce7a",
   "metadata": {},
   "source": [
    "# Method 2: automatic installation from this notebook\n",
    "\n",
    "_Possibly coming soon. [Installing Python packages from Jupyter is non-trivial](https://jakevdp.github.io/blog/2017/12/05/installing-python-packages-from-jupyter) and I still need to wrap my head around it._"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "scheduled-maker",
   "metadata": {},
   "source": [
    "# Step 4 (optional): Spyder desktop shortcut\n",
    "\n",
    "This final step can be completed manually after using either Method 1 or Method 2 to set up FEniCS and Spyder.\n",
    "\n",
    "If you'd prefer not to boot Spyder from the terminal every time, you can create a desktop shortcut. The long form of this explanation can be found here: https://www.howtogeek.com/445303/how-to-create-desktop-shortcuts-on-ubuntu/. The short form is this:\n",
    "\n",
    "1. Create a text file named \"spyder.desktop\" in your Documents folder and enter the following (substituting the appropriate path to Spyder for your installation):\n",
    "   \n",
    "   ```\n",
    "   [Desktop Entry]\n",
    "   Type=Application\n",
    "   Name=Spyder\n",
    "   GenericName=Python IDE\n",
    "   Comment=Scientific Python development environment\n",
    "   Path=/home/connor/anaconda3/bin\n",
    "   Exec=/home/connor/anaconda3/bin/spyder\n",
    "   Icon=/home/connor/anaconda3/share/icons/spyder.png\n",
    "   Terminal=False\n",
    "   Categories=Development\n",
    "   Keywords=Python,dev\n",
    "   ```\n",
    "\n",
    "2. Copy the file to your desktop.\n",
    "3. Right-click on the file and select \"Allow Launching\". You should see the Spyder icon appear. Double-clicking should launch Spyder.\n",
    "4. To allow the file to be launched from the GNOME launcher, you should also copy the file to `~/.local/share/applications`:\n",
    "   \n",
    "   ```\n",
    "   cp ~/Documents/spyder.desktop ~/.local/share/applications\n",
    "   ```\n",
    "\n",
    "You should now see Spyder appear in your list of installed programs when you click the \"Show Applications\" button on the dash."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7cc9dfdc",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}