Project #1: Collatz
Due: Thu, 08 October 2026, 10pm
80 pts, 8% of total grade.

Specification

Write a program, individually or 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 70 points. The remaining 10 points are Cooperation points.
  • During the submission process, each student must independently submit a cooperation evaluation form separately from the project submission.
  • If you work with a partner, you will assign up to 10 points to your partner based on their contribution to the project.
  • Your cooperation score will be the number of cooperation points assigned to you by your partner.
  • If you complete the project individually, you must still submit the cooperation evaluation form and assign yourself the full 10 cooperation points.
  • If you work with a partner, you may discuss the point assignment with your partner and collectively consider a fair score. However, your final point assignment is your individual decision.
  • If you do not submit your cooperation evaluation form, you will receive 0 cooperation points.
  • If you receive a low cooperation score from your partner, further action may be taken to determine whether the score accurately reflects your contribution to the project.

Requirements

  1. Feel free to add helper functions, but don't modify the function interfaces.
  2. Estimate time to completion.
  3. Create a GitLab account if you do not already have one.
  4. 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/cs330e-collatz.git ) to become your private code repo (https://gitlab.com/<YourGitLabUsername>/collatz/).
        Fork, rename, and change visibility of public code repo, cs330e-collatz.
      • Locate the public code repo.
        • Log in to your GitLab account.
        • Click on "Explore projects", then click on "All".
        • Search for "cs330e-collatz".
        • Click on Fares Fraij / cs330e-collatz.
        • Click on Fork.
        • You will be asked to Select a namespace to fork the project; click on your namespace.
      • Rename the project name and path to collatz and change its visibility to private.
        • Click on the forked project.
        • Rename the forked project: Settings > General > Project name.
        • Change the path of the forked project: Settings > General > Advanced > Change path.
        • Replace cs330e-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 the collatz_eval method.
      • A feature example: Refactoring the collatz_eval method by extracting a helper 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 to your local computer.
    • 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.
  5. 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 into main after a successful GitLab CI pipeline.
    • 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 have not yet correctly implemented collatz_eval (it still returns 1 every time). When the correct output is not 1, the test will fail. You still run the unit tests to observe the expected failures and confirm that your test runner is working.
    • Write more unit tests in TestCollatz.py that test corner cases and failure cases until you have at least 3 unit tests for each required function/method, excluding helper functions. 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. Continue 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 input in RunCollatz.in that test corner cases, and create the corresponding expected output in RunCollatz.out.
    • 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 #3: Implement and debug a cache-based optimization.
    • Implement and debug the cache-based 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/cs330e-collatz-tests.git ) to your local computer.
      It is critical that you clone the public test repo into a different directory from the one you are using for your private code repo.
    • Copy your unit tests and 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 <YourGitLabUsername>-RunCollatz.in, <YourGitLabUsername>-RunCollatz.out, <YourGitLabUsername>-TestCollatz.py, and <YourGitLabUsername>-TestCollatz.out. <YourGitLabUsername> must be replaced with the GitLab username of the owner of the private code repo.
    • Uncomment the corresponding lines in the makefile that correspond to these files. Do not forget to add a "\" immediately after TestCollatz.py. 
      TestCollatz.py \
