.. _core-walkthrough:

What's Ray Core?

.. toctree:: :maxdepth: 1 :hidden:

Key Concepts <key-concepts>
User Guides <user-guide>
Examples <examples/overview>
api/index
Internals <internals>

Ray Core is a powerful distributed computing framework that provides a small set of essential primitives (tasks, actors, and objects) for building and scaling distributed applications. This walk-through introduces you to these core concepts with simple examples that demonstrate how to transform your Python functions and classes into distributed Ray tasks and actors, and how to work effectively with Ray objects.

.. note::

Ray has introduced an experimental API to transfer objects using GLOO / NCCL / NIXL / (bring your own)
as an alternative to the default shared memory + gRPC based object store.
See :ref:`Ray Direct Transport <direct-transport>` for more details.

Getting Started

To get started, install Ray using pip install -U ray. For additional installation options, see :ref:Installing Ray <installation>.

The first step is to import and initialize Ray:

.. literalinclude:: doc_code/getting_started.py :language: python :start-after: starting_ray_start :end-before: starting_ray_end

.. note::

Unless you explicitly call ray.init(), the first use of a Ray remote API call will implicitly call ray.init() with no arguments.

Running a Task

Tasks are the simplest way to parallelize your Python functions across a Ray cluster. To create a task:

1. Decorate your function with @ray.remote to indicate it should run remotely
2. Call the function with .remote() instead of a normal function call
3. Use ray.get() to retrieve the result from the returned future (Ray object reference)

Here's a simple example:

.. literalinclude:: doc_code/getting_started.py :language: python :start-after: running_task_start :end-before: running_task_end

Calling an Actor

While tasks are stateless, Ray actors allow you to create stateful workers that maintain their internal state between method calls. When you instantiate a Ray actor:

1. Ray starts a dedicated worker process somewhere in your cluster
2. The actor's methods run on that specific worker and can access and modify its state
3. The actor executes method calls serially in the order it receives them, preserving consistency

Here's a simple Counter example:

.. literalinclude:: doc_code/getting_started.py :language: python :start-after: calling_actor_start :end-before: calling_actor_end

The preceding example demonstrates basic actor usage. For a more comprehensive example that combines both tasks and actors, see the :ref:Monte Carlo Pi estimation example <monte-carlo-pi>.

Passing Objects

Ray's distributed object store efficiently manages data across your cluster. There are three main ways to work with objects in Ray:

1. Implicit creation: When tasks and actors return values, they are automatically stored in Ray's :ref:distributed object store <objects-in-ray>, returning object references that can be later retrieved.
2. Explicit creation: Use ray.put() to directly place objects in the store.
3. Passing references: You can pass object references to other tasks and actors, avoiding unnecessary data copying and enabling lazy execution.

Here's an example showing these techniques:

.. literalinclude:: doc_code/getting_started.py :language: python :start-after: passing_object_start :end-before: passing_object_end

Next Steps

.. tip:: To monitor your application's performance and resource usage, check out the :ref:Ray dashboard <observability-getting-started>.

You can combine Ray's simple primitives in powerful ways to express virtually any distributed computation pattern. To dive deeper into Ray's :ref:key concepts <core-key-concepts>, explore these user guides:

.. grid:: 1 2 3 3 :gutter: 1 :class-container: container pb-3

.. grid-item-card::
    :img-top: /images/tasks.png
    :class-img-top: pt-2 w-75 d-block mx-auto fixed-height-img

    .. button-ref:: ray-remote-functions

        Using remote functions (Tasks)

.. grid-item-card::
    :img-top: /images/actors.png
    :class-img-top: pt-2 w-75 d-block mx-auto fixed-height-img

    .. button-ref:: ray-remote-classes

        Using remote classes (Actors)

.. grid-item-card::
    :img-top: /images/objects.png
    :class-img-top: pt-2 w-75 d-block mx-auto fixed-height-img

    .. button-ref:: objects-in-ray

        Working with Ray Objects