Computational Setup

SoftDes Windows Setup

This guide walks you through the steps necessary to set up your computer for the work you will do in this course. In a nutshell, these steps involve installing and configuring several applications on your computer. Once you have completed this setup, you should have all of the software tools you need to complete the worksheets and projects in this course.

This guide is written for Windows 10, which is the officially support operating system in the course. We have chosen Windows 10 because most, if not all, students in the course have a school-issued Windows 10 laptop. If you do not have a Windows laptop, you should still be able to complete most of the setup by downloading and running the appropriate file for your operating system (e.g. downloading the macOS version of an application instead).

We have split each step into a Context section that explains what you are doing and why, a Directions section that explains what to do, and a Check section with instructions for you to test that you have completed the step successfully. Reading the Context section isn’t necessary, but strongly recommended.

The setup has quite a few steps and may appear daunting at first. We ask that you try to follow these instructions as closely as you can, because we have done quite a bit of testing with these instructions and have confirmed that they work reasonably well for most student setups. If you run into any issues and need our help, it will be very helpful for us to know if and how you did anything differently from what these instructions specify. We are happy to provide help if you get stuck, so please do not hesitate to ask!

Install and Configure Windows Subsystem for Linux (WSL)

If you are using Linux or macOS, you can skip this step.

Context

Most previous iterations of this course were taught in Ubuntu Linux (website), and many subsequent computing courses are taught in a Linux environment. Because of this, much of our actual coding work will take place in an approximation of an Ubuntu system within your Windows operating system. Windows Subsystem for Linux (WSL) provides the infrastructure needed to install and run Ubuntu on Windows. You should begin by enabling and installing WSL on your machine, then installing Ubuntu.

After installing Ubuntu, you will make two small configuration changes. The first is adding a firewall configuration that allows your Ubuntu system to use network communications. The second is a change to make some keyboard shortcuts in WSL match those of Ubuntu.

Directions

Follow the official instructions for installing WSL on Windows 10 to enable and install WSL. As you follow these instructions, please note the following:

  • You only need to do Steps 1 and 3 of the linked guide: “Install the Windows Subsystem for Linux” and “Install your Linux distribution of choice”.
  • To open PowerShell as administrator, open the Start menu and begin to type “PowerShell” until the application option appears. You can then right-click and select “Run as administrator”, which will prompt you for confirmation.
  • When installing a Linux distribution, select “Ubuntu 20.04 LTS” as your distribution. The installation page has a link to the Microsoft store page that you can use, or you can search directly in the Microsoft store.

At this point, you should have WSL and Ubuntu installed on your machine. If everything has gone well, you should be able to select and launch the “Ubuntu 20.04 LTS” app from your Start menu. When you first launch Ubuntu, you will be prompted to create a new username and password. These do not have to match what you use for Windows, and can be whatever you’d like.

You may see a firewall warning when first starting Ubuntu. Allowing connections with the default configuration (on private networks only) is fine.

The next step is to configure Ubuntu to use Ctrl+Shift+C and Ctrl+Shift+V for copy and paste, respectively. This is standard in Linux environments like Ubuntu, but it is not set by default in WSL. To make this change, right-click the title bar at the top of the window and select Properties. In the Options tab (which is displayed by default), under the section Edit Options, check the box “Use Ctrl+Shift+C/V as Copy/Paste”. Then click OK to save this change.

Check

To test that everything works, launch Ubuntu. You should see a line ending in $ with a blinking cursor after it, and you should be able to type text. Try typing ping olin.edu and pressing Enter. You should see lines that look like this:

PING olin.edu (54.225.220.247) 56(84) bytes of data.
64 bytes from ec2-54-225-220-247.compute-1.amazonaws.com (54.225.220.247): icmp_seq=1 ttl=127 time=17.3 ms
64 bytes from ec2-54-225-220-247.compute-1.amazonaws.com (54.225.220.247): icmp_seq=2 ttl=127 time=22.8 ms
64 bytes from ec2-54-225-220-247.compute-1.amazonaws.com (54.225.220.247): icmp_seq=3 ttl=127 time=22.0 ms

A new line will appear around once every second. You should be able to stop this program by pressing Ctrl-C. If not, you may have forgotten to change the copy/paste shortcuts above. In this case, you can change the shortcut and then press Ctrl-C, or just close the Ubuntu window.

You should also be able to copy and paste text by selecting the desired text with your mouse and using Ctrl-Shift-C and Ctrl-Shift-V, respectively.

Install VS Code

Context

It is possible to write Python code in a plain text editor, such as Notepad, but you will likely find that this is a rather tedious and difficult process because plain text editors have no knowledge of Python’s formatting or syntax. For this course, we will use a code editor called Visual Studio Code (often called VS Code). We recommend this editor because it is widely used, free, and able to run on Windows, Mac, and Linux.

Directions

