Beyond Brute Force

This repository is the starting point for your team's Beyond Brute Force project, which explores exact and heuristic algorithms for NP-complete optimization problems.

Your team will use this repository throughout the project. All source code, tests, experimental materials, required checkpoint artifacts, and final presentation materials should be committed here.

Do not rename required files or directories unless the assignment instructions tell you to do so. Several project requirements are checked automatically.

Checkpoint 1: Project Selection and Setup

Checkpoint 1 is worth 5 project points. It establishes your team repository and records your ranked project choices. Complete the following steps before submitting to Gradescope:

1. Make sure every team member can access the shared repository.
2. Complete the root-level project.json file.
3. Every team member must make and push at least one meaningful commit to the shared repository.
4. Run the local setup checker and correct any reported problems.
5. Push the completed setup to GitHub.
6. Submit the current repository to the Checkpoint 1 Gradescope assignment.

The instructor may inspect the GitHub history to verify that every team member has participated in the repository setup.

Complete project.json

project.json is a small structured text file used by the course scripts and Gradescope. Edit the values in the file, but do not change the field names.

Completed examples for both two-person and three-person teams are available in examples/:

• examples/project_2_person.json
• examples/project_3_person.json

Your project.json records:

• your team name;
• each team member's name and GitHub username;
• your team's three project preferences, listed from most preferred to least preferred; and
• your assigned project, once the instructor has made assignments.

Leave assigned_problem as an empty string ("") for Checkpoint 1. After project assignments are announced, your team will update this field as directed by the instructor.

Project Identifiers

The valid project identifiers are stored in tools/valid_projects.json. Use an identifier from that file exactly as written. Your three project preferences must be different.

Check Your Setup Locally

Before submitting Checkpoint 1, run:

python tools/check_setup.py

The checker validates project.json and the required repository structure. Fix any reported problems, commit and push your changes, and run the checker again.

The local checker is provided for convenience. The Gradescope assessment is the official mechanical check and may perform additional validation.

Gradescope reports five 1-point checks: project.json format/fields, team information, project preferences, repository setup state, and GitHub/Gradescope group submission.

Repository Structure

File or directory	Purpose
README.md	Describes the repository structure and project workflow. As the project develops, add instructions for running programs and reproducing important results.
project.json	Stores team information, ranked project preferences, and the assigned project. Course scripts use this file, so do not rename its fields.
examples/	Contains completed two-person and three-person examples of project.json.
tools/	Contains course-provided utilities and the list of valid project identifiers.
src/	Contains algorithm implementations. Required filenames and interfaces will be specified for the assigned problem.
tests/	Contains test instances and other testing materials created by the team.
experiments/	Contains benchmark scripts, data, and analysis materials.
reports/	Contains required checkpoint artifacts and the final report.
presentation/	Contains materials for the final class presentation.

Git Workflow

This is a shared team repository. Every team member must be able to clone, edit, commit, and push. Commit work regularly rather than waiting until a checkpoint deadline.

At each formal checkpoint, your team will submit the current repository to the corresponding Gradescope assessment. Automated rubric items identify structural, interface, formatting, and basic correctness problems. You may correct those problems and resubmit before the deadline.

Responsibility for Submitted Work

AI tools and other programming resources may be used as permitted by the course policy. Regardless of how code, tests, or ideas are produced, your team is responsible for verifying them.

If material appears in this repository, team members should be prepared to explain what it does, test whether it is correct, modify it when necessary, and defend conclusions based on it.