COMP2521 23T2

Assignment 2
Detective Academy 2521

Changelog

All important changes to the assignment specification and files will be listed here.

[11/07 09:00] Assignment released

[13/07 21:00]
Added note to game.c about not relying on the #defines in game.c
Updated test for MapSetName in testMap.c to reinforce that a copy of the given name
should be made. See the most recent version of testMap.c here.

Admin

Marks contributes 20% towards your final mark (see Assessment section for more details)

Submit see the Submission section

Deadline 8pm on Friday of Week 10
Late penalty 0.2% per hour or part thereof deducted from the attained mark, submissions later
than 5 days not accepted

Prerequisite Knowledge

Graphs
Graph ADT
Graph Traversal
Weighted Graphs
Shortest Path
 Setting Up COMP2521 23T2

Note: As this assignment uses random number generation, you may get different results if
you run it on your local machine.

Change into the directory you created for the assignment and run the following command:

$ unzip /web/cs2521/23T2/ass/ass2/downloads/files.zip

If you're working at home, download files.zip by clicking on the above link and then run the
unzip command on the downloaded file.

You should now have the following files:

Makefile This controls compilation of the program. You only need to modify this if
you create additional files for your implementation.

Map.h This is the interface to the Map ADT. It provides agents with information
about the world including what cities and roads there are. Roads always
go between two different cities and can always be traversed in both
directions, and all the cities will be connected, either directly or indirectly
via other cities. You must not modify this file.

Map.c This is the implementation of the Map ADT. At the moment it is just a
stub file that you need to implement yourself. You can use any of the lab
code or adapt any of the code from lectures to do this.

Agent.h This is the interface to the Agent ADT. An instance of the Agent ADT
represents an 'agent' in the game. An agent represents a detective or a
thief. This interface includes functions to allow the agents to interact with
the client program. You must not modify this file.

Agent.c This is the implementation of the Agent ADT. At the moment this only
supplies the implementation for the RANDOM movement strategy, and will
need to be completed by you. Make sure you understand what has
already been supplied.

testMap.c This is a main program for testing the Map ADT. You can modify this file
to add more extensive tests.

game.c This is the client program that runs the game. The program reads in data
from some data files and creates a map. The agents are also created and
a game starts. You must not modify this file.

data/ This is a directory containing test data that can be used as input to the
program. There are two types of data files, which are described below.
For example, consider the following city data file:
COMP2521 23T2
10
0 5 29 1 41 6 60 7 50 8 40 n sydney
1 2 51 5 29 i adelaide
2 n melbourne
3 5 30 4 36 n perth
4 9 20 n darwin
5 6 10 n hobart
6 n auckland
7 n madrid
8 i new york
9 n brisbane

The first line indicates that there are 10 cities. The second line indicates that Sydney has an ID of 0,
and has a road to Hobart of length 29, a road to Adelaide of length 41, a road to Auckland of
length 60, a road to Madrid of length 50 and a road to New York of length 40. There is an
informant in Adelaide and New York.

Note that roads are bidirectional, so even though some cities do not have any roads in their lists
in the city data file, they will still have roads to other cities due to them appearing in other cities'
road lists. All cities are connected, either directly or indirectly via other cities.

Agent Data
The first line of data represents information about the thief. The first number represents the
amount of stamina the thief starts with, which is also the maximum amount of stamina the thief
can have. The second number represents the starting location of the thief. The third number
indicates where the getaway city is. This is followed by a string representation (i.e., name) of the
thief.

The next four lines represent the detectives. The first two numbers represent the initial/maximum
amount of stamina and the starting location of the detective. The third number represents the
strategy that the detective is assigned. This is followed by a string representation (i.e., name) of
the detective.

For example, consider the following agent data file:

10 5 6 T
1 2 0 D1
1 3 1 D2
5 1 2 D3
5 4 2 D4

The first line indicates that the thief has a stamina of 10 and starts at city 5 (which would be
Hobart if using the city data file above), and that the getaway city is city 6 (which would be
Auckland if using the city data file above).

Commands
Function Description Assumptions
COMP2521 23T2
MapInsertRoad Inserts a road between two cities with the given The given cities are valid
length. Does nothing if there is already a road The given cities are the
between the two cities. not the same
The road length is
positive

MapContainsRoad Returns the length of the road between the two The given cities are valid
given cities, or 0 if no such road exists

MapGetRoadsFrom Stores the roads connected to the given city in The given city is valid
the given roads array in any order and returns The roads array is at
the number of roads stored. The from field least as large as the
should be equal to the given city for all roads in number of cities on the
the array. map

MapShow Displays the map (already implemented)

