A

Getting Started

The labs in this curriculum aim to introduce computational and mathematical concepts, walk through
implementations of those concepts in Python, and use industrial-grade code to solve interesting,
relevant problems. Lab assignments are usually about 510 pages long and include code examples
(yellow boxes), important notes (green boxes), warnings about common errors (red boxes), and
about 37 exercises (blue boxes). Get started by downloading the lab manual(s) for your course from
http://foundations-of-applied-mathematics.github.io/.

Submitting Assignments
Labs
Every lab has a corresponding specications le with some code to get you started and to make your
submission compatible with automated test drivers. Like the lab manuals, these materials are hosted
at http://foundations-of-applied-mathematics.github.io/.
Download the .zip le for your course, unzip the folder, and move it somewhere where it
won't get lost. This folder has some setup scripts and a collection of folders, one per lab, each of
which contains the specications le(s) for that lab. See Student-Materials/wiki/Lab-Index for
the complete list of labs, their specications and data les, and the manual that each lab belongs to.

Achtung!

Do notmove or rename the lab folders or the enclosed specications les; if you do, the test
drivers will not be able to nd your assignment. Make sure your folder and le names match
Student-Materials/wiki/Lab-Index.

To submit a lab, modify the provided specications le and use the le-sharing program
specied by your instructor (discussed in the next section). The instructor will drop feedback
les in the lab folder after grading the assignment. For example, the Introduction to Python lab
has the specications le PythonIntro/python_intro.py. To complete that assignment, modify
PythonIntro/python_intro.py and submit it via your instructor's le-sharing system. After grad-
ing, the instructor will create a le called PythonIntro/PythonIntro_feedback.txt with your score
and some feedback.

1
2 Appendix A. Getting Started

Homework
Non-lab coding homework should be placed in the _Homework/ folder and submitted like a lab
assignment. Be careful to name your assignment correctly so the instructor (and test driver) can nd
it. The instructor may drop specications les and/or feedback les in this folder as well.

Setup

Achtung!

We strongly recommend using a Unix-based operating system (Mac or Linux) for the labs.
Unix has a true bash terminal, works well with git and python, and is the preferred platform
for computational and data scientists. It is possible to do this curriculum with Windows, but
expect some road bumps along the way.

