Los Alamos National Laboratory

August 16-17 2018

09:00-16:30

Instructors: Stephen Andrews, Cameron Bates, Andrew Fraser, Christopher Malone

Helpers: Austin McCartney

General Information

This set of workshops is designed to teach good software development practice to students, post-docs and staff from Los Alamos National Laboratory. Some funding for these lessons has been provided by the Advanced Simulation and Computing project.
Software Carpentry aims to help researchers get their work done in less time and with less pain by teaching them basic research computing skills. This hands-on workshop will cover basic concepts and tools, including program design, version control, data management, and task automation. Participants will be encouraged to help one another and to apply what they have learned to their own research problems.

For more information on what we teach and why, please see our paper "Best Practices for Scientific Computing".

To sign up for this course, visit the IC wiki sign up page. This site is accessible from the internal network. Enter your Z-number and then 'add' the Software Carpentry course. Registration is on a first-come-first-served basis and is limited to 40 participants.

Who: The course is aimed at graduate students and other researchers. You don't need to have any previous knowledge of the tools that will be presented at the workshop.

Where: Room 230 (the Lecture Hall) , Building 2, University of New Mexico at Los Alamos. Get directions with OpenStreetMap or Google Maps.

When: August 16-17 2018. Add to your Google Calendar.

Requirements: Participants must bring a laptop with a Mac, Linux, or Windows operating system (not a tablet, Chromebook, etc.) that they have administrative privileges on. They should have a few specific software packages installed (listed below). They are also required to abide by Software Carpentry's Code of Conduct.

Accessibility: We are committed to making this workshop accessible to everybody. The workshop organizers have checked that:

Contact: Please email saandrews@lanl.gov for more information.


Surveys

Please be sure to complete these surveys before and after the workshop.

Pre-workshop Survey

Post-workshop Survey


Schedule

August 16

Before Pre-workshop survey
09:00 Automating tasks with the Unix shell
10:30 Coffee
12:00 Lunch break
13:00 Building programs with Python
14:30 Coffee
17:00 END

August 17

09:00 Automation with make
10:30 Coffee
12:00 Lunch break
13:00 Version control with Git
14:30 Coffee
16:30 Wrap-up
16:40 Post-workshop Survey
17:00 END

We will use this collaborative document for chatting, taking notes, and sharing URLs and bits of code.


Syllabus

The Unix Shell

  • Files and directories
  • History and tab completion
  • Pipes and redirection
  • Looping over files
  • Creating and running shell scripts
  • Finding things
  • Reference...

Programming in Python

  • Using libraries
  • Working with arrays
  • Reading and plotting data
  • Creating and using functions
  • Loops and conditionals
  • Defensive programming
  • Using Python from the command line
  • Reference...

Version Control with Git

  • Creating a repository
  • Recording changes to files: add, commit, ...
  • Viewing changes: status, diff, ...
  • Ignoring files
  • Working on the web: clone, pull, push, ...
  • Resolving conflicts
  • Open licenses
  • Where to host work, and why
  • Reference...

Automation with make

  • Use of make to automate scientific workflow
  • Structure of a Makefile
  • Listing dependencies
  • Makefile rules
  • Makefile varialbes
  • Makefile functions
  • Self-Documenting Makefiles
  • Latex Example
  • Reference...

Setup

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

We maintain a list of common issues that occur during installation as a reference for instructors that may be useful on the Configuration Problems and Solutions wiki page.

The Bash Shell

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

Windows

  1. Install Ubuntu for Windows
    1. Open the Microsoft Store
    2. Search for 'Ubuntu'
    3. Select Ubuntu 18.04 and hit install
  2. Enable the Windows Subsystem for Linux
    1. Open the Windows Power shell as an administrator
      1. Click the Windows icon in the lower left corner of your screen to open the start menu
      2. In the start menu, search for "Powershell"
      3. Right click on the Microsoft Powershell icon and select "Run as administrator"
      4. When prompted, click Yes to allow powershell to modify your device
    2. In the Powershell enter the following command:
      
      Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
      	      
    3. Close power shell
  3. Restart your computer
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. Click the Power icon in the start menu
    3. Select Restart
  4. Open the "Ubuntu" application
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. In the start menu, search for "Ubuntu"
    3. Click the Ubuntu icon in the search results
    4. A black bash window will appear with the message
      
      Installing, this may take a few moments...
      	      
    5. When the installation is complete, you will be prompted to create a username.
      
      Installing, this may take a few minutes...
      Installation successful!
      Please create a default UNIX user account. The username does not need to match your Windows username.
      For more information visit: https://aka.ms/wslusers
      Enter new UNIX username:
      	      
    6. Type a desired username and press enter
    7. You will be prompted to provide a password for the new account.
      
      Enter new UNIX password:
      	      
    8. Type a memorable and secure password and press enter. This password is case-sensitive and cannot be recovered if forgotten. Do not be alarmed if no text appears on the screen as you enter the password.
    9. You will be prompted to confirm the password.
      
      Enter new UNIX password:
      Retype new UNIX password:
      	      
    10. Retype the password and press enter
    11. Assuming the passwords match, a message confirming the password update should appear
      
      Enter new UNIX password:
      Retype new UNIX password:
      passwd: password updated successfully
      	      
    12. A UNIX shell is successfully installed on your system

macOS

