executorlib 1.10.0

Up-scale python functions for high performance computing (HPC) with executorlib.

executorlib

Up-scale python functions for high performance computing (HPC) with executorlib.

Key Features

• Up-scale your Python functions beyond a single computer. - executorlib extends the Executor interface from the Python standard library and combines it with job schedulers for high performance computing (HPC) including the Simple Linux Utility for Resource Management (SLURM) and flux. With this combination executorlib allows users to distribute their Python functions over multiple compute nodes.
• Parallelize your Python program one function at a time - executorlib allows users to assign dedicated computing resources like CPU cores, threads or GPUs to one Python function call at a time. So you can accelerate your Python code function by function.
• Permanent caching of intermediate results to accelerate rapid prototyping - To accelerate the development of machine learning pipelines and simulation workflows executorlib provides optional caching of intermediate results for iterative development in interactive environments like jupyter notebooks.

Why executorlib?

executorlib is the lightest path to take existing Python functions and scale them across high performance computing (HPC) nodes — with per-function-call resource control and native SLURM and flux integration — without rewriting your code into a new paradigm. It extends the standard library Executor interface you already know, rather than asking you to adopt a new data, actor, or workflow model.

	executorlib	Futures	Dask	Parsl	Ray
Drop-in Executor API	✅	✅	⚠️	⚠️	❌
Per-call resource assignment	✅	❌	⚠️	✅	✅
Native HPC scheduler (SLURM/flux)	✅	❌	⚠️	✅	⚠️
MPI-parallel functions	✅	❌	⚠️	⚠️	⚠️
Caching of results	✅	❌	⚠️	✅	❌
Setup / learning overhead	Low	Very low	Medium	Medium	Medium

✅ first-class · ⚠️ possible via add-on/config · ❌ not supported. See the full comparison: when to use which for honest guidance on when another tool is the better fit.

Examples

The Python standard library provides the Executor interface with the ProcessPoolExecutor and the ThreadPoolExecutor for parallel execution of Python functions on a single computer. executorlib extends this functionality to distribute Python functions over multiple computers within a high performance computing (HPC) cluster. This can be either achieved by submitting each function as individual job to the HPC job scheduler with an HPC Cluster Executor - or by requesting a job from the HPC cluster and then distribute the Python functions within this job with an HPC Job Executor. Finally, to accelerate the development process executorlib also provides a Single Node Executor - to use the executorlib functionality on a laptop, workstation or single compute node for testing. Starting with the Single Node Executor:

from executorlib import SingleNodeExecutor


with SingleNodeExecutor() as exe:
    future_lst = [exe.submit(sum, [i, i]) for i in range(1, 5)]
    print([f.result() for f in future_lst])

In the same way executorlib can also execute Python functions which use additional computing resources, like multiple CPU cores, CPU threads or GPUs. For example if the Python function internally uses the Message Passing Interface (MPI) via the mpi4py Python libary:

from executorlib import SingleNodeExecutor


def calc(i):
    from mpi4py import MPI

    size = MPI.COMM_WORLD.Get_size()
    rank = MPI.COMM_WORLD.Get_rank()
    return i, size, rank


with SingleNodeExecutor() as exe:
    fs = exe.submit(calc, 3, resource_dict={"cores": 2})
    print(fs.result())

The additional resource_dict parameter defines the computing resources allocated to the execution of the submitted Python function. In addition to the compute cores cores, the resource dictionary can also define the threads per core as threads_per_core, the GPUs per core as gpus_per_core, the working directory with cwd, the option to use the OpenMPI oversubscribe feature with openmpi_oversubscribe and finally for the Simple Linux Utility for Resource Management (SLURM) queuing system the option to provide additional command line arguments with the slurm_cmd_args parameter - resource dictionary This flexibility to assign computing resources on a per-function-call basis simplifies the up-scaling of Python programs. Only the part of the Python functions which benefit from parallel execution are implemented as MPI parallel Python funtions, while the rest of the program remains serial.

The same function can be submitted to the SLURM job scheduler by replacing the SingleNodeExecutor with the SlurmClusterExecutor. The rest of the example remains the same, which highlights how executorlib accelerates the rapid prototyping and up-scaling of HPC Python programs.

