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. In this step, you will install and configure both WSL and Ubuntu.

Directions #

As a note, the WSL installation instructions below are adapted from the official installation instructions - if you run into any issues, we encourage you to look through these instructions before seeking help.

To start, open PowerShell as administrator. To do this, open the Start menu and begin to type “powershell” until you see the application. Then, right-click and select “Run as administrator”.

Then paste the following command into PowerShell and press Enter:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

After this command is complete, restart your machine. Once your machine is back up, install Ubuntu 20.04 LTS from the Microsoft Store (link here).

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, which is used to run administrative commands on Ubuntu. 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.

On some Windows 10 systems, the above option for copy/paste may not appear. The most common fix for this seems to be to update Windows to the latest version. If you try this and you still do not see the option, ask the teaching team for help.

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. In general, Ctrl-C performs an interrupt operation on the running command, which in most cases simply stops the program.

If pressing Ctrl-C does not work, 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. Most importantly, make sure that “Add to PATH” remains checked. (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.

You may see a prompt to install plugins such as “Remote WSL”. You can go ahead and install these plugins now, but if not, later instructions will cover how to do so.

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. The officially support way to install Python in this course is with Anaconda, which 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. If you know what you are doing, you are free to look up and use a different installation approach, but if something goes wrong, it is unlikely that we can provide support. If you go the Anaconda route, you should install the Individual edition, 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.

These directions are adapted from the official Anaconda Linux installation instructions. If something goes wrong with the installation process, we recommend that you check there for a fix before asking for help.

Head to Anaconda’s downloads page. At the bottom of this page, under the “Linux” column and in the section “Python 3.8”, 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.07-Linux-x86_64.sh' saved.

Once you have downloaded the file, run the following command:

bash Anaconda3-2020.07-Linux-x86_64.sh

You will be prompted to review the license agreement. Press Enter to view the agreement. The agreement text will likely not fit in your window; you can press Space to move forward one page until you reach the end. At the end of the agreement, you will be prompted to type yes or no based on whether you accept the agreement. If you do not want to agree, contact the teaching team and we can help you with an alternate, non-Anaconda installation process.

If you choose to proceed, you will be prompted with a default installation location. This location is fine, and you can accept it simply by pressing Enter. Otherwise, you can specify a new location or press Ctrl-C to abort the installation.

The installation may take a while. If you find that it is taking an excessively long time, you can complete the “Configure VS Code” step below and return here when you are finished.

The installer will then ask if you want to initialize Anaconda. Answer yes to this question, as it sets up your Ubuntu installation to use Anaconda’s version of Python by default.

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. If you already installed the “Remote - WSL” extension when opening VS Code earlier, you do not need to do so again.

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 Assignment 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 Assignment 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.

Change the Ubuntu Color Scheme (Optional) #

The default color scheme for Ubuntu running in WSL may be unappealing to some. You can change the color scheme using Microsoft’s Color Tool.

Before downloading and using the Color Tool, however, you will need to install a program to unpack ZIP archives on Ubuntu. Open an Ubuntu window and run the following command:

sudo apt update

You may need to enter the password you set when you first opened Ubuntu. Then, run the following command:

sudo apt install unzip

To download Color Tool, run the following command:

wget https://github.com/microsoft/terminal/releases/download/1904.29002/ColorTool.zip

To unzip the file, run the following command:

unzip ColorTool.zip

To move into the newly unzipped folder, run the following command:

cd ColorTool

You can now see the names of the available color schemes by running the following command:

./ColorTool.exe -s

You can choose any of these color schemes to apply. As an example, if you want to try the OneHalfDark color scheme, run the following command:

./ColorTool.exe -q -x OneHalfDark.itermcolors

You should see the colors immediately change. Once you are satisfied with your choice, you can save your changes by running a command like the following:

./ColorTool.exe -q -d -x OneHalfDark.itermcolors

(Replace OneHalfDark.itermcolors with your preferred color scheme.) If you want to go back to your default color scheme that you started WSL with, it is likely that campbell-legacy.ini, campbell.ini, or cmd-legacy.ini is the color scheme you started with. Simply switch the scheme back to the one you prefer.