Update docs for dev (build 4348)

Author: Circle CI

dev/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 1b77bf6a6caf24ebdc5f7b8531dc16ff
+config: 9f6349362a41aa79b0d87111c8947c2b
 tags: 645f666f9bcd5a90fca523b33c5a78b7

dev/_downloads/00ee07f9285b4b63fdf636b0111c4697/run_julia_solver.zip

@@ -0,0 +1,129 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Create and run a Julia solver benchmark\n\nThis example shows how to add a Julia solver in a simple benchmark using\nbenchopt's helpers to call Julia code from Python.\n\nThe benchmark objective is a simple minimization task:\n\n\\begin{align}\\min_{\\hat{X}} \\; \\mathrm{MSE}(X, \\hat{X})\\end{align}\n\nWe define:\n\n- a Python ``Objective`` that evaluates MSE between ``X`` and ``X_hat``;\n- a Python ``Dataset`` that generates a random matrix ``X``;\n- two solvers:\n\n  - ``Python-GD`` implemented in Python;\n  - ``Julia-GD`` implemented in Julia and called through ``JuliaSolver``.\n\nAt the end, we run the benchmark and display the comparison.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Import example helpers to define the benchmark and\n# programmatically call the CLI.\nfrom benchopt.helpers.run_examples import ExampleBenchmark\nfrom benchopt.helpers.run_examples import benchopt_cli\nfrom benchopt.helpers.run_examples import EXAMPLES_ROOT"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "First, we define the initial Python benchmark, based on the benchmark\n``examples/minimal_benchmark``. It contains an ``objective.py`` file,\na simulated dataset and a full python solver based on gradient descent.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "benchmark = ExampleBenchmark(\n    base=\"minimal_benchmark\", name=\"julia_solver\",\n    ignore=[\"custom_plot.py\", \"example_config.yml\"]\n)\nbenchmark"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can now add solver in Julia with the same algorithm.\nTo do this, we create a new file ``julia_gd.py`` that defines a solver based\non the ``JuliaSolver`` class. This class provides helpers to call Julia code\nfrom Python, and to define the dependencies of the solver.\nThe Julia code is defined in a separate file ``julia_gd.jl``, that is loaded\nand called from the Python solver.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "JULIA_SOLVER = EXAMPLES_ROOT / \"language_solvers\" / \"julia_gd.py\"\nJULIA_SOLVER_PY = JULIA_SOLVER.read_text(encoding=\"utf-8\")\nJULIA_SOLVER_JL = JULIA_SOLVER.with_suffix(\".jl\").read_text(encoding=\"utf-8\")\n\nbenchmark.update(\n    solvers={\"julia_gd.py\": JULIA_SOLVER_PY, \"julia_gd.jl\": JULIA_SOLVER_JL},\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "In order to load the Julia interpreter, we use ``get_jl_interpreter``. This\nfunction returns a ``Julia`` object from ``PyJulia``, that can be used to\ninteract with Julia. In particular, we can use the ``include`` method to load\na Julia file and retrieve the functions defined in it as attributes of the\nreturned object.\n\nNote that the Julia solver cannot call a Python callback to report\nintermediate results, so we call iteratively the Julia solver with a growing\nnumber of iterations to be able to report the curve of the convergence.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "To be able to run this benchmark, we need to install its dependencies. We can\ndo this with ``benchopt install``, using with the ``-s`` option which allow\nto select only this solver if multiple solvers are present. If Julia is not\navailable in your environment, this command will use ``conda`` to install it.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "benchopt_cli(f\"install {benchmark.benchmark_dir} -s julia-gd\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Then, we can run the benchmark and show the comparison.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "benchopt_cli(f\"run {benchmark.benchmark_dir} -n 20 -r 4\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Here, you see that the Julia solver is faster than the Python one.\nYou also notice that the first iteration seems to take much longer than the\nother, hinting to a loading time for the solver.\n\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.13"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

dev/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip

@@ -0,0 +1,73 @@
+r"""Create and run an R solver benchmark
+====================================
+
+This example shows how to add an R solver in a simple benchmark using
+benchopt's helpers to call R code from Python.
+
+The benchmark objective is a simple minimization task:
+
+.. math::
+
+    \min_{\hat{X}} \; \mathrm{MSE}(X, \hat{X})
+
+We define:
+
+- a Python ``Objective`` that evaluates MSE between ``X`` and ``X_hat``;
+- a Python ``Dataset`` that generates a random matrix ``X``;
+- two solvers:
+
+  - ``Python-GD`` implemented in Python;
+  - ``R-PGD`` implemented in R and called through ``rpy2``.
+
+At the end, we run the benchmark and display the comparison.
+"""
+
+# Import example helpers to define the benchmark and
+# programmatically call the CLI.
+from benchopt.helpers.run_examples import ExampleBenchmark
+from benchopt.helpers.run_examples import benchopt_cli
+from benchopt.helpers.run_examples import EXAMPLES_ROOT
+
+
+# %%
+# First, we define the initial Python benchmark, based on the benchmark
+# ``examples/minimal_benchmark``. It contains an ``objective.py`` file,
+# a simulated dataset and a full python solver based on gradient descent.
+
+benchmark = ExampleBenchmark(
+    base="minimal_benchmark", name="r_solver",
+    ignore=["custom_plot.py", "example_config.yml"]
+)
+benchmark
+
+# %%
+# We can now add a solver in R with the same algorithm.
+# To do this, we create a new file ``r_pgd.py`` that defines a solver calling
+# an R function via ``benchopt.helpers.r_lang`` and ``rpy2``.
+#
+# The R code is defined in a separate file ``r_pgd.R``, loaded from Python.
+
+R_SOLVER = EXAMPLES_ROOT / "language_solvers" / "r_pgd.py"
+R_SOLVER_PY = R_SOLVER.read_text(encoding="utf-8")
+R_SOLVER_R = R_SOLVER.with_suffix(".R").read_text(encoding="utf-8")
+
+benchmark.update(
+    solvers={"r_pgd.py": R_SOLVER_PY, "r_pgd.R": R_SOLVER_R},
+)
+
+# %%
+# To run this benchmark, we need to install solver dependencies.
+# We use ``benchopt install`` with ``-s`` to select only this solver.
+# If R is not available in your environment, this command can install it
+# through conda using the solver requirements.
+
+benchopt_cli(f"install {benchmark.benchmark_dir} -s r-pgd")
+
+# %%
+# Then, we can run the benchmark and show the comparison.
+
+benchopt_cli(f"run {benchmark.benchmark_dir} -n 20 -r 4")
+
+# %%
+# Here, you should see that the R solver and Python solver obtain similar
+# convergence profiles, with runtime differences depending on your setup.

