{"id":13733011,"url":"https://github.com/TUM-DAML/seml","last_synced_at":"2025-05-08T09:31:25.428Z","repository":{"id":38012321,"uuid":"214903849","full_name":"TUM-DAML/seml","owner":"TUM-DAML","description":"SEML: Slurm Experiment Management Library","archived":false,"fork":false,"pushed_at":"2024-10-11T13:05:34.000Z","size":1724,"stargazers_count":168,"open_issues_count":10,"forks_count":30,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-30T10:55:03.308Z","etag":null,"topics":["experiment-manager","experiment-tracking","hyperparameter-optimization","orchestration","slurm","slurm-workload-manager","utility"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TUM-DAML.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":"2019-10-13T22:33:46.000Z","updated_at":"2024-10-11T13:05:38.000Z","dependencies_parsed_at":"2023-02-08T18:32:02.300Z","dependency_job_id":"d027987d-ae2a-4d19-8a96-4491e5f22020","html_url":"https://github.com/TUM-DAML/seml","commit_stats":{"total_commits":469,"total_committers":18,"mean_commits":"26.055555555555557","dds":"0.49466950959488276","last_synced_commit":"1ac4b06fcace4014dae5b9ea2d75cdc9c44daf81"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TUM-DAML%2Fseml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TUM-DAML%2Fseml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TUM-DAML%2Fseml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TUM-DAML%2Fseml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TUM-DAML","download_url":"https://codeload.github.com/TUM-DAML/seml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224717521,"owners_count":17357897,"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":["experiment-manager","experiment-tracking","hyperparameter-optimization","orchestration","slurm","slurm-workload-manager","utility"],"created_at":"2024-08-03T03:00:36.644Z","updated_at":"2024-11-15T01:31:11.274Z","avatar_url":"https://github.com/TUM-DAML.png","language":"Python","funding_links":[],"categories":["SLURM wrappers and libraries"],"sub_categories":[],"readme":"![Github Actions](https://github.com/TUM-DAML/seml/workflows/Test/badge.svg)\n\n# `SEML`: Slurm Experiment Management Library\n**`SEML`** is the missing link between the open-source workload scheduling system `Slurm`, the experiment management tool `sacred`, and a `MongoDB` experiment database. It is lightweight, hackable, written in pure Python, and scales to thousands of experiments.\n\nKeeping track of computational experiments can be annoying and failure to do so can lead to lost results, duplicate running of the same experiments, and lots of headaches.\nWhile workload scheduling systems such as [`Slurm`](https://slurm.schedmd.com/overview.html) make it easy to run many experiments in parallel on a cluster, it can be hard to keep track of which parameter configurations are running, failed, or completed.\n[`sacred`](https://github.com/IDSIA/sacred) is a great tool to collect and manage experiments and their results, especially when used with a [`MongoDB`](https://www.mongodb.com/). However, it is lacking integration with workload schedulers.\n\n**`SEML`** enables you to\n* very easily define hyperparameter search spaces using YAML files,\n* run these hyperparameter configurations on a compute cluster using `Slurm`,\n* and to track the experimental results using `sacred` and `MongoDB`.\n\n\nIn addition, **`SEML`** offers many more features to make your life easier, such as\n* automatically saving and loading your source code for reproducibility,\n* easy debugging on Slurm or locally,\n* automatically checking your experiment configurations,\n* extending Slurm with local workers,\n* and keeping track of resource usage (experiment runtime, RAM, etc.).\n\n## Get started\n### New projects\nThe fastest way to get started with `SEML` is via [`uv`](https://docs.astral.sh/uv/):\n1. Install `uv`:\n    ```bash\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n    ```\n2. Setup a new project\n    ```bash\n    # uvx will execute `SEML` in a temporary virtual environment\n    # and run it to setup your new project.\n    uvx seml project init my_new_project\n    ```\n3. Setup a virtual environment\n    ```bash\n    cd my_new_project\n    uv sync\n    ```\n4. Activate your virtual environment\n    ```bash\n    source .venv/bin/activate\n    ```\n5. Configure `SEML`:\n    ```bash\n    seml configure\n    ```\n\nWhen executing `SEML` make sure to always use the `seml` command from your project's virtual environment and only use `uvx seml` for high-level commands that do not affect experiments (like setting up new projects).\n\n### Existing projects\nIf you want to include `SEML` into existing projects, you can install it via:\n```bash\npip install seml\n```\nThen configure your MongoDB via:\n```bash\nseml configure\n```\n\n\n### SSH Port Forwarding\nIf your MongoDB is only accessible via an SSH port forward, **`SEML`** allows you to directly configure this as well if you install the `ssh_forward` dependencies via:\n```bash\npip install seml[ssh_forward]\n```\nIt remains to configure the SSH settings:\n```bash\nseml configure --ssh_forward\n```\n\n### Development\nFor development, we recommend [`uv`](https://docs.astral.sh/uv/) which you can install via\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\nSetup the right environment use and activate it:\n```bash\nuv sync --locked\nsource .venv/bin/activate\n```\nAlternatively, you can install the repository in any Python environment via:\n```bash\npip install -e .[dev]\n```\n\n#### Pre-commit hooks\nMake sure to install the pre-commit hooks via\n```bash\npre-commit install\n```\n\n## Documentation\nDocumentation is available in our [docs.md](docs.md) or via the CLI:\n```python\nseml --help\n```\n\n## Example\nSee our simple [example](examples) to get familiar with how **`SEML`** works.\n\n## CLI completion\nSEML supports command line completion. To install this feature run:\n```bash\nseml --install-completion {shell}\n```\n\nIf you are using the zsh shell, you might have to append `compinit -D` to the `~/.zshrc` file (see this [issue](https://github.com/tiangolo/typer/issues/180#issuecomment-812620805)).\n\n## Slurm version\n\nSEML should work with Slurm 18.08 and above out of the box. Version 17.11 and earlier do not have a SIGNALING job state, which you have to remove from the SLURM_STATES defined in SEML's settings (`seml/settings.py`). Earlier versions have not been tested and might have other issues.\n\n## Contact\nContact us at zuegnerd@in.tum.de, johannes.gasteiger@tum.de, or n.gao@tum.de for any questions.\n\n## Cite\nWhen you use SEML in your own work, please cite the software along the lines of the following bibtex:\n\n```\n@software{seml_2023,\n  author = {Z{\\\"u}gner, Daniel and Gasteiger, Johannes and Gao, Nicholas and Dominik Fuchsgruber},\n  title = {{SEML: Slurm Experiment Management Library}},\n  url = {https://github.com/TUM-DAML/seml},\n  version = {0.4.0},\n  year = {2023}\n}\n```\n\n\nCopyright (C) 2023\nDaniel Zügner, Johannes Gasteiger, Nicholas Gao, Dominik Fuchsgruber\nTechnical University of Munich\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTUM-DAML%2Fseml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTUM-DAML%2Fseml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTUM-DAML%2Fseml/lists"}