WorkshopHackathon2018

Materials, issues and things for the 2018 Workshop and Hackathon

View the Project on GitHub MDAnalysis/WorkshopHackathon2018

Installing the environment

Overview

You will need to make sure you have the following tools:

  1. The Bash Shell
  2. Git
  3. a text editor (we recommend Atom)
  4. Python (including a number of additional packages required for scientific computing)
  5. MDAnalysis

In each section, find the instructions for your operating system (Windows, macOS, or Linux).

Once you have installed everything, test your installation.

Setup

To participate in the workshop, you will need access to the software described below. In addition, you will need an up-to-date web browser.

If you encounter problems during the installation ask an instructor for help. We also maintain resources for trouble shooting problems during the installation.

The Bash Shell

Bash is a commonly-used shell that gives you the power to do simple tasks more quickly.

Windows

  1. Download the Git for Windows installer.
  2. Run the installer and follow the steps bellow:
    1. Click on "Next".
    2. Click on "Next".
    3. Click on "Next".
    4. Click on "Next".
    5. Click on "Next".
    6. Select "Use Git from the Windows Command Prompt" and click on "Next". If you forgot to do this programs that you need for the class will not work properly. If this happens rerun the installer and select the appropriate option.
    7. Click on "Next". Keep "Checkout Windows-style, commit Unix-style line endings" selected.
    8. Select "Use Windows' default console window" and click on "Next".
    9. Click on "Next".
    10. Click on "Finish".

This will provide you with both Git and Bash in the Git Bash program.

macOS / Mac OS X

The default shell in all versions of macOS (formerly Mac OS X) is Bash, so no need to install anything. You access Bash from the Terminal (found in /Applications/Utilities). You may want to keep Terminal in your dock for this class.

Linux

The default shell is usually Bash, but if your machine is set up differently you can run it by opening a terminal and typing bash. There is no need to install anything.

Git

Git is a version control system that lets you track who made changes to what when and has options for easily updating a shared or public version of your code on github.com. You will need a supported web browser (current versions of Chrome, Firefox, Safari, Microsoft Edge, or Internet Explorer version 11 or above).

Windows

Git should be installed on your computer as part of your Bash install (described above).

macOS / Mac OS X

For OS X 10.9 and higher, install Git for Mac by downloading and running the most recent "mavericks" installer from this list. After installing Git, there will not be anything in your /Applications folder, as Git is a command line program. For older versions of OS X (10.5-10.8) use the most recent available installer labelled "snow-leopard" available here.

Linux

If Git is not already available on your machine you can try to install it via your distro's package manager. For Debian/Ubuntu run sudo apt-get install git and for Fedora run sudo yum install git.

Text Editor

When you're writing code, it's nice to have a text editor that is optimized for writing code, with features like automatic color-coding of key words. The default text editor on macOS and Linux is usually set to Vim, which is not famous for being intuitive. if you accidentally find yourself stuck in it, try typing the escape key, followed by :q! (colon, lower-case 'q', exclamation mark), then hitting Return to return to the shell.

For this class we will use atom as the default editor. It is free, open source, available on Windows, macOS, and Linux, powerful but also accessible for entry-level programmers.

Windows

atom is a good editor that is suitable for professional coding but also accessible to newcomers with its graphical user interface. To install it, download a suitable installer from atom.io and double click on the file to run it. (If you cannot find an appropriate installer, look for a file "AtomSetup-x64.exe" or "AtomSetup.exe" in the list of latest releases.) For more details see Installing atom on Windows.

Others editors that you can use are Notepad++ or Sublime Text. Be aware that you must add its installation directory to your system path. Please ask your instructor to help you do this.

macOS / Mac OS X

We recommend atom as a good editor that is suitable for professional coding but also accessible to newcomers with its graphical user interface. To install it, download a suitable installation zip file from atom.io and double click on the file to unpack it. Open your Applications directory from the Finder in the Go menu. Drag the unpacked Atom application to your Applications directory. (If you cannot find an appropriate installer, look for a file "atom-mac.zip" or in the list of latest releases.) For more details see Installing atom on Mac.

Alternatively, nano is a basic editor. It should be pre-installed.

Others editors that you can use are Text Wrangler or Sublime Text.

Linux

