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..79abf21 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 notebook, which can be run locally or in a +virtual environment such as google colab. diff --git a/docs/get_started_cpp.rst b/docs/get_started_cpp.rst index a96eb3e..4d1e2c8 100644 --- a/docs/get_started_cpp.rst +++ b/docs/get_started_cpp.rst @@ -1,28 +1,80 @@ 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). - -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. +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. 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_ 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 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 +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 all related headers with `tools/build_openbt_clt.sh +`__. +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 + investigation (`Issue 7`_). diff --git a/docs/index.rst b/docs/index.rst index a270b4c..805e61c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,33 @@ |openbt| Python package ======================= +.. _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 breakdown of documents presented here. License, copyright, responsibilities of user, etc. -This package is being developed as part of |band| `framework -`_. +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_. .. toctree:: :numbered: 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} +}