Update

Author: svekars

docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.py

@@ -90,6 +90,23 @@
 # Single Host ProcMesh
 # ~~~~~~~~~~~~~~~~~~~~
 #
+#  **Key insight**: ProcMesh creates one process per GPU, automatically handling the process-to-hardware mapping.
+#
+
+# This simple call:
+procs = this_host().spawn_procs(per_host={"gpus": 8})
+
+# Creates:
+# Process 0 → GPU 0
+# Process 1 → GPU 1
+# Process 2 → GPU 2
+# Process 3 → GPU 3
+# Process 4 → GPU 4
+# Process 5 → GPU 5
+# Process 6 → GPU 6
+# Process 7 → GPU 7
+
+######################################################################
 # .. mermaid::
 #
 #     graph TD
@@ -124,10 +141,16 @@
 #         style P6 fill:#F44336
 #         style P7 fill:#F44336
 
+######################################################################
+# The beauty: you don't manage individual processes or GPU assignments -
+# ProcMesh handles the topology for you.
+
 ######################################################################
 # Multi-Host ProcMesh
 # ~~~~~~~~~~~~~~~~~~~
 #
+# **Key insight**: ProcMesh seamlessly scales across multiple hosts with continuous process numbering.
+#
 # .. mermaid::
 #
 #     graph TD
@@ -169,92 +192,81 @@
 #         style PM2 fill:#4CAF50
 #         style PM3 fill:#2196F3
 
-######################################################################
-# Monarch Actor System Basics
-# ----------------------------
-#
-# This shows the underlying actor system that powers Forge services.
-
-# Mock imports for documentation build
-try:
-    from monarch.actor import Actor, endpoint, Future, ProcMesh, this_host, this_proc
-except ImportError:
-
-    class Actor:
-        pass
-
-    def endpoint(func):
-        return func
+# Same simple API works across hosts:
+cluster_procs = spawn_cluster_procs(
+    hosts=["host1", "host2", "host3"],
+    per_host={"gpus": 4}
+)
 
-    class Future:
-        pass
+# Automatically creates:
+# Host 1: Processes 0-3  → GPUs 0-3
+# Host 2: Processes 4-7  → GPUs 0-3
+# Host 3: Processes 8-11 → GPUs 0-3
 
-    class ProcMesh:
-        pass
+# Your code stays the same whether it's 1 host or 100 hosts
+actors = cluster_procs.spawn("my_actor", MyActor)
 
-    def this_proc():
-        return None
+######################################################################
+# **The power**: Scale from single host to cluster without changing your
+# actor code - ProcMesh handles all the complexity.
 
-    def this_host():
-        return None
+# This shows the underlying actor system that powers Forge services
+# NOTE: This is for educational purposes - use ForgeActor and .as_service() in real Forge apps!
 
+from monarch.actor import Actor, endpoint, this_proc, Future
+from monarch.actor import ProcMesh, this_host
+import asyncio
 
 # STEP 1: Define a basic actor
 class Counter(Actor):
-    """Basic counter actor example."""
-
     def __init__(self, initial_value: int):
         self.value = initial_value
 
     @endpoint
     def increment(self) -> None:
-        """Increment the counter."""
         self.value += 1
 
     @endpoint
     def get_value(self) -> int:
-        """Get current counter value."""
         return self.value
 
+# STEP 2: Single actor in local process
+counter: Counter = this_proc().spawn("counter", Counter, initial_value=0)
 
-async def basic_actor_example():
-    """Example of using Monarch actors."""
-    # STEP 2: Single actor in local process
-    counter = this_proc().spawn("counter", Counter, initial_value=0)
-
-    # STEP 3: Send messages
-    fut = counter.get_value.call_one()
-    value = await fut
-    print(f"Counter value: {value}")  # 0
+# STEP 3: Send messages
+fut: Future[int] = counter.get_value.call_one()
+value = await fut
+print(f"Counter value: {value}")  # 0
 
+# STEP 4: Multiple actors across processes
+procs: ProcMesh = this_host().spawn_procs(per_host={"gpus": 8})
+counters: Counter = procs.spawn("counters", Counter, 0)
 
-async def distributed_actors_example():
-    """Example of actors across multiple processes."""
-    # STEP 4: Multiple actors across processes
-    procs = this_host().spawn_procs(per_host={"gpus": 8})
-    counters = procs.spawn("counters", Counter, 0)
+# STEP 5: Broadcast to all actors
+await counters.increment.call()
 
-    # STEP 5: Broadcast to all actors
-    await counters.increment.call()
+# STEP 6: Different message patterns
+# call_one() - single actor
+value = await counters.get_value.call_one()
+print(f"One counter: {value}")  # Output: One counter: 1
 
-    # STEP 6: Different message patterns
-    # call_one() - single actor
-    value = await counters.get_value.call_one()
-    print(f"One counter: {value}")
+# choose() - random single actor (actors only, not services)
+value = await counters.get_value.choose()
+print(f"Random counter: {value}")  # Output: Random counter: 1
 
-    # choose() - random single actor (actors only, not services)
-    value = await counters.get_value.choose()
-    print(f"Random counter: {value}")
+# call() - all actors, collect results
+values = await counters.get_value.call()
+print(f"All counters: {values}")  # Output: All counters: [1, 1, 1, 1, 1, 1, 1, 1]
 
-    # call() - all actors, collect results
-    values = await counters.get_value.call()
-    print(f"All counters: {values}")
+# broadcast() - fire and forget
+await counters.increment.broadcast()  # No return value - just sends to all actors
 
-    # broadcast() - fire and forget
-    await counters.increment.broadcast()
+# Cleanup
+await procs.stop()
 
