Synchronize feature branch

docs/bibliography_cpp.rst

@@ -10,3 +10,4 @@ Bibliography
 
 .. bibliography:: references.bib
     :style: plain
+    :keyprefix: cpp-

docs/bibliography_py.rst

@@ -10,3 +10,4 @@ Bibliography
 
 .. bibliography:: references.bib
     :style: plain
+    :keyprefix: py-

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.

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
+    <add ~/local/bin to PATH if desired and appropriate>
+    $ 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
+<https://github.com/bandframework/OpenBT/blob/main/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`_).

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
-<https://bandframework.github.io/>`_.
+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:

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}
+}