#    cs330e-collatz-tests/<YourGitLabUsername>-RunCollatz.in   \
#    cs330e-collatz-tests/<YourGitLabUsername>-RunCollatz.out  \
#    cs330e-collatz-tests/<YourGitLabUsername>-TestCollatz.out \
#    cs330e-collatz-tests/<YourGitLabUsername>-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.
  7. Phase #4 (Optional): Submit optimized code to Sphere.
    • Sphere submission is optional; however, SphereCollatz.py is a required project file.
    • If you attempt the Sphere submission, combine Collatz.py and RunCollatz.py into SphereCollatz.py and remove the unnecessary import.
    • Create an account on Sphere.
    • Submit SphereCollatz.py to Sphere and confirm the likely initial result of time limit exceeded or wrong answer.
    • Debug the code until it is accepted by Sphere, and add, commit, and push to the private code repo.
    • If you choose not to attempt the Sphere submission, you must still include SphereCollatz.py in your private repo. In this case, the file may be a placeholder containing a comment such as: 
      # Sphere submission not attempted.
  8. Phase #5: Finalization.
    • For educational purposes only (not required): Run cProfile to explore the runtime performance of your program.
    • Run pydoc on Collatz.py, which will create Collatz.html [make Collatz.html], documenting the interfaces to your functions.
      Create inline comments when needed to explain why a particular implementation was chosen.
      Use a consistent coding convention with good variable names, indentation, blank lines, and spacing (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 while on the main branch: 
      git rev-parse HEAD
      The SHA in your submission must correspond to your final Git commit on the main branch. Please do not make any changes to your private repo after you submit.
    • One submission per group by the project leader: the project leader must fill in the Canvas form. Rename your submission as follows: <YourGitLabUsername>-Project1.json, where <YourGitLabUsername> must be replaced with the GitLab username of the person making the project submission. If you work individually, you are the project leader.

Submission

The following must be provided. If anything is missing, the project 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 incomplete or broken, this process will repeat and you will receive another one-day late penalty.

  1. Your private code repo, collatz, with the graders invited as Maintainers, and containing the following files with these exact names and 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; cProfile is optional)
    7. RunCollatz.in contains between 100 and 200 lines with corresponding expected output in RunCollatz.out
    8. RunCollatz.out (no coverage output)
    9. TestCollatz.py (at least 3 unit tests for each required function/method, excluding helper functions)
    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.
      This file is required even though submission to Sphere is optional. If you attempted the Sphere submission, this file should contain the concatenated Sphere version of Collatz.py and RunCollatz.py. If you did not attempt the Sphere submission, this file may contain only: 
      # Sphere submission not attempted.
  2. The public test repo with the following files, using these exact names and no subfolders:
    1. <YourGitLabUsername>-RunCollatz.in (between 100 and 200 lines with corresponding expected output in <YourGitLabUsername>-RunCollatz.out).
    2. <YourGitLabUsername>-RunCollatz.out (no coverage output and no cProfile output)
    3. <YourGitLabUsername>-TestCollatz.py (at least 3 unit tests for each required function/method, excluding helper functions; do not run cProfile)
    4. <YourGitLabUsername>-TestCollatz.out (include coverage output and no cProfile output)
  3. GitLab issue tracker with at least 15 issues.
  4. An optimization in the form of a cache, 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.
  7. Each student must separately submit the Cooperation Points evaluation form. Students working individually must also submit this form and assign themselves 10 cooperation points.

Rubrics

  1. [5 pts] Quality of the repo.
    • at least 5 commits
    • git log
  2. [10 pts] Quality of the code.
  3. [15 pts] Quality of the issues.
    • at least 15 issues
  4. [10 pts] Quality of the unit tests.
    • at least 3 unit tests for each required function/method, excluding helper functions
    • coverage results
  5. [10 pts] Quality of the acceptance tests.
    • RunCollatz.in contains between 100 and 200 lines with corresponding expected output in RunCollatz.out
  6. [5 pts] Quality of the integration.
    • GitLab CI log
  7. [5 pts] Quality of the documentation.
    • pydoc output
  8. [10 pts] Quality of the Design (Cache Optimization).
    • appropriate implementation and use of the cache

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 project submission must be turned in for the pair. If two project submissions are made for the same pair, there will be a 10% penalty, and the later submission will be graded.
  • Five acceptance tests will be used to test your code. You may lose a maximum of 10 pts, 2 pts for each test your code fails to pass.
  • You receive 10 bonus pts for a solution accepted by Sphere.
  • Point deductions for missing or incomplete requirements are specified in the grading rubric.
  • Bonus pts will not increase the total score beyond the maximum score.

Tools

Guides

Graders

  Tommy Guo tmgu cs330e-collatz-tests
  Yusuf Sinan yusufsinan