{"id":26658983,"url":"https://github.com/trustbit/logistic-hackathon-public","last_synced_at":"2026-02-17T23:35:56.549Z","repository":{"id":244921688,"uuid":"490623772","full_name":"trustbit/logistic-hackathon-public","owner":"trustbit","description":null,"archived":false,"fork":false,"pushed_at":"2022-05-13T14:01:56.000Z","size":2459,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-06-18T09:56:40.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trustbit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-10T09:14:02.000Z","updated_at":"2024-06-18T09:56:49.327Z","dependencies_parsed_at":"2024-06-18T09:56:46.178Z","dependency_job_id":"2ae721c8-21de-4254-b4ef-a69754989af5","html_url":"https://github.com/trustbit/logistic-hackathon-public","commit_stats":null,"previous_names":["trustbit/logistic-hackathon-public"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Flogistic-hackathon-public","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Flogistic-hackathon-public/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Flogistic-hackathon-public/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Flogistic-hackathon-public/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trustbit","download_url":"https://codeload.github.com/trustbit/logistic-hackathon-public/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245440514,"owners_count":20615633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-25T10:17:28.590Z","updated_at":"2025-10-17T04:43:55.079Z","avatar_url":"https://github.com/trustbit.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.bitmovin.com\"\u003e\n    \u003cimg alt=\"Trustbit Hackathon: Sustainable Logistics Simulation\" src=\"images/header.jpeg\" \u003e\n  \u003c/a\u003e\n  \u003ch4 align=\"center\"\u003eThis is the central repository for participants of the \u003cbr\u003e\u003ca href=\"https://trustbit.tech/hackathon\" target=\"_blank\"\u003eTrustbit Hackathon: Sustainable Logistics Simulation\u003c/a\u003e which explains how to participate in the competition and links to all relevant resources like agent templates. The build status of participants agents can be seen in the \u003ca href=\"https://github.com/trustbit/logistic-hackathon-public/actions\"\u003eGitHub Action history\u003c/a\u003e of this repository.\u003c/h4\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License\"\u003e\u003c/img\u003e\u003c/a\u003e\n        \u003ca href=\"https://trustbit.tech\"\u003e\u003cimg src=\"https://img.shields.io/badge/Organizer-Trustbit-%23006871\" alt=\"Join Slack chat\"\u003e\u003c/img\u003e\u003c/a\u003e\n    \u003ca href=\"https://join.slack.com/t/trustbitsusta-vl26615/shared_invite/zt-17i36qlc1-h6L0GsJov2gPLLSYFaqNmw\"\u003e\u003cimg src=\"https://img.shields.io/badge/Slack-join%20chat-green\" alt=\"Join Slack chat\"\u003e\u003c/img\u003e\u003c/a\u003e\n\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Overview\nExperts in data science, machine learning and software development will work together to find efficient and sustainable logistics solutions for the EU at the Trustbit Hackathon: Sustainable Logistics Simulation on 13 May 2022.\n\nFreight transports, delivery routes and logistics systems are key drivers of the European economy. They allow countries to work together across borders, achieve better results together and find efficient and sustainable solutions for the future through cooperation and collaboration. Trustbit aims to foster this cooperation and brings together experts, developers and scientists to demonstrate what we can achieve by joining forces.\n\nYou do not have to be an expert in machine learning or data science. If you know how to code in one of our supported languages (C#, Java, Python) you are ready to go. A simple script making decisions via if / else branches might even be better than an involved machine learning model. We are excited to see what you can achieve!\n\n## Simulation\n\nWe simulate a road network in Europe. For the purpose of the hackathon, it is simplified.\n\n![image-20220512095546609](images/image-20220512095546609.png)\n\nThe world map for this road network is static and available: [map.json](data/map.json). **Map schema** is explained later.\n\nThe world map is represented by locations connected by a network of roads.  Some locations are special, as they produce goods, which will need shipping to other locations. \n\nLocations for producing and consuming goods are semi-deterministic and are not revealed publicly. You can analyse the **simulation trace data** to find out the patterns.\n\nThe participants of the competition will get to program trucks which can load the cargo and deliver it.  **The goal is to make money by delivering the cargo**. \n\nIf you run out of money, your truck(s) are suspended for the current simulation run.\n\nThis is very much like economic games you might have played in high school.\n\n### Implementation\n\nSo how does the simulation work exactly? \n\nThe simulation runtime is provided by Trustbit and is responsible for keeping track of all stats like the current list of cargo offers (= produced goods), the trucks on the map, the current simulation date and time, fuel cost and many more. \n\nWhen the simulation is started it loads the world map, generates an initial list of cargo offers and spawns the trucks of the participants randomly on the map. Then the simulation will iterate through the list of trucks and will ask each one of them for their next move decision.\n\nAfterwards, we simulate the passing of time via [discrete-event simulation](https://en.wikipedia.org/wiki/Discrete-event_simulation). Trucks travel, time passes and we jump forward to the next important event.\n\n### Your Workflow\n\n\n\n![image-20220513090946445](images/image-20220513090946445.png)\n\n1. You code an agent that controls truck(s) and submit it into the competition.\n2. That agents gets packaged as a docker container\n3. Regularly (every 5-10 minutes) we pull all agents in and start a new simulation run.\n4. You can observe the real-time dashboards during the run. \n5. You can also download full simulation trace immediately after the run ends\n\nThe goal is to **observe, iterate and improve**.\n\nWe have two sets of rules:\n\n- **Efficiency rules** - in effect from the start of the competition\n- **Sustainability rules** - come in effect in the second half of the Hackathon\n\n### Efficiency Rules\n\n These rules are in effect since the start of the game.\n\n- Your **truck gets money for delivering** cargo. Prices are market-driven. Certain cargo types tend to have better margins out-of-the-box.\n- You spend money on gas (fuel consumption uses COPERT formula for a loaded/empty truck and diesel price of `2.023`)\n- **Every week, you pay fixed operational costs**. So standing idle and doing nothing is a loosing strategy. You need to hustle to keep.\n- If your balance is negative at the end of the week, the truck is bankrupt until the end of the simulation run.\n- Weekly revenue is taxed progressively.\n\n### Sustainability Rules\n\nThese rules come into effect for the second part of the hackathon.\n\n- **CO2 emissions** (computed via COPER) have an additional associated cost (CO2 offset cost)\n- **Truck drivers get fatigued** over the time. Fatigue accumulates and increases the chance of road incidents. Incidents cause delay and trigger an immediate rest. Full 8-hour sleep is needed to eliminate fatigue.\n- **Locations have working hours**. If a truck arrives at a location outside of its working hours, it has to wait.\n\n### Trucks\n\nYou control trucks by implementing a `decide` function. This function is called whenever the simulation doesn't have a plan for the truck (e.g. at the start of the simulation).\n\nThe simulation runtime will build a current world state for the truck (list of available cargo) and request a decision.\n\nTrucks can decide to **deliver a cargo**, **drive to a specific location** empty, or **let the driver sleep** for a specific amount of time:\n\n- `DELIVER CARGO_UID` (e.g. `DELIVER 23`) - The truck reserves a specific cargo offer, drives to the current cargo location, loads the cargo onto the truck, plans a route to the cargo destination, drives there and unloads the cargo. Fatigue and working hour effects can apply here, if _Sustainability Rules_ are in effect.\n- `ROUTE LOCATION` (e.g. `ROUTE Berlin`) - A truck might decide to plan a route and drive to a specific location, although it is currently empty. For example a truck could anticipate, that a lucrative cargo offer will soon be available at a location and wants to minimize the pick up and delivery time.\n- `SLEEP HOURS` (e.g. `SLEEP 1` or `SLEEP 8`) - When there are no cargo offers available, or when a truck driver is already on duty for a long time, it might be the best strategy to rest for a few hours. Note, that sleeping 8 times for one hour doesn't constitute a full rest.\n\nEach action by a truck agent is an atomic action which will always succeed. After the decision is fully executed, the truck will be able to decide again.\n\n### Simulation time\nThe current time is represented by the float `time` in the simulation. It represents the number of hours that have passed since the start of the simulation. \n\n- A value of 13.25 means `13:15`. \n- `26.0` means `1 day 2 hours`\n\nEach action of a truck takes time. Driving a truck on the map, takes a certain amount of time, which is calculated by the distance and the speed limits of a route. The cargo offers delivery takes 5 hours, the truck will execute all necessary steps. Additional time might pass when _Sustainability Rules_ are active, and the driver gets into an accident due to insufficient resting time (see next section).\n\nExample: \n- `loc`=A, `time`=8 \n  \n  The truck decides at 8:00 to drive from A to B, which will take 5.5 hours.\n\n- `loc`=B, `time`=13.5\n\n  The truck arrives at 13:30 at location B.\n\nHint: you can get time of the day by doing a modulo operation: `tod = time mod 24`\n\n\n### Resting time of truck drivers (Sustainability Only)\n\nWhen _Sustainability Rules_ are active, driver fatigue mechanics come into play. \n\nDrivers can get tired over time. More time has passed since the last full rest (8 hours of undisturbed SLEEP), the higher the chance of road incidents during the journey. \n\nRoad incidents cause a delay and trigger an immediate `SLEEP 8` afterwards.\n\n### Working Hours (Sustainability Only)\n\nWhen _Sustainability Rules_ are in active, cargo delivery locations have working hours. If a truck arrives at such a location outside of the working hours, it will have to wait until it is allowed to unload its cargo.\n\nIf waiting time is 8 hours or more, it counts as a full rest.\n\n\n### CO2 emissions (Sustainability Only)\nDriving emits CO2 which is calculated via a simplified COPERT4 formula (see also http://emisia.com/content/copert-documentation). The simulation tracks the emissions for all trucks on the map. Try to keep your emissions as low as possible, while maximizing your profit.\n\nCO2 emissions are counted as expensses, based on the CO2 offset cost per kg.\n\n### Cargo offers\n\nSimulation runtime tracks cargos available for delivery. Whenever it is time for a truck to make a decision, it will receive a personalized list of cargo offers. \n\n```json\n{\n  \"uid\": 100,                # unique cargo ID\n  \"origin\": \"Zaragoza\",      # city to pick it up\n  \"dest\": \"Innsbruck\",       # destination\n  \"name\": \"Fruits\",          # kind\n  \"price\": 1778.0,           # money you get for delivery\n  \"eta_to_cargo\": 8.16,      # ETA from current loc to pickup loc\n  \"km_to_cargo\": 780.0,      # kms to pickup location\n  \"eta_to_deliver\": 27.76,   # ETA for picking up and delivering\n  \"km_to_deliver\": 2730.0    # total kms to pick up AND deliver\n}\n```\n\n\n\nETA and KM estimates are relative to the current position of the truck. They account only for the driving time, but don't account for the loading/unloading and waiting times.\n\nYou can check out for the sample cargo offers in [data/](data/) directory.\n\n## Available Data\n\nWe have a set of data available for the deeper analysis:\n\n- World map (static)\n- Simulation traces\n- Observability Dashboard\n\n### World Map\n\nYou can [download](data/map.json) the world map. It describes the road graph as a collection of locations and roads that connect them. Estimated driving speed is also provided.\n\n### Simulation Traces\n\nSimulation traces could be downloaded from the [traces folder](https://traces.endpoints.trustbit-hackathon.cloud.goog). These are JSON files stored in [Chrome Tracing format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview).\n\nNote: Simulation traces that were published before the competition start - demonstrate the mechanics, but use a slightly different world. Keep that in mind, if you decide to analyse in advance.\n\nYou can analyse the traces manually or load into the `chrome://tracing` tool. \n\nNavigate to `chrome://tracing` in Chrome or Chromium browser, then drag-and-drop a trace file into the tracing UI.\n\nThere you can see a detailed breakdown of every single action that happened in the simulation, for all the participants and NPC agents.\n\n![image-20220512105849865](images/image-20220512105849865.png)\n\nYou can zoom, filter and dig into the details. Events tend to have associated data:\n\n![image-20220512110108793](images/image-20220512110108793.png)\n\n\n\n#### Caveat - ms instead of hours\n\nChrome tracing simulator isn't suitable for displaying large intervals like hours. So we \"hack\" and pass time and durations as milliseconds instead. When you see a millisecond unit, convert it mentally into hours.\n\nE.g.:\n\n- \"Start 3,839.524 ms \" means \"Start at 3839.524 hours since the start of the simulation\"\n- \"Wall duration 2.034 ms\" means \"Wall duration of 2.034 hours\" (roughly two hours and a minute)\n\n\n\n#### Manual Analysis\n\nThe file looks like the snippet below. Actions of all teams are intertwined there:\n\n```json\n{\"name\": \"DRIVE\", \"ph\": \"B\", \"ts\": 18941.0, \"pid\": 5, \"tid\": 1, \"args\": {\"a\": \"Salzburg\", \"b\": \"Linz\", \"fuel_l\": 24.19, \"co2_kg\": 63.86, \"cargo\": 15, \"km\": 107, \"delay\": 0, \"incident_cost\": 0}},\n{\"name\": \"DRIVE\", \"ph\": \"E\", \"ts\": 20156.90909090909, \"pid\": 5, \"tid\": 1},\n{\"pid\": 5, \"ts\": 20156.90909090909, \"ph\": \"C\", \"name\": \"balance\", \"args\": {\"value\": 24806}},\n{\"name\": \"DECIDE\", \"ph\": \"i\", \"ts\": 19000.0, \"pid\": 8, \"tid\": 0, \"s\": \"t\", \"args\": {\"cmd\": \"SLEEP\", \"arg\": \"1\"}},\n{\"name\": \"SLEEP\", \"ph\": \"B\", \"ts\": 19000.0, \"pid\": 8, \"tid\": 0},\n{\"name\": \"SLEEP\", \"ph\": \"E\", \"ts\": 20000.0, \"pid\": 8, \"tid\": 0},\n{\"pid\": 8, \"ts\": 20000.0, \"ph\": \"C\", \"name\": \"balance\", \"args\": {\"value\": 8713}},\n{\"name\": \"DECIDE\", \"ph\": \"i\", \"ts\": 19080.0, \"pid\": 4, \"tid\": 2, \"s\": \"t\", \"args\": {\"cmd\": \"SLEEP\", \"arg\": \"1\"}},\n{\"name\": \"SLEEP\", \"ph\": \"B\", \"ts\": 19080.0, \"pid\": 4, \"tid\": 2},\n{\"name\": \"SLEEP\", \"ph\": \"E\", \"ts\": 20080.0, \"pid\": 4, \"tid\": 2},\n```\n\nUnique identifiers are `pid` (team ID). You can look them up for your truck at the beginning of the file in the `M` (Metadata) records:\n\n```json\n{\"name\": \"process_name\", \"ph\": \"M\", \"pid\": 1, \"args\": {\"name\": \"npc_truck_naive\"}},\n{\"name\": \"thread_name\", \"ph\": \"M\", \"pid\": 1, \"tid\": 0, \"args\": {\"name\": \"npc_truck_naive/0\"}},\n{\"name\": \"process_name\", \"ph\": \"M\", \"pid\": 2, \"args\": {\"name\": \"npc_truck_rinat\"}},\n{\"name\": \"thread_name\", \"ph\": \"M\", \"pid\": 2, \"tid\": 0, \"args\": {\"name\": \"npc_truck_rinat/0\"}},\n{\"name\": \"process_name\", \"ph\": \"M\", \"pid\": 3, \"args\": {\"name\": \"npc_truck_seb\"}},\n{\"name\": \"thread_name\", \"ph\": \"M\", \"pid\": 3, \"tid\": 0, \"args\": {\"name\": \"npc_truck_seb/0\"}},\n{\"name\": \"process_name\", \"ph\": \"M\", \"pid\": 4, \"args\": {\"name\": \"npc_fleet_profit_seeking\"}}\n```\n\nIf you have multple trucks, they will share the same `pid` but will have different `tid`.\n\n### Observability Dashboard\n\nWe have  dashboards with real-time insight into the system across the simulation runs. \n\nEach run takes 5-10 minutes, and you can see it as a separate peak on the charts.\n\n- [General dashboard](https://telemetry.endpoints.trustbit-hackathon.cloud.goog)\n\n![image-20220512110929530](images/image-20220512110929530.png) \n\n## Competition Results\n\nWe have 4 competition tracks:\n\n- Individual with efficiency rules\n- Team with efficiency rules\n- Individual with sustainability rules\n- Team with sustainability rules\n\nWinners are calculated by running the simulation 3 times (to reduce the role of luck) and picking the winner based on the average final balance across all 3 simulation runs.\n\n\n\n## Agent template repositories and competition build system\n\n**We recommend to perform the steps of this section at the very beginning of the hackathon, just by using one of the supplied language templates without any changes. After the agent build is setup you can start to improve the truck agents behavior.**\n\n### 1. Create private repository from a template\nTo get you started quickly, we created several template repositories for you. Depending on your language preference, click on one of the links below and then click the `Use this template` button to create a new **private** repository in your GitHub account with all the contents of the template. Make sure to make this new repository private, as otherwise all of your competitors will be able to see your code.\n\n- [C# agent template repository](https://github.com/trustbit/logistic-hackathon-agent-template-csharp)\n- [Java agent template repository](https://github.com/trustbit/logistic-hackathon-agent-template-java)\n- [Python agent template repository](https://github.com/trustbit/logistic-hackathon-agent-template-python)\n\n\u003c/br\u003e\n\u003cimg src=\"images/use-as-template.jpeg\" width=\"640\"/\u003e\n\u003c/br\u003e\n\n### 2. Add team members as collaborators to your private repository\n\nIf you are participating in a team, just collect the GitHub handles of you team members and add them in the Collaborators and teams page of your repository's settings. That way all of them will be able to contribute code.\n\n\u003cimg src=\"images/collaborators.jpeg\" width=\"640\"/\u003e\n\u003c/br\u003e\n\n### 3. Create a new SSH key for the competition build system\nNow we need to make sure the competition build system has access to your private repository. We will do that by creating an SSH key pair and by adding the public key to your repository's `Deploy keys` and by sending the private SSH key to our support staff, who will add it to our build system.\n\nSteps in detail:\n\n- Execute the following command on your local machine:\n\n    `ssh-keygen -t rsa -b 4096 -C \"your_email@example.com\" -q -N \"\" -f hackathon`\n\n- This will create 2 files in your current directory: \n  - `hackathon.pub` - the public key\n  - `hackathon` - the private key\n\n- Go to the _Deploy keys_ page of your repository's settings and create a new deploy key `Hackathon` there and paste in the contents of your **public key file**.\n\n\u003cimg src=\"images/deploy-key.jpeg\" width=\"480\"/\u003e\n\n- You will then need to send the **private SSH key file** to us via Slack. The best way to do that is to go to our hackathon Slack workspace, create a new channel there `support-[unique-team-id]` and invite your team members and our support staff via Slack handle `@support-staff`. To reduce the likelihood of copy/paste errors, always upload your key as a file to Slack. If you did not join the Slack workspace yet, you can do that [here](https://join.slack.com/t/trustbitsusta-vl26615/shared_invite/zt-17i36qlc1-h6L0GsJov2gPLLSYFaqNmw).\n\n- Fork this repository, add your teams details in the [agents.json](agents.json) file and open a new PR with those changes. The secret for your team will be created by our support staff in the meantime. The naming convention is `TEAM_[UNIQUE_ID]`. Here is a template for a valid entry in the `agents.json` file:\n\n```json\n    {\n      \"unique_id\": \"trustbit\",\n      \"is_fleet\": false,\n      \"github_repository\": \"trustbit/example-truck-agent\",\n      \"github_private_ssh_key_secret\": \"TEAM_TRUSTBIT\"\n    }\n```\n- If you are participating alone set `is_fleet` to `false`. If you are participating as a team set it to `true`.\n\n- As soon as your PR is merged, we will have your repository included in our build, which is scheduled to run **every 5 minutes** and which will provide new versions of your agent to the simulation. You can check on the status of your builds here: https://github.com/trustbit/logistic-hackathon-public/actions/workflows/docker-images.yml\n\n## We are hiring\nWe — a team of more than 30 people from over 10 nations — organise our daily work around trust and flexibility. You decide whether you want to work full-time or part-time. We are flexible and can adapt to your individual needs. We know that really good projects only happen if employees can concentrate on their personal strengths and deepen their interests. That’s why self-directed, continuous training is a central part of our daily work. To make this possible, we offer numerous opportunities to discover new things and learn from each other.\n\nWhat’s it like to work as a Software Engineer, Designer, Project Manager, Data Scientist or Consultant at Trustbit? That’s exactly what we asked some of our colleagues, [enjoy watching](https://trustbit.tech/careers)! 🍿\n\n\u003cbr/\u003e\n\u003ca href=\"https://trustbit.tech/careers\"\u003e\n  \u003cimg src=\"images/trustbit.png\" width=\"240\"/\u003e\n\u003c/a\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustbit%2Flogistic-hackathon-public","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrustbit%2Flogistic-hackathon-public","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustbit%2Flogistic-hackathon-public/lists"}