diff --git a/README.md b/README.md index 8d88355..264faad 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,27 @@ Published in [ACM Transactions on Graphics (TOG)](https://dl.acm.org/doi/abs/10. - **โœจ Stay Clean**: You can remove all traces after use. - **๐Ÿ‘Œ Open**: We have opted the Apache v2.0 license. +## ๐Ÿ”– Table of Contents + +- [๐ŸŽ“ Technical Materials](#-technical-materials) +- [โšก๏ธ Requirements](#๏ธ-requirements) +- [๐Ÿ“ Change History](#-change-history) +- [๐Ÿ How To Use](#-how-to-use) +- [๐Ÿ–ผ๏ธ Catalogue](#๏ธ-catalogue) +- [๐Ÿ’จ Getting Started](#-getting-started) + - [๐ŸŽฅ Installation Videos](#-installation-videos) + - [๐Ÿณ Installing Docker](#-installing-docker) + - [๐ŸชŸ Windows](#-windows) + - [๐Ÿง Linux](#-linux) + - [๐Ÿงน Cleaning Up](#-cleaning-up) +- [๐Ÿ“ก Deploying on Cloud Services](#-deploying-on-cloud-services) + - [๐Ÿ“ฆ Deploying on vast.ai](#-deploying-on-vastai) + - [๐Ÿ“ฆ Deploying on RunPod](#-deploying-on-runpod) + - [๐Ÿ“ฆ Deploying on Google Compute Engine](#-deploying-on-google-compute-engine) +- [๐Ÿ“ƒ License](#-license) +- [๐Ÿ™ Acknowledgements](#-acknowledgements) +- [๐Ÿ–‹ Citation](#-citation) + ## ๐ŸŽ“ Technical Materials - ๐ŸŽฅ Main video [[Video]](https://drive.google.com/file/d/1OzPbUoqddUYDvXMvRnUHH7kz0nZhmt7K/view?usp=drive_link) @@ -40,6 +61,7 @@ Published in [ACM Transactions on Graphics (TOG)](https://dl.acm.org/doi/abs/10. - (2024.12.16) Removed thrust dependencies to fix runtime errors for the driver version `560.94` [[Issue Link]](https://github.com/st-tech/ppf-contact-solver/issues/1). ## ๐Ÿ How To Use + Our frontend is accessible through ๐ŸŒ a browser using our built-in JupyterLab ๐Ÿ interface. All is set up when you open it for the first time. Results can be interactively viewed through the browser and exported as needed. @@ -147,7 +169,7 @@ This is not a self-hosted runner, meaning that each time the runner launches, al ### ๐ŸŽฅ Installation Videos -We provide uninterrupted recorded installation videos (๐ŸชŸ Windows [[Video]](https://drive.google.com/file/d/1Np3MwUtSlppQPMrawtobzoGtZZWrmFgG/view?usp=sharing), ๐Ÿง Linux [[Video]](https://drive.google.com/file/d/1ZDnzsn46E1I6xNzyg0S8Q6xvgXw_Lw7M/view?usp=sharing) and โ˜ [vast.ai](https://vast.ai) [[Video]](https://drive.google.com/file/d/1k0LnkPKXuEwZZvElaKohWZeDd6M3ONe1/view?usp=sharing)) +We provide uninterrupted recorded installation videos (๐ŸชŸ Windows [[Video]](https://drive.google.com/file/d/1Np3MwUtSlppQPMrawtobzoGtZZWrmFgG/view?usp=sharing), ๐Ÿง Linux [[Video]](https://drive.google.com/file/d/1ZDnzsn46E1I6xNzyg0S8Q6xvgXw_Lw7M/view?usp=sharing), โ˜ [vast.ai](https://vast.ai) [[Video]](https://drive.google.com/file/d/1k0LnkPKXuEwZZvElaKohWZeDd6M3ONe1/view?usp=sharing), and โ˜๏ธ [Google Cloud](https://cloud.google.com/products/compute) [[Video]](https://drive.google.com/file/d/1dj6TvR2IVLKLFXtO8QRrRl-8xQ7G547A/view?usp=sharing)) to reduce stress ๐Ÿ˜ฃ during the installation process. We encourage you to ๐Ÿ‘€ check them out to get a sense of how things go โณ and how long โฑ๏ธ each step takes. ### ๐Ÿณ Installing Docker @@ -304,7 +326,7 @@ and now you can access our JupyterLab frontend from http://localhost:8080 on you The port number `8080` is the one we set for `$MY_WEB_PORT`. Enjoy! ๐Ÿ˜„ -## ๐Ÿงน Cleaning Up +### ๐Ÿงน Cleaning Up To remove all traces, simply stop ๐Ÿ›‘ the container and โŒ delete it. Be aware that all simulation data will be also lost. Back up any important data if needed. @@ -321,7 +343,9 @@ docker rm $MY_CONTAINER_NAME > ``` > but don't do this if you still need it. -## โ˜ Running on [vast.ai](https://vast.ai) +## ๐Ÿ“ก Deploying on Cloud Services + +### ๐Ÿ“ฆ Deploying on [vast.ai](https://vast.ai) The exact same steps above should work (see `.github/workflows/getting-started-vast.yml`), except that you'll need to create a Docker template. Here's one: @@ -332,10 +356,12 @@ The exact same steps above should work (see `.github/workflows/getting-started-v - For a better experience, choose a geographically nearby server with a high connection speed. - Also, make sure to allocate a large disk space, such as 64GB. +**Important**: Don't forget to โŒ delete the instance after use, or youโ€™ll be ๐Ÿ’ธ charged for nothing. + vast template vast diskspace -## ๐Ÿ“ฆ Running on [RunPod](https://runpod.io) +### ๐Ÿ“ฆ Deploying on [RunPod](https://runpod.io) You can deploy our solver on a RunPod instance. To do this, we need to select an official RunPod Docker image instead. Here's how @@ -349,9 +375,64 @@ Here's how - โœ… Make sure to select `SSH Terminal Access` - โŒ Deselect `Start Jupyter Notebook` +**Important**: Don't forget to โŒ delete the instance after use, or youโ€™ll be ๐Ÿ’ธ charged for nothing. + runpod template runpod deploy +### ๐Ÿ“ฆ Deploying on [Google Compute Engine](https://cloud.google.com/products/compute) + +First, set up your `gcloud` CLI by following ๐Ÿ“š [this guide](https://cloud.google.com/sdk/docs/install?hl=en) Next, run the command below to provision an โšก NVIDIA L4 GPU instance. +As of late 2024, this setup costs approximately ๐Ÿ’ต $1 per hour. + +```bash +export IMAGE="projects/ml-images/global/images/c0-deeplearning-common-gpu-v20241118-debian-11-py310" +export ZONE="asia-east1-c" +export INSTANCE_NAME="ppf-contact-solver" +export INSTANCE_TYPE="g2-standard-8" + +gcloud compute instances create $INSTANCE_NAME \ + --zone=$ZONE \ + --machine-type=$INSTANCE_TYPE \ + --network-interface=network-tier=PREMIUM,stack-type=IPV4_ONLY,subnet=default \ + --maintenance-policy=TERMINATE \ + --provisioning-model=STANDARD \ + --accelerator=count=1,type=nvidia-l4 \ + --create-disk=auto-delete=yes,boot=yes,image=$IMAGE,mode=rw,size=50,type=pd-balanced \ + --no-shielded-secure-boot \ + --shielded-vtpm +``` + +After creating the instance, try connecting to it via `ssh` using the ๐ŸŒ `gcloud` interface. Since port `8080` is taken by the deployed image, make sure to select a different port on the host side. +Here, we set the host-side port to `8888`. +Note that the local port remains `8080` so that the JupyterLab interface can be accessed at `http://localhost:8080`. +I know this might be confusing, so just copy and paste if you're okay with it. + +```bash +# Port number 8080 is taken, so let's use 8888 +gcloud compute ssh --zone=$ZONE $INSTANCE_NAME -- -L 8080:localhost:8888 +``` + +As shown in this [[Video]](https://drive.google.com/file/d/1dj6TvR2IVLKLFXtO8QRrRl-8xQ7G547A/view?usp=sharing), the instance may take a few minutes to load, so early SSH access fails. +Keep trying at intervals; it should connect once the host is ready. + +Next, run the same Docker ๐Ÿง [Linux](#-linux) command in the instance to set up a ๐Ÿณ Docker environment. Be sure to change `$MY_WEB_PORT` to `8888` in this case. + +``` +MY_WEB_PORT=8888 # Make sure to set the port to 8888 +MY_TIME_ZONE=Asia/Tokyo # Your time zone +MY_CONTAINER_NAME=ppf-contact-solver # Container name +``` + +The rest of the installation process is identical. After use, don't forget to โŒ delete the instance, or you will continue to be ๐Ÿ’ธ charged. + +```bash +gcloud compute instances stop --zone=$ZONE $INSTANCE_NAME +gcloud compute instances delete --zone=$ZONE $INSTANCE_NAME +``` + +Just to be sure, double-check from the ๐Ÿ–ฅ๏ธ web console to confirm that the instance has been successfully โœ… deleted. + ## ๐Ÿ“ƒ License ๐Ÿ“ This project is licensed under Apache v2.0 license.