If you are on Ubuntu or macOS, you can follow these directions, but download the appropriate version of VS Code for your operating system. On other Linux distributions, we recommend checking your package manager first. If you are on macOS and using the Homebrew package manager, you may be able to use Homebrew Cask to install VS Code.

Go to the VS Code Download page and click the Windows button to download the installer. (By default, this will download the 64-bit User Installer whose link is just below the download button.) Run the installer, using all of the default options. (You can uncheck “Launch Visual Studio Code” at the end of the install process, as you should have the other components installed before configuring it.)

Check

To test that you have installed VS Code correctly, you can simply make sure that it launches for now. Later, we will perform another check to make sure that it is properly configured.

Create a GitHub account

Context

Git is a distributed version control system: there is no “master copy” of your code history, so each copy stands on its own. To share your code with others, it’s helpful to use a hosting service that stores an online copy of your code and its history. (The copy does not necessarily have to be publicly accessible, though this is often the reason for hosting your code online.) For this purpose, we will use GitHub. In this step, you will create a GitHub account.

Directions

If you don’t already have a GitHub account, go to https://github.com and create an account. Feel free to use any email address you want (or create one just for this account), but remember which email address you use, as you will need it when configuring Git on your computer (which is a later step in this guide). Your username does not have to be related to your actual name at all. That being said, like most usernames, it will be publicly visible, so if you plan on sharing code with the world, make sure you choose a username that you would be comfortable with others seeing.

Check

To test that you have correctly set up your GitHub account, go to https://github.com/username, replacing username with the username you created. You should see a profile page for your username. If you get a 404 page, you may not have completed the account creation process.

You may also want to check that you can log into your account.

Install Python/Anaconda

Context

Because virtually all code for this course will be written in Python, you will need to have the Python programming language installed on your computer. We recommend installing Python with Anaconda, particularly if you do not have much programming experience. Anaconda is a bundle of software that includes the Python programming language, a collection of useful additional libraries for data science, and some helpful support tools. You should install the Individual edition of Anaconda, which is free to download and use.

Directions

If you are not setting up a WSL system on Windows 10, do not follow the instructions below. Instead, go directly to the Anaconda Installation guide and follow the instructions for your operating system.

Head to Anaconda’s downloads page. At the bottom of this page, under the “Linux” column and in the section “Python 3.7”, copy the link location for the “64-bit (x86) Installer” (do not download this file normally).

Now launch the Ubuntu app on your machine. Once Ubuntu has started, you should be able to type in the window. Type wget URL into the window, pasting the link location you copied earlier in place of URL. Then press Enter/Return to run the command. You should see a dialog in the window as the file downloads. Look for a message that says something like 'Anaconda3-2020.02-Linux-x86_64.sh' saved.

Once you have done this, follow the instructions from Step 3 through 8 in Anaconda’s Installing on Linux guide. Please note the following during the installation process:

  • The terminal window mentioned throughout the guide refers in this case to the Ubuntu app.
  • In Step 3, be sure to use the line for Python 3.7.
  • In Step 5, if you do not want to agree to the license terms, please contact an instructor and we can help you with an alternate, non-Anaconda installation process.
  • In Step 6, the default install location is fine.
  • In Step 7, make sure to answer yes to having the installer initialize Anaconda, as it simplifies the setup process.

Check

To test if the installation succeeded, close Ubuntu if it is already running, then launch Ubuntu. If the installation was successful, you should see a prompt that starts with (base) after any welcome message that is shown.

If you don’t see (base), try typing conda and pressing Enter. If you see something like conda: command not found, then the installation did not complete successfully. You should be able to simply try the installation instructions again. If you instead see output that starts with usage: conda [-h] [-V] command ..., then you may not have answered “yes” to having the installer initialize Anaconda. In this case, you should be able to simply run conda init, and then close and re-launch Ubuntu.

Configure Git

Context

Good code is designed to be maintained: edited and improved over time. To track the history of revisions and to submit work in this course, we will use a version control system called Git. Because Git is already installed on WSL and on UNIX-based systems (Linux and macOS), you only need to properly configure it. This consists of (1) setting your name and email address so that services like GitHub can properly attribute your work to your account, and (2) setting VS Code as your default text editor for Git so that you can easily input and edit text when using Git. If you are familiar with Terminal-based text editors, step (2) is optional.

If you try to do other operations in Git without having set up your name and email, you will see a message that starts with something like *** Please tell me who you are. and whatever operation you were trying to do will fail.

Directions

To set your name in Git, run git config --global user.name "Alan Turing", substituting your name for Alan Turing (but leaving the quotes in place). This can be any name you want, though you should probably avoid using a name that may be seen an attempt to impersonate someone else (e.g., “Bill Gates”).

To set your email, run git config --global user.email "alan@turing.org", substituting your GitHub email address for alan@turing.org. It’s important that your email match the one that GitHub has, because a mismatch can make Git fail in unintuitive ways.

