{"id":16454977,"url":"https://github.com/lucadibello/movers-sat-problem","last_synced_at":"2026-05-05T04:38:46.919Z","repository":{"id":238454065,"uuid":"796583135","full_name":"lucadibello/movers-sat-problem","owner":"lucadibello","description":"📦 SAT solver for scheduling team-based multi-floor furniture moving","archived":false,"fork":false,"pushed_at":"2024-06-10T14:27:57.000Z","size":5804,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-09T17:59:35.138Z","etag":null,"topics":["optimization-algorithms","python","reactjs","sat-solver","z3-solver"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucadibello.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-05-06T08:26:15.000Z","updated_at":"2024-06-10T14:28:01.000Z","dependencies_parsed_at":"2024-10-11T10:20:47.999Z","dependency_job_id":"303ebfe1-fa29-4fe9-b5a3-97dfccac1285","html_url":"https://github.com/lucadibello/movers-sat-problem","commit_stats":null,"previous_names":["lucadibello/movers-sat-problem"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmovers-sat-problem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmovers-sat-problem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmovers-sat-problem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmovers-sat-problem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucadibello","download_url":"https://codeload.github.com/lucadibello/movers-sat-problem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240943567,"owners_count":19882421,"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":["optimization-algorithms","python","reactjs","sat-solver","z3-solver"],"created_at":"2024-10-11T10:20:37.782Z","updated_at":"2026-05-05T04:38:41.893Z","avatar_url":"https://github.com/lucadibello.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 1. Movers SAT problem\u003c!-- omit in toc --\u003e\n\nThis project allows to compute an optimal forniture moving schedule that allows a team of movers to complete their job in the most efficient way possible. This project provides a complete frontend and backend system that is able to receive a problem instance from the user, solve it using [z3-solver](https://github.com/Z3Prover/z3), and return the solution to the user. The frontend is built using [React](https://react.dev/) and [Chakra UI](https://v2.chakra-ui.com/), while the backend is implemented using [FastAPI](https://fastapi.tiangolo.com/).\n\nTo have a complete overview of how the various parts of the system interact with each other, please refer to the [System Design](#system-design) section.\n\n## Table of Contents\u003c!-- omit in toc --\u003e\n\n- [1.1. Problem Description](#11-problem-description)\n- [1.2. SAT mathematical model](#12-sat-mathematical-model)\n\t- [1.2.1. Input Parameters](#121-input-parameters)\n\t- [1.2.2. Sets / Domains](#122-sets--domains)\n\t- [1.2.3. Variables](#123-variables)\n\t\t- [A. Variables describing the state of the system](#a-variables-describing-the-state-of-the-system)\n\t\t- [B. Variables describing the actions of the movers](#b-variables-describing-the-actions-of-the-movers)\n\t- [1.2.4. Constraints](#124-constraints)\n\t\t- [A. Action Definition](#a-action-definition)\n\t\t- [B. Initial and Final Constraints](#b-initial-and-final-constraints)\n\t\t- [C. Other Constraints](#c-other-constraints)\n- [1.3. System Design](#13-system-design)\n\t- [1.3.1. Frontend - User Interface](#131-frontend---user-interface)\n\t- [1.3.2. Backend - APIs and Solver](#132-backend---apis-and-solver)\n- [1.4. Evaluation and final considerations](#14-evaluation-and-final-considerations)\n\n## 1.1. Problem Description\n\nIn the *movers satisfiability problem*, a moving company is tasked with\nrelocating all furniture from a building with multiple floors. The\nobjective is to move all furniture to the ground floor within a given\ntime frame (maximum number of time steps). For this task, the company\nhas a team of movers of size $m$, and each mover is identified with a\nunique name, and can move up or down one floor at a time.\n\nThe building has $n$ floors, each identified by a unique integer number.\nThe building contains a set of furniture $F = {f1,f2,...,fn}$ to be\nmoved. Each piece of furniture is located within the floors of the\nbuilding, and there could be more than one piece of furniture on the\nsame floor. The movers are initially located on the ground floor of the\nbuilding, and they must move all furniture to the ground floor within a\ngiven time frame. By the end of the time frame, all movers and all\nfurniture must be located on the ground floor in order to solve the\nproblem.\n\nWhen a mover is on the same floor as a piece of furniture, and decides\nto carry it, the mover and the furniture in question are moved together\nto the floor below.\n\n## 1.2. SAT mathematical model\n\n### 1.2.1. Input Parameters\n\n1. $m \\in \\mathbb{N}^+$: number of movers\n\n2. $n \\in \\mathbb{N}^+$: number of floors\n\n3. $t_{max} \\in \\mathbb{N}^+$: maximum number of steps to solve the\n    problem\n\n### 1.2.2. Sets / Domains\n\n- $M = \\{m_1, m_2, ..., m_m\\}$: set of movers\n\n- $L = \\{l_1, l_2, ..., l_n\\}$: set of floors (\\\"levels\\\") in the\n    building\n\n- $F = \\{f_1, f_2, ..., f_k\\}$: set of forniture items\n\n- $T = \\{t_1, t_2, ..., t_{max}\\}$: set of timestamps from 1 to\n    $t_{max}$\n\n### 1.2.3. Variables\n\n#### A. Variables describing the state of the system\n\n- $atFloor(m, l, t) \\in \\{0, 1\\}$, *True* if mover $m$ is at floor $l$\n    at time $t$\n\n- $atFloorForniture(f, l, t) \\in \\{0, 1\\}$, *True* if forniture $f$ is\n    at floor $l$ at time $t$\n\n#### B. Variables describing the actions of the movers\n\n- $ascend(m, t) \\in \\{0, 1\\}$, *True* if mover $m$ is ascending at\n    time $t$\n\n- $descend(m, t) \\in \\{0, 1\\}$, *True* if mover $m$ is descending at\n    time $t$\n\n- $carry(m, f,  t) \\in \\{0, 1\\}$, *True* if mover $m$ is carrying\n    forniture $f$ at time $t$\n\n### 1.2.4. Constraints\n\n#### A. Action Definition\n\nThis section describes how the actions of the movers alter the state of\nthe system.\n\n1. $ascend(m, t)$: a mover can move up one floor at a time (except when at the last floor):\n\n    $$l \u003c n -1 \\land atFloor(m, l, t) \\land ascend(m, t) \\implies atFloor(m, l+1, t+1)$$\n    $\\forall$ mover $m \\in M$, floor $l \\in L$, time $t \\in T$\n\n2. $descend(m, t)$: a mover can move down one floor at a time (except\n    when at the ground floor):\n\n    $$l \u003e 0 \\land atFloor(m, l, t) \\land descend(m, t) \\implies atFloor(m, l-1, t+1)$$\n    $\\forall$ mover $m \\in M$, floor $l \\in L$, time $t \\in T$\n\n3. $carry(m, f, t)$: a mover can carry a piece of forniture if it is at\n    the same floor as the mover. At the next time step, the mover and\n    the forniture will be at the floor below (except when at the ground\n    floor):\n\n    $l \u003e 0 \\land atFloor(m, l, t) \\land atFloorForniture(f, l, t) \\land carry(m, f, t) \\implies atFloor(m, l-1, t+1) \\land atFloorForniture(f, l-1, t+1)$\n\n    $\\forall \\ \\text{mover } m \\in M, \\text{forniture } f \\in F, \\text{floor } l \\in L, \\text{time } t \\in T$\n\n\n#### B. Initial and Final Constraints\n\n1. Initial constraint: movers start at the ground floor\n\n    $$atFloor(m_i, 0, 0)$$\n\n    $\\forall$ mover $m \\in M$\n\n2. Final constraint: movers end at the ground floor\n\n    $$atFloor(m, 0, t_{max}) \\land atFloorForniture(f, 0, t_{max})$$\n\n    $\\forall$ mover $m \\in M$, forniture $f \\in F$\n\n#### C. Other Constraints\n\n1. Each mover is exactly at one floor at a time\n\n    - Each mover is at least at one floor\n        $$\\bigvee_{m \\in M, l \\in L, t\\in T} atFloor(m, l, t)$$\n\n    - A mover cannot be at more than one floor\n        $$atFloor(m, l_1, t) \\implies \\lnot atFloor(m, l_2, t)$$\n\n        $\\forall$ mover $m \\in M$, floors $l_1 \\neq l_2 \\in L$, time\n        $t \\in T$\n\n2. Each forniture is exactly at one floor at a time\n\n    - Each forniture is at least at one floor\n        $$\\bigvee_{f \\in F, l \\in L, t\\in T} atFloorForniture(f, l, t)$$\n\n    - A forniture cannot be at more than one floor\n        $$atFloorForniture(f, l_1, t) \\implies \\lnot atFloorForniture(f, l_2, t)$$\n\n        $\\forall$ forniture $f \\in F$, floors $l_1 \\neq l_2 \\in L$, time\n        $t \\in T$\n\n3. If a mover is not ascending, descending, or carrying it stays at the\n    same floor\n\n    $$atFloor(m,l,t) \\land \\lnot ascend(m, t) \\land \\lnot descend(m, t) \\land \\bigwedge_{f \\in F} \\lnot carry(m, f, t) \\implies atFloor(m,l, t+1)$$\n\n    $\\forall$ mover $m \\in M$, floor $l \\in L$, time $t \\in T$\n\n4. If a forniture is not being carried, it stays at the same floor\n\n    $$atFloorForniture(f, l, t) \\land \\bigwedge_{m \\in M} \\lnot carry(m, f, t) \\implies atFloorForniture(f, l, t + 1)$$\n\n    $\\forall$ forniture $f \\in F$, floor $l \\in L$, time $t \\in T$\n\n5. Each mover can do only one action at a time\n\n    - $ascend(m, t) \\implies \\lnot descend(m, t)$\n\n    - $ascend(m, t) \\implies \\lnot carry(m, f, t)$\n\n    - $descend(m, t) \\implies \\lnot ascend(m, t)$\n\n    - $descend(m, t) \\implies \\lnot carry(m, f, t)$\n\n    - $carry(m, f, t) \\implies \\lnot ascend(m, t)$\n\n    - $carry(m, f, t) \\implies \\lnot descend(m, t)$\n\n    $\\forall$ mover $m \\in M$, floor $l \\in L$, forniture $f \\in F$,\n    time $t \\in T$\n\n6. Each mover can carry at most one piece of forniture\n\n    $$carry(m, f_1, t) \\implies \\lnot carry(m, f_2, t)$$\n\n    $\\forall$ mover $m\\in M$, forniture $f_1 \\neq f_2 \\in F$, time\n    $t \\in T$\n\n7. A piece of forniture can be carried by only one mover\n\n    $$carry(m_1, f, t) \\implies \\lnot carry(m_2, f, t)$$\n\n    $\\forall$ mover $m_1 \\neq m_2 \\in M$, forniture $f\\in F$, time\n    $t \\in T$\n\n8. Movers cannot ascend if they are at the top floor\n\n    $$atFloor(m, n-1, t) \\implies \\lnot ascend(m, t)$$\n\n    $\\forall$ mover $m \\in M$, time $t \\in T$\n\n9. Movers cannot descend if they are at the ground floor\n\n    $$atFloor(m, 0, t) \\implies \\lnot descend(m, t)$$\n\n    $\\forall$ mover $m \\in M$, time $t \\in T$\n\n10. A mover has to be on the same floor as an item in order to carry it\n\n    $$atFloor(m, l_1,t) \\land atFloorForniture(f, l_2, t) \\implies \\lnot carry(m, f, t)$$\n\n    $\\forall$ mover $m \\in M$, floors $l_1 \\neq l_2 \\in L$ , forniture\n    $f \\in F$, time $t \\in T$\n\n11. A mover cannot carry an item which is at the ground floor\n\n    $$atFloorForniture(f, 0, t) \\implies \\lnot carry(m, f, t)$$\n\n    $\\forall$ mover $m \\in M$, forniture $f \\in F$, time $t \\in T$\n\n## 1.3. System Design\n\nThe system has been divided into a frontend and a backend. The frontend\nis responsible for receiving the problem instance from the user and\nsending it to the backend for processing. The backend will receive the\nproblem data from a specialized API and will solve the problem using the\nz3-solver. The solution will be sent back to the frontend as a response.\n\nIn the following sections, the frontend and backend will be described in\nmore detail.\n\n### 1.3.1. Frontend - User Interface\n\nThe frontend of our system is built using Chakra UI, a simple, modular,\nand accessible component library that provides the building blocks\nneeded to build React applications. Chakra UI ensures a consistent look\nand feel across the application and enhances the development experience\nwith its extensive set of customizable components.\n\nTo facilitate interaction with the backend API, we have implemented a\ncustom library. This library simplifies API calls and manages the\ncommunication between the frontend and backend, ensuring a seamless and\nefficient data exchange.\n\nThe user initiates the process by composing a form in the React-app.\nThis form contains information about the problem setup, such as the\nnumber of movers, floors, maximum steps, and furniture details. Once the\nform is completed, the React-app sends an HTTP POST request to the\nbackend solver service at the `/solve` endpoint. This request includes\nthe data provided by the user. This form is used to validate user inputs\nbefore sending data to the backend. It ensures that the data received by\nthe backend is correct and reduces the likelihood of errors, providing a\nsmoother user experience.\n\n![System architecture\ndiagram](./report/images/System_Design.png)\n\n### 1.3.2. Backend - APIs and Solver\n\nThe backend, as previously mentioned, is responsible for receiving the\nproblem instance from the frontend and solving it using the z3-solver.\nThe backend exposes a single endpoint `/solve` which receives a JSON\nobject containing the problem instance and returns a JSON object with\nthe solution.\n\nThis `curl` command showcases an example of how to interact with the `/solve` endpoint using the backend API:\n\n```bash\n    curl -X 'POST' \\\n        'http://localhost:8000/api/v1/solve?n_movers=3\u0026n_floors=3\u0026max_steps=10' \\\n        -H 'accept: application/json' \\\n        -H 'Content-Type: application/json' \\\n        -d '[\n            {\n            \"name\": \"Table\",\n            \"floor\": 1\n            },\n            {\n            \"name\": \"Wardrobe\",\n            \"floor\": 2\n            }\n        ]'\n```\n\nThe sequence diagram below illustrates the interaction between a\nuser, the React-app frontend via Custom API, and the backend solver\nservice in a Movers SAT problem-solving application.\n\n![Sequence Diagram](./report/images/sequenceDiagram.png)\n\nBelow is a step-by-step explanation of the process:\n\n1. **Backend Solver Service**:\n\n    - Upon receiving the request, the backend solver service is\n        activated and begins processing the request.\n\n    - **Data Validation**: The backend performs data validation to\n        ensure that the input parameters (number of movers, floors,\n        maximum steps, and furniture details) are valid and correctly\n        formatted.\n\n    - **Problem Building**: After successful validation, the backend\n        constructs the problem by defining the necessary constraints and\n        setup required to solve the Movers SAT problem.\n\n    - **Problem Solving**: The backend then runs the solver to compute\n        the solution to the problem. This involves calculating the\n        optimal steps and actions needed to move the furniture as\n        specified.\n\n2. **Response to React-app**:\n\n    - Once the problem is solved, the backend sends the solution back\n        to the React-app. This response includes the computed steps and\n        actions for the movers and furniture.\n\n3. **Display Solution**:\n\n    - The React-app receives the solution and displays it to the user.\n        The user can now see the detailed steps and actions taken to\n        solve the Movers SAT problem.\n\nThis diagram captures the entire workflow from user input to solution\ndisplay, highlighting the key interactions and processes involved in\nsolving the Movers SAT problem using the React-app and backend solver\nservice.\n\n## 1.4. Evaluation and final considerations\n\nFirst of all, we needed to thoroughly understand the problem at hand. To\nachieve this, we organized a comprehensive discussion involving all team\nmembers. This discussion aimed to elucidate the various aspects of the\nproblem, ensuring that everyone had a clear and vivid understanding of\nthe issue. We explored different perspectives, asked clarifying\nquestions, and shared relevant insights, all of which contributed to a\nmore profound and collective grasp of the problem's intricacies. Then we\ndivided into smaller groups so that we could work on frontend and\nbackend at the same time.\n\n**General Problems:**\n\n1. As none of us had prior experience with the z3-solver, we had to\n    spend a considerable amount of time learning how to use it\n    effectively.\n\n2. We encountered some difficulty in identifying all the edge cases of\n    the problem due to the lack of clarity in certain descriptions.\n\n**Frontend Problems:**\n\n1. Due to our initial unfamiliarity with the React library, we required\n    a considerable amount of time to learn how to utilize it effectively\n    to achieve the desired results.\n\n2. Offering a user-friendly interface that is both intuitive and easy\n    to use was a significant challenge. We had to ensure that the\n    interface was easy to navigate and that users could input the\n    necessary data without any confusion.\n\n**Backend Problems:**\n\n1. We initially thought that certain constraints were not necessary,\n    but after further analysis, we realized that they were crucial for\n    the problem's correct solution.\n\n2. The backend API was challenging to implement as it required\n    additional features such as data validation, error handling, and\n    response formatting, features that we initially overlooked.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucadibello%2Fmovers-sat-problem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucadibello%2Fmovers-sat-problem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucadibello%2Fmovers-sat-problem/lists"}