The default shell in all versions of macOS is Bash, so no need to install anything. You access Bash from the Terminal (found in /Applications/Utilities). See the Git installation video tutorial for an example on how to open the Terminal. You may want to keep Terminal in your dock for this workshop.

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 or Safari, or Internet Explorer version 9 or above).

You will need an account at github.com for parts of the Git lesson. Basic GitHub accounts are free. We encourage you to create a GitHub account if you don't have one already. Please consider what personal information you'd like to reveal. For example, you may want to review these instructions for keeping your email address private provided at GitHub.

Windows

Git can be installed on your computer following Bash install (described above).

  1. Open a Bash terminal window
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. In the start menu, search for "Ubuntu"
    3. Click the Ubuntu icon in the search results
    4. Click within the black Bash terminal screen that appears
  2. Use the apt package manager distributed with Ubuntu to install git
    1. Type sudo apt-get update and press enter
    2. When prompted for a password, enter the password established when installing Bash
    3. Type sudo apt-get install git and press enter
    4. If prompted for a password, again enter the password established when installing Bash

macOS

Video Tutorial

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 labeled "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 dnf 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.

Windows

nano is a basic editor that can be used for all the modules in this workshop, it is included in the Ubuntu distribution

macOS

nano is a basic editor and the default that instructors use in the workshop. See the Git installation video tutorial for an example on how to open nano. It should be pre-installed.

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

Linux

nano is a basic editor and the default that instructors use in the workshop. It should be pre-installed.

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

Python

Python is a popular language for research computing, and great for general-purpose programming as well. Installing all of its research 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.6 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. Install the Xming Windows X11 server
    1. Download the Xming installation wizard
      1. Click the Windows icon in the lower left corner of your screen to open the start menu
      2. In the start menu, search for "Edge"
      3. Click the Microsoft Edge icon in the search results
      4. In Microsoft Edge, click in the text field at the top of the window with the text Search or enter web address
      5. Type https://sourceforge.net/projects/xming/ into the text field and press enter.
      6. Click the green download button
      7. After a short delay, the web page will update and a prompt will appear at the bottom of the Microsoft Edge window.
      8. Select Run in the prompt
      9. An administrative prompt will appear. When prompted, click Yes to allow Xming installation wizard to modify your device
    2. Run the installation Wizard
      1. Click Next
      2. Select an installation location (or accept the default) and click Next
      3. Select Don't install an SSH client and click Next
      4. Click Next
      5. Click Next
      6. Click Install
  2. Start the X11 server
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. In the start menu, search for "xming"
    3. Click the Xming icon in the search results
  3. Open a Bash terminal window
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. In the start menu, search for "Ubuntu"
    3. Click the Ubuntu icon in the search results
    4. Click within the black Bash terminal screen that appears
  4. Forward X11 output
    1. Type echo export DISPLAY=:0 >> $HOME/.bashrc into the bash terminal and press enter
    2. Type source $HOME/.bashrc into the bash terminal and press enter
    3. Type sudo apt-get install x11-apps
    4. If prompted for a password, again enter the password established when installing Bash
    5. Type xeyes and press enter
    6. If a pair of cartoon eyes should appear on your screen, X11 forwarding has been configured
    7. Click the X along the edge of the window bar above the eyes
  5. Install a web browser within Ubuntu
    1. Type sudo apt-get install firefox into the bash terminal and press enter
    2. If prompted for a password, enter the password established when installing Bash
  6. Install python3
    1. Type sudo apt-get install python3 in the terminal and press enter
    2. If prompted for a password, enter the password established when installing Bash
    3. After accepting the installation
    4. Type which python and press enter
    5. Ensure this command prints a filepath ending in python3
  7. Install pip
    1. Type sudo apt-get install python3-pip in the terminal and press enter
    2. If prompted for a password, enter the password established when installing Bash
  8. Install python packages
    1. sudo apt-get install python3-numpy python3-matplotlib jupyter-notebook
    2. If prompted for a password, enter the password established when installing Bash
  9. Test python
    1. Type $ python into the terminal and press enter
    2. Within python terminal type
      
      import numpy matplotlib
      exit()
      	      
      This should return to the Bash terminal.
    3. Type jupyter-notebook into the terminal and press enter
    4. A website should launch automatically
    5. Close the browser

macOS

Video Tutorial
  1. Open https://www.anaconda.com/download/#macos 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/#linux with your web browser.
  2. Download the Python 3 installer for Linux.
    (The installation requires using the shell. If you aren't comfortable doing the installation yourself stop here and request help at the workshop.)
  3. Open a terminal window.
  4. Type
    bash Anaconda3-
    and then press tab. The name of the file you just downloaded should appear. If it does not, navigate to the folder where you downloaded the file, for example with:
    cd Downloads
    Then, try again.
  5. Press enter. You will follow the text-only prompts. To move through the text, press the space key. 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).
  6. Close the terminal window.

Make

GNU make is a tool for automating your workflow

Windows

  1. Open a Bash terminal window
    1. Click the Windows icon in the lower left corner of your screen to open the start menu
    2. In the start menu, search for "Ubuntu"
    3. Click the Ubuntu icon in the search results
    4. Click within the black Bash terminal screen that appears
  2. Install make
    1. Within the terminal, type apt install build-essential and press enter
    2. If prompted for a password, enter the password established when installing Bash
    3. Type which make and press enter to test

macOS

  1. It should already be installed
  2. Type
    $ which make
    to test

Linux

  1. It should already be installed
  2. Type
    $ which make
    to test