Getting Started

Covalent is developed using Python 3.8 on Linux and macOS. See the Compatibility page for further details on Python versions and operating systems which support Covalent. To set up Python on your computer, refer to the official Python for Beginners page.

Installation

Installation Methods

Pip Install

The easiest way to install Covalent is using the PyPI package manager:

pip install covalent

Docker Install

Covalent can also run in Docker containers instead of covalent start:

git clone git@github.com:AgnostiqHQ/covalent.git
cd covalent
docker compose up -d

Note

The Docker image for Covalent is still being tested. Please open an issue on GitHub if you encounter unexpected behavior.

Install From Source

Covalent can also be downloaded and installed from source:

git clone git@github.com:AgnostiqHQ/covalent.git
cd covalent

# Build dashboard
python setup.py webapp

# Install using pip (-e for developer mode), or...
pip install -e .

# Build and install using Conda (10-15 mins)
conda build .
conda install -c local covalent

The documentation can also easily be built locally:

python setup.py docs

Note

Users who wish to use the draw functionality outside of the UI may also wish to install graphviz and pygraphviz, either using Conda or Linux package managers. This is not required to use Covalent.

Validate the Installation

You can validate Covalent has been properly installed if the following returns without error:

python -c "import covalent"

Start the Server

Use the Covalent CLI tool to manage the Covalent server. The following commands will help you get started.

$ covalent --help
Usage: covalent [OPTIONS] COMMAND [ARGS]...

   Covalent CLI tool used to manage the servers.

Options:
   -v, --version  Display version information.
   --help         Show this message and exit.

Commands:
   config   Get and set the configuration of services.
   logs
   purge    Shutdown server and delete the cache and config settings.
   restart  Restart the server(s).
   start
   status   Return the statuses of the server(s).
   stop     Stop the server(s).

Start the Covalent server:

$ covalent start

Optionally, confirm the server is running:

$ covalent status

Now, navigate to the Covalent UI by entering the address into your web browser. This is where dispatched jobs will appear.

Hello, Covalent!

Let’s look at a simple example to get started with Covalent. Before starting, ensure you have installed Covalent, verified the installation, and started the Covalent server. Next, open a Jupyter notebook or Python console and create a simple workflow:

import covalent as ct

# Construct tasks as "electrons"
@ct.electron
def join_words(a, b):
    return ", ".join([a, b])

@ct.electron
def excitement(a):
    return f"{a}!"

# Construct a workflow of tasks
@ct.lattice
def simple_workflow(a, b):
    phrase = join_words(a, b)
    return excitement(phrase)

# Dispatch the workflow
dispatch_id = ct.dispatch(simple_workflow)("Hello", "World")

Navigate to the Covalent UI at http://localhost:8000 to see your workflow in the queue:

While the workflow is being processed by the dispatch server, you are free to terminate the Jupyter kernel or Python console process without losing access to the results. Make sure the Covalent server remains in the “running” state while you have running workflows.

When the workflow has completed, you can start a new session and query the results:

import covalent as ct

dispatch_id = "8a7bfe54-d3c7-4ca1-861b-f55af6d5964a"
result_string = ct.get_result(dispatch_id).result

When you are done using Covalent, stop the server:

$ covalent stop