For this next step, if you are running in Linux or macOS, the specific command to launch VS Code may not be code; you should check this before making changes. To set the default text editor, run the command git config --global core.editor "code --wait".

If you mistyped your name, email, or the "code --wait" bit in the above steps, you can run the same command again with the correct name/email to fix the typo. If you mistyped user.name or user.email, you can use git config --unset user.naem (replacing user.naem with whatever you mistyped earlier) to remove that setting.

Check

You can check that this process was successful by running git config --list. If you see lines starting with user.name, user.email, and core.editor with the values you expect, then the process was successful.

Configure VS Code

Context

While you can run VS Code from the Start menu as you would with any other program, there are some oddities about the way it works with Anaconda and WSL that will likely cause unintuitive issues if you run it this way. Because of this, you should configure VS Code to work with Anaconda’s version of Python and with WSL. You will do this by installing extensions for VS Code.

Directions

Launch Ubuntu and run code (type it in and press Enter). The first time you run this command, it will do some setup on WSL, so it may take awhile.

Once it has started, you will need to install two extensions. Navigate to the extensions menu via File -> Preferences -> Extensions or by pressing Ctrl-Shift-X. Then search for and install the extensions “Remote - WSL” and “Python”, both from Microsoft.

Check

To check that you completed this step properly, launch VS Code if it is not already running by running the code command in Ubuntu. Once the VS Code window opens, make sure that the lower left corner shows a green box that says “WSL - Ubuntu”. If you do not see this, open the extensions menu as described above and make sure that the “Remote - WSL” extension shows as installed.

Then, open a new file from the File menu or by pressing Ctrl-N. Then save the (blank) file from the File menu or by pressing Ctrl-S. You can save the file under any name as long as it ends in .py. Once you do this, you may see a message that says “Select Python interpreter” as a popup or by the green box that says “WSL - Ubuntu”. Choose the interpreter that ends in “(‘base’: conda)” and make sure that it appears in the lower left corner. If you do not see this prompt, make sure that the “Python” extension is installed.

Once you have done this, you should be properly set up to complete Worksheet 0. In general, if you need to start VS Code in this course, you should do so through Ubuntu (by opening the app and running code), though you will not need to do this until Worksheet 2.

If you would like, there is some optional, additional setup you can do, described below.

Add an SSH key to GitHub (Optional)

This section is optional because it primarily adds a single convenience feature: not having to enter your GitHub username and password when performing certain operations in Git. We will gloss over much of the technical details of what this process actually does, instead focusing on how to get this working on your computer.

In a nutshell, adding an SSH (Secure Shell) key to your GitHub account involves creating a special credential on your computer that provides an alternate way of authenticating you to GitHub. In cryptography, this credential is called a public key. The process consists of two steps: creating the key on your computer, and telling GitHub what this key is.

To create the key, open Ubuntu and run the command ssh-keygen -t ecdsa. You will be presented with a series of prompts; unless you know what changing these prompts will do, you should use the default settings (just hit Enter) for all of them. (In this case, it is fine to use a completely blank passphrase for this process.) This will create two files id_ecdsa and id_ecdsa.pub. Never share the contents of id_ecdsa with anyone. Doing so after you have added the key to GitHub will allow whomever you share the file with to authenticate to GitHub as you with no password necessary.

To add the key to GitHub, log into your account on GitHub. Click on your profile picture in the upper-right corner of the page and select Settings. Click on “SSH and GPG keys”, and then click on the “New SSH key” button to get a form you can fill with the details of your key. For “Title”, use a name that will help you remember the computer that you are currently setting up. For “Key”, start Ubuntu and run cat .ssh/id_ecdsa.pub, copying the resulting text that appears and pasting this into the field. When submitting this form, you will likely be asked to reconfirm your GitHub password.

Once you have set up your key as described above, you can clone (download) a code repository to your computer with a different link which will free you from entering your username and password when working with the repository. As an example, if you visit the repository https://github.com/twbs/bootstrap, you will see a green button in the upper-right area of the page that says “Clone or download”, and if you click on it, you will likely see a box that says “Clone with HTTPS”. You can click on the “Use SSH” link in the upper-right corner of this box, and the link in the box will change. You can use this new link in place of the standard HTTPS link in any Git command.

Update Anaconda Packages (Optional)

At this point, we would also recommend upgrading Anaconda’s packages to the latest version. You can do this by starting Ubuntu and running conda upgrade --all. You should get a long-ish list of packages to upgrade, and prompt that says Proceed ([y]/n)?. In general, when you see a set of choices written like [y]/n or Y/n, pressing Enter without any input will cause the y (yes) option to run by default. Of course, you can also just type y and press Enter. The upgrade process might take a while. At the end of the process, you should see the message done and then the regular prompt. If you instead see error messages, contact a NINJA/instructor for help.