Task 2: Agent Implementation

In this task, you must implement various strategies that the detectives can use to try and catch the
thief in Agent.c. This will require you to modify existing functions and add new fields to the
agent struct (to enable agents to remember things), so make sure you understand the existing
code first.

Stage 0: RANDOM strategy

In stage 0, all agents use the random strategy. In the random strategy, each agent randomly
selects an adjacent city that they have the required stamina to move to and move to it. If the
agent does not have sufficient stamina to move to any city, they must remain in their current city
for another cycle, which will completely replenish their stamina.
The random strategy has already been implemented, so you are not required to do anything to
complete this stage. You should not alter the logic of the random strategy in Agent.c. You should
also not use any random number generation in your implementation of the other strategies.

Stage 1: CHEAPEST_LEAST_VISITED strategy

If a detective is assigned this strategy, it means that at every opportunity they have to move, they
must move to the city they have visited the least number of times, out of the legal options that
are available. This means the detective must work out what cities are actually adjacent to the
current city that they have sufficient stamina to move to and pick from those the one that has
been visited the least. If there is more than one city with the least number of visits, the city which
requires the least stamina among those should be chosen. If there is more than one city with the
CHEAPEST_LEAST_VISITED strategy. The detective may also pass through a city with another
informant in which the detective would find a new least turns path from theCOMP2521 23T2
current location.
You must take into account the stamina of the detective. For example, if one path requires the
detective to travel through 3 cities, but would have to rest twice (5 turns), that is more turns than
the detective travelling through 4 cities but not having to rest (4 turns). If there are multiple paths
that would take the least number of turns, the path that results in the agent having the most
stamina at the end should be chosen. If there are multiple paths that would take the least number
of turns and would also result in the agent having the same stamina, any of them may be chosen.
You can assume that all detectives will be able to reach every city from every other city. That is, for
every pair of cities, there exists a route between them such that the length of the longest road on
that route is less than or equal to the maximum stamina of each detective.

Examples

Stage 0
In this example all detectives are following the RANDOM strategy. The thief always uses the RANDOM
strategy.

$ ./game data/citiesSmall.data data/agentsS0.data 10 6

DETECTIVE ACADEMY 2521

Red alert! A thief is on the run.

Detectives, to your cars. You have 10 hours.

Hour 0
T D1 D2 D3 D4
3 1 1 1 1

Enter command: map

Number of cities: 4
Number of roads: 3
[0] melbourne has roads to: [1] perth (41), [2] darwin (900)
[1] perth has roads to: [0] melbourne (41)
[2] darwin has roads to: [0] melbourne (900), [3] california (30)
[3] california has roads to: [2] darwin (30)

Enter command: stats

Hour 0
T is at [3] california with 1000 stamina
D1 is at [1] perth with 100000 stamina
D2 is at [1] perth with 5000 stamina
D3 is at [1] perth with 50 stamina
 $ ./game data/citiesMedium.data data/agentsS1.data 10 4
COMP2521 23T2
DETECTIVE ACADEMY 2521

Red alert! A thief is on the run.

Detectives, to your cars. You have 10 hours.

Hour 0
T D1 D2 D3 D4
9 8 7 6 2

Enter command: run

Hour 1
T D1 D2 D3 D4
4 0 0 5 1

Hour 2
T D1 D2 D3 D4
9 5 5 0 5

Hour 3
T D1 D2 D3 D4
4 6 6 8 6

Hour 4
T D1 D2 D3 D4
3 5 5 0 0

Hour 5
T D1 D2 D3 D4
5 6 1 1 8

Hour 6
T D1 D2 D3 D4
1 6 2 2 0

Hour 7
T D1 D2 D3 D4
0 0 1 1 7

D1 caught the thief in sydney (0)

YOU WIN - THIEF CAUGHT!

Stage 2
In this example, detectives 3 and 4 use the DFS strategy. In this strategy they do a depth-first
traversal from their starting points and follow this at each cycle. If they do not have the stamina to
go to the next city on their route, they remain at the same location to regain their stamina and
an informant (this is indicated by the * character on the display), so they immediately switch to
the strategy of going along the shortest path to the thief's current location COMP2521 23T2
(city 9). They calculate
the shortest path as follows:

Detective 1 calculates the shortest path as 8 → 0 → 5 → 3 → rest → 4 → 9, which requires 6

turns.
Detective 4 calculates the shortest path as 8 → 0 → 5 → 3 → 4 → 9, which requires 5 turns.

Detective 4 reaches the destination by hour 5 but the thief is no longer there. However the other
detectives have found the thief by this stage anyway. Detective 1 is following the shortest path
from 8 to 9, but has to stop at hour 4 to regain stamina.

