Getting Started with the Skeleton¶

This is meant for students who plan on programming in Python and will use the provided skeleton. We highly recommend doing so, since networking and some bookkeeping is done for you.

If you choose not to use the skeleton, we recommend reading this part about writing a custom client.

Dependencies¶

Python 3¶

Ensure Python 3 is installed. The easiest way to check is to do python --version or python3 --version in terminal. There are guides to install it on Mac OS, Windows, and Linux here.

You should also have an environment with git. If you need a refresher on how to use git, please read the 61b guide.

Pip Packages¶

Once you have Python 3 installed, get the following Pip packages: Flask, NetworkX, and requests.

To do so, run pip install flask==1.0.2 networkx==2.2 requests==2.18.4 --user. You may have to use pip3. If you are using Anaconda, instead do conda install flask networkx requests.

Downloading the Skeleton¶

The skeleton is located at https://github.com/Berkeley-CS170/project-sp19-skeleton.

We may update the skeleton in the future, and will announce if there is anything major you should know. For this reason and for collaboration with your teammates, we highly recommend cloning the skeleton and collaborating with Git. You can create private repositories for free using Github and share them with your teammates.

If you created a Github private repository at myuser/project170, this is the sequence of commands you should run to set up a local Git repository with the skeleton:

git clone https://github.com/myuser/project170
cd project170
git remote add skeleton https://github.com/Berkeley-CS170/project-sp19-skeleton
git pull skeleton master
git push -u origin master

Now if you visit https://github.com/myuser/project170, the skeleton should be there. You should see solver.py, client.py, local_server.py, and a number of folders.

DO NOT FORK THE SKELETON. You need to create a new, private repository, because the fork will be public and is prone to over-collaboration.

Writing your first solver¶

Suppose we wish to write a solver that has every student scout a random vertex, then randomly picks an edge to remote along 100 times. We don't recommend using this as your actual solver, but it allows us to demonstrate parts of the skeleton.

In solver.py, we start with:

import networkx as nx
import random

def solve(client):
    client.end()
    client.start()

    client.end()

This will simply connect to the server, terminate any existing rescues (client.end()), retrieve an instance (client.start()), then terminate (client.end()). Make sure you have a function called solve() that takes in a client in your solver! This is how we know where your code is.

Let's scout a random vertex with every student. list(range(1, client.home)) + list(range(client.home + 1, client.v + 1)) gives a list of the non-home vertices, client.students tells us how many students there are, and client.scout(vertex, students) allows us to scout given a vertex and a list of students. Note that students are 1-indexed.

import networkx as nx
import random

def solve(client):
    client.end()
    client.start()

    all_students = list(range(1, client.students + 1))
    non_home = list(range(1, client.home)) + list(range(client.home + 1, client.v + 1))
    client.scout(random.choice(non_home), all_students)

    client.end()

Next, we want to randomly remote 100 times. client.G stores the NetworkX graph, and client.remote(from, to) is used to remote given an edge.

import networkx as nx
import random

def solve(client):
    client.end()
    client.start()

    all_students = list(range(1, client.students + 1))
    non_home = list(range(1, client.home)) + list(range(client.home + 1, client.v + 1))
    client.scout(random.choice(non_home), all_students)

    for _ in range(100):
        u, v = random.choice(list(client.G.edges()))
        client.remote(u, v)

    client.end()

Testing your solver¶

To test locally, please do the following:

Run the local server using python local_server.py in terminal.

This will start a web server that your client will now connect to. It will pick a random input instance to serve. An instance is a set of parameters (such as bot locations or student correctness) of the problem.
In a separate terminal, run python client.py --solver solver. The --solver flag indicates the solver python file the client should use. It's the file name of your solver, with .py omitted.

In both terminals, you should see a slew of scout and remote calls succeeding. At the bottom of the client terminal your score is shown. The score should be very low (since it's unlikely all bots were moved home).

If there have been no problems thus far, then you're all set up! Please see our Policies page! If you've seen it already, then we recommend looking to see how to use the skeleton.