From 1ef6b63eee968a1b477b0cc6dc70cb89e868e918 Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 10:45:08 -0500 Subject: [PATCH 01/10] various fixes towards getting the pdf build working again --- .readthedocs.yml | 3 +++ README.rst | 4 ++-- docs/conf.py | 4 ++++ pixi.lock | 4 ++-- pyproject.toml | 5 +++++ 5 files changed, 16 insertions(+), 4 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index eb847ef48..0b11a0ecc 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -26,6 +26,9 @@ build: - pixi run -e docs build-docs - mkdir -p $READTHEDOCS_OUTPUT/html/ - cp -r docs/_build/html/** $READTHEDOCS_OUTPUT/html/ + - pixi run -e docs build-pdf + - mkdir -p $READTHEDOCS_OUTPUT/pdf/ + - cp docs/_build/latex/libensemble.pdf $READTHEDOCS_OUTPUT/pdf/ sphinx: configuration: docs/conf.py diff --git a/README.rst b/README.rst index 868d9ab9e..0b797fc6c 100644 --- a/README.rst +++ b/README.rst @@ -25,7 +25,7 @@ and inference problems on the world's leading supercomputers such as Frontier, A **New:** libEnsemble nows supports the `gest-api`_ generator standard, and can run with Optimas and Xopt generators. -The |ScriptCreator| to generate customized scripts for running ensembles with your +Try the |ScriptCreator| to generate customized scripts for running ensembles with your MPI applications. Installation @@ -216,6 +216,6 @@ Resources .. |Bayesian Optimization with Xopt| image:: https://colab.research.google.com/assets/colab-badge.svg :target: https://colab.research.google.com/github/Libensemble/libensemble/blob/develop/examples/tutorials/xopt_bayesian_gen/xopt_EI_example.ipynb -.. |ScriptCreator| image:: https://img.shields.io/badge/Script_Creator-purple?logo=magic +.. |ScriptCreator| image:: https://img.shields.io/badge/Script_Creator-purple :target: https://libensemble.github.io/script-creator/ :alt: Script Creator diff --git a/docs/conf.py b/docs/conf.py index ab82bc429..fda09aaff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -105,6 +105,10 @@ class AxParameterWarning(Warning): # Ensure it's a real warning subclass spelling_ignore_python_builtins = True spelling_ignore_importable_modules = True +# Use ImageMagick v7's `magick` command instead of deprecated `convert` +image_converter = "magick" +image_converter_args = ["convert", "-background", "white"] + bibtex_bibfiles = ["references.bib"] bibtex_default_style = "unsrt" diff --git a/pixi.lock b/pixi.lock index 098ba20f5..3dfe2f509 100644 --- a/pixi.lock +++ b/pixi.lock @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:c7f473ad72a7c038dee9ec8d3dbe035f6e96e3cfe2f95e2c0522e0e937912da5 -size 1056784 +oid sha256:6641e7777cbbe69a6e3634cf4fb2dca7beb8414c6953694c7412e7019942043e +size 1058196 diff --git a/pyproject.toml b/pyproject.toml index d094eb54a..42bb172b3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -138,10 +138,15 @@ mypy = ">=1.19.1,<2" types-psutil = ">=6.1.0.20241221,<7" types-pyyaml = ">=6.0.12.20250915,<7" furo = ">=2025.12.19,<2026" +latexcodec = ">=2.0.1,<3" +latexmk = ">=4.88,<5" [tool.pixi.tasks.build-docs] cmd = "cd docs && make html" +[tool.pixi.tasks.build-pdf] +cmd = "cd docs && make latexpdf" + # Linux dependencies, only for extra tests [tool.pixi.feature.extra.target.linux-64.dependencies] scikit-build = "*" From be67b37a32b40f58148107c6472475c40e73e1c1 Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 12:11:30 -0500 Subject: [PATCH 02/10] add imagemagick --- pixi.lock | 4 ++-- pyproject.toml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/pixi.lock b/pixi.lock index 3dfe2f509..8df04d717 100644 --- a/pixi.lock +++ b/pixi.lock @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:6641e7777cbbe69a6e3634cf4fb2dca7beb8414c6953694c7412e7019942043e -size 1058196 +oid sha256:2ea06a21d57979529f90b4dff9ed39cd1279667235598e91edccce65f6435fbd +size 1085121 diff --git a/pyproject.toml b/pyproject.toml index 42bb172b3..ed94a8d36 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -140,6 +140,7 @@ types-pyyaml = ">=6.0.12.20250915,<7" furo = ">=2025.12.19,<2026" latexcodec = ">=2.0.1,<3" latexmk = ">=4.88,<5" +imagemagick = ">=7.1.2_16,<8" [tool.pixi.tasks.build-docs] cmd = "cd docs && make html" From 2a9d552a62241df1d7edcf44aed8c095b2747ba0 Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 13:09:21 -0500 Subject: [PATCH 03/10] are fonts available? --- docs/conf.py | 2 +- pixi.lock | 4 ++-- pyproject.toml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index fda09aaff..3b7cbb7f5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -107,7 +107,7 @@ class AxParameterWarning(Warning): # Ensure it's a real warning subclass # Use ImageMagick v7's `magick` command instead of deprecated `convert` image_converter = "magick" -image_converter_args = ["convert", "-background", "white"] +# image_converter_args = ["convert", "-background", "white"] bibtex_bibfiles = ["references.bib"] bibtex_default_style = "unsrt" diff --git a/pixi.lock b/pixi.lock index 8df04d717..beacfa9d3 100644 --- a/pixi.lock +++ b/pixi.lock @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:2ea06a21d57979529f90b4dff9ed39cd1279667235598e91edccce65f6435fbd -size 1085121 +oid sha256:335e6482eef4f3abbd2de4caa77ad98d7472ba7b6546af89dfbde94ac192db12 +size 1058911 diff --git a/pyproject.toml b/pyproject.toml index ed94a8d36..3eed6fddd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -140,7 +140,7 @@ types-pyyaml = ">=6.0.12.20250915,<7" furo = ">=2025.12.19,<2026" latexcodec = ">=2.0.1,<3" latexmk = ">=4.88,<5" -imagemagick = ">=7.1.2_16,<8" +fonts-conda-forge = ">=1,<2" [tool.pixi.tasks.build-docs] cmd = "cd docs && make html" From 9893e740fdd476e329315a4c8130dfc1aacb383e Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 13:34:25 -0500 Subject: [PATCH 04/10] ...put imagemagick back --- pixi.lock | 4 ++-- pyproject.toml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/pixi.lock b/pixi.lock index beacfa9d3..8fa829e09 100644 --- a/pixi.lock +++ b/pixi.lock @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:335e6482eef4f3abbd2de4caa77ad98d7472ba7b6546af89dfbde94ac192db12 -size 1058911 +oid sha256:95763b1326e2a21dd0aabb08e20c13f004f5fa6aef87a33614101e024318c05e +size 1085121 diff --git a/pyproject.toml b/pyproject.toml index 3eed6fddd..de3bb6e8e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -141,6 +141,7 @@ furo = ">=2025.12.19,<2026" latexcodec = ">=2.0.1,<3" latexmk = ">=4.88,<5" fonts-conda-forge = ">=1,<2" +imagemagick = ">=7.1.2_16,<8" [tool.pixi.tasks.build-docs] cmd = "cd docs && make html" From b559b3197017cdb9fe9510d66950160fb57e7ceb Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 13:55:33 -0500 Subject: [PATCH 05/10] claude blames the imgconverter --- docs/conf.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3b7cbb7f5..8647bbf4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,7 +91,6 @@ class AxParameterWarning(Warning): # Ensure it's a real warning subclass "sphinx.ext.napoleon", # 'sphinx.ext.autosectionlabel', "sphinx.ext.intersphinx", - "sphinx.ext.imgconverter", "sphinx.ext.mathjax", "sphinxcontrib.autodoc_pydantic", "sphinx_design", @@ -105,10 +104,6 @@ class AxParameterWarning(Warning): # Ensure it's a real warning subclass spelling_ignore_python_builtins = True spelling_ignore_importable_modules = True -# Use ImageMagick v7's `magick` command instead of deprecated `convert` -image_converter = "magick" -# image_converter_args = ["convert", "-background", "white"] - bibtex_bibfiles = ["references.bib"] bibtex_default_style = "unsrt" From 49c91a385bf7debf736d254f7bccb1adfcff4232 Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 14:13:07 -0500 Subject: [PATCH 06/10] pdf try skipping the badges that are incompatible --- README.rst | 8 ++++++++ docs/introduction.rst | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/README.rst b/README.rst index 0b797fc6c..77f73518d 100644 --- a/README.rst +++ b/README.rst @@ -25,9 +25,13 @@ and inference problems on the world's leading supercomputers such as Frontier, A **New:** libEnsemble nows supports the `gest-api`_ generator standard, and can run with Optimas and Xopt generators. +.. before_script_creator_tag + Try the |ScriptCreator| to generate customized scripts for running ensembles with your MPI applications. +.. after_script_creator_tag + Installation ============ @@ -109,6 +113,8 @@ and an exit condition. ensemble.save_output(__file__) print("Some output data:\n", ensemble.H[["x0", "x1", "f"]][:10]) +.. before_colab_tag + |Inline Example| Try some other examples live in Colab. @@ -127,6 +133,8 @@ Try some other examples live in Colab. | Bayesian Optimization with Xopt. | |Bayesian Optimization with Xopt| | +---------------------------------------------------------------+-------------------------------------+ +.. after_colab_tag + There are many more examples in the `regression tests`_ and `Community Examples repository`_. Resources diff --git a/docs/introduction.rst b/docs/introduction.rst index 87ccac72f..0e1ebca6f 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1,5 +1,13 @@ .. include:: ../README.rst :start-after: after_badges_rst_tag + :end-before: before_script_creator_tag + +.. include:: ../README.rst + :start-after: after_script_creator_tag + :end-before: before_colab_tag + +.. include:: ../README.rst + :start-after: after_colab_tag See the :doc:`tutorial` for a step-by-step beginners guide. From d178b7c560d099e210df7310a70ee5c0309b2c9a Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 14:41:36 -0500 Subject: [PATCH 07/10] try getting the colab buttons to not appear in pdf --- docs/tutorials/aposmm_tutorial.rst | 4 +++- docs/tutorials/executor_forces_tutorial.rst | 4 +++- docs/tutorials/gpcam_tutorial.rst | 4 +++- docs/tutorials/local_sine_tutorial/local_sine_tutorial.rst | 5 ++++- docs/tutorials/xopt_bayesian_gen.rst | 4 +++- 5 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/aposmm_tutorial.rst b/docs/tutorials/aposmm_tutorial.rst index d5b3f4f04..7cc0d7b9f 100644 --- a/docs/tutorials/aposmm_tutorial.rst +++ b/docs/tutorials/aposmm_tutorial.rst @@ -10,7 +10,9 @@ simulation :ref:`sim_f` that defines a function with multiple minima, then write a libEnsemble calling script that imports APOSMM and parameterizes it to check for minima over a domain of outputs from our ``sim_f``. -|Open in Colab| +.. only:: html + + |Open in Colab| Six-Hump Camel Simulation Function ---------------------------------- diff --git a/docs/tutorials/executor_forces_tutorial.rst b/docs/tutorials/executor_forces_tutorial.rst index 33142fb60..e1f7d4b81 100644 --- a/docs/tutorials/executor_forces_tutorial.rst +++ b/docs/tutorials/executor_forces_tutorial.rst @@ -6,7 +6,9 @@ This tutorial highlights libEnsemble's capability to portably execute and monitor external scripts or user applications within simulation or generator functions using the :doc:`executor<../executor/ex_index>`. -|Open in Colab| +.. only:: html + + |Open in Colab| The calling script registers a compiled executable that simulates electrostatic forces between a collection of particles. The simulator function diff --git a/docs/tutorials/gpcam_tutorial.rst b/docs/tutorials/gpcam_tutorial.rst index 096d5584c..190697374 100644 --- a/docs/tutorials/gpcam_tutorial.rst +++ b/docs/tutorials/gpcam_tutorial.rst @@ -5,7 +5,9 @@ This example uses gpCAM_ to construct a global surrogate of ``f`` values using a In each iteration, a batch of points is produced for concurrent evaluation, maximizing uncertainty reduction. -|Open in Colab| +.. only:: html + + |Open in Colab| Ensure that libEnsemble, and gpCAM are installed via: ``pip install libensemble gpcam`` diff --git a/docs/tutorials/local_sine_tutorial/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial/local_sine_tutorial.rst index d5e587a0f..8413c3de7 100644 --- a/docs/tutorials/local_sine_tutorial/local_sine_tutorial.rst +++ b/docs/tutorials/local_sine_tutorial/local_sine_tutorial.rst @@ -9,7 +9,10 @@ calculations in parallel using :doc:`libEnsemble<../../introduction>`. We recommend reading this brief :doc:`Overview<../../overview_usecases>`. -|Open in Colab| +.. only:: html + + |Open in Colab| + For this tutorial, our generator will produce uniform randomly sampled values, and our simulator will calculate the sine of each. By default we don't diff --git a/docs/tutorials/xopt_bayesian_gen.rst b/docs/tutorials/xopt_bayesian_gen.rst index 9271efd75..9227ac8ce 100644 --- a/docs/tutorials/xopt_bayesian_gen.rst +++ b/docs/tutorials/xopt_bayesian_gen.rst @@ -10,7 +10,9 @@ We'll show two approaches: 1. Using an xopt-style simulator (callable function) 2. Using a libEnsemble-style simulator function -|Open in Colab| +.. only:: html + + |Open in Colab| Imports ------- From d5954d6f3514c331df07a5afab0bf2ab33dac76d Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 15:01:55 -0500 Subject: [PATCH 08/10] and then hopefully a typo fix is all we need? --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 0b11a0ecc..d99031f43 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: - cp -r docs/_build/html/** $READTHEDOCS_OUTPUT/html/ - pixi run -e docs build-pdf - mkdir -p $READTHEDOCS_OUTPUT/pdf/ - - cp docs/_build/latex/libensemble.pdf $READTHEDOCS_OUTPUT/pdf/ + - cp docs/_build/latex/libEnsemble.pdf $READTHEDOCS_OUTPUT/pdf/ sphinx: configuration: docs/conf.py From f19cf8ca8d81d8aec481c3279566ab87a8cc07eb Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 15:42:56 -0500 Subject: [PATCH 09/10] try copying everything over? --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index d99031f43..eadb67ec3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: - cp -r docs/_build/html/** $READTHEDOCS_OUTPUT/html/ - pixi run -e docs build-pdf - mkdir -p $READTHEDOCS_OUTPUT/pdf/ - - cp docs/_build/latex/libEnsemble.pdf $READTHEDOCS_OUTPUT/pdf/ + - cp -r docs/_build/latex/** $READTHEDOCS_OUTPUT/pdf/ sphinx: configuration: docs/conf.py From 0fc4c7d0d033777e8be92607895c608a5e321a70 Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 8 May 2026 15:51:18 -0500 Subject: [PATCH 10/10] it can only be the pdf apparently --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index eadb67ec3..d7c674392 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: - cp -r docs/_build/html/** $READTHEDOCS_OUTPUT/html/ - pixi run -e docs build-pdf - mkdir -p $READTHEDOCS_OUTPUT/pdf/ - - cp -r docs/_build/latex/** $READTHEDOCS_OUTPUT/pdf/ + - cp -r docs/_build/latex/libEnsemble.pdf $READTHEDOCS_OUTPUT/pdf/ sphinx: configuration: docs/conf.py