Project Repository and Infrastructure

Each team uses one shared GitHub repository for the Beyond Brute Force project. The repository is created through Classroom 50 and is used throughout all checkpoints and the final submission.

The repository has an explicit ownership boundary. Course-owned files provide common infrastructure and may be updated during the semester. Student-owned files contain your team’s algorithm implementations and will not be overwritten by a course infrastructure update.

Do not rename required files or directories unless the project instructions explicitly tell you to do so. Gradescope and the supplied project tools depend on this structure.

Creating Your Repository

Use the Classroom 50 assignment below to create your team’s Beyond Brute Force repository:

Start the Beyond Brute Force repository: Classroom 50 assignment

After the repository has been created, open it on GitHub, copy the clone URL, and clone it in the usual way:

git clone YOUR_REPOSITORY_URL
cd YOUR_REPOSITORY_DIRECTORY

The repository is the working copy for the entire project. It contains the course infrastructure, student implementation files, public test instances, local validation tools, benchmark collections, and the standard directories for experiments, reports, and presentation materials.

Public tests are included directly in the repository under:

tests/public/

and local checkpoint test runners are provided under:

tools/

Gradescope uses additional hidden tests, but students do not need to download a separate hidden or public test bundle.

Course-Owned and Student-Owned Files

The most important ownership rule is visible directly in the source tree:

src/course/     COURSE-OWNED
src/student/    STUDENT-OWNED

Course-owned source

Everything under:

src/course/

is maintained as part of the project. These files implement common data structures, input handling, problem dispatch, command-line support, and other infrastructure. Do not modify files under src/course/ unless the project instructions explicitly tell you to do so.

If a correction or infrastructure update is needed during the semester, the course may replace files under src/course/. Such an update will not overwrite files under src/student/.

The launcher:

src/solve.py

is also course-owned.

Student-owned source

Everything under:

src/student/

belongs to your team. This is where you implement the verifier, exhaustive solver, improved exact solver, heuristic algorithms, and bound required by the checkpoints.

Course infrastructure updates will not replace or overwrite files under src/student/.

Other repository locations

The ownership of other important paths is:

Repository Layout

The following tree shows the important parts of the repository. All five student problem directories are included in the template; the Minimum Vertex Cover directory is expanded here as an example.

beyondbruteforce/
├── README.md
├── project.json
│
├── examples/
│   ├── project_2_person.json
│   └── project_3_person.json
│
├── src/
│   ├── solve.py                              # COURSE
│   │
│   ├── course/                              # COURSE-OWNED
│   │   ├── __init__.py
│   │   ├── driver.py
│   │   │
│   │   ├── common/
│   │   │   ├── __init__.py
│   │   │   ├── graph.py
│   │   │   ├── graph_io.py
│   │   │   ├── graph6.py
│   │   │   ├── weighted_graph.py
│   │   │   └── weighted_graph_io.py
│   │   │
│   │   └── problems/
│   │       ├── __init__.py
│   │       ├── minimum_vertex_cover.py
│   │       ├── traveling_salesperson.py
│   │       ├── minimum_graph_coloring.py
│   │       ├── longest_path.py
│   │       └── maximum_clique.py
│   │
│   └── student/                             # STUDENT-OWNED
│       ├── __init__.py
│       └── problems/
│           ├── __init__.py
│           ├── traveling_salesperson/
│           ├── minimum_graph_coloring/
│           ├── longest_path/
│           ├── maximum_clique/
│           └── minimum_vertex_cover/
│               ├── __init__.py
│               ├── verifier.py
│               ├── bound.py
│               ├── exhaustive.py
│               ├── improved.py
│               ├── heuristic1.py
│               └── heuristic2.py
│
├── tests/
│   ├── public/                              # COURSE
│   └── student/                             # STUDENT
│
├── benchmarks/                              # COURSE core benchmark suites
├── experiments/                             # STUDENT
│   ├── scripts/                             # tracked
│   ├── results/                             # tracked when needed
│   └── local/                               # NOT tracked (except README)
├── reports/                                 # STUDENT
├── presentation/                            # STUDENT
│
└── tools/                                   # COURSE infrastructure

The exact set of course-owned support files may grow as later checkpoints introduce additional infrastructure. Required paths and public interfaces remain documented on the project website.

Python Packages and Imports

Student algorithms use data structures from the course package. For example, an unweighted graph algorithm imports:

from course.common.graph import Graph

and a weighted graph algorithm imports:

from course.common.weighted_graph import WeightedGraph

Student implementations live in packages such as:

src/student/problems/minimum_vertex_cover/
src/student/problems/traveling_salesperson/

