Update documentation

Author: github-actions[bot]

main/.doctrees/developers_guide/api.doctree

@@ -653,7 +653,7 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
     <span class="n">prefix</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
     <span class="n">pixi_cfg</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
     <span class="n">runtime</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
-    <span class="n">compute_mpi</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+    <span class="n">compute_mpi</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span>
     <span class="n">runtime_pixi</span> <span class="o">=</span> <span class="n">runtime</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;pixi&#39;</span><span class="p">)</span>
     <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">runtime_pixi</span><span class="p">,</span> <span class="nb">dict</span><span class="p">):</span>
@@ -671,6 +671,8 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
     <span class="n">resolved_login_mpi</span><span class="p">,</span> <span class="n">login_mpi_prefix</span> <span class="o">=</span> <span class="n">_get_mpi_settings</span><span class="p">(</span>
         <span class="n">pixi_cfg</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;mpi&#39;</span><span class="p">:</span> <span class="n">login_mpi</span><span class="p">}</span>
     <span class="p">)</span>
+    <span class="k">if</span> <span class="n">resolved_login_mpi</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">login_mpi_prefix</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;login_mpi must resolve to a non-empty MPI setting&#39;</span><span class="p">)</span>
 
     <span class="k">if</span> <span class="s1">&#39;login_prefix&#39;</span> <span class="ow">in</span> <span class="n">runtime_pixi</span><span class="p">:</span>
         <span class="n">login_prefix_raw</span> <span class="o">=</span> <span class="n">runtime_pixi</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;login_prefix&#39;</span><span class="p">)</span>
@@ -993,15 +995,12 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
     <span class="o">*</span><span class="p">,</span>
     <span class="n">pixi_cfg</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
     <span class="n">runtime</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
-<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span>
-    <span class="n">mpi_override</span> <span class="o">=</span> <span class="kc">None</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">]:</span>
+    <span class="n">mpi_cfg</span> <span class="o">=</span> <span class="n">pixi_cfg</span>
     <span class="n">runtime_pixi</span> <span class="o">=</span> <span class="n">runtime</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;pixi&#39;</span><span class="p">)</span>
     <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">runtime_pixi</span><span class="p">,</span> <span class="nb">dict</span><span class="p">):</span>
-        <span class="n">mpi_override</span> <span class="o">=</span> <span class="n">runtime_pixi</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;mpi&#39;</span><span class="p">)</span>
-    <span class="k">if</span> <span class="n">mpi_override</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="n">mpi_cfg</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;mpi&#39;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">mpi_override</span><span class="p">)}</span>
-    <span class="k">else</span><span class="p">:</span>
-        <span class="n">mpi_cfg</span> <span class="o">=</span> <span class="n">pixi_cfg</span>
+        <span class="k">if</span> <span class="s1">&#39;mpi&#39;</span> <span class="ow">in</span> <span class="n">runtime_pixi</span><span class="p">:</span>
+            <span class="n">mpi_cfg</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;mpi&#39;</span><span class="p">:</span> <span class="n">runtime_pixi</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;mpi&#39;</span><span class="p">)}</span>
     <span class="k">return</span> <span class="n">_get_mpi_settings</span><span class="p">(</span><span class="n">pixi_cfg</span><span class="o">=</span><span class="n">mpi_cfg</span><span class="p">)</span>
 
 
@@ -1514,7 +1513,7 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
     <span class="n">software_version</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
     <span class="n">runtime_version_cmd</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">machine</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