-    # Cleanup
-    await procs.stop()
+######################################################################
+# Remember: This raw Monarch code is for understanding how Forge works internally.
+# In your Forge applications, use ForgeActor, .as_service(), .as_actor() instead!
 
 
 ######################################################################
@@ -264,93 +276,25 @@ async def distributed_actors_example():
 # **ActorMesh** is created when you spawn actors across a ProcMesh.
 # Each process in the ProcMesh gets one instance of your actor.
 #
-# .. mermaid::
-#
-#     graph TD
-#         subgraph Creation["Actor Creation Process"]
-#             Code["mesh.spawn('policy', PolicyActor, model='Qwen/Qwen3-7B')"]
-#
-#             subgraph ProcMesh["ProcMesh (4 processes)"]
-#                 P0["Process 0<br/>GPU 0"]
-#                 P1["Process 1<br/>GPU 1"]
-#                 P2["Process 2<br/>GPU 2"]
-#                 P3["Process 3<br/>GPU 3"]
-#             end
-#
-#             subgraph ActorMesh["ActorMesh PolicyActor"]
-#                 A0["PolicyActor Instance #0: model=Qwen/Qwen3-7B"]
-#                 A1["PolicyActor Instance #1: model=Qwen/Qwen3-7B"]
-#                 A2["PolicyActor Instance #2: model=Qwen/Qwen3-7B"]
-#                 A3["PolicyActor Instance #3: model=Qwen/Qwen3-7B"]
-#             end
-#
-#             Code --> ProcMesh
-#             P0 --> A0
-#             P1 --> A1
-#             P2 --> A2
-#             P3 --> A3
-#         end
-#
-#         style A0 fill:#4CAF50
-#         style A1 fill:#4CAF50
-#         style A2 fill:#4CAF50
-#         style A3 fill:#4CAF50
+# - **One actor instance per process**: `mesh.spawn("policy", PolicyActor)` creates one PolicyActor in each process
+# - **Same constructor arguments**: All instances get the same initialization parameters
+# - **Independent state**: Each actor instance maintains its own state and memory
+# - **Message routing**: You can send messages to one actor or all actors using different methods
+
+# Simple example:
+procs = spawn_procs(per_host={"gpus": 4})  # 4 processes
+policy_actors = procs.spawn("policy", PolicyActor, model="Qwen/Qwen3-7B")
+
+# Now you have 4 PolicyActor instances, one per GPU
+# All initialized with the same model parameter
 
-######################################################################
-# Message Routing Through ActorMesh
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# .. mermaid::
-#
-#     graph TD
-#         subgraph MessageFlow["Message Flow Patterns"]
-#             Client["await policy_actors.generate.METHOD(prompt)"]
-#
-#             subgraph Methods["Different Adverbs Route Differently"]
-#                 Choose["choose(): Routes to ONE actor, Load balanced"]
-#                 Call["call(): Routes to ALL actors, Collects results"]
-#                 Broadcast["broadcast(): Routes to ALL actors, Fire and forget"]
-#                 Stream["stream(): Routes to ALL actors, Iterator of results"]
-#             end
-#
-#             subgraph ActorInstances["PolicyActor Instances"]
-#                 A0["Actor 0: GPU 0, generates response"]
-#                 A1["Actor 1: GPU 1, generates response"]
-#                 A2["Actor 2: GPU 2, generates response"]
-#                 A3["Actor 3: GPU 3, generates response"]
-#             end
-#
-#             Client --> Choose
-#             Client --> Call
-#             Client --> Broadcast
-#             Client --> Stream
-#
-#             Choose -.->|"Load balanced"| A1
-#             Call --> A0
-#             Call --> A1
-#             Call --> A2
-#             Call --> A3
-#             Broadcast --> A0
-#             Broadcast --> A1
-#             Broadcast --> A2
-#             Broadcast --> A3
-#             Stream --> A0
-#             Stream --> A1
-#             Stream --> A2
-#             Stream --> A3
-#         end
-#
-#         style Choose fill:#4CAF50
-#         style Call fill:#FF9800
-#         style Broadcast fill:#E91E63
-#         style Stream fill:#9C27B0
 
 ######################################################################
 # How Forge Services Use Monarch
 # -------------------------------
 #
-# Now the key insight: **Forge services are ServiceActors that manage
-# ActorMeshes of your ForgeActor replicas**.
+# Now the key insight: **Forge services are ``ServiceActors`` that manage
+# ``ActorMeshes`` of your ``ForgeActor`` replicas**.
 #
 # The Service Creation Process
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -445,7 +389,7 @@ async def distributed_actors_example():
 # -----------------------------------------
 #
 # In real RL systems, you have multiple services that can share or use
-# separate ProcMeshes:
+# separate ``ProcMeshes``:
 #
 # .. mermaid::
 #
@@ -515,24 +459,6 @@ async def distributed_actors_example():
 # * **Scale effectively**: Where to add resources for maximum impact?
 
 
-def demonstrate_architecture_benefits():
-    """Example showing why the architecture matters."""
-    # Process Isolation: Failures don't cascade
-    # If one PolicyActor crashes, others continue serving
-
-    # Location Transparency: Same API whether local or remote
-    # await policy.generate.route(prompt)  # Works same everywhere
-
-    # Structured Distribution: ProcMesh maps to hardware
-    # per_host={"gpus": 8} creates 8 processes, 1 per GPU
-
-    # Message Passing: No locks needed
-    # Each actor processes messages sequentially, naturally thread-safe
-
-    # Service Abstraction: Simple interface, powerful backend
-    # await service.method.route() hides all distribution complexity
-    pass
-
 
 ######################################################################
 # Conclusion