Monarch Documentation

Monarch's public APIs are organized into several specialized packages depending on your task:

• monarch.actor: Used for defining and managing actors (the units of computation).
• monarch: Contains APIs for computing with distributed tensors.
• monarch.job: Provides a declarative interface for managing distributed job resources.
• monarch.rdma: Provides RDMA (Remote Direct Memory Access) support for high-performance networking.
• monarch.spmd: Provides primitives for running torchrun-style SPMD (Single Program, Multiple Data) scripts over Monarch meshes.

Monarch is a distributed programming framework for PyTorch built on scalable actor messaging. It provides remote actors with scalable messaging, fault tolerance via supervision trees, point-to-point RDMA transfers, and distributed tensors.

Key Components:

• Rust Core: Implements the core actor system, messaging, RDMA, and tensor operations.
• Python API: Provides Python bindings to expose functionality through a simple API.
• Hyperactor System: The underlying actor mesh implementation.
• Tensor Engine: Optional component providing GPU/RDMA support for distributed tensors (can be disabled for CPU-only builds).

Note for Python users: If you are writing code using the Monarch Python API, refer to docs/DOCS_INDEX.md for tutorials, API documentation, and examples.

The Simulator is a tool designed to simulate execution time and memory usage based on input messages. It can be used in two ways:

1. As a backend: Functioning similarly to ProcessBackend.
2. As a standalone object: Receiving messages from a pre-stored file.

Its primary purpose is to provide insights into how a workload would perform in terms of resource consumption without requiring actual hardware execution.

This example demonstrates how to run torchtitan (specifically the llama3_debugmodel configuration) across multiple H100 nodes (e.g., 4 nodes with 32 GPUs total) using the monarch apply and monarch exec workflow.

Key characteristics:

• H100 x86 only: Designed for this specific hardware.
• Remote Mount Workflow: The trainer code (torchtitan + torch) is shipped to workers via a remote_mount of a uv-managed .venv, rather than being packaged into the worker's fbpkg. This keeps the worker bootstrap slim (~530 MB vs ~5 GB).
• Vanilla Scripts: You write standard Python training scripts (train.py) that run locally with a standard venv and can be executed remotely via monarch exec without requiring import monarch in your code.

The monarch module provides the core API for distributed tensor computation. It allows users to manage tensors across distributed meshes, handle asynchronous execution via streams, and perform collective operations like reductions and remote calls.

Key components include:

• Tensor: The primary abstraction for distributed data.
• Stream: Manages execution flow and synchronization.
• Mesh Operations: Functions like to_mesh, slice_mesh, and world_mesh allow you to control how tensors are distributed across hardware topologies.
• Collective Operations: Functions such as reduce, reduce_, coalescing, and fetch_shard enable communication between distributed processes.

The hyperactor crate provides a suite of macros designed to support a complete message-passing workflow. These macros facilitate defining message enums, generating client APIs, routing messages, and exporting actors for dynamic or remote use.

Key capabilities include:

• Generating message handling and client traits.
• Implementing client traits for ActorHandle<T> and ActorRef<T>.
• Assigning globally unique names and ports for routing and reflection.
• Making actors remotely spawnable and routable.
• Routing messages to user-defined handler trait implementations.
• Defining façade actor types to expose restricted or stable APIs.

The Monarch Python documentation is organized into four main categories to help you build, run, and observe distributed workloads:

• Tutorials & Guides: Includes the Getting Started tutorial, a complete guide to Actors, a task-oriented Cookbook, a Debugging Guide, and Installation instructions.
• API Reference: Detailed documentation for core modules including monarch.actor, monarch.rdma, monarch.config, monarch.job, and monarch.spmd.
• Tools & Observability: Covers observability concepts, distributed telemetry, the Mesh Admin TUI, the Monarch Dashboard, and OpenTelemetry/Grafana integration.
• Examples: Practical implementations such as GRPO actors, distributed tensors, ping-pong communication, crawlers, and various DDP (Distributed Data Parallel) patterns for Kubernetes or SPMD.

The Referable trait is a marker trait used to indicate that a type is eligible to serve as a reference to a remote actor. This is particularly useful in distributed systems where an actor may reside on a different process than the one attempting to reference it.

To implement Referable, a type must also implement the Named trait, which ensures the type provides a static name used for identification across process boundaries.

Note on Thread Safety: Referable does not impose Send or Sync bounds by default. If you are spawning actors across threads or storing them in shared data structures, you must add these bounds explicitly at the call site.

pub trait Referable: Named {}