-    <span class="n">compute_pixi_mpi</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+    <span class="n">compute_pixi_mpi</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">toolchain_compiler</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">toolchain_mpi</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">spack_library_view</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
@@ -1602,7 +1601,7 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
         <span class="n">runtime_version_cmd_sh</span><span class="o">=</span><span class="n">shlex</span><span class="o">.</span><span class="n">quote</span><span class="p">(</span><span class="n">runtime_version_cmd</span> <span class="ow">or</span> <span class="s1">&#39;&#39;</span><span class="p">),</span>
         <span class="n">machine</span><span class="o">=</span><span class="n">machine</span> <span class="ow">or</span> <span class="s1">&#39;&#39;</span><span class="p">,</span>
         <span class="n">load_script</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">script_path</span><span class="p">),</span>
-        <span class="n">compute_pixi_mpi</span><span class="o">=</span><span class="n">compute_pixi_mpi</span><span class="p">,</span>
+        <span class="n">compute_pixi_mpi</span><span class="o">=</span><span class="n">compute_pixi_mpi</span> <span class="ow">or</span> <span class="s1">&#39;&#39;</span><span class="p">,</span>
         <span class="n">login_prefix</span><span class="o">=</span><span class="n">login_prefix_abs</span><span class="p">,</span>
         <span class="n">login_pixi_toml</span><span class="o">=</span><span class="n">login_pixi_toml</span><span class="p">,</span>
         <span class="n">login_pixi_mpi</span><span class="o">=</span><span class="n">login_pixi_mpi</span><span class="p">,</span>
@@ -1635,7 +1634,7 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
     <span class="n">software_version</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
     <span class="n">runtime_version_cmd</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">machine</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
-    <span class="n">compute_pixi_mpi</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+    <span class="n">compute_pixi_mpi</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">toolchain_pairs</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]],</span>
     <span class="n">spack_results</span><span class="p">:</span> <span class="n">Any</span><span class="p">,</span>
     <span class="n">spack_software_env</span><span class="p">:</span> <span class="n">Any</span><span class="p">,</span>
@@ -1808,29 +1807,26 @@ <h1>Source code for mache.deploy.run</h1><div class="highlight"><pre>
 
 <span class="k">def</span><span class="w"> </span><span class="nf">_get_mpi_settings</span><span class="p">(</span>
     <span class="n">pixi_cfg</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
-<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;Determine MPI-related template replacements.</span>
 
 <span class="sd">    Returns</span>
 <span class="sd">    -------</span>
-<span class="sd">    mpi : str</span>
+<span class="sd">    mpi : str or None</span>
 <span class="sd">        The conda package name for MPI (e.g. &quot;mpich&quot;, &quot;openmpi&quot;, or &quot;nompi&quot;).</span>
-<span class="sd">    mpi_prefix : str</span>
+<span class="sd">    mpi_prefix : str or None</span>
 <span class="sd">        The conda-forge variant prefix used in build-string selectors</span>
 <span class="sd">        (e.g. &quot;nompi&quot;, &quot;mpi_mpich&quot;, &quot;mpi_openmpi&quot;).</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="k">if</span> <span class="s1">&#39;mpi&#39;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">pixi_cfg</span><span class="p">:</span>
-        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
-            <span class="s2">&quot;&#39;mpi&#39; not found in [pixi] section of deploy/config.yaml.j2&quot;</span>
-        <span class="p">)</span>
+        <span class="k">return</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span>
 
-    <span class="n">mpi_raw</span> <span class="o">=</span> <span class="n">pixi_cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;mpi&#39;</span><span class="p">)</span>
-    <span class="n">mpi</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">mpi_raw</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="k">if</span> <span class="n">mpi_raw</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="s1">&#39;&#39;</span>
-    <span class="k">if</span> <span class="ow">not</span> <span class="n">mpi</span><span class="p">:</span>
-        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
-            <span class="s2">&quot;&#39;mpi&#39; in [pixi] section of deploy/config.yaml.j2 is empty&quot;</span>
-        <span class="p">)</span>
+    <span class="n">mpi</span> <span class="o">=</span> <span class="n">_normalize_optional_token</span><span class="p">(</span><span class="n">pixi_cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;mpi&#39;</span><span class="p">))</span>
+    <span class="k">if</span> <span class="n">mpi</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="k">return</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span>
+
+    <span class="n">mpi</span> <span class="o">=</span> <span class="n">mpi</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
     <span class="k">if</span> <span class="nb">any</span><span class="p">(</span><span class="n">ch</span><span class="o">.</span><span class="n">isspace</span><span class="p">()</span> <span class="k">for</span> <span class="n">ch</span> <span class="ow">in</span> <span class="n">mpi</span><span class="p">):</span>
         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
             <span class="s2">&quot;&#39;mpi&#39; in [pixi] section of deploy/config.yaml.j2 must not &quot;</span>