Course infrastructure is responsible for selecting the assigned problem, reading the input, and locating the appropriate student solver. Student algorithm files should not implement their own command-line parser or input-file parser.

Common Driver

The command-line entry point remains:

src/solve.py

This small course-owned launcher invokes the shared driver under src/course/. The course infrastructure is responsible for:

• processing command-line arguments;
• selecting the requested problem;
• selecting the requested student algorithm;
• reading the input instance;
• constructing the common JSON result;
• writing output; and
• handling common errors.

Students should not reproduce this infrastructure in their algorithm files.

The command-line interface is defined on the Program Interface page.

Problem Implementations

Each problem has two complementary pieces.

The course-owned adapter handles routine infrastructure. For Minimum Vertex Cover, that adapter is:

src/course/problems/minimum_vertex_cover.py

The student-owned implementation directory contains the algorithmic work being assessed:

src/student/problems/minimum_vertex_cover/

For MVC, students implement:

src/student/problems/minimum_vertex_cover/verifier.py
src/student/problems/minimum_vertex_cover/exhaustive.py
src/student/problems/minimum_vertex_cover/improved.py
src/student/problems/minimum_vertex_cover/heuristic1.py
src/student/problems/minimum_vertex_cover/bound.py

Three-person teams also implement:

src/student/problems/minimum_vertex_cover/heuristic2.py

The same pattern is used for the other four project problems. The specification page for each problem defines the exact verifier, solution representation, and bound interface.

Tests

Course-provided test instances are stored under:

tests/public/

For an MVC team, for example:

tests/public/minimum_vertex_cover/

contains public instances that can be used while developing and validating the algorithms.

Your team should place additional tests that you create under:

tests/student/

Gradescope may use additional test instances that are not included in the repository. Hidden tests follow the same documented input formats and problem assumptions as the public tests.

Local checkpoint checks

Run checkpoint-specific public tests from the root of the repository. For example:

python tools/run_cp2_tests.py
python tools/run_cp3_tests.py

The local test runners show detailed diagnostics by default when student code raises an exception. When possible, the output identifies the student-owned file, line number, function, and source line that caused the exception. This is intended to make the local checker useful as a development and debugging tool.

If you want only compact PASS/FAIL messages, add --quiet:

python tools/run_cp2_tests.py --quiet

For Checkpoint 2, the public runner first tests the student verifier directly. Once those tests pass, public solver tests reuse that verifier to check the certificate returned by the solver while also checking the expected objective value and required result structure. If verifier tests fail, dependent solver tests are skipped. The private Gradescope grader validates solver results independently and does not trust the student verifier.

Input formats are documented on the Input Files page.

Project Information

The root-level:

project.json

contains team information, project preferences, and the assigned problem. The source-tree ownership change does not change the project.json schema.

The valid project identifiers are stored in:

tools/valid_projects.json

The same problem identifier is used by project.json, the command-line interface, Gradescope, experimental tools, and JSON result files.

After project assignment, the value of assigned_problem must agree with the problem identifier supplied to src/solve.py.

Experiments and Reports

Use the experiment directory according to this layout:

experiments/
├── scripts/     experiment or analysis scripts that should be committed
├── results/     results that should be preserved with the project
└── local/       machine-local files that are intentionally not committed

Files under experiments/scripts/ and experiments/results/ are normal repository files. Commit scripts and results that are required by a checkpoint or needed to reproduce the important conclusions of the project.

experiments/local/ is different. Except for its README, that directory is excluded by the repository’s .gitignore. Files placed there are not backed up by GitHub and are not included in normal repository submissions. Use it only for disposable or machine-local intermediate files. Do not place required source code, benchmark instances, final experimental results, checkpoint artifacts, or anything needed to reproduce your conclusions there.

Course-provided benchmark collections remain under benchmarks/; they should not be copied into experiments/local/.

Use:

reports/

for checkpoint reports and final written materials required by the assignment.

Use:

presentation/

for final presentation materials.

Your repository should contain enough information and supporting material for another person to reproduce the important experimental results described in your final submission.

Git and Submission 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 checkpoint that uses Gradescope, submit the current GitHub repository to the corresponding Gradescope assessment and include all team members in the Gradescope group.

The Gradescope autograder may check repository structure, required interfaces, basic correctness, and other mechanical requirements appropriate to that checkpoint.

Instructor-reviewed portions of the checkpoint are described on the Checkpoints and Final Submission page.

Responsibility for Submitted Work

Regardless of which tools or resources contributed to the project, your team is responsible for the contents of the repository.

Team members should be prepared to explain submitted code, verify that it is correct, modify it when necessary, and defend conclusions based on its output.