Skip to content

Using the Skeleton

Contents

Here you can find a description of what the skeleton contains.

  • solver.py: This is where you will be writing your solution. All your code should go in here.
  • client.py: This is our skeleton that connects to servers and does bookkeeping, (hopefully) making your life easier. We don't recommend modifying client.py.
  • local_server.py: This is the local testing server that will pretend to be the official evaluation server during testing. You can modify this to make it serve the client anything you need, but note that the local server is an accurate emulation of the remote evaluation server, so if your client performs differently against the evaluation server because the local server was modified, we do not take responsibility.
  • test_graphs/: A number of local testing graphs and instances are found here. Graphs are stored in a json edgelist format are found here. You're welcome to create graphs of your own to test with. You can find their format below.
  • eval_graphs/: A number of evaluation graphs without instances. Please don't modify these graphs since they will also be used to evaluate your code - the evaluation server shares the same graphs.

Client Class

Your solver will be provided an instance of the Client class. This client should be how you interact with the local or remote servers. You can read and modify the client.py code, but note that we are not responsible for any issues caused by modifying the client.

Methods

Client has 5 relevant methods:

  • client.start(): This tells the server you are starting a rescue. The server responds with the instance data, which the client automatically stores. Returns True on success, False on error.
  • client.scout(vertex, students): Scout at a vertex with some set of students. Both are 1-indexed. Returns a dictionary where the key is the student number, and the value is the student's response. None on error.
  • client.remote(from, to): Remote all bots along the from->to edge. Both are 1-indexed. Returns the number of bots remoted, None on error.
  • client.end(): This tells the server you are ending your rescue. You may end the rescue pre-maturely, for a worse score. Returns True on success, False on error.
  • client.submission(): Retrieves and locally saves your submit token from the evaluation server. Does not use up or affect any rescues. Also useful for checking how many rescues you have completed and have remaining. Returns True on success, False on error.

Instance Variables

Client remembers the instance's variables:

  • client.G, client.graph, or client.city: The networkx graph that you will be rescuing on.
  • client.h or client.home: An integer value; the home vertex that you must return all bots to.
  • client.k or client.students: An integer value; the number of students you can ask to scout.
  • client.l or client.bots: An integer value; the number of bots in the city.
  • client.s or client.scout_time: An integer value representing the time it takes for one student to scout one vertex.
  • client.n or client.v: An integer value; the number of vertices in the graph.
  • client.m or client.e: An integer value; the number of edges in the graph.

Bookkeeping

Client also does some bookkeeping for you:

  • client.time: An integer value; the amount of time elapsed thusfar.
  • client.cant_scout: A list of sets, 1-indexed by student number. Each set stores the vertices that the student cannot scout.
  • client.bot_count: A list of integers, 1-indexed by vertex number. Each entry represents the number of known bots at that vertex.
  • client.bot_locations: A list of integers representing the vertices that the known bots are on. Contains one value for each known bot.

Running the local test server

See Testing your solver.

client.py Arguments

python client.py accepts a number of arguments.

  • --solver my_solver: If my_solver.py is in the same directory as the client, and there exists a function solve(client) in the file, the client will use my_solver. Defaults to solver.py.
  • --submit: Include this argument anywhere if you wish to evaluate against our remote server.

local_server.py Arguments

python local_server.py accepts arguments as well.

  • --instance instance_name: Searchs test_graphs for an instance with instance_name, repeatedly serving it if found. If the instance is not found or not specified, then default to random instance selection.

The local server will print out which instance it is serving.

Graph/Instance format

In case you wish to create your own inputs or wish to understand our input format, we have laid out the details below.

Each graph in test_graphs/ has a number of instances. Graphs without instances (those in eval_graphs/) are used for evaluation tests.

Instances are of the following form:

{
  "instanceName": "toronto_0_0"
  "home": 53,
  "bots": [18, 64, ...],
  "studentErrors": [
    [15, 23, 63, 95, ...],  # list of vertices where student 1 is wrong
    [45, 83, ...], # student 2
  ]
}

Graphs are defined as follows:

{
  "city": "toronto_0",
  "vertices": 100,
  "students": 10,
  "scoutTime": 1,
  "edgelist": [
    [1, 2, 259],    # (u, v, weight)
    [1, 4, 325], ...
  ],
  "instances": [
    ...
  ],
}

Note that the graph/city name is a prefix of the instance name, and are separated by an underscore (_).

Check out the Submission page once you're confident in your solver!