init

docs/rcrs-competition/rcrs-competition-manual.adoc

+= RoboCup Rescue Simulation Competition Manual
+:author: RoboCup Rescue Simulation Team
+:revnumber: 1.0
+:revdate: September 27, 2021
+:size: A4
+:reproducible: true
+:encode: UTF-8
+:lang: en
+:sectids!:
+:sectnums:
+:sectnumlevels: 3
+:toclevels: 3
+:outlinelevels: 3
+:xrefstyle: short
+:imagesoutdir: images
+:imagesdir: images
+:math:
+:stem: latexmath
+:source-highlighter: highlight.js
+:bibtex-file: rcrs-competition/references.bib
+:bibtex-style: apa
+:bibtex-order: alphabetical
+:bibtex-format: asciidoc
+:title-page:
+:toc: left
+
+<<<
+
+[#purpose]
+== Purpose
+The manual describes the sequence of tasks to setup and run the RoboCup Rescue Simulation competition on a cluster of Linux computers.
+
+[#general-notes]
+== General Notes
+This manual assumes the RoboCup Rescue Simulation competition will run in a cluster of Linux machines.
+
+[#requirements]
+=== Software Requirements
+
+* https://www.openssh.com/[OpenSSH]
+* https://openjdk.java.net/[Java OpenJDK 11+]
+* https://git-scm.com/[Git]
+* https://gradle.org/[Gradle]
+* Utilities like bash`, `xterm`, `tar`, `7zip`, `gzip`, etc. +
+  *Note:* If you are using Ubuntu, all of these utilities are present in the default software repositories.
+
+[#setup]
+== Setup
+The competition environment is composed of 5 Linux computers, one controller called `controller` and four simulation computer called `c1-1`, `c1-2`, `c1-3`, and `c1-4`. The `c1-1` runs the RoboCup Rescue Simulator, while each other computer `c1-2`, `c1-3`, and `c1-4` runs a specific type of agents (i.e., ambulance teams, fire brigades, and police forces).
+
+[#controller]
+=== Installation
+In Ubuntu, the installation proceeds according to the following commands.
+
+[source,shell]
+.Installation on Ubuntu
+----
+$ git clone https://github.com/roborescue/rcrs-server.git
+$ cd rcrs-server
+$ ./gradlew completeBuild
+----
+
+You can download the simulation server by cloning the `https://github.com/roborescue/rcrs-server` repository. Clone the simulator server using the command
+
+[source,shell]
+----
+git clone https://github.com/roborescue/rcrs-server.git
+----
+
+General Notes:
+Getting server access for the first time:
+ssh-keygen
+ssh-copy-id rescue@116.203.191.59
+
+Login to the server: ssh -X rescue@116.203.191.59
+Validate display is connected by typing in the terminal:
+“echo $DISPLAY” or “xcalc”
+check.sh -> checks cluster connection
+
+To access the clusters:
+Cluster 1: ssh c1-1
+Cluster 2: ssh c2-1
+
+Teams names in the scripts: AIT, CSU, MRL, RI1
+
+Preparing for competition day:
+nano scripts/remote-control/config.sh -> to select the right day, ex: DAY = Day1, DAY = Final
+
+Copy maps to clusters:
+Check map exists in /home/rescue/in_maps/submission_day/
+Copy map to /home/rescue/maps/    ->   cp -r paris/ ../../maps/paris3
+./copyToServers.sh maps/ -> maps folder should contains maps directly, ex: maps/paris3
+
+Check teams submitted their code:
+Teams codes should be in /home/team_name/code/submission_day_time/
+
+Copy new submitted code to clusters:
+cd home/rescue/codeDir
+rm -rf in/*
+rm -rf out/*
+./fetchCodes.sh  ->  nano before copying & validate the code version is correct, ex: 10 = day 1 first submission, 11 = day 1 2nd submission….etc
+./prepare.sh teams_name (ex: RI1, MRL)
+./uploadCodes.sh
+cd .. -> go back to rescue folder
+./copyToClients.sh code/
+
+Run maps:
+./run.sh [cluster_number] [map] [team_name]
+Example: ./run.sh 1 berlin1 AIT
+./cancelRun.sh (1 or 2) -> if there are any errors
+
+Generate logs:
+nano scripts/evaluation/config.py -> make sure teams, maps per day & days are added properly
+evalAll.sh -> if this doesn’t work then run evalLog for each team
+evalLog.sh [path_to_gz_file] [map] [team_name]
+Example: evalLog.sh logs/Day1/kernel/0624-104636-CSU-Yunlu-eindhoven1.gz eindhoven1 CSU
+
+== Notes
+
+evaluation = log execution
+code = team code
+codeDir = prepare team code
+codeDir/in = team code
+
+./fetch Codes to fix copy
+nn = variable
+
+./prepare.sh CS | AIT | RIO | MRL
+
+./updateCodes.sh
+
+./copyToClients.sh code/ = copy code to all machines
+./check.sh = check all machine connections
+./copyToServers.sh  maps/
+* maps with the proper numbering
+
+=== Run the competition
+
+./run.sh [cluster number] [map name] [team name]
+
+./cancelRun.sh [cluster number]
+
+=== Update Web Interface
+./evalAll.sh
+
+scripts/remote_control/config.sh
+scripts/evaluation/config.py
+
+logs/Day1/kernel = Log of teams
+
+./evalLog.sh logs/Day1/kernel/<filename> [map name] [team name]
+
+./gatherLogs.sh
\ No newline at end of file

docs/rcrs-server/rcrs-server-manual.adoc

+= RoboCup Rescue Simulator Manual
+:author: RoboCup Rescue Simulation Team
+:revnumber: 1.5
+:revdate: September 27, 2021
+:size: A4
+:reproducible: true
+:encode: UTF-8
+:lang: en
+:sectids!:
+:sectnums:
+:sectnumlevels: 3
+:toclevels: 3
+:outlinelevels: 3
+:xrefstyle: short
+:imagesdir: images
+:math:
+:stem: latexmath
+:source-highlighter: highlight.js
+:bibtex-style: apa
+:bibtex-order: alphabetical
+:bibtex-format: asciidoc
+:title-page:
+:toc: left
+
+<<<
+
+[#purpose]
+== Purpose
+The manual facilitates the understanding of the RoboCup Rescue Simulation server and helps people interested in participating in RoboCup Rescue Agent Simulation competitions.
+
+[#installation]
+== Installation
+This manual assumes the simulator will run in a Linux machine even though it is possible to run them in Microsoft Windows or Apple macOS. We recommend to use Linux because it is open-source and most of the distributions have a good support from the users' community. If you have never used Linux before and intend to, we recommend starting with a user-friendly distribution, such as https://www.ubuntu.com/[Ubuntu] or https://getfedora.org[Fedora].
+
+[#requirements]
+=== Software Requirements
+
+* https://openjdk.java.net/[Java OpenJDK 11+]
+* https://git-scm.com/[Git]
+* https://gradle.org/[Gradle]
+* Utilities like `wget`, `bash`, `xterm`, `tar`, `gzip`, etc. +
+  *Note:* If you are using Ubuntu, all of these utilities are present in the default software repositories.
+
+[#download]
+=== Download
+You can download the simulation server by cloning the `https://github.com/roborescue/rcrs-server` repository. Clone the simulator server using the command
+
+[source,shell]
+----
+git clone https://github.com/roborescue/rcrs-server.git
+----
+
+[#directories]
+=== Directories
+The `rcrs-server` contains multiple directories. The important directories of the server are:
+
+* `boot`: scripts to run the simulation server
+** `boot/config/`: default configuration files
+** `boot/logs/`: text log files
+** `boot/records/`: JSON log files
+* `build/`: compiled Java classes
+* `docs/`: documentation
+* `jars/`: simulator JAR files
+* `lib/`: external libraries
+* `maps/`: maps and scenarios
+* `modules/`: simulator source code
+* `oldsims/`: old simulator source code
+
+[#compiling]
+=== Compiling
+The simulation server has to be compiled on your machine to generate the required JAR files to run the simulator. Execute the steps below to compile the simulation server.
+
+. Change to the directory `rcrs-server`
+.. If macOS, patch the file `boot/functions.sh` using command +
+     `sed -i -e "/readlink/s/^/#/" boot/functions.sh`
+. Compile the simulator using the command `./gradlew completeBuild`
+. Check the message at the end of the installation. If the installation is successfully completed, the message `BUILD SUCCESSFUL` is displayed; otherwise `BUILD FAILED` is displayed.
+
+[#example]
+=== Example
+In Ubuntu, the installation proceeds according to the following commands.
+
+[source,shell]
+.Installation on Ubuntu
+----
+$ git clone https://github.com/roborescue/rcrs-server.git
+$ cd rcrs-server
+$ ./gradlew completeBuild
+----
+
+The following message will be displayed if the installation is successfully completed.
+
+[source,text]
+.Install Completion
+----
+BUILD SUCCESSFUL in 2s
+1 actionable task: 1 executed
+----
+
+[#running]
+== Running
+There are two modes of execution of the simulation server: *Precomputation* and *Normal*.
+
+[#precomputation_mode]
+=== Precomputation Mode
+In the precomputation mode, the simulator connects one agent of each type and allows them to write the computation results.
+
+The sequence of commands to run the simulation server in precomputation mode are:
+
+[source,shell]
+.Running simulation server in precomputation mode
+----
+$ cd rcrs-server
+$ cd boot
+$ bash start-precompute.sh
+----
+
+After running the simulation server, run the agents. Once the precomputation is completed, push _Control-C_ and type `sh kill.sh` to stop the simulation server of running.
+
+[source,shell]
+.Stop running simulation server in precomputation mode
+----
+Control-C
+$ bash kill.sh
+----
+
+[#normal_mode]
+=== Normal Mode
+In the normal mode, the simulator connects all agents defined in the scenario and allows them to use the precomputation output.
+
+The sequence of commands to run the simulation server in normal mode are:
+
+[source,shell]
+.Running simulation server in normal mode
+----
+$ cd rcrs-server
+$ cd boot
+$ bash start-comprun.sh
+----
+
+After running the simulation server, run the agents. Once the simulation is completed, the server will stop automatically.
+
+[#parameters]
+=== Parameter Options
+The following parameters can be used to run the simulation server:
+
+* `-m MAPDIR` or `--map MAPDIR`, where `MAPDIR` is the path to the directory containing the map you want to run (default is `../maps/gml/test/map`).
+* `-c CONFIGDIR` or `--config CONFIGDIR`, where `CONFIGDIR` is the directory containing the configuration associated with a map (default is `../maps/gml/test/config`).
+* `-l LOGDIR` or `--log LOGDIR`, where `LOGDIR` is the directory where the log files will be stored (default is `./logs`).
+
+These parameters can be used at running a precomputaion and a normal simulation. You must use the same parameters for `MAPDIR` and `CONFIGDIR` to run a simulation server in precomputation and normal mode. An example of how to run the simulation server using these parameters is:
+
+[source,shell]
+.Running Simulation Server with Options
+$ bash start-precompute.sh -m ../maps/gml/kobe/map -l logs2
+(After completing precomputation)
+Control-C
+$ bash kill.sh
+$ bash start-comprun.sh -m ../maps/gml/kobe/map -l logs2
+
+[#tools]
+== Tools
+The simulation server comes with several tools to support the development of new maps and scenarios as well as replaying of the simulation.
+
+[#map-editor]
+=== Map editor
+Open a terminal window, navigate to the `rcrs-server` root directory and execute
+
+[source,shell]
+----
+$ ./gradlew gmlEditor --args=<map file path>
+----
+
+where `--args=<map file path>` is optional.
+
+For example,
+[source,shell]
+----
+$ ./gradlew gmlEditor
+
+$ ./gradlew gmlEditor --args="../maps/gml/test/map"
+----
+
+[#scenario-editor]
+=== Scenario Editor
+Open a terminal window, navigate to the `rcrs-server` root directory and execute
+
+[source,shell]
+----
+$ ./gradlew scenarioEditor --args=<scenario path>
+----
+
+where `--args=<scenario path>` is optional.
+
+For example,
+[source,shell]
+----
+$ ./gradlew scenarioEditor
+
+$ ./gradlew scenarioEditor --args="../maps/gml/test/map"
+----
+
+[#random-scenario]
+=== Random Scenario
+Open a terminal window, navigate to the `rcrs-server` root directory and execute
+
+[source,shell]
+----
+$ ./gradlew randomScenario --args=<map path>
+----
+
+where `--args=<map path>` is optional.
+
+For example,
+[source,shell]
+----
+$ ./gradlew randomScenario
+
+$ ./gradlew randomScenario --args="../maps/gml/test/map -civ 10 100 -fb 1 50 -fs 0 1 -pf 1 50 -po 0 1 -at 1 50 -ac 0 1 -refuge 1 2 -fire 0 1"
+----
+
+[#log-viewer]
+=== Log Viewer
+Open a terminal window, navigate to the `rcrs-server` root directory and execute
+
+[source,shell]
+----
+$ ./gradlew logViewer --args='-c config/logviewer.cfg <log path>'
+----
+
+where `--args='-c config/logviewer.cfg <log path>'` is optional and `<log path>` defines the log file path. The default log file path is `logs/rescue.log`.
+
+[#osm2gml]
+=== `osm2gml`
+Open a terminal window, navigate to the `rcrs-server` root directory and execute
+
+[source,shell]
+----
+$ ./gradlew osm2gml --args='<osm map path> <gml map path>'
+----
+
+The `<osm map path>` is the path to the OSM map file and the `<gml map path>` is the destination GML map path.
+
+[#design]
+== Simulator Design
+This section describes the simulator architecture and its main features as well as the entities composing a simulation scenario.
+
+[#architecture]
+=== Architecture
+The RoboCup Rescue Simulation server is composed of several simulators as listed in <<table:simulators>>.
+
+[#table:simulators]
+.List of Simulators
+|===
+| Simulator     | Description
+
+| Clear         | Manage blockade removal
+| Collapse      | Manage buildings' structural damage and blockade creation
+| Ignition      | Randomly ignites fire on buildings during the simulation
+| Fire          | Manage the fire spread between buildings and extinction
+| Traffic       | Manage humans' movement
+| Miscellaneous | Manage human damage and buriedness
+|===
+
+These simulators establish connections to the _kernel simulator_, responsible for coordinating the simulators' processes and centralizing the data they generate cite:[skinnerRamchurn2010]. These connections are illustrated in <<fig:simulator_architecture>>.
+
+[#fig:simulator_architecture]
+.RoboCup Rescue Agent Simulation platform architecture
+image::simulator_architecture.png[RoboCup Rescue Agent Simulation platform architecture, align="center"]
+
+The RoboCup Rescue simulator was designed to create a _partially observable_, _discrete-time_, _dynamic_, _stochastic_, _multiagent_ environment. In other words, in this environment:
+
+* the complete world current state cannot be known through a single agent's perception (even if the agent has an infinite range of sight, it still will not be able to see through a building's walls);
+* time is divided in intervals, as opposed to continuous time;
+* there are random elements that affect its state transition;
+* there is more than one agent present, and one's actions may interfere with the others' performance.
+
+Time is divided in _timesteps_; during each timestep, the agent perceives the environment and reasons about what action it will perform. In each timestep, the following happens:
+. The kernel updates all agents' perception (visual and communication) and waits for the agents' commands.
+. The agents updates their world model and make their decisions, sending their commands to the kernel.
+. The kernel sends the agents' commands to the simulators.
+. The simulators process the agents' commands and send the changes suffered by the environment back to the kernel.
+. The kernel sends the environment changes to the viewers.
+
+[#entities]
+=== Entities
+Several objects are represented in the simulator as depicted in <<fig:entities>>.
+
+[#fig:entities]
+.Entities of the simulator
+image::entities.png[Entities of the simulator]
+
+[#blockades]
+==== Blockades
+Blockades obstruct the path of agents and civilians; they are represented as black polygons in roads. Blockades appear in the beginning of the simulation and are not produced after this. They must be removed by Police Forces.
+
+The properties constituting a blockade are:
+
+[horizontal]
+position:: ID of the road to which the blockade belongs
+repair cost:: cost to completely remove the blockade from the road
+shape:: a rectangle which surrounds the whole blockade
+X & Y:: coordinates of the blockade's centroid
+apexes:: vector containing the apexes of the blockade
+
+[#area]
+==== Area
+Area entities represent buildings and roads.
+
+The properties constituting an area are:
+
+[horizontal]
+blockades:: a list with the blockades in that area
+edges:: a list with the edges that limit the area
+neighbours:: a list of the areas that can be accessed from this area
+X & Y:: coordinates representing the area in the map
+
+While both *Buildings* and *Roads* have the blockades attribute, blockades are valid only in *Roads*.
+
+[#buildings]
+==== Buildings
+Buildings represent all kinds of buildings in the simulator. There are special kinds of buildings like *Refuges*, *Ambulance Centres*, *Fire Stations*, and *Police Offices* that cannot catch on fire. <<table:special_buildings>> shows the illustration of these special buildings, they will be described in later sections of this document.
+
+[#table:special_buildings]
+[cols="2*^"]
+.Special buildings
+|===
+| image:refuge.png[Refuge] +
+*Refuge*
+| image:ambulance_centre.png[Ambulance Centre] +
+*Ambulance Centre*
+| image:fire_station.png[Fire Station] +
+*Fire Station*
+| image:police_office.png[Police Office] +
+*Police Office*
+|===
+
+The properties constituting a building are:
+
+[horizontal]
+brokenness:: how structurally damaged the building is; does not change during the simulation
+fieryness:: the intensity of the fire and fire-related damage in the building
+  * __UNBURNT__ - not burnt at all
+  * __WATER_DAMAGE__ - not burnt at all, but has water damage
+  * __HEATING__ - on fire a bit
+  * __BURNING__ - on fire a bit more
+  * __INFERNO__ - on fire a lot
+  * __MINOR_DAMAGE__ - extinguished but minor damage
+  * __MODERATE_DAMAGE__ - extinguished but moderate damage
+  * __SEVERE_DAMAGE__ - extinguished but major damage
+  * __BURNT_OUT__ - completely burnt out
+floors:: the number of floors the building has
+ground area:: the area of each floor
+ignition:: indicates if the simulator has lit this building on fire (*NOTE:* A building can catch on fire by being ignited by the simulator or by being close to a burning building; ignition will be set to "1" if the building was, at some point of the simulation, ignited by the simulator.)
+importance:: unknown function; has equal values to all buildings
+temperature:: temperature of the building; if it crosses a certain threshold, the building catches on fire
+total area:: the total area of the building (*floors* x *ground area*)
+
+Regular buildings are represented as polygons of various colors, depending of their status, as shown in <<fig:building_status>>; the darker the color, the greater the structural fire or water damage.
+
+[#fig:building_status]
+.Possible status of regular buildings
+image::building_status.png[Building status,600]
+
+In the beginning of the simulation, broken buildings trap humans inside it under debris; these debris must be removed by *Ambulance Teams*, who then proceeds to rescue the human.
+
+A *Refuge* is a special kind of building: it represents a place destined to support the rescue activity, providing medical care for the wounded and water to the *Fire Brigades*. In the simulator, humans inside a refuge have their damage zeroed, which means they do not lose health while they stay there; damage will, however, resume when the human entity leaves the refuge.
+
+Also, *Fire Brigades* have their water supply replenished by a certain amount during each cycle while they are inside the refuge.
+
+[#roads]
+==== Roads
+Area entities representing roads have no new attributes besides those of *Area* entities.
+
+[#humans]
+==== Humans
+These are the entities representing humans. In the simulator, they can be *Civilians*, *Ambulance Teams*, *Fire Brigades*, or *Police Forces*. They are all represented by circles of different colors, and cannot move by themselves if they are dead or buried.
+
+The properties constituting a human are:
+
+[horizontal]
+buriedness:: how deep the human is buried
+damage:: how much HP the human loses per cycle; zeroes when a refuge is reached
+direction:: direction to where the human is moving (inferred); the Y-axis positive half is zero, and the value increases until 129599 ((360 * 60 * 60) - 1) seconds anti-clockwise
+HP:: health points of the human; if it reaches 0, the human dies
+position:: ID of the entity where the human is; may be an Area entity or a human entity (if it is inside an ambulance)
+position history:: a list of the entities the human has passed during the last cycle, in chronological order
+stamina:: not implemented; would decrease each time the agent took an action and would be partially replenished at the beginning of each cycle
+travel distance:: (unknown)
+X & Y:: coordinates representing the human in the map
+
+The color of each human in the simulator is defined by its type and its health: the lower its health, the darker it is. Dead humans are represented by the black color.
+
+[#civilians]
+==== Civilians
+Civilians are human entities and they are not part of a rescue team; they are represented by the color green. Their standard behavior is to walk to the closest refuge on their on if they are not wounded or buried; otherwise, they will have to be transported by an *Ambulance Team*.
+
+[#agents]
+=== Agents
+These are the entities that will compose your rescue team; in other words, this is what you will program. Agents are divided in two types: *Platoon Agents* (<<platoon_agents>>) and *Centre Agents* (<<centre_agents>>).
+
+[#platoon_agents]
+==== Platoon agents
+Platoon agents are able to interact with the simulated environment through perception and executing actions on it. They can also exchange messages with other agents by vocal or radio communication. They are comprised of three different categories: the *Ambulance Team*, *Fire Brigade*, and *Police Force*.
+
+[horizontal]
+Ambulance Team:: is responsible for transporting rescued victims to a refuge.
+Fire Brigade:: is responsible for unburying (i.e., rescuing) victims and extinguishing fires on buildings. They carry a certain amount of water in their tanks and they can replenish it in a refuge.
+Police Force:: is responsible for removing blockades from the roads. When ordered to do so, they will clean a certain amount, specified in the repair cost parameter, from the target blockade at each cycle. However, differently from *Ambulance Teams* and *Fire Brigades*, having two *Police Forces* acting on the same blockade brings no advantage to the process: it will be as though there was only one *Police Force* acting on it.
+
+[#centre_agents]
+==== Centre Agents
+Centre agents are a type of agents whose only interaction with the world is through radio communication. There are three types of central agents: *Ambulance Centres*, *Fire Stations* and *Police Offices*, and they are represented as buildings.
+
+[#perception_commands]
+=== Perception and Commands
+The simulator has two perception modes: _standard_ and _line of sight_.
+
+The _line of sight_ perception simulates visual perception of the agent: a vision range and a number of rays are defined and the agent percepts anything that is reached by these rays.
+
+[#fig:no_los]
+.No Light of Sight
+image::no_los.png[No Light of Sight,450]
+
+[#fig:los]
+.Include Light of Sight
+image::with_los.png[Include Light of Sight,450]
+
+The set of currently visible entities for an agent is stored in a structure named _ChangeSet_; entities present in it are automatically updated in its world model; that is, if an agent perceives a blockade it did not know that was there before, this blockade is automatically added to its world model. The opposite, though does not happen: if the agent does not perceive a blockade any more, nothing in its world model changes, even if it knew that there was a blockade there before. In that case, the agent will still think that there is a blockade in that road, even though such blockade has already been cleared. Thus, it is up to the agent to figure this out and modify its world model accordingly.
+
+[#communication]
+=== Communication
+There are two forms of communication available in the simulator: _direct communication_ and _radio communication_. Direct communication, done with the command _speak_, is communication audible to humans within a radius from the emitter agent, as if the emitter shouted something.
+
+Radio communication is done with the command _tell_, and transmits information to all agents that are signed up to the channel on which it was broadcasted. Radio communication channels are present in limited number, each one with a limited bandwidth.
+
+In both types of communication, the message has to be coded into a string of bytes before being sent; the receptor must decode it once it receives the message. Both types might be susceptible to message _drop out_, where the message is not received by its targets; radio communication is also susceptible to message _failure_, where the message is received empty.
+
+:!sectnums:
+[#references]
+== References
+
+bibliography::[]
\ No newline at end of file

docs/rcrs-server/references.bib

+@InProceedings{skinnerRamchurn2010,
+  author = {Skinner, Cameron and Ramchurn, Sarvapali},
+  title = {The RoboCup rescue simulation platform},
+  booktitle = {Proceedings of the 9th International Conference on Autonomous Agents
+	and Multiagent Systems: volume 1 - Volume 1},
+  year = {2010},
+  series = {AAMAS '10},
+  pages = {1647--1648},
+  address = {Richland, SC},
+  publisher = {International Foundation for Autonomous Agents and Multiagent Systems},
+  location = {Toronto}
+}
\ No newline at end of file