Detective 2 finds an informant in city 1 in hour 1 and goes via the shortest path from city 1 to 4,
which is calculated as 1 → 5 → rest → 3 → 4.

Detective 3 finds an informant in city 1 in hour 3 and goes via the shortest path from city 1 to 4,
which is calculated as 1 → 5 → 3 → rest → 4.

$ ./game data/citiesInformants.data data/agentsS3.data 10 2

DETECTIVE ACADEMY 2521

Red alert! A thief is on the run.

Detectives, to your cars. You have 10 hours.

Hour 0
T D1 D2 D3 D4
9 8* 2 6 8*

Enter command: run

Hour 1
T D1 D2 D3 D4
4 0 1* 0 0

Hour 2
T D1 D2 D3 D4
9 5 5 0 5

Hour 3
T D1 D2 D3 D4
4 3 5 1* 3

Hour 4
T D1 D2 D3 D4
9 3 3 5 4

Hour 5
T D1 D2 D3 D4
4 4 4 3 9
made a reasonable attempt to debug your program yourself using these methods before asking
for help. COMP2521 23T2
You can learn about GDB and Valgrind in the Debugging with GDB and Valgrind lab exercise.

Frequently Asked Questions

Do the detectives communicate with each other at all? No. Each detective operates
independently of the other detectives.
Are we allowed to create our own functions? You are always allowed to create your own
functions. All additional functions you create should be made static.
Are we allowed to create our own #defines and structs? Yes.
Are we allowed to #include any other libraries? No. All the libraries required for this
assignment are provided already.
Are we allowed to change the signatures of the given functions? No. If you change these,
your code won't compile and we won't be able to test it.
What errors do we need to handle? You should handle common errors such as NULL returned
from malloc by printing an error message to stderr and terminating the program (the exact
message is not important). You are not required to handle other errors.
What invalid inputs do we need to handle? You are not required to handle invalid inputs,
such as NULL being passed in as a Map or Agent. It is the user's responsibility to provide valid
inputs.
Will we be assessed on our tests? No. You will not be submitting any test files, and therefore
you will not be assessed on your tests.
Are we allowed to share tests? No. Testing is an important part of software development.
Students that test their code more will likely have more correct code, so to ensure fairness,
each student should independently develop their own tests.

Submission

You must submit the files Map.c and Agent.c. In addition, you can submit as many supporting
files (.c and .h) as you want. Please note that none of your submitted files should contain a main
function, and you must not submit Map.h or Agent.h as you are not permitted to modify these
files. You can submit via the command line using the give command:

$ give cs2521 ass2 Map.c Agent.c your-supporting-files...

You can also submit via give's web interface. You can submit multiple times. Only your last
submission will be marked. You can check the files you have submitted here.
Style
COMP2521 23T2
20% of the marks for this assignment will come from hand marking of the readability of the code
you have written. These marks will be awarded on the basis of clarity, commenting, elegance and
style. The following is an indicative list of characteristics that will be assessed, though your
program will be assessed wholistically so other characteristics may be assessed too (see the style
guide for more details):
Consistent and sensible indentation and spacing
Using blank lines and whitespace
Using functions to avoid repeating code
Decomposing code into functions and not having overly long functions
Using comments effectively and not leaving planning or debugging comments

The course staff may vary the assessment scheme after inspecting the assignment submissions
but it will remain broadly similar to the description above.

Originality of Work

This is an individual assignment. The work you submit must be your own work and only your work
apart from the exceptions below. Joint work is not permitted. At no point should a student read or
have a copy of another student's assignment code.
You may use any amount of code from the lectures and labs of the current iteration of this
course. You must clearly attribute the source of this code in a comment.
You may use small amounts (< 10 lines) of general purpose code (not specific to the assignment)
obtained from sites such as Stack Overflow or other publicly available resources. You must clearly
attribute the source of this code in a comment.

You are not permitted to request help with the assignment apart from in the course forum, help
sessions or from course lecturers or tutors.

Do not provide or show your assignment work to any other person (including by posting it
publicly on the forum) apart from the teaching staff of COMP2521. When posting on the course
forum, teaching staff will be able to view the assignment code you have recently submitted with
give.
The work you submit must otherwise be entirely your own work. Submission of work partially or
completely derived from any other person or jointly written with any other person is not
permitted. The penalties for such an offence may include negative marks, automatic failure of the
course and possibly other academic discipline. Assignment submissions will be examined both
automatically and manually for such issues.

Relevant scholarship authorities will be informed if students holding scholarships are involved in
an incident of plagiarism or other misconduct. If you knowingly provide or show your assignment