{"id":31802492,"url":"https://github.com/tidedra/doma","last_synced_at":"2026-05-08T15:01:43.174Z","repository":{"id":309725998,"uuid":"1037282604","full_name":"TideDra/doma","owner":"TideDra","description":"Automatically hold idle GPU.","archived":false,"fork":false,"pushed_at":"2025-08-20T14:12:38.000Z","size":333,"stargazers_count":78,"open_issues_count":5,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T05:59:27.833Z","etag":null,"topics":["gpu","nvidia","python"],"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/TideDra.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":"2025-08-13T10:39:51.000Z","updated_at":"2025-09-24T06:09:51.000Z","dependencies_parsed_at":"2025-08-13T14:20:32.852Z","dependency_job_id":"9990b18e-1c9e-404c-83d6-39f7004bce8d","html_url":"https://github.com/TideDra/doma","commit_stats":null,"previous_names":["tidedra/doma"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TideDra/doma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TideDra%2Fdoma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TideDra%2Fdoma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TideDra%2Fdoma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TideDra%2Fdoma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TideDra","download_url":"https://codeload.github.com/TideDra/doma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TideDra%2Fdoma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005650,"owners_count":26083942,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["gpu","nvidia","python"],"created_at":"2025-10-11T00:41:47.798Z","updated_at":"2026-05-08T15:01:43.166Z","avatar_url":"https://github.com/TideDra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Doma\n\n**Doma** (Dog in the Manger) is a GPU utilization controller that guarantees a minimum GPU utilization percentage on NVIDIA and AMD GPUs. It dynamically adjusts GPU workload to maintain the desired utilization level, making it useful for GPU reservation, testing, and preventing GPUs from being idle.\n\n## Features\n\n- 🎯 **Guaranteed Minimum Utilization**: Ensures your GPUs maintain at least the specified utilization percentage.\n- 🔧 **Multi-GPU Support**: Control multiple GPUs simultaneously with individual thread management.\n- 🔄 **Dynamic Adjustment**: Automatically adjusts workload based on other processes using the GPU. No performance impact on your real job.\n- ⚡ **Extremely Light-weight**: No PyTorch, CUDA Toolkit, or ROCm compiler is needed at runtime. NVIDIA uses the driver/NVML stack, and AMD uses embedded HSACO kernels plus ROCm HIP/AMD SMI runtime libraries.\n\n\n## Installation\n\n### From Source\n\n```bash\n# Make sure rust environment is installed\ngit clone https://github.com/TideDra/doma.git\ncd doma\ncargo build --release\n```\n\nThe compiled binary will be available at `target/release/doma`.\n\nRuntime requirements:\n\n- NVIDIA: NVIDIA driver libraries (`libcuda.so.1`) and NVML.\n- AMD: ROCm HIP runtime (`libamdhip64.so`) and AMD SMI (`libamd_smi.so`). `hipcc` and HIPRTC are not needed to run doma.\n\n### Use compiled binary\nCompiled binary can be found at [Releases](https://github.com/TideDra/doma/releases).\n```bash\n# Download the binary\nwget https://github.com/TideDra/doma/releases/download/v0.1.0/doma-v0.1.0-x86_64-unknown-linux-gnu.tar.gz\n# Unzip the binary\ntar -xzf doma-v0.1.0-x86_64-unknown-linux-gnu.tar.gz\n# Run the binary\n./doma 50\n```\n\nDoma automatically selects an available backend. To force a specific backend:\n\n```bash\n./doma 50 --backend nvidia\n./doma 50 --backend amd\n```\n\n## Usage\n\n### Basic Usage\n\nSet minimum GPU utilization to 50% on all available GPUs:\n\n```bash\n./doma 50\n```\n\n### Control Specific GPUs\n\nSet minimum utilization to 70% on GPUs 0 and 2:\n\n```bash\n./doma 70 --device-ids 0,2\n# or use short form\n./doma 70 -d 0,2\n```\n\nFor AMD GPUs, device IDs are HIP device IDs, which normally match `amd-smi list` ordering.\n\n### Stop the Controller\n\nPress `Ctrl+C` to gracefully stop all GPU controllers.\n\n## How It Works\n\nDoma operates by:\n\n1. **Calibration**: On startup, it calibrates an embedded CUDA PTX or AMD HSACO kernel to determine how many loop iterations are needed per millisecond on your GPU\n2. **Monitoring**: Uses NVML on NVIDIA and AMD SMI on AMD to monitor current GPU utilization and process activity\n3. **Dynamic Adjustment**: Calculates how much additional utilization is needed to reach the target\n4. **Workload Injection**: Executes calibrated CUDA/AMD kernels in time windows (100ms by default) to maintain the desired utilization\n5. **Sleep Cycles**: Sleeps for the remaining time in each window to avoid exceeding the target\n\nThe controller continuously adjusts its workload based on other processes using the GPU, ensuring the total utilization stays at or above the minimum threshold. If your GPU job already reaches the threshold, **doma will not occupy the GPU.**\n\nThe AMD kernel is precompiled and embedded in the binary for common ROCm targets (`gfx90a`, `gfx942`, `gfx950`, `gfx1030`, `gfx1100`, `gfx1101`, and `gfx1102`). If you modify `src/hip/kernel.hip`, regenerate `src/hip/kernel.hsaco` with `hipcc --genco` before building a release.\n\n## Command-Line Options\n\n```\nUsage: doma [OPTIONS] \u003cMIN_UTIL\u003e\n\nArguments:\n  \u003cMIN_UTIL\u003e  Minimum utilization percentage (1-100)\n\nOptions:\n  -d, --device-ids \u003cDEVICE_IDS\u003e  GPU IDs to control, separated by commas\n  -m, --mem-reserve \u003cMEM_RESERVE\u003e GPU memory to reserve in GB when no other compute process is present\n      --backend \u003cBACKEND\u003e         GPU backend to use [default: auto] [possible values: auto, nvidia, amd]\n  -h, --help                      Print help\n  -V, --version                   Print version\n```\n\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**TideDra** - [gearyzhang@outlook.com](mailto:gearyzhang@outlook.com)\n\n## Repository\n\n[https://github.com/TideDra/doma](https://github.com/TideDra/doma)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidedra%2Fdoma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftidedra%2Fdoma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidedra%2Fdoma/lists"}