{"id":26035258,"url":"https://github.com/jeepway/pat","last_synced_at":"2026-04-30T02:32:31.454Z","repository":{"id":262653242,"uuid":"887930951","full_name":"JeepWay/PaT","owner":"JeepWay","description":"Online 2D Bin Packing Problem Based on Deep Reinforcement Learning with Transformer and PPO","archived":false,"fork":false,"pushed_at":"2025-06-11T06:29:48.000Z","size":170,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T07:39:25.439Z","etag":null,"topics":["2d-bin-packing","bin-packing","deep-reinforcement-learning","online-bin-packing","ppo","reinforcement-learning","transformer"],"latest_commit_sha":null,"homepage":"","language":"Python","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/JeepWay.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,"zenodo":null}},"created_at":"2024-11-13T14:27:20.000Z","updated_at":"2025-06-11T06:29:51.000Z","dependencies_parsed_at":"2025-01-04T15:21:24.171Z","dependency_job_id":"dd222640-9cf3-449d-9d2a-d34ad7e05008","html_url":"https://github.com/JeepWay/PaT","commit_stats":null,"previous_names":["jeepway/mask-pack","jeepway/pat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JeepWay/PaT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeepWay%2FPaT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeepWay%2FPaT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeepWay%2FPaT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeepWay%2FPaT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeepWay","download_url":"https://codeload.github.com/JeepWay/PaT/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeepWay%2FPaT/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262266711,"owners_count":23284747,"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":["2d-bin-packing","bin-packing","deep-reinforcement-learning","online-bin-packing","ppo","reinforcement-learning","transformer"],"created_at":"2025-03-07T03:06:37.705Z","updated_at":"2026-04-30T02:32:31.449Z","avatar_url":"https://github.com/JeepWay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PaT: Transformer-based Deep Reinforcement Learning for Large-sized Online 2D Bin Packing\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/JeepWay/PaT)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/JeepWay/PaT/blob/main/LICENSE)  \n\n## 1. Environment\n- OS: Ubuntu 20.04.1\n- Python: 3.9.15\n- PyTorch: 2.4.1+cu118\n- stable-baselines3: 2.3.2\n\u003e Note: The training results might change across different hardware configurations (e.g., different GPUs), even under the same .yaml setting file and OS.\n\n\n## 2. Installation\n### 2.1 Clone this project\n```bash\ngit clone https://github.com/JeepWay/PaT.git\n```\nAfter cloning, navigate to the project directory:\n```bash\ncd PaT\n```\n\n### 2.2 Create new conda environment\nIf you want to create the new conda environment, you can execute the following commands.\n\n```bash\n# only cpu\nbash scripts/install.sh -c 0\n\n# use cuda (version: 11.8) (recommended)\nbash scripts/install.sh -c 11.8\n```\nYou may need to modify the path to your `conda.sh` file in the `install.sh` script, depending on where Miniconda or Anaconda is installed on your system.\n\nAfter installing the conda environment, you need to activate it.\n\n```bash\nconda activate PaT\n```\n\n### 2.2 Use existing conda environment\nIf you want to use the existing conda environment, you can execute the following command.\n\n```bash\nconda activate \u003cyour-env-name\u003e\n```\n\n```bash\n# use cuda\npip install -r requirements.txt\n```\n\n\n## 3. Repository structure\n```bash\n├── envs/                  # 2D bin packing environment\n│   ├── bpp/               # Core bin packing environment  \n│   │   ├── __init__.py    # Package (bpp) setup\n│   │   ├── bpp.py         # Main BppEnv class  \n│   │   ├── bin.py         # Manage bin state\n│   │   ├── creator.py     # Create requested items\n│   │   └── item.py        # Item class definition  \n│   └── register.py        # Environment registration \n├── fig/                   # Store training curves files, ignored by git\n│   └── *.png              # Training curves PNG files, ignored by git\n├── logs/                  # Store training logs, model weights and so on, ignored by git\n│   └── ppo/               # Algorithm name, ignored by git\n│   │   ├── 2DBpp-v1_PPO-*/ # 10x10 environment, named according to .yaml, ignored by git\n│   │   ├── 2DBpp-v2_PPO-*/ # 20x20 environment, named according to .yaml, ignored by git \n│   │   └── 2DBpp-v3_PPO-*/ # 40x40 environment, named according to .yaml, ignored by git\n├── pat/                   # DRL agent implementation (PPO with Transformer)  \n│   ├── common/            # Custom Stable-Baselines3 (SB3) common utilities\n│   ├── ppo/               # PPO algorithm implementation (SB3)\n│   ├── __init__.py        # Package (pat) setup\n├── save_weight/           # Trained model weights of main method\n│   ├── 2DBpp-v1_PPO-*/    # 10x10 environment \n│   ├── 2DBpp-v2_PPO-*/    # 20x20 environment \n│   └── 2DBpp-v3_PPO-*/    # 40x40 environment\n├── scripts/               # Installation and execution scripts  \n│   ├── install.sh         # Environment setup (CPU/GPU)  \n│   ├── all.sh             # Commands to run all experiments\n│   ├── build_docker.sh    # script to build Docker image, called by Makefile\n│   ├── run_docker_cpu.sh  # script to run Docker CPU image, called by Makefile  \n│   └── run_docker_gpu.sh  # script to run Docker GPU image, called by Makefile  \n├── settings/              # YAML configuration files for experiments  \n│   ├── cnn_net/           # CNN-based network\n│   ├── diff_reward_type/  # Different reward function\n│   ├── general/           # Generalization mechanism testing\n│   ├── hybrid_net/        # Hybrid network (CNN + Transformer)\n│   ├── main/              # Main methods\n│   ├── mixed/             # Mixed-training\n│   ├── mask_replace/      # Grid search of replace method in action masking\n│   └── multi_layer/       # Multi-layer for Transformer  \n├── test_data/             # Requested item sequences in testing phase, use `get_test_data.py` to get it\n│   ├── 2DBpp-v1/          # 10x10 environment \n│   ├── 2DBpp-v2/          # 20x20 environment \n│   └── 2DBpp-v3/          # 40x40 environment\n├── get_test_data.py       # Get the information of requested item sequences in testing\n├── main.py                # Main entry point for single-env training/testing  \n├── main_mixed.py          # Mixed environment training  \n├── main_general.py        # Generalization mechanism testing\n├── UI.py                  # Gradio-based visualization interface to demo bin packing progress\n└── utils.py               # Functions to format result, update .yaml files, and plot training curves.\n```\n\n\n## 4. Usage example\n### 4.1 Run the main methods with configuration files\nAll experiment configuration files (.yaml) are organized under the [/settings](/settings/) directory, categorized by different network types (e.g., main, hybrid_net, multi_layer, cnn_net, etc.).\n\n```bash\n# 10x10\npython main.py --config_path settings/main/v1_PPO-h200-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml\n\n# 20x20\npython main.py --config_path settings/main/v2_PPO-h400-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml\n\n# 40x40\npython main.py --config_path settings/main/v3_PPO-h1600-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml\n```\n\nFor more examples, please refer to the [scripts/all.sh](scripts/all.sh) script, which contains the complete commands for all experiments in the thesis. \n\nEach command corresponds to specific YAML configuration files in the [settings/](/settings/) directory, ensuring experimental reproducibility and systematic management.\n\nFor more details about the configuration files, please refer to the [update_yaml_files](utils.py#L69) function in the [utils.py](/utils.py) file. \n\nYou can copy a template from [settings/main/v1_PPO-h200-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml](settings/main/v1_PPO-h200-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml) and rename the copied file according to your experiment, and then use the [update_yaml_files](utils.py#L69) function to update the content in YAML file.\n\nTraining and Testing are stored in `/logs/ppo/2DBpp-vX_PPO-*` folder, generated and named based on the filename of the given YAML configuration file.\n\nIf you want to formatting testing results, you can run [formatted_result](utils.py#L13) function in the [utils.py](/utils.py) file. This function will extract testing results from `eval_50_20.txt` under each sub-folder to a single `csv` file.\n\nFor the usage of plotting training figure, you can see the [example](utils.py#L406) in  [utils.py](/utils.py) file.\n\n### 4.2 Choose training, testing mode, or both\nYou can choose to run the training, testing, or both modes by adding the `--mode` flag into the command, you can also set it to `train` or `test`, or `both`. If you don't set the `--mode` flag, it will default to `both` mode.\n\nFor example, if you want to run the testing phase after completing training phase, you can execute the following command:\n\n```bash\npython main.py --mode test --config_path settings/main/v1_PPO-h200-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml\n```\n\n### 4.3 Watch the training process in tensorboard (Optional)\nif you want to watch the training process in tensorboard, you can execute the following command in the terminal:\n```bash\ntensorboard --logdir=logs/\n```\n\n### 4.4 Upload the training process to wandb (Optional)\nIf you want to upload the training results to Weights \u0026 Biases (wandb), you need to add the `--use_wandb` flag to the command. For example:\n\n```bash\n# 10x10\npython main.py --config_path settings/main/v1_PPO-h200-c02-n64-b32-R15-transform3_TF,64,4,256,0,1-k1-rA-T.yaml --use_wandb\n```\n\nAfter executing the above command, you will be asked to choose the visualization mode like below.\n\n```bash\nwandb: (1) Create a W\u0026B account\nwandb: (2) Use an existing W\u0026B account\nwandb: (3) Don't visualize my results\nwandb: Enter your choice: \n```\nIf you want to visualize the training results on the wandb website, you can choose the second option, and then you will be asked to paste the API key of your wandb account. \n\nIf you don't have one, you can choose the first option to create a new account.\n\nIf you just want to save the training results locally, you can choose the third option.\n\n### 4.5 Visualize the bin packing process (Optional)\nIf you want to watch the progress of the bin packing process, you can run `UI.py` file, which provides a Gradio-based interface to visualize the bin packing process.\n\n```bash\npython UI.py\n```\n\nThere is also an online demo hosted on Hugging Face Spaces, running on a free CPU. You can try it out [here](https://huggingface.co/spaces/JeepWay/PaT_2D_Bin_Packing_Environment).\n\n## 5. Use docker images (Optional)\nFor more detail of `make` command, please refer to the [Makefile](Makefile).\n\n### Build docker image\nBuild CPU image:\n```bash\nmake docker-cpu\n```\nBuild GPU image (with nvidia-docker):\n```bash\nmake docker-gpu\n```\n\n### Run GPU images\nRun the nvidia-container-toolkit GPU image\n```bash\ndocker run -it --rm --gpus=all --volume $(pwd):/home/user/pat jeepway/pat-gpu:latest bash -c \"cd /home/user/pat \u0026\u0026 ls \u0026\u0026 pwd \u0026\u0026 /bin/bash\"\n```\n\nOr, use `make` command to run with the shell file\n```bash\nmake docker-run-gpu\n```\nAfter executing the above command, you will enter the terminal of the container.\n\n### Run CPU images\nRun the docker CPU image\n```bash\ndocker run -it --rm --volume $(pwd):/home/user/pat jeepway/pat-cpu:latest bash -c \"cd /home/user/pat \u0026\u0026 ls \u0026\u0026 pwd \u0026\u0026 /bin/bash\"\n```\n\nOr, use `make` command to run with the shell file\n```bash\nmake docker-run-cpu\n```\nAfter executing the above command, you will enter the terminal of the container.\n\n\n## 6. Compared algorithms\nyou can watch the source code of the compared algorithms in this [repository](https://github.com/JeepWay/pat-compare-algorithm)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeepway%2Fpat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeepway%2Fpat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeepway%2Fpat/lists"}