There are two ways to submit code to the instructor: with git (http://git-scm.com/), or with
a le-syncing service like Google Drive. Your instructor will indicate which system to use.

Setup With Git

Git is a program that manages updates between an online code repository and the copies of the
repository, called clones, stored locally on computers. If git is not already installed on your computer,
download it at http://git-scm.com/downloads. If you have never used git, you might want to read
a few of the following resources.

ˆ Ocial git tutorial: https://git-scm.com/docs/gittutorial

ˆ Bitbucket git tutorials: https://www.atlassian.com/git/tutorials

ˆ GitHub git cheat sheet: services.github.com/.../github-git-cheat-sheet.pdf

ˆ GitLab git tutorial: https://docs.gitlab.com/ce/gitlab-basics/start-using-git.html

ˆ Codecademy git lesson: https://www.codecademy.com/learn/learn-git

ˆ Training video series by GitHub: https://www.youtube.com/playlist?list=PLg7.../

There are many websites for hosting online git repositories. Your instructor will indicate which
web service to use, but we only include instructions here for setup with Bitbucket.

1. Sign up. Create a Bitbucket account at https://bitbucket.org. If you use an academic email
address (ending in .edu, etc.), you will get free unlimited public and private repositories.

2. Make a new repository. On the Bitbucket page, click the + button from the menu on the
CREATE
left and, under Repository
, select . Provide a name for the repository, mark the
private
repository as , and make sure the repository type is Git . ForInclude a README? ,
No
select (if you accidentally include a README, delete the repository and start over). Un-
der Advanced settings No forks
, enter a short description for your repository, select un-
Python
der forking, and select as the language. Finally, click the blueCreate repository
button. Take note of the URL of the webpage that is created; it should be something like
https://bitbucket.org/<name>/<repo>.
 3

3. Give the instructor access to your repository. On your newly created Bitbucket repository
page (https://bitbucket.org/<name>/<repo> or similar), go to Settings in the menu to
the left and selectUser and group access , the second option from the top. Enter your
Users
instructor's Bitbucket username under and clickAdd Write
. Select the blue button so
your instructor can read from and write feedback to your repository.

4. Connect your folder to the new repository. In a shell application (Terminal on Linux or Mac,
or Git Bash (https://gitforwindows.org/) on Windows), enter the following commands.

# Navigate to your folder.

$ cd /path/to/folder # cd means 'change directory'.

# Make sure you are in the right place.

$ pwd # pwd means 'print working directory'.
/path/to/folder
$ ls *.md # ls means 'list files'.
README.md # This means README.md is in the working directory.

# Connect this folder to the online repository.

$ git init
$ git remote add origin https://<name>@bitbucket.org/<name>/<repo>.git

# Record your credentials.

$ git config --local user.name "your name"
$ git config --local user.email "your email"

# Add the contents of this folder to git and update the repository.
$ git add --all
$ git commit -m "initial commit"
$ git push origin master

For example, if your Bitbucket username is greek314, the repository is called acmev1, and the
folder is called Student-Materials/ and is on the desktop, enter the following commands.

# Navigate to the folder.

$ cd ~/Desktop/Student-Materials

# Make sure this is the right place.

$ pwd
/Users/Archimedes/Desktop/Student-Materials
$ ls *.md
README.md

# Connect this folder to the online repository.

$ git init
$ git remote add origin https://greek314@bitbucket.org/greek314/acmev1.git

# Record credentials.
$ git config --local user.name "archimedes"
4 Appendix A. Getting Started

$ git config --local user.email "greek314@example.com"

# Add the contents of this folder to git and update the repository.
$ git add --all
$ git commit -m "initial commit"
$ git push origin master

At this point you should be able to see the les on your repository page from a web browser. If
you enter the repository URL incorrectly in the git remote add origin step, you can reset
it with the following line.

$ git remote set-url origin https://<name>@bitbucket.org/<name>/<repo>.git

5. Download data les. Many labs have accompanying data les. To download these les, navi-
gate to your clone and run the download_data.sh bash script, which downloads the les and
places them in the correct lab folder for you. You can also nd individual data les through
Student-Materials/wiki/Lab-Index.

# Navigate to your folder and run the script.

$ cd /path/to/folder
$ bash download_data.sh

6. Install Python package dependencies. The labs require several third-party Python packages
that don't come bundled with Anaconda. Run the following command to install the necessary
packages.

# Navigate to your folder and run the script.

$ cd /path/to/folder
$ bash install_dependencies.sh

7. (Optional) Clone your repository. If you want your repository on another computer after
completing steps 14, use the following commands.

# Navigate to where you want to put the folder.

$ cd ~/Desktop/or/something/

# Clone the folder from the online repository.

$ git clone https://<name>@bitbucket.org/<name>/<repo>.git <foldername>

# Record your credentials in the new folder.

$ cd <foldername>
$ git config --local user.name "your name"
$ git config --local user.email "your email"

# Download data files to the new folder.

$ bash download_data.sh
 5

Setup Without Git

Even if you aren't using git to submit les, you must install it (http://git-scm.com/downloads)
in order to get the data les for each lab. Share your folder with your instructor according to their
directions, and follow steps 5 and 6 of the previous section to download the data les and install
package dependencies.

Using Git
Git manages the history of a le system through commits, or checkpoints. Use git status to see
the les that have been changed since the last commit. These changes are then moved to the staging
area, a list of les to save during the next commit, with git add <filename(s)>. Save the changes
in the staging area with git commit -m "<A brief message describing the changes>".

Staged: the files with changes

to be saved at commit time
git log:
a record of all
git reset HEAD -- "<filename>" commit messages
(unstage changes)
git add "<filename>" New Commit
(stage changes) git commit -m "<message>" Previous Commit
Modified: the files with (save changes)
changes since the last commit ...

git checkout -- "<filename>" Second Commit

(discard changes) First Commit
Modify file

Tracked: the files that have

Untracked: the files that have
been added to git, but with no
never been added to git
changes since the last commit

Figure A.1: Git commands to stage, unstage, save, or discard changes. Commit messages are recorded
in the log.

All of these commands are done within a clone of the repository, stored somewhere on a com-
puter. This repository must be manually synchronized with the online repository via two other git
commands: git pull origin master, to pull updates from the web to the computer; and git
push origin master, to push updates from the computer to the web.

Online Repository

git push origin master git pull origin master

Computer

Figure A.2: Exchanging git commits between the repository and a local clone.
6 Appendix A. Getting Started

Command Explanation
git status Display the staging area and untracked changes.
git pull origin master Pull changes from the online repository.
git push origin master Push changes to the online repository.
git add <filename(s)> Add a le or les to the staging area.
git add -u Add all modied, tracked les to the staging area.
git commit -m "<message>" Save the changes in the staging area with a given message.
git checkout -- <filename> Revert changes to an unstaged le since the last commit.
git reset HEAD -- <filename> Remove a le from the staging area.
git diff <filename> See the changes to an unstaged le since the last commit.
git diff --cached <filename> See the changes to a staged le since the last commit.
git config --local <option> Record your credentials (user.name, user.email, etc.).

Table A.1: Common git commands.

Note

When pulling updates with git pull origin master, your terminal may sometimes display
the following message.

Merge branch 'master' of https://bitbucket.org/<name>/<repo> into master

# Please enter a commit message to explain why this merge is necessary,

# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.
~
~

This means that someone else (the instructor) has pushed a commit that you do not yet have,
while you have also made one or more commits locally that they do not have. This screen,
displayed in vim (https://en.wikipedia.org/wiki/Vim_(text_editor)), is asking you to
enter a message (or use the default message) to create a merge commit that will reconcile both
changes. To close this screen and create the merge commit, type :wq and press enter.

Example Work Sessions

$ cd ~/Desktop/Student-Materials/
$ git pull origin master # Pull updates.
### Make changes to a file.
$ git add -u # Track changes.
$ git commit -m "Made some changes." # Commit changes.
$ git push origin master # Push updates.
 7

# Pull any updates from the online repository (such as TA feedback).

$ cd ~/Desktop/Student-Materials/
$ git pull origin master
From https://bitbucket.org/username/repo
* branch master -> FETCH_HEAD
Already up-to-date.

### Work on the labs. For example, modify PythonIntro/python_intro.py.

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

PythonIntro/python_intro.py

# Track the changes with git.

$ git add PythonIntro/python_intro.py
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

modified: PythonIntro/python_intro.py

# Commit the changes to the repository with an informative message.

$ git commit -m "Made some changes"
[master fed9b34] Made some changes
1 file changed, 10 insertion(+) 1 deletion(-)

# Push the changes to the online repository.

$ git push origin master
Counting objects: 3, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 327 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://username@bitbucket.org/username/repo.git
5742a1b..fed9b34 master -> master

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean