Project #1: Collatz
Due: Thu, 20 June 2024, 10pm
120 pts, 12% of total grade.

Specification

Write a program, ideally with a partner, to solve The 3n+1 Problem in Python with an optimization in the form of a cache:

Analysis

These are additional descriptions of the underlying math:

Cooperation Points

  • The content of this project is worth 100 points. The remaining 20 points are Cooperation points.
  • During the submission process, each student will independently submit an evaluation form seperately from the project submission.
  • In this form, you will assign 20 points to your partner based on their contribution to the project.
  • Your cooperation score is the cooperation points assigned to you by your partner.
  • You cannot give points to yourself.
  • You are free to discuss the point assignments with your partner and collectively plan a fair distribution. However, your final point assignments is up to you.
  • If you do not submit your evaluation form, you will receive 0 cooperation points.
  • If you receives a low cooperation score, further action may be taken.

Requirements

  1. Estimate time to completion
  2. Get a GitLab account at GitLab
  3. Phase #1: Fork and clone the public code repo and run the unit tests and acceptance tests
    • Fork the public code repo ( https://gitlab.com/fareszf/cs373-collatz.git) to become your private code repo (https://gitlab.com/YourGitLabID/collatz/)
        Fork, rename, and change visibility of public code repo, cs373-collatz
      • Locate the public code repo
        • Login to your GitLab account
        • Click on “Explore projects”, then click on “All”
        • Search for “cs373-collatz”
        • Click on Fares Fraij / cs373-collatz
        • Click on Fork
        • You’ll be asked to Select a namespace to fork the project, click on your namespace.
      • Rename the project name and path to become collatz and change its visibility to private
        • Rename: Settings > General > Project name
        • Change the path: Settings > General > Advanced > Change path
        • Replace cs373-collatz with “collatz”
        • Change visibility: Settings > General > “Visibility, project features, permissions” Change the visibility to private
    • Add at least 10 issues from these requirements to the issue tracker at GitLab
      Add at least 5 more issues during the lifetime of the project, one for each bug or feature, with a good description and a label
      • a bug example: Currently stuck in an infinite loop due to a computation error in the main loop in collatz_eval method
      • a feature example: Refactoring collatz_eval method by extracting a helping function
    • Make at least 5 commits, one for each bug or feature during the lifetime of the project.
      If you cannot describe your changes in a sentence, you are not committing often enough.
      Make meaningful commit messages identifying the corresponding issue in the issue tracker (see closing issues via commit messages).
    • Invite the graders to your private code repo as maintainers
    • Clone your private code repo onto your local directory
    • Run the given unit tests and acceptance tests [make test], confirm the expected successes, and add, commit, and push to the private code repo
      • Before continuing, confirm a successful build on GitLab CI
  4. Phase #2: fix the given unit tests and acceptance tests and implement collatz_eval() in Collatz.py
    • Create a dev branch in git (see git branching and merging)
    • Only merge with the main after a successful build on GitLab CI
    • Fix the given unit tests, confirm the expected failures, and add, commit, and push to the private code repo.
      Failure cases happen when your tests are valid but you haven't correctly implemented collatz_eval (it still returns 1 every time). So, when the correct output is not 1 the test will fail. You still run the unit tests to see the expected failures to be sure that your test runner is working.
    • Write more unit tests in TestCollatz.py that test corner cases and failure cases until you have an average of 3 tests for each function/method, confirm the expected failures, and add, commit, and push to the private code repo
    • Run coverage to confirm that your tests have good code coverage
    • Implement and debug the simplest possible solution in collatz_eval() in Collatz.py with assertions that check pre-conditions, post-conditions, argument validity, and return-value validity, until all tests pass, and add, commit, and push to the private code repo
    • Before continuing, confirm a successful build on GitLab CI
    • Create between 100 and 200 lines of acceptance tests in RunCollatz.in and RunCollatz.out that test corner cases
    • Run the modified unit tests and acceptance tests [make test], confirm the expected successes, and add, commit, and push to the private code repo
      • Before continuing, confirm a successful build on GitLab CI
  5. Phase #3: implement and debug the simplest optimization
    • Implement and debug the simplest optimization until all tests pass, and add, commit, and push to the private code repo
    • Before continuing, confirm a successful build on GitLab CI
    • Fork and clone the public test repo ( https://gitlab.com/fareszf/cs373-collatz-tests.git) onto your local directory
      It is critical that you clone the public test repo into a different directory than the one you're using for your private code repo
    • Copy your unit tests and your acceptance tests to your clone of the public test repo, rename the files, do a git pull to synchronize your clone, and then add, commit and make a merge request to the public test repo
      The files MUST be named YourGitLabID-RunCollatz.in, YourGitLabID-RunCollatz.out, YourGitLabID-TestCollatz.py, and YourGitLabID-TestCollatz.out in the public test repo (YourGitLabID must be identical to the name of the private code repo).
    • Uncoment the corresponding lines in the makefile that corresponds to these files (don't forget to add a “ \” right after TestCollatz.py) 
      					    TestCollatz.py

#    cs373-collatz-tests/YourGitLabID-RunCollatz.in   \
#    cs373-collatz-tests/YourGitLabID-RunCollatz.out  \
#    cs373-collatz-tests/YourGitLabID-TestCollatz.out \
#    cs373-collatz-tests/YourGitLabID-TestCollatz.py  \
#
    • Run the modified unit tests and acceptance tests [make test], confirm the expected successes, and add, commit, and push to the private code repo
      • Before continuing, confirm a successful build on GitLab CI
  6. Phase #4: Submit optimized code to Sphere
    • Combine Collatz.py and RunCollatz.py into SphereCollatz.py (don't forget to remove all import statements except "import sys")
    • Create an account on Sphere
    • Submit SphereCollatz.py to Sphere and confirm the likely result of time exceeded or wrong answer
    • Debug the code until it's accepted by Sphere, and add, commit, and push to the private code repo
    • It's your responsbility to pass Sphere. We don't vet, review or debug your code.
  7. Phase #5: Finalization
    • Run cProfile to check for runtime inefficiencies
    • Run pydoc on Collatz.py, which will create Collatz.html [make Collatz.html], that then documents the interfaces to your functions
      Create inline comments if you need to explain the why of a particular implementation
      Use a consistent coding convention with good variable names, good indentation, blank lines, and blank spaces (see Google Python Style Guide)
    • Run autopep8, which will format your code in a standard way [make format]
    • Create a log of your commits in Collatz.log [make Collatz.log]
    • Obtain the git SHA with (must be on main branch)
      git rev-parse HEAD
      The SHA in you submission must correspond to your final Git commit on main branch. So, please do not make any changes to your private repo after you submit.
    • Fill in the Canvas form (don't forget to rename your submission as follows "YourUTEID-Project1.json")

Submission

The following must be provided. If anything is missing it will not be graded. You will be informed within 24 hrs if it is incomplete, and you will have 24 hrs to resubmit it. You must e-mail the graders when you resubmit it, and you will receive a one-day late penalty. If the resubmission is still broken this process will repeat and you'll lose another one-day penalty.

  1. Your private code repo, collatz, with graders invited as Maintainers and with the following files, with these exact names, no subfolders:
    1. .gitignore
    2. .gitlab-ci.yml
    3. makefile
    4. requirements.txt
    5. Collatz.py (do not change the interfaces)
    6. RunCollatz.py (do not run coverage, run cProfile)
    7. RunCollatz.in (between 100 and 200 lines)
    8. RunCollatz.out (no coverage output, no cProfile output)
    9. TestCollatz.py (average of 3 unit tests per function/method, run coverage-3.5)
    10. TestCollatz.out (include coverage output)
    11. Collatz.html (output of pydoc)
    12. Collatz.log (output of git log with at least 5 commits)
    13. SphereCollatz.py (concatenation of Collatz.py and RunCollatz.py)
  2. The public test repo with the following files, with these exact names, no subfolders:
    1. YourGitLabID-RunCollatz.in (between 100 and 200 lines)
    2. YourGitLabID-RunCollatz.out (no coverage output, no cProfile output)
    3. YourGitLabID-TestCollatz.py (average of 3 unit tests per function/method, run coverage3, do not run cProfile)
    4. YourGitLabID-TestCollatz.out (include coverage output, no cProfile output)
  3. GitLab issue tracker with at least 15 issues.
  4. An optimization in the form of a cache, and with a successful build on GitLab CI.
  5. It is your responsibility to protect your code from the rest of the students in the class. If your code gets out, you are as guilty as the recipient of academic dishonesty.
  6. Canvas form with GitLab Pipelines and time estimate.

Rubrics

  1. [10 pts] Quality of the repo.
    • at least 5 commits
    • git log
  2. [15 pts] Quality of the code.
  3. [15 pts] Quality of the issues.
    • at least 15 issues
  4. [15 pts] Quality of the unit tests.
    • average of three unit tests per function/method
    • coverage results
  5. [15 pts] Quality of the acceptance tests.
    • between 100 and 200 lines
  6. [10 pts] Quality of the integration.
    • GitLab CI log
  7. [10 pts] Quality of the documentation.
    • pydoc output
  8. [10 pts] Passing the Sphere challenge.
    • SphereCollatz.py must be included in your submission

Bonuses and Penalties

  • If you work with a partner using pair programming, you must vouch for the fact that you worked on the project together for more than 75% of the time (write that in the comment section of your JSON file submission).
    Only one solution must be turned in for the pair. If two solutions are turned in, there will be a 10% penalty, and the later one will be graded.
  • Five acceptance tests will be used to test your code. You lose a max of 10 pts, 2 pts for every test your code fails to pass.
  • You loose 2 points for each missing requirement.
  • Bonus pts will not increase the total score beyond the max score.

Tools

Guides

Graders

  Name   GitLab ID   Public Test Repo
  Pranav Venkatesh Pranav-V cs373-collatz-tests
  Vrishank Viswanath vrishank