ClusterOps API Reference
ClusterOps is a Python library for managing and executing tasks across CPU and GPU resources in a distributed computing environment. It provides functions for resource discovery, task execution, and performance monitoring.
Installation
$ pip3 install clusterops
Table of Contents
CPU Operations
GPU Operations
Utility Functions
Resource Monitoring
CPU Operations
list_available_cpus()
Lists all available CPU cores.
Returns
Type
Description
List[int]
A list of available CPU core indices.
Raises
Exception
Description
RuntimeError
If no CPUs are found.
Example
from clusterops import list_available_cpus
available_cpus = list_available_cpus ()
print ( f "Available CPU cores: { available_cpus } " )
execute_on_cpu(cpu_id: int, func: Callable, *args: Any, **kwargs: Any) -> Any
Executes a callable on a specific CPU.
Parameters
Name
Type
Description
cpu_id
int
The CPU core to run the function on.
func
Callable
The function to be executed.
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
Any
The result of the function execution.
Raises
Exception
Description
ValueError
If the CPU core specified is invalid.
RuntimeError
If there is an error executing the function on the CPU.
Example
from clusterops import execute_on_cpu
def sample_task ( n : int ) -> int :
return n * n
result = execute_on_cpu ( 0 , sample_task , 10 )
print ( f "Result of sample task on CPU 0: { result } " )
execute_with_cpu_cores(core_count: int, func: Callable, *args: Any, **kwargs: Any) -> Any
Executes a callable using a specified number of CPU cores.
Parameters
Name
Type
Description
core_count
int
The number of CPU cores to run the function on.
func
Callable
The function to be executed.
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
Any
The result of the function execution.
Raises
Exception
Description
ValueError
If the number of CPU cores specified is invalid or exceeds available cores.
RuntimeError
If there is an error executing the function on the specified CPU cores.
Example
from clusterops import execute_with_cpu_cores
def parallel_task ( n : int ) -> int :
return sum ( range ( n ))
result = execute_with_cpu_cores ( 4 , parallel_task , 1000000 )
print ( f "Result of parallel task using 4 CPU cores: { result } " )
GPU Operations
list_available_gpus() -> List[str]
Lists all available GPUs.
Returns
Type
Description
List[str]
A list of available GPU names.
Raises
Exception
Description
RuntimeError
If no GPUs are found.
Example
from clusterops import list_available_gpus
available_gpus = list_available_gpus ()
print ( f "Available GPUs: { available_gpus } " )
select_best_gpu() -> Optional[int]
Selects the GPU with the most free memory.
Returns
Type
Description
Optional[int]
The GPU ID of the best available GPU, or None if no GPUs are available.
Example
from clusterops import select_best_gpu
best_gpu = select_best_gpu ()
if best_gpu is not None :
print ( f "Best GPU for execution: GPU { best_gpu } " )
else :
print ( "No GPUs available" )
execute_on_gpu(gpu_id: int, func: Callable, *args: Any, **kwargs: Any) -> Any
Executes a callable on a specific GPU using Ray.
Parameters
Name
Type
Description
gpu_id
int
The GPU to run the function on.
func
Callable
The function to be executed.
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
Any
The result of the function execution.
Raises
Exception
Description
ValueError
If the GPU index is invalid.
RuntimeError
If there is an error executing the function on the GPU.
Example
from clusterops import execute_on_gpu
def gpu_task ( n : int ) -> int :
return n ** 2
result = execute_on_gpu ( 0 , gpu_task , 10 )
print ( f "Result of GPU task on GPU 0: { result } " )
execute_on_multiple_gpus(gpu_ids: List[int], func: Callable, all_gpus: bool = False, timeout: float = None, *args: Any, **kwargs: Any) -> List[Any]
Executes a callable across multiple GPUs using Ray.
Parameters
Name
Type
Description
gpu_ids
List[int]
The list of GPU IDs to run the function on.
func
Callable
The function to be executed.
all_gpus
bool
Whether to use all available GPUs (default: False).
timeout
float
Timeout for the execution in seconds (default: None).
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
List[Any]
A list of results from the execution on each GPU.
Raises
Exception
Description
ValueError
If any GPU index is invalid.
RuntimeError
If there is an error executing the function on the GPUs.
Example
from clusterops import execute_on_multiple_gpus
def multi_gpu_task ( n : int ) -> int :
return n ** 3
results = execute_on_multiple_gpus ([ 0 , 1 ], multi_gpu_task , 5 )
print ( f "Results of multi-GPU task: { results } " )
distributed_execute_on_gpus(gpu_ids: List[int], func: Callable, *args: Any, **kwargs: Any) -> List[Any]
Executes a callable across multiple GPUs and nodes using Ray's distributed task scheduling.
Parameters
Name
Type
Description
gpu_ids
List[int]
The list of GPU IDs across nodes to run the function on.
func
Callable
The function to be executed.
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
List[Any]
A list of results from the execution on each GPU.
Example
from clusterops import distributed_execute_on_gpus
def distributed_task ( n : int ) -> int :
return n ** 4
results = distributed_execute_on_gpus ([ 0 , 1 , 2 , 3 ], distributed_task , 3 )
print ( f "Results of distributed GPU task: { results } " )
Utility Functions
retry_with_backoff(func: Callable, retries: int = RETRY_COUNT, delay: float = RETRY_DELAY, *args: Any, **kwargs: Any) -> Any
Retries a callable function with exponential backoff in case of failure.
Parameters
Name
Type
Description
func
Callable
The function to execute with retries.
retries
int
Number of retries (default: RETRY_COUNT from env).
delay
float
Delay between retries in seconds (default: RETRY_DELAY from env).
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
Any
The result of the function execution.
Raises
Exception
Description
Exception
After all retries fail.
Example
from clusterops import retry_with_backoff
def unstable_task ():
# Simulating an unstable task that might fail
import random
if random . random () < 0.5 :
raise Exception ( "Task failed" )
return "Task succeeded"
result = retry_with_backoff ( unstable_task , retries = 5 , delay = 1 )
print ( f "Result of unstable task: { result } " )
Resource Monitoring
monitor_resources()
Continuously monitors CPU and GPU resources and logs alerts when thresholds are crossed.
Example
from clusterops import monitor_resources
# Start monitoring resources
monitor_resources ()
profile_execution(func: Callable, *args: Any, **kwargs: Any) -> Any
Profiles the execution of a task, collecting metrics like execution time and CPU/GPU usage.
Parameters
Name
Type
Description
func
Callable
The function to profile.
*args
Any
Arguments for the callable.
**kwargs
Any
Keyword arguments for the callable.
Returns
Type
Description
Any
The result of the function execution along with the collected metrics.
Example
from clusterops import profile_execution
def cpu_intensive_task ():
return sum ( i * i for i in range ( 10000000 ))
result = profile_execution ( cpu_intensive_task )
print ( f "Result of profiled task: { result } " )
This API reference provides a comprehensive overview of the ClusterOps library's main functions, their parameters, return values, and usage examples. It should help users understand and utilize the library effectively for managing and executing tasks across CPU and GPU resources in a distributed computing environment.
October 21, 2024
October 21, 2024
Your Name
GitHub