We recommend atom as a good editor that is suitable for professional coding but also accessible to newcomers with is graphical user interface. Please follow the instructions on Installing atom on Linux and ask an instructor for help if anything is unclear.

Alternatively, nano is a basic editor. It should be pre-installed.

Others editors that you can use are Gedit, Kate or Sublime Text.

Python

Python is a popular language for scientific computing, and great for general-purpose programming as well. Installing all of its scientific packages individually can be a bit difficult, so we recommend Anaconda, an all-in-one installer.

Regardless of how you choose to install it, please make sure you install Python version 3.x (e.g., 3.4 or 3.5 is fine).

We will teach Python using the Jupyter notebook, a programming environment that runs in a web browser. For this to work you will need a reasonably up-to-date browser. The current versions of the Chrome, Safari and Firefox browsers are all supported (some older browsers, including Internet Explorer version 9 and below, are not).

Windows

  1. Open https://www.anaconda.com/download/ with your web browser.
  2. Download the Python 3 installer for Windows.
  3. Install Python 3 using all of the defaults for installation except make sure to check Make Anaconda the default Python.

macOS / Mac OS X

  1. Open https://www.anaconda.com/download/ with your web browser.
  2. Download the Python 3 installer for OS X.
  3. Install Python 3 using all of the defaults for installation.

Linux

  1. Open https://www.anaconda.com/download/ with your web browser.
  2. Download the Python 3 installer for Linux.
  3. Install Python 3 using all of the defaults for installation. (Installation requires using the shell. If you aren't comfortable doing the installation yourself stop here and request help.)
  4. Open a terminal window.
  5. Type `bash Anaconda-` and then press tab. The name of the file you just downloaded should appear.
  6. Press enter. You will follow the text-only prompts. When there is a colon at the bottom of the screen press the down arrow to move down through the text. Type yes and press enter to approve the license. Press enter to approve the default location for the files. Type yes and press enter to prepend Anaconda to your PATH (this makes the Anaconda distribution the default Python).

MDAnalysis and other related Python packages

You will need to install the following packages. Install MDAnalysis with conda (from the conda-forge channel):

conda config --add channels conda-forge 
conda install mdanalysis mdanalysistests mdanalysisdata pmda
conda install nglview

For downloading test trajectories for the workshop see the wiki page on downloading data; please check this page before the workshop for any updates.

Testing

Bash shell

Open a terminal (macOS, Linux) or open Git Bash (under All Programs/Git/Git Bash) in Windows.

Type

echo $SHELL

Should show /bin/bash or /usr/bin/bash (or similar).

We use “shell” and “terminal” (and “console”) pretty interchangeably.

Git

In the shell, type

git --version

which should show something like git version 2.7.0.

editor (atom)

First time

Open atom using your GUI

A window should open, showing the atom logo and welcome screen.

If it tries to install additional commands (atom and apm) then let it do it and provide your system administrator password if required.

Then exit the editor again (Quit from the menu or close the window).

From the shell

In the shell, type

atom

It should open the editor. Exit the editor.

If this does not work then you need to let atom install additional commands. Open the (Command Palette), choosing the instructions appropriate for your platform. In the Command Palette type Window: Install Shell Commands (and provide your system administrator password if requested).

Python

In the shell, type

python -c 'import sys; print(sys.version)'

which should give something similar to 3.5.3 |Anaconda custom (x86_64)| (default, Mar 6 2017, 12:15:08) (and more stuff). Important: you should have Python 3, i.e., a version like 3.5.x or 3.6.x

Jupyter notebook

  1. In the shell, type ``` jupyter notebook ``` This should open a browser window at http://localhost:8888.
  2. Open the New menu on the right hand side.
  3. Under Notebooks select Python or Python [conda root] (if it is shown)
  4. In the new window ("Untitled"), type print("Hello World!") and press shift and return keys simultaneously to evaluate the cell. It should print "Hello World!".
  5. Close the browser tab with menu File: Close and Halt.
  6. In the files listing, select from New under Notebooks select Python [conda root]
  7. Close the browser tab with menu File: Close and Halt.

If you have problems, ask an instructor.

Common problems

See also troubleshooting problems during the installation

Credits

The instructions were adapted from the Computational Methods in Physics course, which were themselves adapted from Software Carpentry.