diff --git a/docs/README.md b/docs/README.md index 8a2c4b4..ae3e000 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,30 +23,55 @@ ParallelZone's documentation has two parts: - The Doxygen-generated C++ API documentation The C++ API documentation is built as part of the build process and then moved -to `docs/source/parallelzone_cxx_api`. When the Sphinx front-end documentation is built -it will link to the C++ documentation. If the C++ documentation does not exist, -building the Sphinx front-end will still work, but the link to the C++ API won't -work. +to `docs/source/parallelzone_cxx_api`. When the Sphinx front-end documentation +is built it will link to the C++ documentation. If the C++ documentation does +not exist, building the Sphinx front-end will still work, but the link to the +C++ API won't work. -Building the Sphinx Front-End ------------------------------ +Building the C++ Documentation +------------------------------ -The Sphinx front-end of the documentation requires the following Python packages -(all can be installed with pip): +The C++ documentation is built by Doxygen. You will need to have Doxygen +installed on your system (it is likely available in your operating system's +package manager, *e.g.*, try `apt-get install doxygen`). By default, when you +run CMake on ParallelZone, building documentation is disabled. To enable it, +either pass `BUILD_DOCS=TRUE` to the CMake command, or (preferred) set +`BUILD_DOCS` to true in your toolchain file. Optionally, you may set +`ONLY_BUILD_DOCS` to `TRUE` if you would like to skip building ParallelZone +(useful, for example, if you are iterating on the documentation locally). As +an example: + +```.sh +# In the ParallelZone repository's root +cmake -H. -Bbuild -DBUILD_DOCS=TRUE -DONLY_BUILD_DOCS=TRUE +cmake --build build --target parallelzone_cxx_api +``` -- sphinx_rtd_theme (The Read-The-Docs theme for sphinx) -- sphinx (The thing that makes the documenation) +When you are done building there should be a file `build/html/index.html`, this +is the entry point into the C++ API docs. Unfortunately, Sphinx does not allow +you to link to files which reside in parent directories of the `conf.py` file, +hence the link to the C++ API in the Sphinx documentation can not be made to +point to `build/html/index.html`. It is thus easier to view the C++ API +documentation separately by directing your web browser directly at +`build/html/index.html`. + +Building the Sphinx Front-End +----------------------------- -To build the Sphinx front-end of the documentation it is recommended that you -use Python's virtual environments. Assuming you want to call your virtual -environment `parallelzone_venv` the steps are (run from this directory): +The Sphinx front-end of the documentation requires several Python packages to +be installed (see the `requirements.txt` file). These packages are all available +from PIP. The workflow below shows how to setup a Python virtual environment, +download the dependencies, and build the Sphinx documentation. For the sake +of this tutorial we assume you want to call your virtual +environment `parallelzone_venv`: ```.bash +# In the docs/ directory python3 -m venv parallelzone_venv source parallelzone_venv/bin/activate pip install -r requirements.txt make html ``` -You can then point your webbrowser at `build/html/index.html` to view the +You can then point your webbrowser at `docs/build/html/index.html` to view the documentation. diff --git a/docs/source/abbreviations.rst b/docs/source/background/abbreviations.rst similarity index 88% rename from docs/source/abbreviations.rst rename to docs/source/background/abbreviations.rst index d93bad3..3fea304 100644 --- a/docs/source/abbreviations.rst +++ b/docs/source/background/abbreviations.rst @@ -19,9 +19,10 @@ Abbreviations Used Throughout ParallelZone ########################################## -The following subsections list (in alphabetical order) abbreviations encountered -throughout ParallelZone. Pages are encouraged to link to each abbreviation on -its first use. +The following is a list (in alphabetical order) of abbreviations encountered +throughout ParallelZone. Pages are encouraged to use these abbreviations and +to link to the abbreviation on its first use (instead of defining the +abbreviation). .. _api: diff --git a/docs/source/about.rst b/docs/source/background/about.rst similarity index 72% rename from docs/source/about.rst rename to docs/source/background/about.rst index 9ba16e2..ac05132 100644 --- a/docs/source/about.rst +++ b/docs/source/background/about.rst @@ -24,53 +24,7 @@ The ParallelZone Worldview GPUs, *etc.*) that processes have direct/local access to. To use ParallelZone it is helpful to understand the abstraction model at a high -level. ParallelZone expands on the :ref:`MPI` model. So we start with a brief -review of MPI. - -********** -MPI Primer -********** - -:numref:`fig_mpi_runtime` illustrates a simplified version of how MPI sees a -program. The view is process-centric. When the program starts, MPI defines a -set ``MPI_COMM_WORLD`` which includes all of program's processes. Within our -example ``MPI_COMM_WORLD`` has three processes. MPI assigns these processes an -integer value (ranging from 0 to "the number of processes minus 1") called the -process's rank. More complicated MPI setups can have further partition -``MPI_COMM_WORLD`` into subsets, but the overall point remains: MPI's view of -a program is a series of processes somehow grouped together. - -.. _fig_mpi_runtime: - -.. figure:: assets/mpi.png - :align: center - - Illustration of MPI's runtime abstraction model. - -In a typical MPI-based program parallelism is expressed by somehow mapping tasks -and data to ranks. For example say we have three arbitrary functions ``foo``, -``bar``, and ``baz` and a chunk of data we want to run ``foo``, ``bar``, and -``baz`` on. :numref:`fig_mpi_mappings` shows the three ways we can do this in -parallel. - -.. _fig_mpi_mappings: - -.. figure:: assets/mpi_mappings.png - :align: center - - Possible ways of mapping data and tasks to MPI ranks. - -In the :ref:`simd` approach depicted at the top of :numref:`fig_mpi_mappings` we -distribute the data over the MPI ranks and have each rank pass its local chunk -of data to the three functions. In :ref:`misd`, which is shown in the middle of -:numref:`fig_mpi_mappings` we instead distribute the functions over the ranks. -Finally, in the :ref:`mimd` model shown at the bottom of -:numref:`fig_mpi_mappings` we distribute both the data and the functions. - -Unfortunately on today's machines it takes more than distributing tasks and/or -data to otherwise opaque ranks to achieve high-performance. This is because -the performance also depends on the hardware available to each rank and how -well utilized that hardware is. +level. ********************* Focusing on Resources diff --git a/docs/source/assets/hardware2mpi.png b/docs/source/background/assets/hardware2mpi.png similarity index 100% rename from docs/source/assets/hardware2mpi.png rename to docs/source/background/assets/hardware2mpi.png diff --git a/docs/source/assets/mpi.png b/docs/source/background/assets/mpi.png similarity index 100% rename from docs/source/assets/mpi.png rename to docs/source/background/assets/mpi.png diff --git a/docs/source/assets/mpi_mappings.png b/docs/source/background/assets/mpi_mappings.png similarity index 100% rename from docs/source/assets/mpi_mappings.png rename to docs/source/background/assets/mpi_mappings.png diff --git a/docs/source/assets/nesting_runtime_views.png b/docs/source/background/assets/nesting_runtime_views.png similarity index 100% rename from docs/source/assets/nesting_runtime_views.png rename to docs/source/background/assets/nesting_runtime_views.png diff --git a/docs/source/assets/resourceset_mapping.png b/docs/source/background/assets/resourceset_mapping.png similarity index 100% rename from docs/source/assets/resourceset_mapping.png rename to docs/source/background/assets/resourceset_mapping.png diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst new file mode 100644 index 0000000..f2e118d --- /dev/null +++ b/docs/source/background/index.rst @@ -0,0 +1,29 @@ +.. Copyright 2023 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +####################### +ParallelZone Background +####################### + +The topics in this section are intended to provide the interested reader with an +overview of the concepts underlying ParallelZone and the history leading up to +the development of ParallelZone. Readers wanting to know how to use ParalellZone +should skip ahead to :ref:`installing_parallelzone`. + +.. toctree:: + :maxdepth: 1 + + abbreviations + mpi_primer + about diff --git a/docs/source/background/mpi_primer.rst b/docs/source/background/mpi_primer.rst new file mode 100644 index 0000000..aef63ac --- /dev/null +++ b/docs/source/background/mpi_primer.rst @@ -0,0 +1,59 @@ +.. Copyright 2023 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +########## +MPI Primer +########## + +:numref:`fig_mpi_runtime` illustrates a simplified version of how :ref:`mpi` +sees a program. The view is process-centric. When the program starts, MPI +defines a +set ``MPI_COMM_WORLD`` which includes all of program's processes. Within our +example ``MPI_COMM_WORLD`` has three processes. MPI assigns these processes an +integer value (ranging from 0 to "the number of processes minus 1") called the +process's rank. More complicated MPI setups can have further partition +``MPI_COMM_WORLD`` into subsets, but the overall point remains: MPI's view of +a program is a series of processes somehow grouped together. + +.. _fig_mpi_runtime: + +.. figure:: assets/mpi.png + :align: center + + Illustration of MPI's runtime abstraction model. + +In a typical MPI-based program parallelism is expressed by somehow mapping tasks +and data to ranks. For example say we have three arbitrary functions ``foo``, +``bar``, and ``baz` and a chunk of data we want to run ``foo``, ``bar``, and +``baz`` on. :numref:`fig_mpi_mappings` shows the three ways we can do this in +parallel. + +.. _fig_mpi_mappings: + +.. figure:: assets/mpi_mappings.png + :align: center + + Possible ways of mapping data and tasks to MPI ranks. + +In the :ref:`simd` approach depicted at the top of :numref:`fig_mpi_mappings` we +distribute the data over the MPI ranks and have each rank pass its local chunk +of data to the three functions. In :ref:`misd`, which is shown in the middle of +:numref:`fig_mpi_mappings` we instead distribute the functions over the ranks. +Finally, in the :ref:`mimd` model shown at the bottom of +:numref:`fig_mpi_mappings` we distribute both the data and the functions. + +Unfortunately on today's machines it takes more than distributing tasks and/or +data to otherwise opaque ranks to achieve high-performance. This is because +the performance also depends on the hardware available to each rank and how +well utilized that hardware is. diff --git a/docs/source/developer/design/ram.rst b/docs/source/developer/design/ram.rst index aec74b6..304c0c0 100644 --- a/docs/source/developer/design/ram.rst +++ b/docs/source/developer/design/ram.rst @@ -132,7 +132,7 @@ Examples of one-to-one communications } // Sends the data to rank 1, type U determined by template meta-programming - std::optional output = rt.at(1).ram().send(data); + std::optional output = rt.at(1).ram().send(data, "some tag"); if(output.has_value()){ // This part is only run by rank 1 diff --git a/docs/source/developer/design/runtime_view.rst b/docs/source/developer/design/runtime_view.rst index abd124a..e4d52be 100644 --- a/docs/source/developer/design/runtime_view.rst +++ b/docs/source/developer/design/runtime_view.rst @@ -101,7 +101,20 @@ Examples of all-to-all communications auto data = generate_data(); // This is an all gather - auto output = rt.gather(data); + auto output = rt.gather(data); // This is an all reduce - auto output2 = rt.reduce(data, op); + auto output2 = rt.reduce(data, op); + +.. note:: + + As written the APIs assume the data is going to/from RAM. If we eventually + want to support other memory spaces we could create overloads which take the + target space. In particular we note that we can NOT do things like: + + .. code-block:: c++ + + auto output = rt.my_resource_set().ram().gather(data); + + because that would result in deadlock (it calls a series of all-to-one calls + where each rank thinks it's the root). diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst index 91d246e..e78f3a0 100644 --- a/docs/source/developer/index.rst +++ b/docs/source/developer/index.rst @@ -18,13 +18,13 @@ Developer Documentation The documentation in this section is intended primarily for people who are interested in developing for, or understanding the internals of ParallelZone. -As part of the NWChemEx organization, developers may also find the -`NWChemEx Developer Documentation -`__` to be useful. +The documentation in this section is specific to the design and development of +ParallelZone. Since ParallelZone is developed by the NWChemEx organization, +developers may also find the more general `NWChemEx Developer Documentation +`__ to be useful. .. toctree:: :maxdepth: 2 :caption: Contents: - repo_layout design/index diff --git a/docs/source/developer/repo_layout.rst b/docs/source/developer/repo_layout.rst deleted file mode 100644 index edcfea9..0000000 --- a/docs/source/developer/repo_layout.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. Copyright 2022 NWChemEx-Project -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. - -############################## -ParallelZone Repository Layout -############################## - -This page is meant to bring developers up to speed on what the various -directories and files are supposed to be used for. - -********************* -Top-Level Directories -********************* - -In alphabetical order the top-level directories in this repo are: - -- ``.github/``. Workflows and assets needed for continuous integration using - GitHub actions. -- ``cmake/``. CMake modules needed by the build system. -- ``docs/``. Contains source files and infrastructure for building - ParallelZone's documentation. -- ``include/``. C++ header files exposing the public :ref:`api` of ParallelZone. -- ``src/``. C++ source files implementing the functionality exposed in the - header files. -- ``tests/``. Source files and testing apparatuses for testing ParallelZone. - -*************** -Top-Level Files -*************** - -- ``.clang-format``. Settings used by the ``clang-format`` command to format - the C++ files. -- ``.gitignore``. Tells ``git`` command which files and directories are not - under version control. -- ``CMakeLists.txt``. Tells ``cmake`` command how to build ParallelZone. -- ``LICENSE``. The legal terms governing the use of ParallelZone. -- ``README.md``. The introduction/splash page people see when they go to the - GitHub repo. - - -************************ -docs/ Directory Contents -************************ - -- ``source/``. Contains the source files for the documentation. The internal - layout reflects the intended layout of the documentation. -- ``Makefile``. Tells the ``make`` command how to build the documentation. -- ``README.md``. Instructions for building the documentation. -- ``requirements.txt``. Python dependencies needed to build the documentation. - -************************* -tests/ Directory Contents -************************* - -The tests are partitioned based on the types of tests. - -- ``cxx``. Contain tests written in C++. -- ``cxx/unit_tests/``. Unit tests for the classes and functions written in C++. -- ``cxx/doc_snippets/``. The C++ code snippets used throughout the documentation. - The snippets are literal included in the documentation and the testing - mechanism ensures they stay up to date with code modifications. -- ``py``. Contains tests written in Python. -- ``py/unit_tests/``. Unit tests of the auto-generated Python APIs. diff --git a/docs/source/index.rst b/docs/source/index.rst index ec3e545..eaef7ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,10 +44,9 @@ Planned features: :maxdepth: 1 :caption: Contents: + background/index install - abbreviations quickstart - about user/index developer/index diff --git a/docs/source/install.rst b/docs/source/install.rst index baeb276..e890577 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -12,6 +12,8 @@ .. See the License for the specific language governing permissions and .. limitations under the License. +.. _installing_parallelzone: + ####################### Installing ParallelZone ####################### @@ -26,7 +28,7 @@ its build system, more detailed build instructions can be found ``cmake`` command. Typically CMake toolchains live in files named ``-toolchain.cmake``, where ``-`` is an optional prefix to distinguish among toolchains. The contents of the CMake toolchain file - usually just sets configuration values via a the standard CMake ``set`` + usually just sets configuration values set via the standard CMake ``set`` function, *i.e.*, ``set( )``. @@ -46,24 +48,43 @@ In many cases ParallelZone can be installed by: git clone https://github.com/NWChemEx-Project/ParallelZone cd ParallelZone - cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE= - cmake --build build + cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE= \ + -DCMAKE_INSTALL_PREFIX= cmake --build build --target install Where ```` should be replaced by the path to your -toolchain file (absolute path is recommended). +toolchain file, and ```` should be replaced +with where you want to put the installed library (absolute path is recommended +in both cases). -.. todo:: +.. note:: + + The above command will build serially. To build ParallelZone with ``N`` + processors additionally pass ``--parallel `` to the last command in the + above code block, *i.e.*, - Can this be simplified by dropping the ``cmake --build build`` command? + .. code-block:: console + + cmake --build build --parallel --target install ********************* Configuration Options ********************* -- ``BUILD_TESTING``. Off by default. Set to a truth-y value to enable testing. -- ``BUILD_PYBINDINGS``. On by default. When enabled the optional Python API is - built. +This is a list of configuration options recognized by ParallelZone's build +system. + +``BUILD_TESTING``. + Off by default. Set to a truth-y value to enable testing. +``BUILD_DOCS``. + Off by default. Set to a truth-y value to build the C++ API documentation. +``ONLY_BUILD_DOCS``. + Off by default. If ``BUILD_DOCS`` is set to a truth-y value and + ``ONLY_BUILD_DOCS`` is also set to a truth-y value, then the configure + process will skip all other aspects of the configuration aside from creating + the ``parallelzone_cxx_api`` target. +``BUILD_PYBINDINGS``. + On by default. When enabled the optional Python API is built. ************************* @@ -148,3 +169,18 @@ URL: ``__ Used to simplify writing a CMake-based build system. The build system will grab it for you. + +Doxygen +------- + +URL: ``__ + +Used to generate the C++ API documentation. Only needed if ``BUILD_DOCS`` is +set to a truth-y value. + +spdlog +------ + +URL: ``__ + +The guts of the logging system provided by ParallelZone.