dev/_downloads/29629f8c22f6cb2460d350b639bd96ab/run_julia_solver.ipynb

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "# Running an existing benchmark\n\nThis Example demonstrates how to run an existing benchmark with benchopt.\nIt uses the `benchopt_run` helper function to run the benchmark, which runs\nprogrammatically the equivalent of the command line interface:\n"
+        "# Running an existing benchmark\n\nThis example demonstrates how to run an existing benchmark with benchopt.\n"
       ]
     },
     {
@@ -15,7 +15,25 @@
       },
       "outputs": [],
       "source": [
-        "from benchopt.helpers.run_examples import benchopt_run"
+        "# Import example helpers to define the benchmark and\n# programmatically call the CLI.\nfrom benchopt.helpers.run_examples import ExampleBenchmark\nfrom benchopt.helpers.run_examples import benchopt_cli"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We will use the minimal benchmark defined in the ``examples`` folder.\nThe benchmark objective is a simple minimization task:\n\n\\begin{align}\\min_{\\hat{X}} \\; \\mathrm{MSE}(X, \\hat{X})\\end{align}\n\nWe define:\n\n- an ``Objective`` that evaluates MSE between ``X`` and ``X_hat``;\n- a ``Dataset`` that generates a random matrix ``X``;\n- a ``Solver`` that minimizes this objective with gradient descent. It is\n  parametrized with parameter ``lr`` for the step size.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "benchmark = ExampleBenchmark(\n    base=\"minimal_benchmark\", name=\"minimal_benchmark\",\n    ignore=[\"custom_plot.py\", \"example_config.yml\"]\n)\nbenchmark"
       ]
     },
     {
@@ -33,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "benchopt_run('minimal_benchmark', n=20, r=2)"
+        "benchopt_cli(f\"run {benchmark.benchmark_dir} -n 20 -r 2\")"
       ]
     },
     {
@@ -51,7 +69,7 @@
       },
       "outputs": [],
       "source": [
-        "benchopt_run('minimal_benchmark', n=30, r=5)"
+        "benchopt_cli(f\"run {benchmark.benchmark_dir} -n 30 -r 5\")"
       ]
     },
     {
@@ -78,7 +96,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.10.20"
+      "version": "3.12.13"
     }
   },
   "nbformat": 4,

dev/_downloads/3916d00937ce16b1b91eb22f8384b543/run_r_solver.py

@@ -1,18 +1,40 @@
 """Running an existing benchmark
 =============================
 
-This Example demonstrates how to run an existing benchmark with benchopt.
-It uses the `benchopt_run` helper function to run the benchmark, which runs
-programmatically the equivalent of the command line interface:
+This example demonstrates how to run an existing benchmark with benchopt.
 """
 
-from benchopt.helpers.run_examples import benchopt_run
+# Import example helpers to define the benchmark and
+# programmatically call the CLI.
+from benchopt.helpers.run_examples import ExampleBenchmark
+from benchopt.helpers.run_examples import benchopt_cli
+
+# %%
+# We will use the minimal benchmark defined in the ``examples`` folder.
+# The benchmark objective is a simple minimization task:
+#
+# .. math::
+#
+#     \min_{\hat{X}} \; \mathrm{MSE}(X, \hat{X})
+#
+# We define:
+#
+# - an ``Objective`` that evaluates MSE between ``X`` and ``X_hat``;
+# - a ``Dataset`` that generates a random matrix ``X``;
+# - a ``Solver`` that minimizes this objective with gradient descent. It is
+#   parametrized with parameter ``lr`` for the step size.
+
+benchmark = ExampleBenchmark(
+    base="minimal_benchmark", name="minimal_benchmark",
+    ignore=["custom_plot.py", "example_config.yml"]
+)
+benchmark
 
 # %%
 # To run the benchmark, just execute:
 #
 
-benchopt_run('minimal_benchmark', n=20, r=2)
+benchopt_cli(f"run {benchmark.benchmark_dir} -n 20 -r 2")
 
 # %%
 # This runs the benchmark named ``minimal_benchmark`` located in the
@@ -24,7 +46,7 @@
 #
 # To get a more precise curve, you can increase ``n`` and ``r``:
 
-benchopt_run('minimal_benchmark', n=30, r=5)
+benchopt_cli(f"run {benchmark.benchmark_dir} -n 30 -r 5")
 
 # %%
 # Here, the display is not ideal because both solvers reach convergence very