diff --git a/docs/source/_static/message_flow.svg b/docs/source/_static/message_flow.svg new file mode 100644 index 000000000..b82b1e053 --- /dev/null +++ b/docs/source/_static/message_flow.svg @@ -0,0 +1,12 @@ + + + Actor A + + Actor B + + + + + + + diff --git a/docs/source/assets/__init__.py b/docs/source/assets/__init__.py new file mode 100644 index 000000000..50f7413e3 --- /dev/null +++ b/docs/source/assets/__init__.py @@ -0,0 +1,18 @@ +import os + +from IPython.display import display, HTML + + +def show_svg(filename: str) -> None: + """Display an SVG file centered in the notebook. + + Args: + filename: Name of the SVG file (e.g., 'message_flow.svg') + """ + cwd = os.getcwd() + monarch_path, subpath = cwd.rsplit("/docs", maxsplit=1) + svg_path = os.path.join(monarch_path, "source", "assets", filename) + with open(svg_path, "r") as f: + svg_content = f.read() + html_content = f'
{svg_content}
' + display(HTML(html_content)) diff --git a/docs/source/assets/config.py b/docs/source/assets/config.py new file mode 100644 index 000000000..e69de29bb diff --git a/docs/source/conf.py b/docs/source/conf.py index 6ca3a0051..42ea23a4e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -63,6 +63,7 @@ sys.path.insert(0, os.path.abspath(".")) sys.path.insert(0, os.path.abspath("../..")) sys.path.insert(0, os.path.abspath("_ext")) # Add our custom extensions +sys.path.insert(0, os.path.abspath("generated/examples")) # assets for examples html_theme = "pytorch_sphinx_theme2" html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()] @@ -159,6 +160,16 @@ ".md": "markdown", } + +ONE_GALLERY_EXAMPLE = os.environ.get("ONE_GALLERY_EXAMPLE", None) +if ONE_GALLERY_EXAMPLE is not None: + import re + + exclude_patterns = ["**"] # Reset exclude_patterns to ensure books are included + sphinx_gallery_conf["filename_pattern"] = re.escape(ONE_GALLERY_EXAMPLE) + sphinx_gallery_conf["plot_gallery"] = "True" + sphinx_gallery_conf["only_warn_on_example_error"] = "False" + # Configure MyST-Parser to properly handle relative links in the books directory myst_url_schemes = ["http", "https", "mailto"] diff --git a/docs/source/examples/presentation.py b/docs/source/examples/presentation.py new file mode 100644 index 000000000..6903ab482 --- /dev/null +++ b/docs/source/examples/presentation.py @@ -0,0 +1,55 @@ +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +# pyre-unsafe + +""" +Getting Started +=============== + +This guide introduces the core concepts of Monarch, a framework for building +multi-machine training programs using actors. We'll cover: + +- Defining actors with endpoint functions +- Spawning actors locally and across multiple hosts and processes +- Sending messages and organizing actors into meshes +- The supervision tree for fault tolerance +- Distributed tensors and RDMA capabilities +""" + +from assets import show_svg + +# %% +# Defining an Actor +# ----------------- +# At its core, Monarch uses actors as a way to create multi-machine training programs. +# Actors are Python objects that expose a number of endpoint functions. These functions +# can be called by other actors in the system and their responses gathered asynchronously. +# +# Let's start by defining a simple actor: + +from monarch.actor import Actor, endpoint, this_proc + + +class Counter(Actor): + def __init__(self, initial_value: int): + self.value = initial_value + + @endpoint + def increment(self) -> None: + self.value += 1 + + @endpoint + def get_value(self) -> int: + return self.value + + +# %% +# Message Flow Diagram +# =================== +# Here's how messages flow between actors: + +show_svg("message_flow.svg")