From 2528c425d8919f13e116ecca36f11e6818b15819 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 09:05:44 -0500 Subject: [PATCH 1/7] (Issue #13) Need to distinguish references with two distinct bibiliographies. All citations from the common bibtex file should be prefixed by py- or cpp- based on which subdocument (and therefore which bibiliography) contains the reference. This resolved a build warning reporting multiple citations when in fact I had added only the single citation in the Python examples section. --- docs/bibliography_cpp.rst | 1 + docs/bibliography_py.rst | 1 + docs/examples_py.rst | 8 +++++--- docs/references.bib | 11 +++++++++++ 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/bibliography_cpp.rst b/docs/bibliography_cpp.rst index 45e41e1..203aa7f 100644 --- a/docs/bibliography_cpp.rst +++ b/docs/bibliography_cpp.rst @@ -10,3 +10,4 @@ Bibliography .. bibliography:: references.bib :style: plain + :keyprefix: cpp- diff --git a/docs/bibliography_py.rst b/docs/bibliography_py.rst index 45e41e1..cb2fcb0 100644 --- a/docs/bibliography_py.rst +++ b/docs/bibliography_py.rst @@ -10,3 +10,4 @@ Bibliography .. bibliography:: references.bib :style: plain + :keyprefix: py- diff --git a/docs/examples_py.rst b/docs/examples_py.rst index 48c2c73..0c480c9 100644 --- a/docs/examples_py.rst +++ b/docs/examples_py.rst @@ -1,5 +1,7 @@ Examples ======== -.. todo:: - Reference single example notebook and update after Matt finishes cleaning - the contents of the repo (Issue #6). +.. _BART_BMM_Technometrics: https://github.com/bandframework/OpenBT/blob/main/Examples/BART_BMM_Technometrics.ipynb + +The examples from :cite:t:`py-BARTMix_Yannotty2024` are reproduced in the +BART_BMM_Technometrics_ Jupyter noteboook, which can be run locally or in a +virtual environment such as google colab. diff --git a/docs/references.bib b/docs/references.bib index e69de29..a5a151e 100644 --- a/docs/references.bib +++ b/docs/references.bib @@ -0,0 +1,11 @@ +@article{BARTMix_Yannotty2024, +author = {John C. Yannotty and Thomas J. Santner and Richard J. Furnstahl and Matthew T. Pratola}, +title = {Model Mixing Using Bayesian Additive Regression Trees}, +journal = {Technometrics}, +volume = {66}, +number = {2}, +pages = {196--207}, +year = {2024}, +publisher = {Taylor \& Francis}, +doi = {10.1080/00401706.2023.2257765} +} From 9778f95a019f1ccc9bbcaf16cdc9f962f41c8a80 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 09:10:24 -0500 Subject: [PATCH 2/7] (Issue #13) Include basic technical details of the overall OpenBT system. --- docs/index.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 792fd41..5ed4bd3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,31 @@ |openbt| Python package ======================= +.. _Open MPI: https://www.open-mpi.org +.. _MPICH: https://www.mpich.org .. todo:: Write high-level description, explain development history, and motivate breakdown of documents presented here. License, copyright, responsibilities of user, etc. +The heart of |openbt| is a set of C++ tools that can be used directly |via| the +command line or indirectly through the ``openbt`` Python package, which wraps +them. Typically these tools are built with an implementation of the Message +Passing Interface (MPI) such as `Open MPI`_ or MPICH_ to enable distributed +parallelization of computations. In particular, the Python wrapper package is +always built with MPI support. + +The |openbt| software and its distribution scheme have been developed to allow +users to use |openbt| with the MPI installation of their choice. For instance, +it can be built with MPI installed on a laptop using the system's package +manager or with MPI installations on leadership class platforms and clusters +that were installed by experts and optimized for their specific platform. + +.. note:: + While an R wrapper does exist for the original |openbt| and |openbtmixing| + repositories, that functionality has not yet been included in this new, + combined repository (Issue #XYZ). + This package is being developed as part of |band| `framework `_. From 99f42775ca481d34501ff52782bd690ed79b45bb Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 09:11:57 -0500 Subject: [PATCH 3/7] (Issue #13) Rough draft of C++ install guide. Built up from pieces of the README. I will trim material out of the README after the User Guide is a sufficiently good replacement for the README. --- docs/get_started_cpp.rst | 86 ++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 16 deletions(-) diff --git a/docs/get_started_cpp.rst b/docs/get_started_cpp.rst index a96eb3e..dc44f72 100644 --- a/docs/get_started_cpp.rst +++ b/docs/get_started_cpp.rst @@ -1,28 +1,82 @@ Getting Started with C++ ======================== -.. todo:: - General information about building and using C++ CLTs. Emphasize - relationship to Python and R wrappers. - -.. note:: - While an R wrapper does exist for the original |openbt| and |openbtmixing| - repositories, that functionality has not yet been included in this new, - combined repository (Issue #XYZ). +These instructions should be followed by users and developers that would like to +work with the C++ command line tools directly. All others should follow the +installation instructions of the wrapper package provided for their desired +programming language. General Installations --------------------- -.. todo:: - Emphasize that these instructions are only for those who want to use the - C++ CLTs directly. All others should follow the installation guides for - their particular language. Dependencies ^^^^^^^^^^^^ .. _Meson: https://mesonbuild.com .. _ninja: https://ninja-build.org +.. _Eigen: https://gitlab.com/libeigen/eigen +.. _homebrew: https://brew.sh + +Before building and installing C++ command line tools, users must provide + +* a compiler suite that includes a C++ compiler that supports the C++14 + standard, +* the Meson_ and its prerequistes such as Python 3 and ninja_, +* an MPI installation that is compatible with the compiler suite, and +* optionally the Eigen_ software package. + +We presently have a single GitHub action that tests the C++ command line tools +with both Open MPI and MPICH installed |via| Ubuntu's Advanced Packaging Tool +(`apt`) and homebrew_ on macOS. In addition, we have successfully tested with +the Intel MPI implementation by experts on clusters and that are available as +modules. + +Note that if installing MPI using a package manager, related developer library +packages such as ``libopenmpi-dev`` or ``libmpich-dev`` might need to be +installed in addition to the base MPI packages such as ``openmpi-bin`` or +``mpich``. + +Meson installation +^^^^^^^^^^^^^^^^^^ +The Meson build system documentation suggests installing Meson |via| package +manager when possible. Please refer to that documentation for detailed and +up-to-date installation information. -Building -^^^^^^^^ +If Meson cannot be installed by package manager or the manager's version is too +old, the following is contrary to Meson suggestions but has been used +successfully to install Meson with Python into a dedicated virtual environment +as well as to install ``meson`` in the ``PATH`` for use without needing to +activate that virtual environment. -Testing -------- +.. code-block:: bash + + $ /path/to/target/python -m venv ~/local/venv/meson + $ . ~/local/venv/meson/bin/activate + $ which python + $ python -m pip install --upgrade pip + $ python -m pip install meson + $ python -m pip list + $ ln -s ~/local/venv/meson/bin/meson ~/local/bin + + $ deactivate + $ which meson + $ meson --version + +Note that this ``meson`` virtual environment is for installing **just** the +Meson build system. + +Building & Testing +^^^^^^^^^^^^^^^^^^ +.. _Issue 7: https://github.com/bandframework/OpenBT/issues/7 + +|openbt|'s Meson build system is setup to automatically detect the compiler +suite and MPI installation to use. If Eigen already exists in the system and +Meson can find it, then Meson will use it for the build. Otherwise, Meson will +automatically obtain a copy of Eigen for internal use. + +Developers and C++ users can directly build and install the command line tools, +an |openbt| library, and library tests with `tools/build_openbt_clt.sh +`__. +Please read the documentation at the top of that script for more information. + +.. note:: + The state and effectiveness of the C++ command line tool test suite is under + investigation (`Issue 7`_). From 03a6131c88ef752e4bcd16047023b2209673c463 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 09:38:33 -0500 Subject: [PATCH 4/7] (Issue #13) Sensible change needed to trigger RTD build in PR. --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 5ed4bd3..3e59de0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,7 @@ ======================= .. _Open MPI: https://www.open-mpi.org .. _MPICH: https://www.mpich.org +.. _framework: https://bandframework.github.io .. todo:: Write high-level description, explain development history, and motivate @@ -26,8 +27,7 @@ that were installed by experts and optimized for their specific platform. repositories, that functionality has not yet been included in this new, combined repository (Issue #XYZ). -This package is being developed as part of |band| `framework -`_. +This package is being developed as part of |band| framework_. .. toctree:: :numbered: From 5def4158ba885b7c8620139f1be265a6878d1953 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 13:26:45 -0500 Subject: [PATCH 5/7] (Issue #13) Cleaning as part of review. --- docs/get_started_cpp.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/get_started_cpp.rst b/docs/get_started_cpp.rst index dc44f72..d77d145 100644 --- a/docs/get_started_cpp.rst +++ b/docs/get_started_cpp.rst @@ -19,15 +19,15 @@ Before building and installing C++ command line tools, users must provide * a compiler suite that includes a C++ compiler that supports the C++14 standard, -* the Meson_ and its prerequistes such as Python 3 and ninja_, +* the Meson_ build system and its prerequisites such as Python 3 and ninja_, * an MPI installation that is compatible with the compiler suite, and * optionally the Eigen_ software package. We presently have a single GitHub action that tests the C++ command line tools with both Open MPI and MPICH installed |via| Ubuntu's Advanced Packaging Tool -(`apt`) and homebrew_ on macOS. In addition, we have successfully tested with -the Intel MPI implementation by experts on clusters and that are available as -modules. +(``apt``) and homebrew_ on macOS. In addition, we have successfully run tests +manually with the Intel MPI implementation as installed by experts on a cluster +and made available as a module. Note that if installing MPI using a package manager, related developer library packages such as ``libopenmpi-dev`` or ``libmpich-dev`` might need to be @@ -73,9 +73,10 @@ Meson can find it, then Meson will use it for the build. Otherwise, Meson will automatically obtain a copy of Eigen for internal use. Developers and C++ users can directly build and install the command line tools, -an |openbt| library, and library tests with `tools/build_openbt_clt.sh +an |openbt| library, and all related headers with `tools/build_openbt_clt.sh `__. -Please read the documentation at the top of that script for more information. +This script also runs the command line tool test suite and prints test results. +Please read the documentation at the top of the script for more information. .. note:: The state and effectiveness of the C++ command line tool test suite is under From db07238af7c25e410f6f94370a8c5fc1fc5627c4 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Thu, 18 Jun 2026 13:39:03 -0500 Subject: [PATCH 6/7] (Issue #13) More cleaning as part of review. --- docs/get_started_cpp.rst | 9 +++------ docs/index.rst | 2 +- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/get_started_cpp.rst b/docs/get_started_cpp.rst index d77d145..4d1e2c8 100644 --- a/docs/get_started_cpp.rst +++ b/docs/get_started_cpp.rst @@ -5,11 +5,8 @@ work with the C++ command line tools directly. All others should follow the installation instructions of the wrapper package provided for their desired programming language. -General Installations ---------------------- - Dependencies -^^^^^^^^^^^^ +------------ .. _Meson: https://mesonbuild.com .. _ninja: https://ninja-build.org .. _Eigen: https://gitlab.com/libeigen/eigen @@ -35,7 +32,7 @@ installed in addition to the base MPI packages such as ``openmpi-bin`` or ``mpich``. Meson installation -^^^^^^^^^^^^^^^^^^ +------------------ The Meson build system documentation suggests installing Meson |via| package manager when possible. Please refer to that documentation for detailed and up-to-date installation information. @@ -64,7 +61,7 @@ Note that this ``meson`` virtual environment is for installing **just** the Meson build system. Building & Testing -^^^^^^^^^^^^^^^^^^ +------------------ .. _Issue 7: https://github.com/bandframework/OpenBT/issues/7 |openbt|'s Meson build system is setup to automatically detect the compiler diff --git a/docs/index.rst b/docs/index.rst index 3e59de0..eae63cc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ The heart of |openbt| is a set of C++ tools that can be used directly |via| the command line or indirectly through the ``openbt`` Python package, which wraps them. Typically these tools are built with an implementation of the Message -Passing Interface (MPI) such as `Open MPI`_ or MPICH_ to enable distributed +Passing Interface (MPI), such as `Open MPI`_ or MPICH_, to enable distributed parallelization of computations. In particular, the Python wrapper package is always built with MPI support. From ba69ff7b1dc3a0127ec4c20a0100b59e762e0111 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Mon, 22 Jun 2026 15:49:21 -0500 Subject: [PATCH 7/7] (Issue #13) Fix typo. --- docs/examples_py.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples_py.rst b/docs/examples_py.rst index 0c480c9..79abf21 100644 --- a/docs/examples_py.rst +++ b/docs/examples_py.rst @@ -3,5 +3,5 @@ Examples .. _BART_BMM_Technometrics: https://github.com/bandframework/OpenBT/blob/main/Examples/BART_BMM_Technometrics.ipynb The examples from :cite:t:`py-BARTMix_Yannotty2024` are reproduced in the -BART_BMM_Technometrics_ Jupyter noteboook, which can be run locally or in a +BART_BMM_Technometrics_ Jupyter notebook, which can be run locally or in a virtual environment such as google colab.