DOCSEARCHbyAlgolia
Submit Docs

Covalent Documentation

repository·develop·Indexed 21 days ago

https://github.com/agnostiqhq/covalent

A Python library for AI/ML engineers and researchers to run compute-intensive jobs across diverse cloud and on-premise infrastructures using a unified, serverless-like interface. It features an executor plugin system for AWS, Azure, GCP, Kubernetes, SLURM, and others, a CLI for server management, and a web application for real-time job monitoring.

Tokens
77.9K
Snippets
247
Records
322
Agent score
61%

What's inside Covalent

  1. What is Covalent?

    develop

    Covalent is a Python library designed for AI/ML engineers, developers, and researchers. It allows you to run compute jobs (such as LLMs, generative AI, and scientific research) on various cloud platforms or on-premise clusters by abstracting the underlying infrastructure management.

    Key capabilities include:

    • Run Code Anywhere: Execute Python functions on any cloud or on-prem cluster by simply swapping decorators with executor plugins.
    • Infrastructure Abstraction: Decouple your business logic from infrastructure/resource definitions (e.g., cloud consoles, Terraform, or IaC).
    • Serverless Infrastructure: Automatically converts infrastructure like on-prem SLURM clusters or cloud compute into a serverless setup.
    • Real-Time Monitoring: Provides a user-friendly UI for monitoring jobs in real-time.

  2. Core benefits of using Covalent for AI/ML experimentation

    develop

    Covalent is designed to solve computational and operational challenges in AI/ML workflows by providing an abstraction layer between your code and the underlying hardware.

    Key capabilities include:

    • Resource Abstraction: Assign specific functions to appropriate resources (e.g., using quantum computers or HPC clusters for heavy computation while using commodity hardware for bookkeeping).
    • Local-to-Remote Workflow: Test functions on local servers before deploying them to advanced hardware.
    • Automatic Parallelization: Covalent analyzes functions for data independence and automatically parallelizes execution to speed up workflows.
    • Interactive Development: Run experiments directly from Jupyter notebooks or other interactive Python environments.
    • Observability: Track workflows and examine results through a browser-based GUI.

  3. Manage the Covalent server with the Covalent CLI

    develop

    The covalent CLI tool is used to manage the lifecycle and state of a Covalent server instance. You can use it to control the server process, check its health, manage logs, and interact with the underlying database or cluster configurations.

    covalent [COMMAND]

  4. What is a Lattice in Covalent?

    develop

    A lattice is a runnable workflow in Covalent, created using the @covalent.lattice decorator. A lattice represents a sequence of operations (a workflow) on one or more datasets.

    Key Requirements and Behaviors:

    • Task Composition: A lattice must contain one or more electrons.
    • Data Manipulation: For Covalent to properly dispatch all tasks to executors, the lattice must operate on data only by calling electrons. If you perform data manipulation directly in the lattice function instead of calling an electron, that manipulation will not be offloaded to an executor.
    • Hardware Independence: By using electrons, the task's code is decoupled from the specific hardware it runs on.
    • Parallelization: The Covalent dispatcher can run independent electrons in parallel. Two electrons are considered independent if their inputs are unaffected by each other's execution outcomes (outputs or side effects).
    import covalent as ct

@ct.electron
def load_data():
    return [1, 2, 3]

@ct.electron
def process_data(data):
    return [x * 2 for x in data]

@ct.lattice
def my_workflow():
    data = load_data()
    result = process_data(data)
    return result

  5. What is a sublattice and how to define one

    develop

    A sublattice is a lattice wrapped with an @ct.electron decorator, allowing it to behave as a single task within a larger workflow. This abstraction allows you to nest complex lattices inside other lattices while maintaining a clean transport graph.

    To create a sublattice, apply both the @ct.electron and @ct.lattice decorators to a function that contains calls to other electrons.

    @ct.electron
@ct.lattice
def sub_workflow():
    # Lattice code containing calls to other electrons ...

  6. What is an Executor?

    develop
    An executor is the compute resource that runs a single task (electron). Executors can be local machines, AWS clusters, or other remote resources. The Covalent dispatcher manages these executors to run tasks, often in parallel. By default, Covalent uses a Dask cluster running on the Covalent server as the executor.

  7. What is an Electron in Covalent?

    develop

    An electron is the simplest unit of computational work in Covalent. It represents a single task that can be run by a Covalent executor.

    You create an electron by using the @covalent.electron decorator on a Python function. This decorator makes the function runnable in a Covalent executor without changing its standard Python behavior.

    Best Practices:

    • Treat an electron as a single, well-defined task (e.g., a single data transformation, reading/writing a record, or a specific computation).
    • An electron behaves like a regular Python function unless it is called from within a lattice. When called from a lattice, the code is invoked in an executor.
    • Important: If an electron is called from another electron, it executes as a normal Python function within the calling electron's executor rather than being farmed out to its own executor.
    import covalent as ct

@ct.electron
def add(x, y):
    return x + y

  8. Use Quantum Executors for quantum circuits

    develop

    Quantum executors are specialized executors designed specifically for running quantum circuits. When used in conjunction with quantum electrons, they enable quantum circuits to run on various local or cloud-based quantum backends.

    Supported quantum executor plugins include:

    • qiskit
    • ibmq
    • braketqubit
    • localbraketqubit
    • simulator

  9. Covalent coding best practices overview

    develop

    Covalent coding practices are divided into two categories to ensure efficient and successful workflow execution:

    1. Patterns and techniques for improvement: These focus on enhancing efficiency, performance, and code maintainability (e.g., handling large data or dynamic workflows).
    2. Required techniques for server-based execution: These are mandatory requirements for the Covalent server to correctly dispatch and execute workflows. Violating these typically causes workflows to fail.

  10. How Covalent Services and the Transport Graph work

    develop

    The Covalent server operates as a service containing a dispatcher and executors.

    1. Dispatcher: Analyzes workflows (lattices) and constructs a transport graph. The transport graph is a directed acyclic graph (DAG) where nodes represent tasks (electrons) and edges represent dependencies. The dispatcher sequentially inspects electrons to build this graph.
    2. Executors: These are adapters to backend hardware resources. They take an electron and execute it on a specific platform (e.g., local, Dask, GPU, or Quantum).
    3. Workflow Execution: Once a workflow is dispatched, the dispatcher manages the execution lifecycle, allowing you to close your local script or notebook while the server continues the work.

  11. How Covalent works: Executor Plugins

    develop

    Covalent uses an executor plugin system to handle the execution of code across different environments. To change where your code runs, you simply swap the decorator used in your Python code with the appropriate executor plugin.

    Supported and available plugin categories include:

    • Cloud Providers: AWS, Azure, GCP.
    • Cluster Managers: Kubernetes, SLURM, PBS, LSF.
    • Distributed Computing: Dask.
    • Quantum Computing: IBMQ.

    You can use existing plugins or create custom ones using the covalent-executor-template for tailored infrastructure interactions.

  12. Execute workflows with Local or Dask Executors

    develop

    Executors determine where your electrons are actually run.

    • LocalExecutor: Executes tasks (electrons) directly on the local machine where the code is running.
    • DaskExecutor: Executes tasks in a distributed Dask cluster, allowing for scalable parallel computation.

    To use an executor, you typically pass it as an argument when dispatching your workflow or lattice.