The Problem with Default Settings

Oct 13, 2025 by wbrum.org 36 views

Introduction

Coiled is a powerful tool for running distributed tasks on various cloud providers, including AWS. However, when running tasks locally, Coiled's LocalCluster can sometimes behave unexpectedly, especially when dealing with CPU-intensive tasks. In this article, we will explore how to pass additional keyword arguments (kwargs) to the LocalCluster initialization when using Coiled's function decorator with local=True.

Understanding Coiled's LocalCluster

Coiled's LocalCluster is a Dask-based cluster that allows you to run tasks on your local machine. When you use the function decorator with local=True, Coiled will automatically create a LocalCluster instance with default settings. However, as we will see later, these default settings may not always be suitable for CPU-intensive tasks.

The Problem with Default Settings

When you run a task that requires a GPU or is very CPU-intensive, Coiled's LocalCluster may spin up multiple workers and threads per worker, leading to performance issues. This is because the default settings for the LocalCluster are not optimized for CPU-intensive tasks.

Digging into Coiled's Code

To better understand how Coiled's LocalCluster is created, we can dig into the installed Coiled code on our local machine. Specifically, we can look at the function.py file, which contains the relevant code:

if self._local:
    with _set_local_environ(self._environ or {}):
        cluster = dask.distributed.LocalCluster(
            name=self._name,
            threads_per_worker=self._cluster_kwargs["worker_options"]["nthreads"],
        )
        if isinstance(self._cluster_kwargs["n_workers"], (list, tuple)):
            cluster.adapt(
                minimum=self._cluster_kwargs["n_workers"][0],
                maximum=self._cluster_kwargs["n_workers"][1],
            )

As we can see, the LocalCluster is created with default settings, including the number of threads per worker and the minimum and maximum number of workers.

Passing Additional kwargs to LocalCluster

While we cannot directly pass additional kwargs to the LocalCluster initialization using the function decorator, we can use the local_cluster_kwargs parameter to pass additional settings to the LocalCluster instance. Here's an example:

@coiled.function(
    # other args ...
    local=True,
    local_cluster_kwargs={"processes": True, "nthreads": 4, "n_workers": 2}
)

In this example, we are passing three additional kwargs to the LocalCluster instance: processes=True, nthreads=4, and n_workers=2. These settings will override the default settings for the LocalCluster.

Example Use Case

Let's say we have a pipeline that includes a task that requires a GPU. We can use the function decorator with local=True and pass additional kwargs to the LocalCluster instance to ensure that the task runs on a single worker with multiple threads:

@coiled.function(
    # other args ...
    local=True,
    local_cluster_kwargs={"processes": False, "nthreads": 8, "n_workers": 1}
)
def gpu_task():
    # task code here

In this example, we are passing three additional kwargs to the LocalCluster instance: processes=False, nthreads=8, and n_workers=1. These settings will ensure that the task runs on a single worker with multiple threads.

Conclusion

In conclusion, while we cannot directly pass additional kwargs to the LocalCluster initialization using the function decorator, we can use the local_cluster_kwargs parameter to pass additional settings to the LocalCluster instance. By passing additional kwargs, we can customize the behavior of the LocalCluster instance and ensure that our tasks run efficiently on our local machine.

Best Practices

When using Coiled's function decorator with local=True, it's essential to pass additional kwargs to the LocalCluster instance to ensure that your tasks run efficiently. Here are some best practices to keep in mind:

Always pass processes=True to ensure that your tasks run on multiple processes.
Set nthreads to the number of threads required by your task.
Set n_workers to the number of workers required by your task.
Use local_cluster_kwargs to pass additional settings to the LocalCluster instance.

Q&A

Q: What is Coiled and how does it relate to Dask? A: Coiled is a tool that allows you to run distributed tasks on various cloud providers, including AWS. It is built on top of Dask, a parallel computing library that provides a high-level interface for parallelizing existing serial code.

Q: What is the difference between Coiled's LocalCluster and Dask's LocalCluster? A: Coiled's LocalCluster is a Dask-based cluster that allows you to run tasks on your local machine. While Dask's LocalCluster is a more general-purpose cluster that can be used for various purposes, Coiled's LocalCluster is specifically designed for running distributed tasks on your local machine.

Q: Why do I need to pass additional kwargs to the LocalCluster instance? A: When you use the function decorator with local=True, Coiled will automatically create a LocalCluster instance with default settings. However, these default settings may not always be suitable for your specific use case. By passing additional kwargs, you can customize the behavior of the LocalCluster instance and ensure that your tasks run efficiently.

Q: How do I pass additional kwargs to the LocalCluster instance? A: You can pass additional kwargs to the LocalCluster instance using the local_cluster_kwargs parameter. For example:

@coiled.function(
    # other args ...
    local=True,
    local_cluster_kwargs={"processes": True, "nthreads": 4, "n_workers": 2}
)

Q: What are some best practices for using Coiled's LocalCluster? A: Here are some best practices to keep in mind:

Always pass processes=True to ensure that your tasks run on multiple processes.
Set nthreads to the number of threads required by your task.
Set n_workers to the number of workers required by your task.
Use local_cluster_kwargs to pass additional settings to the LocalCluster instance.

Q: Can I use Coiled's LocalCluster with other libraries? A: Yes, you can use Coiled's LocalCluster with other libraries that support Dask. However, you may need to modify the code to work with Coiled's LocalCluster.

Q: How do I troubleshoot issues with Coiled's LocalCluster? A: If you encounter issues with Coiled's LocalCluster, you can try the following:

Check the Coiled documentation for troubleshooting guides.
Use the coiled logs command to view the logs of the Coiled process.
Use the dask debug command to view the debug information of the Dask process.

Q: Can I use Coiled's LocalCluster with a GPU? A: Yes, you can use Coiled's LocalCluster with a GPU. However, you will need to ensure that your system has a compatible GPU and that the necessary drivers are installed.

Q: How do I upgrade Coiled to the latest version? A: You can upgrade Coiled to the latest version using pip:

pip install --upgrade coiled

Q: Can I use Coiled's LocalCluster with a remote cluster? A: No, Coiled's LocalCluster is designed for running tasks on your local machine. If you need to run tasks on a remote cluster, you will need to use a different Coiled feature, such as the coiled cluster command.

Q: How do I get support for Coiled? A: You can get support for Coiled through the following channels:

Coiled documentation: The Coiled documentation provides detailed guides and tutorials on using Coiled.
Coiled community: The Coiled community is a forum where you can ask questions and get help from other Coiled users.
Coiled support: You can contact Coiled support directly for help with specific issues.