{"id":8017,"library":"clusterscope","title":"Clusterscope","description":"Clusterscope is a Python library and CLI tool designed to extract information from High-Performance Computing (HPC) clusters and jobs, particularly those using Slurm. It provides functionalities for cluster detection, GPU/CPU/memory information, job requirement generation, and AWS environment detection. The library is actively maintained, with frequent releases, and is currently at version 0.0.32.","status":"active","version":"0.0.32","language":"en","source_language":"en","source_url":"https://github.com/facebookresearch/clusterscope","tags":["HPC","CLI","cluster management","Slurm","job management","GPU","CPU","AWS"],"install":[{"cmd":"pip install clusterscope","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The `cluster()` function directly returns the detected cluster name.","symbol":"cluster","correct":"import clusterscope; clusterscope.cluster()"},{"note":"Used to retrieve detailed GPU information. The CLI command `cscope gpus` is a common way to access this functionality.","symbol":"get_gpus","correct":"from clusterscope.gpus import get_gpus"}],"quickstart":{"code":"import clusterscope\n\n# Get the detected cluster name\ncluster_name = clusterscope.cluster()\nprint(f\"Detected cluster: {cluster_name}\")\n\n# You can also use the CLI for more specific information:\n# print(\"\\nTry running these commands in your terminal:\")\n# print(\"  $ cscope gpus\") # Show GPU information\n# print(\"  $ cscope cpus\") # Show CPU counts per node\n# print(\"  $ cscope mem\")  # Show memory information per node\n# print(\"  $ cscope aws\")  # Check if running on AWS and show NCCL settings","lang":"python","description":"Demonstrates how to import the `clusterscope` library and use its `cluster()` function to identify the current HPC cluster name. It also hints at the available command-line interface (CLI) tools like `cscope gpus` for detailed hardware information."},"warnings":[{"fix":"Review code for `clusterscope` object instantiation and method calls within `__init__`. Ensure methods are called explicitly after object creation if they were implicitly called by the constructor in prior versions.","message":"Changes in v0.0.31 removed direct `init` calls to methods. Code relying on implicit initialization or specific method call order in constructors might break.","severity":"breaking","affected_versions":"v0.0.31 and later"},{"fix":"Ensure a properly configured and accessible Slurm environment on the head node. Verify that standard Slurm CLI commands (`sinfo`, `squeue`, `scontrol`, `srun`, `sbatch`) are functional and produce expected output. Consult Slurm documentation and cluster administrators for environment setup.","message":"Clusterscope heavily integrates with Slurm. Misconfigurations in the Slurm environment (e.g., missing `sinfo`, `squeue` commands, incorrect `srun` environment variables, or unexpected Slurm output formats) can lead to incorrect or incomplete information being extracted.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For unexpected results, particularly with `gpus`, `cpus`, or `aws` commands, check the clusterscope documentation or GitHub issues for known compatibility notes with specific cluster setups (e.g., different AWS instance types, Slurm versions, or NVIDIA driver configurations).","message":"The library's functionality might be affected by specific cluster hardware or cloud configurations, especially regarding GPU visibility or resource allocation details. For instance, the changelog mentions `getting max gpus, cpus out of sinfo output` and updates related to `aws nccl defaults`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install clusterscope`","cause":"The `clusterscope` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'clusterscope'"},{"fix":"Ensure your Python environment is activated (e.g., `source .venv/bin/activate`) or that pip's script directory is in your system's PATH. If using `pipx`, ensure `pipx ensurepath` has been run.","cause":"The `cscope` command-line entry point is not in your system's PATH, or the package was installed into an environment not activated in your shell.","error":"cscope: command not found"},{"fix":"Verify that you are on a node with Slurm client tools installed and configured. Try running native Slurm commands like `sinfo`, `squeue` to confirm they work. Ensure necessary environment variables (e.g., `SLURM_CONF`) are set correctly.","cause":"Clusterscope could not detect the cluster type or retrieve information from the underlying HPC system (e.g., Slurm). This often happens if Slurm commands are not available or if the output format is unexpected.","error":"(CLI output is empty or shows 'Unknown cluster')"}]}