zhangyiss/mlx
1
0
Fork 0
mirror of https://github.com/ml-explore/mlx.git synced 2025-09-18 01:50:16 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs update

Browse Source
This commit is contained in:
Awni Hannun
2024-04-11 17:33:33 -07:00
committed by CircleCI Docs
parent 1d2cadbc78
commit f77d99b285
413 changed files with 9992 additions and 2202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/build/html/dev/metal_debugger.html vendored
View File

@@ -8,7 +8,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<title>Metal Debugger &#8212; MLX 0.9.0 documentation</title>
<title>Metal Debugger &#8212; MLX 0.10.0 documentation</title>
@@ -36,7 +36,7 @@
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=5b4479735964841361fd" />
<script src="../_static/vendor/fontawesome/6.1.2/js/all.min.js?digest=5b4479735964841361fd"></script>
<script src="../_static/documentation_options.js?v=2a76c96f"></script>
<script src="../_static/documentation_options.js?v=cb265169"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/scripts/sphinx-book-theme.js?v=efea14e4"></script>
@@ -130,8 +130,8 @@
<img src="../_static/mlx_logo.png" class="logo__image only-light" alt="MLX 0.9.0 documentation - Home"/>
<script>document.write(`<img src="../_static/mlx_logo_dark.png" class="logo__image only-dark" alt="MLX 0.9.0 documentation - Home"/>`);</script>
<img src="../_static/mlx_logo.png" class="logo__image only-light" alt="MLX 0.10.0 documentation - Home"/>
<script>document.write(`<img src="../_static/mlx_logo_dark.png" class="logo__image only-dark" alt="MLX 0.10.0 documentation - Home"/>`);</script>
</a></div>
@@ -285,6 +285,7 @@
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.erf.html">mlx.core.erf</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.erfinv.html">mlx.core.erfinv</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.exp.html">mlx.core.exp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.expm1.html">mlx.core.expm1</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.expand_dims.html">mlx.core.expand_dims</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.eye.html">mlx.core.eye</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.flatten.html">mlx.core.flatten</a></li>
@@ -317,6 +318,7 @@
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.max.html">mlx.core.max</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.maximum.html">mlx.core.maximum</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.mean.html">mlx.core.mean</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.meshgrid.html">mlx.core.meshgrid</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.min.html">mlx.core.min</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.minimum.html">mlx.core.minimum</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.moveaxis.html">mlx.core.moveaxis</a></li>
@@ -351,6 +353,7 @@
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.square.html">mlx.core.square</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.squeeze.html">mlx.core.squeeze</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.stack.html">mlx.core.stack</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.std.html">mlx.core.std</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.stop_gradient.html">mlx.core.stop_gradient</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.subtract.html">mlx.core.subtract</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.sum.html">mlx.core.sum</a></li>
@@ -378,6 +381,7 @@
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.gumbel.html">mlx.core.random.gumbel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.key.html">mlx.core.random.key</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.normal.html">mlx.core.random.normal</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.multivariate_normal.html">mlx.core.random.multivariate_normal</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.randint.html">mlx.core.random.randint</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.seed.html">mlx.core.random.seed</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.random.split.html">mlx.core.random.split</a></li>
@@ -431,6 +435,8 @@
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.metal.get_cache_memory.html">mlx.core.metal.get_cache_memory</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.metal.set_memory_limit.html">mlx.core.metal.set_memory_limit</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.metal.set_cache_limit.html">mlx.core.metal.set_cache_limit</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.metal.start_capture.html">mlx.core.metal.start_capture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python/_autosummary/mlx.core.metal.stop_capture.html">mlx.core.metal.stop_capture</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../python/nn.html">Neural Networks</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-11"><i class="fa-solid fa-chevron-down"></i></label><ul>
@@ -773,25 +779,39 @@ document.write(`
<section id="metal-debugger">
<h1>Metal Debugger<a class="headerlink" href="#metal-debugger" title="Link to this heading">#</a></h1>
<p>Profiling is a key step for performance optimization. You can build MLX with
the <code class="docutils literal notranslate"><span class="pre">MLX_METAL_DEBUG</span></code> option to improve the Metal debugging and optimization
workflow. The <code class="docutils literal notranslate"><span class="pre">MLX_METAL_DEBUG</span></code> debug option:</p>
the <code class="docutils literal notranslate"><span class="pre">MLX_METAL_DEBUG</span></code> option to improve the Metal debugging and
optimization workflow. The <code class="docutils literal notranslate"><span class="pre">MLX_METAL_DEBUG</span></code> debug option:</p>
<ul class="simple">
<li><p>Records source during Metal compilation, for later inspection while
debugging.</p></li>
<li><p>Labels Metal objects such as command queues, improving capture readability.</p></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">metal::start_capture</span></code> function initiates a capture of all MLX GPU work.</p>
<div class="highlight-C++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">metal</span><span class="o">::</span><span class="n">start_capture</span><span class="p">(</span><span class="s">&quot;/Users/Jane/Developer/MLX.gputrace&quot;</span><span class="p">);</span>
<p>To build with debugging enabled in Python prepend
<code class="docutils literal notranslate"><span class="pre">CMAKE_ARGS=&quot;-DMLX_METAL_DEBUG=ON&quot;</span></code> to the build call.</p>
<p>The <a class="reference internal" href="../python/_autosummary/mlx.core.metal.start_capture.html#mlx.core.metal.start_capture" title="mlx.core.metal.start_capture"><code class="xref py py-func docutils literal notranslate"><span class="pre">metal.start_capture()</span></code></a> function initiates a capture of all MLX GPU
work.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To capture a GPU trace you must run the application with
<code class="docutils literal notranslate"><span class="pre">MTL_CAPTURE_ENABLED=1</span></code>.</p>
</div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">mlx.core</span> <span class="k">as</span> <span class="nn">mx</span>
<span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">arange</span><span class="p">(</span><span class="mf">10.f</span><span class="p">,</span><span class="w"> </span><span class="mf">20.f</span><span class="p">,</span><span class="w"> </span><span class="mf">1.f</span><span class="p">,</span><span class="w"> </span><span class="n">float32</span><span class="p">);</span>
<span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">b</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">arange</span><span class="p">(</span><span class="mf">30.f</span><span class="p">,</span><span class="w"> </span><span class="mf">40.f</span><span class="p">,</span><span class="w"> </span><span class="mf">1.f</span><span class="p">,</span><span class="w"> </span><span class="n">float32</span><span class="p">);</span>
<span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">c</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">add</span><span class="p">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">);</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">mx</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">512</span><span class="p">,</span> <span class="mi">512</span><span class="p">))</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">mx</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">512</span><span class="p">,</span> <span class="mi">512</span><span class="p">))</span>
<span class="n">mx</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
<span class="w"> </span><span class="n">eval</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
<span class="n">trace_file</span> <span class="o">=</span> <span class="s2">&quot;mlx_trace.gputrace&quot;</span>
<span class="w"> </span><span class="n">metal</span><span class="o">::</span><span class="n">stop_capture</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">mx</span><span class="o">.</span><span class="n">metal</span><span class="o">.</span><span class="n">start_capture</span><span class="p">(</span><span class="n">trace_file</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Make sure to run with MTL_CAPTURE_ENABLED=1 and &quot;</span>
<span class="sa">f</span><span class="s2">&quot;that the path </span><span class="si">{</span><span class="n">trace_file</span><span class="si">}</span><span class="s2"> does not already exist.&quot;</span><span class="p">)</span>
<span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
<span class="n">mx</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="n">mx</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">))</span>
<span class="n">mx</span><span class="o">.</span><span class="n">metal</span><span class="o">.</span><span class="n">stop_capture</span><span class="p">()</span>
</pre></div>
</div>
<p>You can open and replay the GPU trace in Xcode. The <code class="docutils literal notranslate"><span class="pre">Dependencies</span></code> view
@@ -800,8 +820,8 @@ documentation</a> for more information.</p>
<img alt="../_images/capture.png" class="dark-light" src="../_images/capture.png" />
<section id="xcode-workflow">
<h2>Xcode Workflow<a class="headerlink" href="#xcode-workflow" title="Link to this heading">#</a></h2>
<p>You can skip saving to a path by running within Xcode. First, generate an Xcode
project using CMake.</p>
<p>You can skip saving to a path by running within Xcode. First, generate an
Xcode project using CMake.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">build</span> <span class="o">&amp;&amp;</span> <span class="n">cd</span> <span class="n">build</span>
<span class="n">cmake</span> <span class="o">..</span> <span class="o">-</span><span class="n">DMLX_METAL_DEBUG</span><span class="o">=</span><span class="n">ON</span> <span class="o">-</span><span class="n">G</span> <span class="n">Xcode</span>
<span class="nb">open</span> <span class="n">mlx</span><span class="o">.</span><span class="n">xcodeproj</span>