from executorlib import SlurmClusterExecutor


def calc(i):
    from mpi4py import MPI

    size = MPI.COMM_WORLD.Get_size()
    rank = MPI.COMM_WORLD.Get_rank()
    return i, size, rank


with SlurmClusterExecutor() as exe:
    fs = exe.submit(calc, 3, resource_dict={"cores": 2})
    print(fs.result())

In this case the Python simple queuing system adapter (pysqa) is used to submit the calc() function to the SLURM job scheduler and request an allocation with two CPU cores for the execution of the function - HPC Cluster Executor. In the background the sbatch command is used to request the allocation to execute the Python function.

Within a given SLURM job executorlib can also be used to assign a subset of the available computing resources to execute a given Python function. In terms of the SLURM commands, this functionality internally uses the srun command to receive a subset of the resources of a given queuing system allocation.

from executorlib import SlurmJobExecutor


def calc(i):
    from mpi4py import MPI

    size = MPI.COMM_WORLD.Get_size()
    rank = MPI.COMM_WORLD.Get_rank()
    return i, size, rank


with SlurmJobExecutor() as exe:
    fs = exe.submit(calc, 3, resource_dict={"cores": 2})
    print(fs.result())

In addition, to support for SLURM executorlib also provides support for the hierarchical flux job scheduler. The flux job scheduler is developed at Larwence Livermore National Laboratory to address the needs for the up-coming generation of Exascale computers. Still even on traditional HPC clusters the hierarchical approach of the flux is beneficial to distribute hundreds of tasks within a given allocation. Even when SLURM is used as primary job scheduler of your HPC, it is recommended to use SLURM with flux as hierarchical job scheduler within the allocations.

Which Executor should I use?

executorlib provides five Executor classes. They all share the same submit() / map() interface and only differ in where the Python functions are executed and how the resources are requested. A common workflow is to develop and test with the SingleNodeExecutor on a laptop and then switch to one of the HPC executors by changing only the class name:

Executor	Where it runs	Scheduler command	Best for
SingleNodeExecutor	laptop, workstation or single compute node	subprocess	developing and testing a workflow
SlurmClusterExecutor	HPC login node	sbatch (one job per function)	long-running functions that should outlive the Python session
SlurmJobExecutor	inside a SLURM allocation	srun (job steps)	many functions within one existing allocation
FluxClusterExecutor	HPC login node or Flux instance	flux submit	long-running functions; disconnecting and reconnecting
FluxJobExecutor	inside a Flux allocation	flux run	high-throughput execution of many short functions

The Cluster executors submit each Python function as an individual job and communicate via the file system, so the Python process which created the executor can be closed and the results reloaded later. The Job executors run inside an existing allocation and communicate via sockets, which has lower overhead and is the better choice for many short function calls.

Documentation

• Installation
  • Minimal
  • MPI Support
  • Caching
  • HPC Cluster Executor
  • HPC Job Executor
  • Visualisation
  • For Developers
• Comparison
  • At a glace
  • Concurrent futures
  • Dask
  • Parsl
  • Ray
  • Choose executorlib when
• Single Node Executor
  • Basic Functionality
  • Parallel Functions
  • Performance Optimization
  • Advanced Scheduling
  • Testing and Debugging
• HPC Cluster Executor
  • SLURM
  • Flux
  • Disconnecting and Reconnecting
  • Combine both
  • Cleaning Cache
• HPC Job Executor
  • SLURM
  • SLURM with Flux
  • Flux
• Application
  • GPAW
  • Quantum Espresso
• Integration
  • emcee
  • pipefunc
  • omp4py
  • pylammpsmpi
  • General Pattern
• Trouble Shooting
  • Filesystem Usage
  • Firewall Issues
  • Message Passing Interface
  • Test Coverage for Integration Tests
  • Python Version
  • Resource Dictionary
  • SSH Connection
• Support & Contribution
  • Issues
  • Pull Requests
  • License
  • Modules
  • Interface Class Hierarchy
  • Execution Flow
  • Test Environment
  • Communication
  • External Libraries
  • External Executables
• Interface