Milestone 1

Due: Tuesday, October 29th at 11:59 PM

You will now begin your final project to develop a Python package for automatic differentiation. Please get together with your project group and complete the tasks below for Milestone 1.

Steps to complete

1. Form a GitHub organization (with a descriptive team name).
   1. Do not use cs207_project or cs207_group# as your Github organization name. Come up with a creative organization name.
   2. Please give all of the teaching staff access.
2. You can have as many repositories as you like within your organization. However, we will only grade the repository called cs207-FinalProject. This repo is where all of your project code must live.
   1. Update the README.md file at the root of your repo with your group number and the names of your group members.
   2. Set up Travis CI and CodeCov for your project repo. Make sure your README.md file includes badges indicating how many tests are passing and the coverage of your code.
   3. Note: It is ok if you do not have any tests implemented at the time of submission for this milestone, but you should still show badges for when you develop code and tests.
3. Protect your master branch in your cs207-FinalProject repo. All of your code for your project should be developed on other branches, and then merged into master through a PR.
   1. Click on the Settings tab on the homepage of your repo.
   2. Click on the Branches tab on the left-side panel.
   3. Click on the Add rule button on the right-side of the screen.
   4. Enter master in the text box under Branch name pattern.
   5. Check the box next to Require pull request reviews before merging. Select 1 in the drop-down menu that reads Required approving reviews. Whenever a team member wants to add code to the master branch, at least one other team member must review and approve of the code.
   6. Check the box next to Dismiss stale pull request approvals when new commits are pushed. Your screen should be identical to the screenshot below.
   7. Click the green Create button at the bottom of the page.
   8. If you click on the Branches tab on the left-side panel, you should see one rule for master under Branch protection rules.
4. Within your cs207-FinalProject repo, you must set up Travis CI and CodeCov. Make sure the README.md file at the root of your repo includes badges indicating how many tests are passing and the coverage of your code.

5. One group member must fill out this Google form with your group # and the URL to your group's cs207-FinalProject repo.

6. Within your final project repo, you should create a directory called docs. You can use this directory to organize documentation and tutorials for your final package.

   1. For Milestone 1, you should have a file called milestone1. The type of file is up to you and your group. Two good choices are markdown (milestone1.md) or a Jupyter notebook (milestone1.ipynb).
   2. Read the Milestone1 Document section below for what your milestone1 document should contain.
   3. Your milestone1 document submission should be in the following format:

cs207-FinalProject/
             README.md
             docs/  
                  milestone1
             ...

The teaching staff will only be able to give you a grade if you follow the exact structure just outlined!

Milestone1 Document

You must clearly outline your software design for the project. This is the main deliverable for this milestone. We are checking to make sure you have a realizable software design, that you understand the scope of the project, and that you understand the details of the project. Here are some sections your group should include in your document along with some prompts that you will want to address.

Introduction

Describe the problem the software solves and why it's important to solve that problem.

Background

Describe (briefly) the mathematical background and concepts as you see fit. You do not need to give a treatise on automatic differentation or dual numbers. Just give the essential ideas (e.g. the chain rule, the graph structure of calculations, elementary functions, etc). Do not copy and paste any of the lecture notes. We will easily be able to tell if you did this as it does not show that you truly understand the problem at hand.

How to Use PackageName

How do you envision that a user will interact with your package? What should they import? How can they instantiate AD objects?

Note: This section should be a mix of pseudo code and text. It should not include any actual operations yet. Remember, you have not yet written any code at this point.

Software Organization

Discuss how you plan on organizing your software package.

• What will the directory structure look like?
• What modules do you plan on including? What is their basic functionality?
• Where will your test suite live? Will you use TravisCI? CodeCov?
• How will you distribute your package (e.g. PyPI)?
• How will you package your software? Will you use a framework? If so, which one and why? If not, why not?
• Other considerations?

Implementation

Discuss how you plan on implementing the forward mode of automatic differentiation.

• What are the core data structures?
• What classes will you implement?
• What method and name attributes will your classes have?
• What external dependencies will you rely on?
• How will you deal with elementary functions like sin, sqrt, log, and exp (and all the others)?

Be sure to consider a variety of use cases. For example, don't limit your design to scalar functions of scalar values. Make sure you can handle the situations of vector functions of vectors and scalar functions of vectors. Don't forget that people will want to use your library in algorithms like Newton's method (among others).

Document Length

Try to keep your report to a reasonable length. It will form the core of your documentation, so you want it to be a length that someone will actually want to read. Since some of you will use Markdown while others will use Jupyter notebooks and still other group use Latex, we cannot standardize a page length. Use your best judgement. You will only lose points if your document is overly terse (e.g. you do not discuss aspects outlined above) or unbearably long (e.g. you provide so much information that it obscures the message).

Additional Comments

There is no need to have an implementation started for Milestone 1. You are currently in the planning phase of your project. This means that you should feel free to have a project_planning repo in your project organization for scratch work and code.
The actual implementation of your package will start after Milestone 1.

Final Deliverables

There are three primary requirements for this first milestone.

1. Create a project organization and invite the teaching staff.
   • Within the project organization, create a project repo (make sure teaching staff has access).
   • Protect your master branch.
2. Create a README.md inside the project repo. At this point, the README should include your the group number, a list of the members on your the team, and badges for Travis CI and CodeCov.
3. Fill out this Google form for your group.
4. The docs/ directory should include a document called milestone1 (the extension is up to you, but .md or .ipynb are recommended. Details on how to create milestone1 are provided in the Milestone 1 Document section above.

Grading breakdown

Total: 20 points