diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml index db54bfbd..fe661393 100644 --- a/.github/workflows/pull_request.yaml +++ b/.github/workflows/pull_request.yaml @@ -23,8 +23,3 @@ on: jobs: check_formatting: uses: ./.github/workflows/check_formatting.yaml - - test_nwx_docs: - uses: ./.github/workflows/test_nwx_docs.yaml - with: - doc_target: "Sphinx" diff --git a/.gitignore b/.gitignore index f16fb6d1..1b33a377 100644 --- a/.gitignore +++ b/.gitignore @@ -15,10 +15,17 @@ # This is where VSCode stores its settings .vscode +# This is Claude/Cursor directory +.claude +.cursor + #This is a common Python3 virtual environment name +.venv/ venv/ # This is the default build directory for the docs docs/build + +# Mac Files .DS_Store diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 3917a44e..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = DeveloperTools -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f58b4627..00000000 --- a/docs/README.md +++ /dev/null @@ -1,45 +0,0 @@ - - -Source Files for Developer Documentation -======================================== - -This directory contains the source files for NWChemEx's developer documentation. - -Building the Documentation --------------------------- - -The developer documentation has several dependencies which can be installed via -`pip` - -~~~.sh -#These first two steps are recommended, but not required -python3 -m venv venv -. venv/bin/activate -pip3 install -r requirements.txt -~~~ - -With the dependencies installed the documentation is built by running (in the -same directory as this README): - -~~~.sh -make html -~~~ - -This will result in HTML documentation, the main index of which will be -located at `/build/html/index.html` and can be -viewed by directing your web browser of choice to that file (this is done by -using `file:///path/to/index.html` as the URL). diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 2110383a..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -docutils<=0.16 -sphinx -sphinx_rtd_theme -sphinx_tabs -sphinxcontrib.bibtex diff --git a/docs/source/BuildValidation.md b/docs/source/BuildValidation.md deleted file mode 100644 index 9799773f..00000000 --- a/docs/source/BuildValidation.md +++ /dev/null @@ -1,75 +0,0 @@ - - -NWChemEx Build Validation Policy -================================ - -It is impractical to test all functionality in NWChemEX on every permutation -of software/hardware platforms for every pull request. We should identify a -core test set which executes on every pull request in order to catch -low-hanging bugs, and a more comprehensive extended test set to run before -releases. - -- Core test set - - Adequatly cover core functionality such as Hartree-Fock, DFT, MP2, CC for - a small range of molecules/basis sets. - - Hard execution time limit for the complete set (1 hour?). - - While the core test set might not explicitly test the features contributed - in the pull request, the core test set is executed in addition to the new - tests included with the pull request. - -- Extended test set - - Run before each public release, or periodically. - - A hard execution time limit makes less sense here. - - In addition to covering more of the NWChemEx code, - -- NWChemEx should be validated for most or all of the hardware/softare environments - in use at major supercomputing centers. Covering all permutations is impractical, - but the most important combinations should be identified and updated as platforms are - introduced or retired. - - Hardware: - - Intel Xeon CPU - - AMD CPU - - IBM PowerX CPU - - Intel Xeon Phi - - Nvidia GPU - - Software: - - Compilers - - Intel - - GCC - - PGI - - clang - - Math Libraries - - MKL - - ATLAS - - OpenBLAS - - MPI - - MVAPICH - - IMPI - - OpenMPI - - Other Software - - Linux kernel (from experience, this is important) - - Current Ubuntu and Redhat LTS? - - Just cover kernels used on target supercomputers? - - Different versions of CUDA, OpenCL, OpenACC, etc. - - -- Continuous integration software - - TravisCI is convenient for the core test set triggered on each PR. It does - not offer an adequate hardware/software environment to validate code for - the full range of use cases. - - What are some alternative CI frameworks which offer more control over these - parameters? diff --git a/docs/source/TestRequirements.md b/docs/source/TestRequirements.md deleted file mode 100644 index c36c5ebb..00000000 --- a/docs/source/TestRequirements.md +++ /dev/null @@ -1,50 +0,0 @@ - - -Testing Requirements for New Pull Requests -========================================== - -The usefulness of automated testing is dictated by the code coverage spanned -by the test set. Developers are required to provide tests which adequately evaluate -the functionality of their newly contributed code. - -There are outstanding questions regarding the test requirements: -- Maintaining code coverage - - Require a minimum percentage for the lines of code spanned by the tests? - - We can evaluate this automatically with things like gcov, Codecov. - - Put the burden on NWX code reviewers to ensure that the major functionality - of the new code is covered by the tests? - - More work, and more arbitrary. - - Tests from approved pull requests should be added to either the [core or - extended test sets](BuildValidation.md), as determined by the code reviewers. -- What do tests look like? - - Unit tests - - Very useful, but they don't test interoperability with other software - components. For example, a unit test for some Rys Quadrature code doesn't test - whether those AO integrals can be used successfully in a subsequent coupled - cluster job. - - While guidelines and requirements for unit testing are not yet outlined, - [Catch](https://github.com/philsquared/Catch) has been chosen as the automated - test framework for NWX. - - NWX input files - - Tests module interoperability, but tests overlap unnecessarily over core - routines. - - Care must be taken to minimize the execution time while maintaining - code coverage. - - Developers are responsible for submitting tests with their pull requests - which test functionality without unnecessarily long execution time. For - example, a molecular dynamics equilibration run with thousands of timesteps - is a poor test for a canonical Hartree-Fock gradient code. diff --git a/docs/source/bibliography/bibliography.rst b/docs/source/bibliography/bibliography.rst deleted file mode 100644 index 2c845456..00000000 --- a/docs/source/bibliography/bibliography.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. 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. - -########## -References -########## - -.. bibliography:: diff --git a/docs/source/bibliography/software.bib b/docs/source/bibliography/software.bib deleted file mode 100644 index 10491eb4..00000000 --- a/docs/source/bibliography/software.bib +++ /dev/null @@ -1,32 +0,0 @@ -% ------------------------------------------------------------------------------ -% -- Python Binding Libraries -------------------------------------------------- -% ------------------------------------------------------------------------------ - -@inproceedings{cppyy16, - author = {Lavrijsen, Wim T. L. P. and Dutta, Aditi}, - title = {High-Performance Python-{C}++ Bindings with {PyPy} and {Cling}}, - year = {2016}, - isbn = {9781509052202}, - publisher = {IEEE Press}, - booktitle = { - Proceedings of the 6th Workshop on Python for High-Performance and - Scientific Computing - }, - pages = {27--35}, - numpages = {9}, - location = {Salt Lake City, Utah}, - series = {PyHPC '16} -} -@misc{pybind11, - author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan}, - year = {2017}, - note = {https://github.com/pybind/pybind11}, - title = {pybind11 -- Seamless operability between C++11 and Python} -} - -@misc{nanobind, - author = {Wenzel Jakob}, - year = {2022}, - note = {https://github.com/wjakob/nanobind}, - title = {nanobind: tiny and efficient C++/Python bindings} -} diff --git a/docs/source/coding/cxx/cxx_development_workflow.rst b/docs/source/coding/cxx/cxx_development_workflow.rst deleted file mode 100644 index 7148126b..00000000 --- a/docs/source/coding/cxx/cxx_development_workflow.rst +++ /dev/null @@ -1,299 +0,0 @@ -.. Copyright 2025 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. - -************************ -C++ Development Workflow -************************ - -This page assumes you have already read -:ref:`development_preliminaries` and that you are adding a module to a repo -which is considered part of NWChemEx - -.. todo:: - - Link to documentation detailing what is/isn't part of NWX - -If you are developing a plugin for NWChemEx you should follow the documentation -at xxx. - -.. todo:: - - Write plugin documentation and link to it - -Adding new features to NWChemEx is accomplished by adding new modules. NWChemEx -relies on a plugin-based architecture and module development follows a -more-or-less traditional plugin development cycle. This means you write your -module's source code largely decoupled from the rest of NWChemEx. When you need -to get a quantity that your module does not know how to compute (and is not an -input) you call out to a submodule. You do not have to write the submodule you -call (unless it's not available in any other repo). Providing your module with -the submodule will happen at runtime. - -Module development looks a little different depending on whether your module -needs to call a submodule or not. The former is the easier scenario - -Developing a Module without Submodules -====================================== - -This can be done largely as you would expect. You add your source code to the -repo, add a unit test for your module's source code, and then make sure the unit -test works. - -.. todo:: - - Make this into a true tutorial. - - -Developing a Module with Submodule(s) -===================================== - -Development gets a bit more hairy when your module depends on a submodule (and -those submodules are not part of the current repo). For concreteness let's -assume we are writing a module called ``JCanonical`` which does a naive -canonical J build. The source file for such a module will live in the SCF repo -and will have the path ``nwx_workspace/SCF/src/scf/j_canonical.cpp``. The -contents of this source file could be something like: - -.. code-block:: c++ - - #include "scf/property_types.hpp" // List of property types used in SCF repo - #include "scf/scf_modules.hpp" // Declarations of SCF modules, including ours - #include "scf/types.hpp" // types of objects used in SCF repo - - namespace scf { - - - MODULE_CTOR(JCanonical) { - // Our module knows how to compute J - using j_prop_type = pt::coulomb>; - satisfies_property_type(); - - add_submodule>("ERI Builder") - .set_description("Computes 4C ERI integrals"); - } - - MODULE_RUN(JCanonical) { - using j_prop_type = pt::coulomb>; - auto [mol, MOs, bra, ket] = j_prop_type::unwrap_inputs(inputs); - - auto& eri_mod = submods.at("ERI Builder"); - auto [ERI4] = eri_mod.run_as>(bra, bra, ket, ket); - - type::tensor J; - type::tensor rho; - const auto& C = MOs.C(); - rho("mu,nu") = C("mu,i") * C("nu,i"); - J("mu, nu") = rho("lambda, sigma") * ERI4("lambda, sigma, mu, nu"); - - auto rv = results(); - return j_prop_type::wrap_results(rv, J); - } - - } // namespace scf - -Of importance for our current purposes is the fact that this module depends on a -submodule (for computing the four-center, electron-repulsion integrals) which is -not part of the SCF repo. Aside from that, there's nothing too remarkable about -the implementation of this module. - -To finish off the implementation we also need to make sure ``JCanonical`` is -declared in ``nwx_workspace/SCF/src/scf/scf_modules.hpp`` and -we need to make sure our new module is added to the module manager in -``nwx_workspace/SCF/src/scf/scf_mm.cpp``. The former amounts to adding: - -.. code-block:: c++ - - DECLARE_MODULE(JCanonical); - -to ``nwx_workspace/SCF/include/scf/scf_modules.hpp`` and the latter requires -adding: - -.. code-block:: c++ - - mm.add_module("A key users will use to request your module"); - -to ``nwx_workspace/SCF/src/scf/scf_mm.cpp``. - -Running the Module ------------------- - -Now that we wrote the module we need to test/run it. Since our module needs -integrals, and integrals are not provided by the SCF repo, we can't simply add a -unit test to ``nwx_workspace/SCF/tests`` which calls our module (we'll get to -how to unit test the module, in the SCF repo, later) because our module won't -have integrals. How to proceed depends on whether you are ok with using a Python -script to run the calculation or if you insist on the entire development -(including running the calculation) occurring in C++ (the former is preferred -and the latter will likely be deprecated at some point). - -Running the module from Python -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In theory you write a Python script which looks like: - -.. code-block:: python - - import nwchemex as nwx - - mm = nwx.sde.ModuleManager() - nwx.load_modules(mm) - - #We need to tell our module which ERIs to use - key = "whatever key you used in SCF for your module" - eri_key = "ERI4" # or whatever 4-center ERIs you want to use - mm.change_submod(key, "ERI Builder", eri_key); - - # Make the input for our module - mol = nwx.libchemist.Molecule() # Make a Molecule - aos = nwx.libchemist.apply_basis(mol, "sto-3g") - mos = nwx.libchemist.DerivedSpaceD # get MOs from somewhere - - # Call our module and bask in the result - mod = mm.at("the key you put your module under") - derived_space_type = nwx.scf.type.derived_space_t[double] - j_prop_type = nwx.scf.pt.coulomb[double, derived_space_type] - J = mod.run_as[j_prop_type](mol, mos, aos, aos) - print(J) - -Assuming ``nwx.load_modules()`` is written in Python, you then would simply need -to recompile ``nwx_workspace/SCF`` and run the above Python script. Python would -take care of all of the dynamic linking etc. - -.. todo:: - - Finish/write this section when NWX's Python bindings allow this workflow. - - -Running the module from C++ -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To run our module from C++ the eaiest way is to add a validation test to the -NWChemEx repo, say ``nwx_workspace/NWChemEx/tests/j_canonical.cpp``. The -contents of this validation test look something like: - -.. code-block:: c++ - - #include - #include - #include - #include - - using namespace scf; - using j_prop_type = pt::coulomb>; - - TEST_CASE("Canonical J"){ - sde::ModuleManager mm; - nwx::load_modules(mm); - - // We need to tell our module which ERIs to use - const auto key = "whatever key you used in SCF for your module"; - const auto eri_key = "ERI4"; // or whatever 4-center ERIs you want - mm.change_submod(key, "ERI Builder", eri_key); - - // Make the input for our module - auto mol = ;// Make a Molecule - auto aos = libchemist::apply_basis(mol, "sto-3g"); - auto mos = ;// get MOs from somewhere - - // Call our module and bask in the result - auto mod = mm.at("the key you put your module under"); - auto [J] = mod.run_as(mol, mos, aos, aos); - std::cout << J << std::endl; - } - -With this validation test written, we then compile ``nwx_workspace/NWChemEx``, -and run the tests in ``nwx_workspace/NWChemEx``. *N.B.*, we are not compiling -the SCF repo; if the toolchain file is setup correctly building -``nwx_workspace/NWChemEx`` will use our local, modified, copy of SCF. - -.. note:: - - After development is complete you should add the ``mm.change_submod`` line - to the ``NWChemEx/src/nwchemex/load_modules.cpp`` file. So that the module is - ready to be used outside of just the validation test. - -Unit Testing the Module ------------------------ - -It's sometimes easier to get a module working using "real" data, which is what -the previous section focused on. That said the unit test for our module should -live in the SCF repo and not be coupled to the module used to get the integrals, -*i.e.*, if the integrals module breaks/changes we don't want it break our -module's unit test too. To avoid this coupling in our module's unit test we use -a lambda module, which wraps some hard-coded data. - -To start with we create a source file ``nwx_workspace/SCF/tests/jcanonical.cpp`` -with the contents: - -.. code-block:: c++ - - #include - #include - #include - #include - #include - - using namespace scf; - using j_prop_type = pt::coulomb>; - using eri_prop_type = pt::eri4c; - - TEST_CASE("Canonical J"){ - sde::ModuleManager mm; - scf::load_modules(mm); - - // Make the input for our module - auto mol = ;// Make a Molecule - auto aos = libchemist::apply_basis(mol, "sto-3g"); - auto mos = ;// get MOs from somewhere - - // Make the lambda module which will serve as the submodule - type::tensor eris; // hard-coded ERIS, in practice need state - auto l = [=](auto& bra1, auto& bra2, auto& ket1, auto& ket2) { - // Make sure our module passes the right info to the submodule - REQUIRE(bra1 == aos); - REQUIRE(bra2 == aos); - REQUIRE(ket1 == aos); - REQUIRE(ket2 == aos); - - // It did so return the hard coded result - return eris; - }; - auto submod = sde::make_lambda(l); - - - // Tell our module to use the lambda module - const auto key = "whatever key you used in SCF for your module"; - auto& mod = mm.at(key); - mod.change_submod("ERI Builder", submod); - - // Call our module and compare J to the correct value - auto [J] = mod.run_as(mol, mos, aos, aos); - std::cout << J << std::endl; - } - -We now build ``nwx_workspace/SCF`` and run its tests to ensure our module works -correctly. In particular note that this test is self-contained in that it should -only fail if the implementation of our module changes (ignoring infrastructure -breaks). - -Neding hard-coded data for unit tests is very common which is why we made the -``NWChemEx/testing`` repo -(https://github.com/NWChemEx/testing). You are encouraged to use that -data when it makes sense. - -.. note:: - - For developers who prefer test-based development it's entirely possible to - start with these unit tests and then to proceed to the validation tests with - real integrals modules. diff --git a/docs/source/coding/cxx/index.rst b/docs/source/coding/cxx/index.rst deleted file mode 100644 index e753a63c..00000000 --- a/docs/source/coding/cxx/index.rst +++ /dev/null @@ -1,24 +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. - -.. _coding_cxx: - -####################### -Developing C++ Software -####################### - -.. toctree:: - :maxdepth: 1 - - cxx_development_workflow diff --git a/docs/source/coding/ides/index.rst b/docs/source/coding/ides/index.rst deleted file mode 100644 index b73fc1d8..00000000 --- a/docs/source/coding/ides/index.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Copyright 2025 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. - -.. _nwx-ide-development: - -######################### -Using IDEs to Develop NWX -######################### - -While you can develop code for NWChemEx purely from the terminal you'll probably -be more productive if you use an integrated development environment (IDE). IDEs -are intimidating at first, but once you get them setup, and log some hours, -you'll never go back to command line development again. Advantages of using an -IDE include (this is a union of features from across IDEs; most IDEs support -most of the features on this list, but they may not support all of them): - -- Built-in debugging - - - Click to add break points - - Easily inspect variable values - -- Code inspection - - - Shows you errors/warnings without you having to compile - - Can suggest best practices - -- Code autocomplete - - - Auto inserts closing braces, brackets, etc. - - Knows about classes, variables, etc. so you only need to type the first few - letters - -- Automatic formatting - - - No more forgetting to run ``clang-format``!!!! - -- Typically a single click to build/debug -- Built in version control -- Syntax highlighting - - - Makes reading code much easier - -- Code folding - - - Allows you to hide irrelevant parts of the code - - -The following sections focus on how to set-up various IDEs for developing NWX. -All of these tutorials assume that you have a directory set-up akin to that -suggested in the :ref:`development_preliminaries` section. - -.. toctree:: - :maxdepth: 2 - :caption: Contents - - vscode/index diff --git a/docs/source/coding/ides/vscode/assets/add_folder_to_workspace.png b/docs/source/coding/ides/vscode/assets/add_folder_to_workspace.png deleted file mode 100644 index 1fbe684a..00000000 Binary files a/docs/source/coding/ides/vscode/assets/add_folder_to_workspace.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/click_explorer.png b/docs/source/coding/ides/vscode/assets/click_explorer.png deleted file mode 100644 index 7d7c5129..00000000 Binary files a/docs/source/coding/ides/vscode/assets/click_explorer.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/click_explorer.svg b/docs/source/coding/ides/vscode/assets/click_explorer.svg deleted file mode 100644 index ab7d0a4c..00000000 --- a/docs/source/coding/ides/vscode/assets/click_explorer.svg +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - diff --git a/docs/source/coding/ides/vscode/assets/click_extensions.svg b/docs/source/coding/ides/vscode/assets/click_extensions.svg deleted file mode 100644 index 6d004f79..00000000 --- a/docs/source/coding/ides/vscode/assets/click_extensions.svg +++ /dev/null @@ -1,1966 +0,0 @@ - - - - - - - - - - - - - - diff --git a/docs/source/coding/ides/vscode/assets/docker/blue_button.png b/docs/source/coding/ides/vscode/assets/docker/blue_button.png deleted file mode 100644 index cccc367f..00000000 Binary files a/docs/source/coding/ides/vscode/assets/docker/blue_button.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/docker/in_container.png b/docs/source/coding/ides/vscode/assets/docker/in_container.png deleted file mode 100644 index 12367f14..00000000 Binary files a/docs/source/coding/ides/vscode/assets/docker/in_container.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/docker/install_dev_containers.png b/docs/source/coding/ides/vscode/assets/docker/install_dev_containers.png deleted file mode 100644 index d9b9ee17..00000000 Binary files a/docs/source/coding/ides/vscode/assets/docker/install_dev_containers.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/docker/select_options.png b/docs/source/coding/ides/vscode/assets/docker/select_options.png deleted file mode 100644 index 0f5b288d..00000000 Binary files a/docs/source/coding/ides/vscode/assets/docker/select_options.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/explorer_open.png b/docs/source/coding/ides/vscode/assets/explorer_open.png deleted file mode 100644 index f4fa5d7b..00000000 Binary files a/docs/source/coding/ides/vscode/assets/explorer_open.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/add_to_workspace.png b/docs/source/coding/ides/vscode/assets/mac_setup/add_to_workspace.png deleted file mode 100644 index 5561e99a..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/add_to_workspace.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/add_toolchain_to_kit.png b/docs/source/coding/ides/vscode/assets/mac_setup/add_toolchain_to_kit.png deleted file mode 100644 index 9c2133d7..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/add_toolchain_to_kit.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/allow_github.png b/docs/source/coding/ides/vscode/assets/mac_setup/allow_github.png deleted file mode 100644 index bef8bc52..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/allow_github.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/bad_cmake_executable.png b/docs/source/coding/ides/vscode/assets/mac_setup/bad_cmake_executable.png deleted file mode 100644 index b2858f4f..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/bad_cmake_executable.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/choose_apps.png b/docs/source/coding/ides/vscode/assets/mac_setup/choose_apps.png deleted file mode 100644 index 17981de7..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/choose_apps.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/click_build.png b/docs/source/coding/ides/vscode/assets/mac_setup/click_build.png deleted file mode 100644 index 3b2deba9..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/click_build.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/click_commit.png b/docs/source/coding/ides/vscode/assets/mac_setup/click_commit.png deleted file mode 100644 index a1338551..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/click_commit.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/click_no_active_kit.png b/docs/source/coding/ides/vscode/assets/mac_setup/click_no_active_kit.png deleted file mode 100644 index 3ca26469..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/click_no_active_kit.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/click_synch.png b/docs/source/coding/ides/vscode/assets/mac_setup/click_synch.png deleted file mode 100644 index 3c73ecce..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/click_synch.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/clone_from_github.png b/docs/source/coding/ides/vscode/assets/mac_setup/clone_from_github.png deleted file mode 100644 index d5735385..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/clone_from_github.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/clone_repo.png b/docs/source/coding/ides/vscode/assets/mac_setup/clone_repo.png deleted file mode 100644 index a0b5c6c0..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/clone_repo.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/commit_message.png b/docs/source/coding/ides/vscode/assets/mac_setup/commit_message.png deleted file mode 100644 index f02d0439..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/commit_message.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/cryptic_error.png b/docs/source/coding/ides/vscode/assets/mac_setup/cryptic_error.png deleted file mode 100644 index 9f6ba8b9..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/cryptic_error.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/cxx_extension.png b/docs/source/coding/ides/vscode/assets/mac_setup/cxx_extension.png deleted file mode 100644 index eb5ddee1..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/cxx_extension.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/edit_kit.png b/docs/source/coding/ides/vscode/assets/mac_setup/edit_kit.png deleted file mode 100644 index 96d50d29..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/edit_kit.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/error_git_name_not_set.png b/docs/source/coding/ides/vscode/assets/mac_setup/error_git_name_not_set.png deleted file mode 100644 index 0603548c..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/error_git_name_not_set.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/install_command_line_tools.png b/docs/source/coding/ides/vscode/assets/mac_setup/install_command_line_tools.png deleted file mode 100644 index b33f0f18..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/install_command_line_tools.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/missing_python_headers.png b/docs/source/coding/ides/vscode/assets/mac_setup/missing_python_headers.png deleted file mode 100644 index bbea7487..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/missing_python_headers.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/nwx_module_dir_not_set.png b/docs/source/coding/ides/vscode/assets/mac_setup/nwx_module_dir_not_set.png deleted file mode 100644 index 9da265be..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/nwx_module_dir_not_set.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/open_cloned_repo.png b/docs/source/coding/ides/vscode/assets/mac_setup/open_cloned_repo.png deleted file mode 100644 index 12350f23..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/open_cloned_repo.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/pick_theme.png b/docs/source/coding/ides/vscode/assets/mac_setup/pick_theme.png deleted file mode 100644 index a4d4c8f9..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/pick_theme.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/python_extension.png b/docs/source/coding/ides/vscode/assets/mac_setup/python_extension.png deleted file mode 100644 index 10c534b4..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/python_extension.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/run_configure.png b/docs/source/coding/ides/vscode/assets/mac_setup/run_configure.png deleted file mode 100644 index b5172709..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/run_configure.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/run_ctest.png b/docs/source/coding/ides/vscode/assets/mac_setup/run_ctest.png deleted file mode 100644 index 2e1814ff..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/run_ctest.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/save_workspace.png b/docs/source/coding/ides/vscode/assets/mac_setup/save_workspace.png deleted file mode 100644 index 04c81e0f..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/save_workspace.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/search_git_clone.png b/docs/source/coding/ides/vscode/assets/mac_setup/search_git_clone.png deleted file mode 100644 index 4e86421b..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/search_git_clone.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/select_active_project.png b/docs/source/coding/ides/vscode/assets/mac_setup/select_active_project.png deleted file mode 100644 index 18040267..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/select_active_project.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/select_clang.png b/docs/source/coding/ides/vscode/assets/mac_setup/select_clang.png deleted file mode 100644 index f2fe826b..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/select_clang.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/select_configuration.png b/docs/source/coding/ides/vscode/assets/mac_setup/select_configuration.png deleted file mode 100644 index 56b748f8..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/select_configuration.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/select_what_to_build.png b/docs/source/coding/ides/vscode/assets/mac_setup/select_what_to_build.png deleted file mode 100644 index 9708f569..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/select_what_to_build.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/set_git_name.png b/docs/source/coding/ides/vscode/assets/mac_setup/set_git_name.png deleted file mode 100644 index 7f8cb5af..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/set_git_name.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/settings_open.png b/docs/source/coding/ides/vscode/assets/mac_setup/settings_open.png deleted file mode 100644 index 08437f50..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/settings_open.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/source_control_view.png b/docs/source/coding/ides/vscode/assets/mac_setup/source_control_view.png deleted file mode 100644 index 42eee7e7..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/source_control_view.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/stage_changes.png b/docs/source/coding/ides/vscode/assets/mac_setup/stage_changes.png deleted file mode 100644 index be24e7bb..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/stage_changes.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/switch_to_source_control.png b/docs/source/coding/ides/vscode/assets/mac_setup/switch_to_source_control.png deleted file mode 100644 index 97166cba..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/switch_to_source_control.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/synch_settings.png b/docs/source/coding/ides/vscode/assets/mac_setup/synch_settings.png deleted file mode 100644 index 992b2c67..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/synch_settings.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/trust_us.png b/docs/source/coding/ides/vscode/assets/mac_setup/trust_us.png deleted file mode 100644 index e4460a9a..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/trust_us.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/tune_settings.png b/docs/source/coding/ides/vscode/assets/mac_setup/tune_settings.png deleted file mode 100644 index df37c72c..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/tune_settings.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/assets/mac_setup/your_repos.png b/docs/source/coding/ides/vscode/assets/mac_setup/your_repos.png deleted file mode 100644 index f871fac0..00000000 Binary files a/docs/source/coding/ides/vscode/assets/mac_setup/your_repos.png and /dev/null differ diff --git a/docs/source/coding/ides/vscode/building.rst b/docs/source/coding/ides/vscode/building.rst deleted file mode 100644 index 0df2812a..00000000 --- a/docs/source/coding/ides/vscode/building.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. Copyright 2025 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. - -Building NWX with VSCode -======================== - -Once you've minimally added the C++ and CMake extensions it's time to start -setting up your build process. For the purposes of this tutorial we assume you -are using a toolchain file with all of your CMake options. For sake of arguement -we assume that the full path to your toolchain file is given by: -``/home/user/nwx_workspace/toolchain.cmake``. - -To modify VSCode's CMake settings click on the gear in the left toolbar and then -settings. You will then be presented with all of VSCode's settings. At the top -you will see three tabs ("User", "Workspace", and the name of your current -folder); these tabs indicate the scope of the settings you are setting (user -settings follow you, workspace settings are for the entire workspace, and folder -setings are only for the current folder). Since building is somewhat project- -specific we recommend you click on either "Workspace" or folder. The CMake -settings are then accessed by expanding the "Extensions" settings and navigating -to "CMake configuration". - -Configuring the Build ---------------------- - -The first step is to set the paths of the CMake executables. If the ``cmake`` -and ``ctest`` executables are in your path feel free to skip this step. -Otherwise set "CMake Path" to the full path to your CMake executable. VSCode -will automatically use the ``ctest`` executable that comes with the ``cmake`` -executable you specify (but if you want to use a different one you can change -its path below via the "Ctest Path" option). - -Next we need to make sure the build uses our toolchain file. For our purposes -the main option we need to change is "Configure Args" (do not confuse this with -"Build Tool Args", which are the arguments that get passed to -the underlying build tool, typically ``make``). Under "Configure Args" click on -"Add Item" and type: - -.. code-block:: - - -DCMAKE_TOOLCHAIN_FILE=/home/user/nwx_workspace/toolchain.cmake - -substituting in your toolchain's path. - -Configuring the Project (i.e., running CMake) ---------------------------------------------- - -Once you've setup the options it's time to actually configure the project. To -configure say SCF, click on a C++ file or a CMake file in the ``SCF`` directory. -The bottom toolbar should show a folder icon with ``SCF`` next to it; this is -how you can tell which project will be configured. In the bottom toolbar you -should also see a panel with something like "CMake: [Debug]: Ready". Click on -this. You will get a pop-up asking you to select a kit. Choose "Unspecified" to -let CMake detect the kit for you (it'll end-up using your toolchain file). Then -pick the build type you want (Debug for normal development). After this you -should see the normal CMake configuration dialog fly by in the terminal. You'll -know it's configured successfully if you get a line like - -.. code-block:: bash - - -- Build files have been written to: - -Building the Project --------------------- - -Once the project has been configured you simply click the word "Build" in the -toolbar at the bottom. Akin to the configure step, you should see the usual -build dialog fly by on the terminal. - -Testing the Project -------------------- - -After a successful build you should be able to click the play arrow -(right-facing triangle) in the bottom toolbar to run the resulting executable -(assuming you enabled testing by putting ``BUILD_TESTING=TRUE`` in your -toolchain file). Again the normal testing output will fly by in the terminal. - -Building Sphinx Documentation ------------------------------ - -As a preliminary step you will need to install the documentation dependencies. -Each repo should contain instructions on how to do this, which amount to -something like: - -- Create a virtual Python environment -- run ``pip install -r requirements.txt`` - -Assuming you have installed the documentation's actual dependencies and the -``reStructuredText`` extension, the easiest way to setup the documentation build -is to go to settings (click on gear, then "settings") and navigate to -``Extensions->reStructuredText`` in the settings scope of your choice. - -.. note:: - - All NWX repos follow the same conventions for documentation so if you like - you can safely use these settings for the entire workspace. - -Minimally you should then set: - -- ``Built Documentation Path`` to ``${workspaceFolder}/build/html`` -- ``Conf Path`` to ``${workspaceFolder}/docs/source`` - -It is then recommended that you set: - -- ``Update on Text Changed`` to ``true`` (may be the default) -- ``Update Delay`` to a smaller value - -and if you are using virtual environments you will need to set -``Sphinx Build Path`` so that it points to the ``sphinx-build`` executable in -your virtual environment (should be something like -``/path/to/venv/bin/sphinx-build``. If for each repo you always create the -virtual environment in the same location you can still set this for the entire -workspace. - -Once you have set this all up you can open a ``.rst`` file and hit -``ctrl+shift+R`` to build the documentation (you'll want to point your -webbrowser at ``${workspaceFolder}/build/html/index.html`` to see it). diff --git a/docs/source/coding/ides/vscode/developing.rst b/docs/source/coding/ides/vscode/developing.rst deleted file mode 100644 index 60c72f11..00000000 --- a/docs/source/coding/ides/vscode/developing.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. Copyright 2025 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. - -Developing NWX with VSCode -========================== - -Once you've got the build working you're ready to start developing. The -following subsections provide some basic advice on how to go about doing -common development tasks. - -Version Control ---------------- - -It's strongly recommended that you do your development on a new branch and not -on "master" (the bottom toolbar should show your current branch next to the -version control icon, three circles in a V-like pattern). Clicking on the branch -name will bring up a menu where you can select "Create new branch" to create -your new branch (clicking "Create new branch" will lead to a new menu where you -name the branch). - -More version control options are available in the left toolbar by clicking on -the version control symbol. Here you will see a list of uncommitted changes for -each repo in your workspace. You can click on a change to see the difference. -Next to the file you also will see buttons for opening the file, reverting the -file, and staging the file. Next to the branch name is a checkmark which can be -used to quickly stage and commit all changed files (you'll have to type a -commit message in the provided box). Finally For the ellipses (three dots) will -bring up a menu with common git commands like push and pull. - -Code Formatting ---------------- - -C++ -^^^ - -Todo! - -.. _vscode-python-yapf: - -Python -^^^^^^ - -VSCode can use ``yapf`` to automatically format Python code through the -`official Microsoft Python extension `__. - -1. Install the `yapf extension `__. - -2. Ensure that the Python interpreter you want to run ``yapf`` with has - ``yapf`` installed. - -3. In settings, under ``yapf.interpreter``, set the path to the Python - interpreter from step 2. - -Documentation -------------- - -C++ (Doxygen) -^^^^^^^^^^^^^ - -Todo! - -.. _vscode-docstring-gen: - -Python (Docstrings) -^^^^^^^^^^^^^^^^^^^ - -Sphinx-style docstrings can be autogenerated for fully-defined functions/classes -in VSCode using the `Python Docstring `__ extension. Once the extension is -installed, set the ``autoDocstring.docstringFormat`` setting to "sphinx" to -match current NWX team :ref:`python-coding-conventions`. - -.. note:: - - Further information can be found `here `__. - -Debugging ---------- - -Debugging is one of the main reasons to use an IDE. To debug an executable, -click on the play-arrow with a bug on it in the left toolbar. If you have no -debug configurations set up yet there will be a big "Run and Debug" button -Click on it. This will bring up a menu asking you about the type of C++ debugger -you want to use. Pick the appropriate one (probably GDB/LLVM). Next, it'll ask -you which configuration you want to use. This will generate a JSON with your -debug configuration and open it in an editor. For most purposes the only thing -we need to change is the value associated with the "program" key; change this to -the path for the executable you want to debug (note you can use -``${workspaceFolder}`` to get an absolute path to the top-level directory of -your current folder). - -Clicking the green play arrow in the top toolbar will start a debugging session -for the current selected configuration (use the drop down menu next to the -arrow to select the configuration). The run will automatically stop on any -signal (such as segfault). It also will automatically stop when it hits a -breakpoint (you can set a breakpoint by clicking to the left of the line number -you want to break on). When the program stops the debugging pane will show the -values of the current variables and the current stack. You can use the toolbar -at the top-center to respectively: resume/pause execution, go to the next line -in the current source file, enter the function on the current line, go up one -call in the stack, restart execution, or stop execution. - -Profiling ---------- - -TODO: Write Me!!!! diff --git a/docs/source/coding/ides/vscode/developing_docker.rst b/docs/source/coding/ides/vscode/developing_docker.rst deleted file mode 100644 index 85565f0e..00000000 --- a/docs/source/coding/ides/vscode/developing_docker.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. Copyright 2025 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. - -############################################ -Developing in a Docker Container With VSCode -############################################ - -For the purposes of this page we define "Local" to mean in your native operating -system (OS) / file system. "Local" is contrasted with "Docker", which means the -OS and file system being used in a Docker container. - -**** -Why? -**** - -Compared to just running VSCode in the local OS this introduces additional -complexity, so why would you want to do it? - -- You want to develop for a different OS than what you currently have. The - quintessential example is targeting true Linux from MacOS. -- You want to containerize your development environment so that it is the same - on all systems, i.e., no more setting it up on each computer you go to. - -************************************************************ -Scenario 1: VSCode Creates a Docker Container and Runs In It -************************************************************ - -In this scenario, we have a local directory containing source files that we -want to do development on and do NOT yet have a Docker container. The files will -be accessible from inside the Docker container we create, but will ultimately -live locally (meaning changes to the files will persist even after the Docker -container is closed). Development will occur in the Docker container. We will -run the VSCode GUI (the graphical user interface) locally, but run the VSCode -server (the guts of the VSCode application responsible for most VSCode tasks) in -the Docker container (more efficient than running all of VSCode locally). - -Prerequisites -------------- - -- We assume you have VSCode installed locally already. -- If you haven't installed Docker locally you need to do that. We recommend - using `Docker Desktop `__. - Make sure you open the app and complete setup before continuing. - -Creating the Container ----------------------- - -- Start up VSCode locally. -- Install the "Dev Containers" extension. - - .. figure:: assets/docker/install_dev_containers.png - :align: center - - Navigate to the "Extensions" tab of VSCode and search for "Dev Containers" - and click install. - -- If you haven't already, add the repository you want to develop to your - current workspace. - - - ``command palette -> git clone`` and follow prompts. - -- Add the repository to a container. - - - ``command palette -> Dev Containers: Open Folder in Container`` - - We strongly suggest "add configuration to workspace" (and then adding - ``.devcontainer`` to ``.gitignore``). This will ensure you can find the - settings easily. - - .. figure:: assets/docker/select_options.png - :align: center - - Follow the prompts the Dev Containers Extension raises. - - - The Dev Containers extension will build your container in the background, so - it may take a while for this step to complete. - -- If the container was built successful you will be dropped into a "normal" - VSCode session except that it will actually be running in the container. - - .. figure:: assets/docker/in_container.png - :align: center - - You can see the name of the container in the explorer and in the bottom - right. - -- If you want to install dependencies into the container edit ``Dockerfile``. - - - If you followed our advice to add settings to the project, ``Dockerfile`` - will be in ``.devcontainers/``. - - After editing, make sure you rebuild by clicking on the "blue button" in - the bottom left and then choosing "Rebuild Container". Note rebuilding the - container will destroy any changes you made to the environment (but not the - source files). - - .. figure:: assets/docker/blue_button.png - :align: center - - The location of the "blue button". - -- When you are happy with the development environment start developing! - - - Again, note that changes to the environment will be lost the next time the - container is built. - -- When you're done developing click the "blue button" in the bottom left and - choose "Close Remote Connection". - -******* -Sources -******* - -- `Dev Containers Extension `__. diff --git a/docs/source/coding/ides/vscode/faqs.rst b/docs/source/coding/ides/vscode/faqs.rst deleted file mode 100644 index 6ea0bb0d..00000000 --- a/docs/source/coding/ides/vscode/faqs.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. Copyright 2025 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. - -FAQs -==== - -This subsection covers frequently asked questions regarding VSCode and -developing NWX with VSCode. - -**How do I change the editor font size?** ------------------------------------------ - -In settings search "editor.fontSize". Change the field to your preferred font -size. - -**How do I get a ruler to signify the 80 character limit?** ------------------------------------------------------------ - -In settings search "editor.rulers". Click on the "edit in settings.json" link. -In the ``settings.json file`` add "80" to the settings file that gets opened. - -**How do I get the reST extension to use a virtual environment?** ------------------------------------------------------------------ - -Assuming you have created a virtual environment ``venv`` and installed all of -your reST/Sphinx dependencies in to it. Start by using ctrl+shift+p to bring up -the command palette. Then select ``Python: Select Interpreter``. Navigate to -``venv/bin/python3``. Now the reST extension should use the virtual environment -``venv`` for rendering your documentation preview. - -**How do I get the debugger to set breakpoints per file and not per filename?** -------------------------------------------------------------------------------- - -By default VSCode assumes that when you set a breakpoint in a file ``x.cpp`` -you want that breakpoint to be set in ``src/x.cpp`` and in ``tests/x.cpp``; -you probably don't. To fix this add to the ``launch.json`` file for your -debugging session: - -.. code-block:: json - - "sourceFileMap": { - "${workspaceFolder}": { - "editorPath": "${workspaceFolder}", - "useForBreakpoints": "true" - } - } - -**How do I get the debugger to break on a throw?** --------------------------------------------------- - -Add the following to the ``"setupCommands"`` block of your ``launch.json`` file: - -.. code-block:: json - - "description": "Enable break on all exceptions", - "text": "catch throw", - "ignoreFailures": true diff --git a/docs/source/coding/ides/vscode/index.rst b/docs/source/coding/ides/vscode/index.rst deleted file mode 100644 index 4f0d74ce..00000000 --- a/docs/source/coding/ides/vscode/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. Copyright 2025 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. - -****** -VSCode -****** - -Visual Studio Code, or VSCode, is an IDE from Microsoft. Despite being from -Microsoft, VSCode is free, has a Linux version, and is suprisingly light weight -for C++ development. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - setup - setup_mac - building - developing - developing_docker - tips_and_tricks - faqs diff --git a/docs/source/coding/ides/vscode/setup.rst b/docs/source/coding/ides/vscode/setup.rst deleted file mode 100644 index b2f2aa6e..00000000 --- a/docs/source/coding/ides/vscode/setup.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. Copyright 2025 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. - -########################### -Setting Up VSCode for Linux -########################### - -This page focuses on how to initially setup VSCode, specifically from the -perspective of developing a module/plugin for NWChemEx on a Linux machine. - -***************** -Adding Extensions -***************** - -By default VSCode is pretty bare bones. Additional features -are added/enabled by installing extensions. When you load up source code VSCode -will inspect it and automatically recommend you install the corresponding -extenstion (if it's not installed already). For developing NWX we recommend you -minimally install: - -#. ``ms-vscode.cpptools`` -#. ``ms-vscode.cmake-tools`` -#. ``ms-python.python`` - -.. _fig_click_extensions: - -.. figure:: assets/click_extensions.svg - :align: center - - Location of the extensions view. - -To install an extension click on the extensions view (see -:numref:`fig_click_extensions`) and search for the identifiers given in the -above list. - -******************** -Creating a Workspace -******************** - -When you first start up VSCode you will have an empty workspace. We need to add -content to that workspace. - -.. _fig_add_folder_to_workspace: - -.. figure:: assets/add_folder_to_workspace.png - :align: center - - Navigate to ``files->add folder to workspace``. - -To do this navigate to ``files->add folder to workspace`` as shown in -:numref:`fig_add_folder_to_workspace`. This will bring up a file explorer, -which you should then use to navigate to the root directory of the repository -you want to add. - -.. _fig_click_explorer: - -.. figure:: assets/click_explorer.svg - :align: center - - The explorer icon. - -To see the repositories you've added so far click on the explorer icon shown -in :numref:`fig_click_explorer`. - -.. _fig_explorer_open: - -.. figure:: assets/explorer_open.png - :align: center - - View of VSCode with the explorer pane open. - -This will open the explorer pane and VSCode will look something like shown -in :numref:`fig_explorer_open`. For developing an NWChemEx module/plugin you -will minimally want to have the repositories for NWChemEx and your plugin in -your workspace. Repeat adding folders for each other repository you want to -have in your workspace. - -.. note:: - - AFAIK adding each repo individually in this manner is the only way for the - CMake extension to properly register the root CMakeLists.txt for each repo. diff --git a/docs/source/coding/ides/vscode/setup_mac.rst b/docs/source/coding/ides/vscode/setup_mac.rst deleted file mode 100644 index 3b9d1c08..00000000 --- a/docs/source/coding/ides/vscode/setup_mac.rst +++ /dev/null @@ -1,457 +0,0 @@ -.. Copyright 2025 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. - -########################## -Setting Up VSCode on MacOS -########################## - -These instructions were created on 9/16/2025 for macOS Sonoma (Version 14.6.1) -targeting VSCode Version 1.93.1. - -**************** -Obtaining VSCode -**************** - -The easiest way to obtain VSCode is from their -`website `__. Select the version you -want, download it, open the downloaded file, and copy the application to the -``Applications`` directory. - -************************ -Setup From Fresh Install -************************ - -When you start up VSCode you'll be greeted with the "Get Started with VS Code" -screen. - -- Pick your preferred theme. - - .. figure:: assets/mac_setup/pick_theme.png - :align: center - - First you will be asked to pick your theme. The choice is up to you. - -- Pick your languages. We want the C/C++, and Python language extensions. - - .. figure:: assets/mac_setup/choose_apps.png - :align: center - - You will be prompted to choose the coding languages you will use. - - .. figure:: assets/mac_setup/cxx_extension.png - :align: center - - The VSCode C++ extension. - - .. figure:: assets/mac_setup/python_extension.png - :align: center - - Install the Python extension. - - - If you have not previously installed "command line developer tools" follow - the prompts. - - .. figure:: assets/mac_setup/install_command_line_tools.png - :align: center - - If necessary, install command line developer tools to get access to - Python. - -- Tune your settings. Click "Open Settings". - - .. figure:: assets/mac_setup/tune_settings.png - :align: center - - Tune VSCode's settings to your liking. - - - Recommended to enable backup and sync settings. If you want do this then - sign in before changing any options. - - .. figure:: assets/mac_setup/synch_settings.png - :align: center - - Recommended to turn on settings synch to ensure a consistent VSCode - experience across devices. - - - Settings to consider (you can search for them to quickly find them): - - .. figure:: assets/mac_setup/settings_open.png - :align: center - - VSCode has a lot of settings. If you're new to IDEs you probably just - want to start with the suggestions below. - - - Files: Auto Save - - Editor: Rulers (we're sticklers for 80 character lines) - - CMake: Options: Status Bar Visibility (set to visible) - - .. note:: - - With setting synching on make sure you don't set any user setting to a - workspace specific path or it will be set across all your accounts. - -- At this point you're free to follow the remaining "Get Started" steps, but - VSCode is mainly interested in showing you how to start a new project and we - want to use an existing one. - -******************************************** -Creating an NWChemEx Development Environment -******************************************** - -Now that you have VSCode initialized we will create a development environment, -or as VSCode calls it, a "workspace". Workspaces reside in directories so go -ahead and create the directory for the workspace now. We recommend something -like ``/Users/your_username/nwchemex`` (you can create the directory in Finder -or via terminal). The remainder of this tutorial refers to this directory as -the "workspace directory". - -Adding Repositories -=================== - -.. figure:: assets/mac_setup/source_control_view.png - :align: center - - Step 1. Switch to the source control view (if it's not there go to - ``"View"->"Source Control"``). (If you have files open you will instead - see the source control for those files. To add a repo close the files or - skip ahead to step 9). - - - If you have not previously installed git see - `obtaining_dependencies_on_macos` (if you click on "Download Git for - macOS", it'll just redirect you to git's website which will duplicate - our instructions). Once git is installed, click ``reload`` in the source - control view. - -.. figure:: assets/mac_setup/clone_repo.png - :align: center - - Step 2. (With git installed) click "Clone Repository". - -.. figure:: assets/mac_setup/clone_from_github.png - :align: center - - Step 3. Click "Clone from Github". - -.. figure:: assets/mac_setup/allow_github.png - :align: center - - Step 4. If asked, allow the GitHub extension to sign in. - -.. figure:: assets/mac_setup/your_repos.png - :align: center - - Step 5. You should now see all the repos you have. Search for the one you - want. For sake of the tutorial search for ``NWChemEx/.github``, i.e., this - repo. - -6. That will bring up Finder. Select the workspace directory as the - destination. - -.. figure:: assets/mac_setup/open_cloned_repo.png - :align: center - - Step 7. When prompted open the repository. - -.. figure:: assets/mac_setup/trust_us.png - :align: center - - Step 8. If prompted, decide whether you trust us (we'll assume you do and - click yes). - -.. figure:: assets/mac_setup/search_git_clone.png - :align: center - - Step 9. Once there are files in your workspace the souce control view will - change to allow you to interact with the version control of the open files. - Unfortunately, this means we can not add additional repositories the same way - we did in Step 2. Rather, you need to use the command palate - (command + shift + P) then search ``Git: Clone``. That will return you to - Step 3 above, with the caveat that what was Step 7 should be replaced by - Step 10 below. - -.. figure:: assets/mac_setup/add_to_workspace.png - :align: center - - Step 10. Since you have files in your workspace already the dialog box from - Step 7 will change and you will want to select "Add to Workspace" instead of - "Open". - -.. figure:: assets/mac_setup/save_workspace.png - :align: center - - Step 11. Repeat Steps 9 and 10 until you have all the repositories you want. - Once you are done save your workspace by going to - ``File->"Save Workspace As..."``. We recommend saving it into the - ``nwchemex`` workspace directory and naming it as - ``nwchemex.code-workspace``. - - .. note:: - - If you choose a repository containing C++ source code, e.g., - ``NWChemEx/chemist``, VSCode may prompt you to select a kit. - Instructions for this are below. To get this to go away for now just - click "unspecified" or press esc. - -.. _creating_a_cmake_toolchain_file: - -Creating a CMake Toolchain File -=============================== - -CMake relies on toolchain files to pass configuration variables to dependencies. - -.. note:: - - We suggest putting the toolchain in the workspace directory and not in any - of the repositories. Unfortunately, this means we can't use VSCode's editor - to create/edit the file (VSCode will only let us create/edit files in the - repository directories we downloaded). Thus, if you put it in the workspace - you'll have to use an external editor to write the file. - -1. In the directory of you choice, create a new file ``toolchain.cmake``. -2. Modify the toolchain file. Syntax is ``set( )``. - Some variables you may want to include are: - - - ``NWX_MODULE_DIRECTORY``. Set this to where you want plugins and - modules to be installed to. - - ``CMAKE_CXX_STANDARD``. Set this to 17 if for some reason your C++17 - compliant compiler doesn't at least default to 17 being enabled. - - ``BUILD_TESTING``. To build the unit tests. - - An example: - - .. code-block:: cmake - - set(NWX_MODULE_DIRECTORY /path/to/your/workspace/directory) - set(CMAKE_CXX_STANDARD 17) - set(BUILD_TESTING TRUE) - -.. _setting_up_kits: - -Setting up Kits -=============== - -Kits are sets of tools to use to build the code. They are usually named based -on the compiler you want to use. Since MacOS ships with Clang, this tutorial -assumes you have Clang and are creating a Clang kit. - -.. note:: - - This tutorial assumes you have set the setting - ``cmake.options.statusBarVisibility`` to visible. - -.. figure:: assets/mac_setup/click_no_active_kit.png - :align: center - - Step 1. Click on ``No active kit``. If you had previously selected a kit, - this may instead display the name of that kit. - -.. figure:: assets/mac_setup/select_clang.png - :align: center - - Step 2. Select ``Clang ``. - - .. note:: - - Depending on your VSCode settings, selecting your kit will - immediately start a CMake configuration run. Since we're not done setting - up, it will likely fail... - -.. figure:: assets/mac_setup/edit_kit.png - :align: center - - Step 3. If you want to always use the same options with the same - tool kit (e.g., always use Ninja generator), you can edit the tool - kit file. To do this, open the command palette (command + shift + P) - and search for ``Edit User-Local CMake Kits``. - -.. figure:: assets/mac_setup/add_toolchain_to_kit.png - :align: center - - Step 4. If we want to always use the same toolchain file with the same - toolkit, we can edit the kit to know about the toolchain file. - Add ``"toolchainFile": ""`` to your kit. - - .. note:: - - This step assumes you did not skip the - :ref:`creating_a_cmake_toolchain_file` section. - - Another good idea, assuming you have Ninja installed - (``brew install ninja``) is to add it to your kit via: - - .. code-block:: - - "preferredGenerator": { - "name": "Ninja" - }, - "environmentVariables": { - "PATH": "/opt/homebrew/bin;${env:PATH}" - } - -Configuring a Project -===================== - -.. figure:: assets/mac_setup/select_active_project.png - :align: center - - Step 1. If you have multiple git projects open, make sure you select the one - you want to configure. - -.. figure:: assets/mac_setup/run_configure.png - :align: center - - Step 2. Click ``CMake: [Debug]: Ready`` to start configuring. - -.. figure:: assets/mac_setup/select_configuration.png - :align: center - - Step 3. Select the configuration you would like. - -Troubleshooting ---------------- - -- If you get an error about the CMake executable like: - - .. figure:: assets/mac_setup/bad_cmake_executable.png - :align: center - - Bad CMake executable error. - - it most likely means you do not have CMake installed (see - :ref:`obtaining_dependencies_on_macos` for instructions) or VSCode can not - find CMake. To set the CMake executable open the command pallette - (command + shift + P) and search for ``cmake.cmakePath``. - -- If you get an error about ``NWX_MODULE_DIRECTORY`` not being set, i.e.: - - .. figure:: assets/mac_setup/nwx_module_dir_not_set.png - :align: center - - Failure to set ``NWX_MODULE_DIRECTORY``. - - it either means you did not pass your toolchain to CMake (see - :ref:`creating_a_cmake_toolchain_file`) or you did not set - ``NWX_MODULE_DIRECTORY`` in your toolchain file. - -- If the configuration fails because of a missing dependency (e.g., - MPI or Boost) consult :ref:`obtaining_dependencies_on_macos`. - -- If the configuration fails because of the missing Python developer files, - e.g., - - .. figure:: assets/mac_setup/missing_python_headers.png - :align: center - - CMake could not locate the Python header files. - - consult :ref:`obtaining_dependencies_on_macos`. - -Building and Testing -==================== - -.. note:: - - We assume you have setup a kit already. If not see :ref:`setting_up_kits`. - -.. figure:: assets/mac_setup/select_what_to_build.png - :align: center - - Step 1. Set the project, build configuration, and kit to what you want. - -.. figure:: assets/mac_setup/click_build.png - :align: center - - Step 2. Click build. - -.. figure:: assets/mac_setup/run_ctest.png - :align: center - - Step 3. Assuming Step 2 is successful, click on "Run CTest" to run the test - suite. - -Committing Changes Back to GitHub -================================= - -.. note:: - - This section assumes familiarity with git terminology. - -.. figure:: assets/mac_setup/switch_to_source_control.png - :align: center - - Step 1. Switch to the source control view. - -.. figure:: assets/mac_setup/stage_changes.png - :align: center - - Step 2. (Optional) select the file(s) you want to stage by clicking on the - "+" next to the file(s). If you do not stage files VSCode will assume you - want to commit all changed files. - -.. figure:: assets/mac_setup/commit_message.png - :align: center - - Step 3. Type a descriptive commit message. - -.. figure:: assets/mac_setup/click_commit.png - :align: center - - Step 4. Click on the commit button. At this point your changes are only - committed to your local copy of the repository. We still need to push them - to GitHub. - -.. figure:: assets/mac_setup/click_synch.png - :align: center - - Step 5. Once you click "Commit" the button should change to "Synch Changes". - Click that to push your changes to GitHub. - -Troubleshooting ---------------- - -- You get an error about ``user.name`` and/or ``user.email`` for git is not set. - i.e., something like: - - .. figure:: assets/mac_setup/error_git_name_not_set.png - :align: center - - Error when your git credentials have not been set. - - The easiest way to fix this is to open a terminal (the one in VSCode works - fine) and run: - - .. code-block:: bash - - git config --global user.email "your email goes here" - git config --global user.name "your name goes here" - - For example: - - .. figure:: assets/mac_setup/set_git_name.png - :align: center - - How to set the email and user name for git. - - -- When attempting to synchronize with GitHub you get a cryptic error like: - - .. figure:: assets/mac_setup/cryptic_error.png - :align: center - - Cryptic error when synchronizing. - - For me this was caused by a credentials issue. I simply ran ``git push`` from - the VSCode terminal (in the root directory of the repo) and gave permission - to VSCode to use my passwords. From that point forward commit and - synchronization worked fine from VSCode. diff --git a/docs/source/coding/ides/vscode/tips_and_tricks.rst b/docs/source/coding/ides/vscode/tips_and_tricks.rst deleted file mode 100644 index ace3a2e7..00000000 --- a/docs/source/coding/ides/vscode/tips_and_tricks.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. Copyright 2025 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. - -Tips and Tricks for VSCode -========================== - -TODO: Add tips and tricks as they come up!!! diff --git a/docs/source/coding/index.rst b/docs/source/coding/index.rst deleted file mode 100644 index d4b9d95b..00000000 --- a/docs/source/coding/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Copyright 2025 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. - -################### -Developing NWChemEx -################### - -The topics in this part focus on how to develop code for NWChemEx. The -topics are concerned with literally writing the code. It is thus assumed that -you understand: - -- the basics of C++, -- how to build a C++ package, -- the basics of CMake, -- the basics of Python, -- PluginPlay topics such as property types and modules, -- how to write a module/property type, -- and the design of NWChemEx. - -.. TODO: - - Add links so people can educate themselves on these topics. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - preliminaries - cxx/index - python/index - ides/index diff --git a/docs/source/coding/preliminaries.rst b/docs/source/coding/preliminaries.rst deleted file mode 100644 index 3e424a03..00000000 --- a/docs/source/coding/preliminaries.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. Copyright 2025 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. - -.. _development_preliminaries: - -############# -Preliminaries -############# - -NWChemEx modules are written in C++ and a large part of the setup for developing -for NWChemEx pertains to setting up a good C++ development environment. - -************ -Dependencies -************ - -The NWChemEx build system can build a lot of dependencies for you; however, it -can't build everything. You'll need to get: - -- git -- C and C++ compilers -- CMake -- MPI -- BLAS/LAPACK -- Boost - -.. _obtaining_dependencies_on_ubuntu: - -Obtaining Dependencies on Ubuntu -================================= - -TODO: write me - -.. _obtaining_dependencies_on_macos: - -Obtaining Dependencies on MacOS -=============================== - -We recommend using `Homebrew `__ for obtaining packages on Mac. - -Obtaining Homebrew ------------------- - -- Go to `https://brew.sh`. -- Copy the command they have listed (or follow one of the other install methods) -- Open a terminal and paste the command. -- Enter your password. -- Press enter to accept the install parameters. -- Recommended: run the commands under "Next steps" to add Homebrew to your path. - -Installing Dependencies ------------------------ - -With Homebrew the dependencies and corresponding terminal commands are: - -- python3 -- git ``brew install git``. -- C and C++ compilers (MacOS comes with ``clang`` and ``clang++``) -- CMake ``brew install cmake``. -- MPI ``brew install mpich``. -- Boost ``brew install boost``. - -.. note:: - - To find the Python developer libraries run ``python3-config --include``. - Add the output of this command (without the ``-I``) to the CMake variables: - ``Python_INCLUDE_DIRS`` and ``Python3_INCLUDE_DIRS``. - -******************* -Directory Structure -******************* - -Once you have your dependencies you'll need to get the NWChemEx source code. The -source code for NWChemEx is spread out over a series of repos. It is strongly -recommended that you create a folder named something like ``nwx_workspace`` and -check out each repo you intend to develop for into this directory. We'll term -this directory your NWChemEx workspace. - -As a bare minimum you'll want the ``NWChemEx/NWChemEx`` repo in your -NWChemEx workspace. More than likely you will need to clone at least one -additional repository, namely the repo where your module/code will live. For -example if you are writing a module that will live in the SCF repo, you'll -also need to clone the ``NWChemEx/SCF``. For this example your NWChemEx -workspace will look like: - -.. code-block:: - - nwx_workspace/ - | - |-- NWChemEx/ - | - |-- SCF/ - | - `-- toolchain.cmake - -where the ``toolchain.cmake`` file will be described below. It should be noted -that to do development in the SCF repo this a complete NWChemEx workspace, you -don't need to clone any other repo. - -************** -Toolchain File -************** - -The last piece of the preliminary set-up is the toolchain file. By convention -this is a file named ``toolchain.cmake``. Its contents are a series of CMake -``set`` commands like: - -.. code-block:: cmake - - set(CMAKE_CXX_COMPILER /path/to/your/C++/compiler) - set(BUILD_TESTING TRUE) # Always a good idea to enable tests when developing - set(CMAIZE_GITHUB_TOKEN my_super_secret_token) # Needed to get private repos - set(CMAKE_BUILD_POSITION_INDEPENDENT_CODE TRUE) # Adds -fPIC to static libs - -For development purposes we also want to tell the build system to use our local -copies of repos we're developing in. This is done with CMake's -``FETCHCONTENT_SOURCE_DIR_XXX`` variables. For example if we're developing code -for the SCF repo we need to also add: - -.. code-block:: cmake - - set(FETCHCONENT_SOURCE_DIR_SCF /path/to/nwx_workspace/SCF) - -to our toolchain. If you are writing code for multiple repos you simply set -multiple ``FETCHCONTENT_SOURCE_DIR_XXX`` values, one for each repo. - -.. note:: - - Having a line like ``FETCHCONENT_SOURCE_DIR_SCF`` in a toolchain file is fine - when building repos which live upstream from SCF (such as SimDE and Chemist) - and even for SCF itself. Thus it's possible to use one toolchain file for the - entire workspace. diff --git a/docs/source/coding/python/index.rst b/docs/source/coding/python/index.rst deleted file mode 100644 index fd26f109..00000000 --- a/docs/source/coding/python/index.rst +++ /dev/null @@ -1,24 +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. - -.. _coding_python: - -########################## -Developing Python Software -########################## - -.. toctree:: - :maxdepth: 1 - - python_development_workflow diff --git a/docs/source/coding/python/python_development_workflow.rst b/docs/source/coding/python/python_development_workflow.rst deleted file mode 100644 index 02d3f0f7..00000000 --- a/docs/source/coding/python/python_development_workflow.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. Copyright 2025 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. - -.. _development_python_development_workflow: - -########################### -Python Development Workflow -########################### - -This page is intended to get you up and running so that you can develop for -NWX from Python. These instructions walk you through getting to a point -where you can do ``import nwchemex`` in Python. - -.. todo:: - - At some point it will probably make sense to combine at least some of these - instructions with the build instructions in the NWChemEx repo. - -********************* -Step 0: Preliminaries -********************* - -The Python workflow builds off of the :ref:`development_preliminaries` setup. - -******************** -Step 1: Python Setup -******************** - -When doing Python development it's always a good idea to do so in a virtual -environment. Assuming you completed the preliminary step, run these commands -in the NWChemEx workspace directory you created: - -.. code-block:: bash - - python3 -m venv - source /bin/activate - pip install cppyy - -```` should be replaced with whatever you want to call -the virtual environment. The last line installs Cppyy which is needed for -generating the Python bindings for NWChemEx. It is worth noting that you may -want to respectively set the environment variables ``CC`` and ``CXX`` to -the full paths of your C and C++ compilers before running ``pip install cppyy`` -to help ensure that Cppyy is built with the correct compiler. - -.. note:: - - There is a known - `issue `__ with - Cppyy, NWChemEx, and GCC 9. It is thus strongly recommended you use GCC 11 - (or newer). - -Unfortunately, by default the Python detection in NWChemEx will not find -the virtual environment Python interpreter by default. To get around this -you can add: - -.. code-block:: cmake - - set(Python3_EXECUTABLE /bin/python3) - -to your toolchain (obviously substituting the actual path). This is a known -`issue `__. - -********************** -Step 2: Build NWChemEx -********************** - -Instructions for building NWChemEx can be found -`here `__. - -For the sake of this tutorial we'll assume that ``${BUILD_DIR}`` is the build -directory where NWChemEx was built. - -******************* -Step 3: Python Path -******************* - -After Step 2, the NWChemEx Python modules will reside at -``${BUILD_DIR}/Python`` so assuming you have a Python script ``test.py`` which -contains: - -.. code-block:: python - - import nwchemex as nwx - - # Do stuff with nwx - -You'll have to run ``test.py`` like: - -.. code-block:: bash - - PYTHONPATH=${BUILD_DIR}/Python python3 test.py - -(or similarly correctly set up the Python path). - - -At this point you should now have access to all of NWChemEx from Python. diff --git a/docs/source/community/faqs.rst b/docs/source/community/faqs.rst deleted file mode 100644 index fc1da849..00000000 --- a/docs/source/community/faqs.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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. - -####################### -NWChemEx Community FAQs -####################### - -****************************************************** -When do I open an issue vs. a draft pull request (PR)? -****************************************************** - -TL;DR, if you're not sure, open an issue first. - -Draft PRs are meant to signal to the community that you intend to work on a -task, are ready to get started on it, and have a pretty good idea of how you -are going to accomplish the task. It should be possible to accomplish the task -in about two weeks (if you go over two weeks we're not going to close your PR -or anything, that's just a suggestion). Conversations in PRs should focus on -reviews of the code and what needs to happen to get it merged. - -If you need help designing, are not sure how to implement the task, or think -that the task will take longer than two weeks, you probably want to open an -issue first (specifically a feature request issue). Admittedly, the distinction -is not always as clear cut as we tried to depict here and whether to open an -issue or a draft PR is somewhat subjective. If you open a draft PR, but should -have opened an issue, or vice versa, it's fine. diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst deleted file mode 100644 index 7522f1b9..00000000 --- a/docs/source/community/index.rst +++ /dev/null @@ -1,28 +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. - -################## -NWChemEx Community -################## - -Topics in this section go over governance of the NWChemEx Community and explain -decisions we've made regarding community interactions (*i.e.*, how we landed on -our PR and issue templates etc.) - -.. toctree:: - :maxdepth: 1 - - pull_requests - issues - faqs diff --git a/docs/source/community/issues.rst b/docs/source/community/issues.rst deleted file mode 100644 index be8047f4..00000000 --- a/docs/source/community/issues.rst +++ /dev/null @@ -1,199 +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. - -.. _issues_and_nwx: - -######################################## -NWChemEx Community Guidelines for Issues -######################################## - -The TL;DR is that the NWChemEx community has elected to use GitHub for hosting -the source code of NWChemEX. Issues are well integrated into the GitHub -ecosystem and thus we will use Issues for logging bug reports, and tracking -user feedback. User feedback includes, but is not limited to: feature requests, -performance concerns, questions related to the code, and suggestions. - -This page is an academic look at issues. For tutorials on how to use issues, -from the perspective of the NWChemEx organization, see :ref:`nwx_github_issues`. - -************************* -What are (GitHub) Issues? -************************* - -GitHub introduced Issues for planning and tracking work that needs to be done -on a code base. The basic idea is any time you find a bug, think of a feature -which would be cool, find an algorithm which runs slow, or can't find -documentation to answer a question you have, you open an issue. If you're a -developer, you can then use Issues as a task list. If you're a user, you can -use Issues to give feedback to the code developers. - -For a tutorial on using GitHub issues within the NWChemEx organization -see :ref:`nwx_github_issues`. - -********************** -Why Do We Need Issues? -********************** - -As much as we wish it weren't true, NWChemEx can always be improved. When we -find something that could be better, we need to fix it. Often times -we're in the middle of something else and don't want to drop everything -to address the problem. This is where Issues can help. Using Issues we are -able to track tasks and make the code better. - -.. _issues_use_cases: - -********************************** -What Do We Want to Use Issues For? -********************************** - -#. Bug tracking and pull requests. - - - It's easy to open an issue, link it to a line of code, or type a quick - description. - - "TODO" statements in PRs or other Issues get forgotten (there's GitHub - integrations for turning - them into issues. This is very convenient for avoiding context switching - from the code to GitHub to open the issue.). - - Emails, Slack conversations, forum posts, etc. get lost/forgotten. - -#. Feature Requests - - - Most new features require some planning. - - Opening an issue starts the process. - - Issues integrate easily with GitHub Projects, facilitating organization. - -#. Work Planning - - - Similar to feature requests, but more general. - - Documents individual tasks in a longer sprint (not necessarily a feature). - - Issues are natural building blocks for GitHub Projects. - -#. User to Developer Communication - - - Bug tracking and feature requests are specific use cases. - - Users can ask questions. - - Users can provide other feedback (code is slow, hard to use, etc.). - - Users can see challenges that other users are having. - - -****************** -Issue Alternatives -****************** - -To provide background, this section explores some of the other alternatives to -GitHub Issues. This is -far from exhaustive and just represents some other options we considered. - -GitHub Discussions -================== - -Over the years GitHub has rolled out many communication features. To help GitHub -users navigate the options, GitHub provides guidance -`here `__. -The take-away is that of all the GitHub communication features, issues most -overlaps with Discussions. - -Based on the aforementioned link, discussions is meant for forum-style, -open-ended communication. Discussions targets: - -- questions not related to specific pieces of the code -- sharing news -- open-ended discussions -- announcements - -This contrasts with Issues, which are supposed to be tied to specific lines of -code. These lines of code can be: in the repo already, planned, or part of an -invocation of the repo. - -Slack, Forums, Email Servers, etc. -================================== - -There are a variety of tools for "real-time" communication among users and -developers. Generally speaking the biggest problem with these options is that -they're not dedicated to tracking bugs/feedback, and bugs/feedback can get lost -in the noise. That said, in many cases it makes sense to talk about -bugs/feedback via these avenues when the bug report/feedback is still being -formulated. Once formulated, it's better to move the bug report/feedback to a -dedicated tool. - -Jira -==== - -`Main page `__. - -Jira is a commercial software solution for tracking product development. At -this point the NWChemEx project is not at a point where we would use Jira for -anything beyond what Issues already provides. With the most recent changes and -improvements -in GitHub project boards, some of the Jira project management features are also -available in -a GitHub workflow. Thus it's not clear what the -benefit would be. It's possible that with a more thorough review of Jira this -opinion would change, but for now, the fact that Issues is free and well -integrate with GitHub make us prefer Issues over Jira. - -Trello -====== - -`Main page `__. - -Before GitHub Projects Trello, was a very attractive option. Trello allows you -to create tickets, and organize them on kanban boards. Now, however, using -Trello just adds an extra synchronization step between the repo and the Trello -board. - -Monday -====== - -`Main page `__. - -This winner of worst name (try googling ``monday`` and seeing how far you need -to scroll to find a relevant result) is arguably just a more advanced version -of Trello. Again, it's somewhat redundant with GitHub Projects, and it's use -just adds another synchronization step. - -************************************ -Using Issues in the NWChemEx Project -************************************ - -Ultimately because of how well Issues integrates with GitHub, the decision has -been made to use Issues. To address the considerations in -:ref:`issues_use_cases` we rely on Issue templates. The Issue templates for the -NWChemEx organization are kept in the ``.github`` repository in the -``.github/ISSUE_TEMPLATES`` directory. We presently have three templates: - -#. Bug reports -#. Feature requests -#. Questions - -(it's assumed that most user feedback will be questions, not statements). - -The full details of project planning are beyond this page. What is relevant -here is that GitHub Projects are comprised of Issues. The idea is that when -a more involved feature or development effort is to be undertaken the team -creates a project board. In the project board, individual tasks are added as -Issues. As PRs are merged, the Issues are closed and removed from the project. - -We also note that Issue templates hosted in the ``.github`` repository are used -as the defaults organization wide. They can be overridden on a repo by repo -basis by also defining Issue templates in individual repos. - -********************* -Future Considerations -********************* - -GitHub is currently (as of 12/9/2022) introducing issue forms. These are an -upgraded version of issue templates. Once available for private repos (or our -repos are all public) we should move to issue forms for a better user -experience. diff --git a/docs/source/community/pull_requests.rst b/docs/source/community/pull_requests.rst deleted file mode 100644 index 7dc7fa20..00000000 --- a/docs/source/community/pull_requests.rst +++ /dev/null @@ -1,393 +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. - -.. _prs_and_nwx: - -############################################### -NWChemEx Community Guidelines for Pull Requests -############################################### - -TL;DR Pull Requests (PRs) are the most natural way to update a project hosted -on GitHub. We have created a PR template to help PR authors include enough -detail for reviewers to do their job. And we have suggested workflows for -authors and reviewers. - -************* -What is a PR? -************* - -A PR is a GitHub feature used to contribute changes to a GitHub repo. More -specifically, each GitHub repo contains one or more branches. When you -want to modify one of those branches you open a PR with the suggested changes. -Maintainers of the branch then determine whether or not they want to pull your -changes into the branch. Often this is an iterative process where the branch -maintainers request changes to the PR before they will merge it. - -A full tutorial on PRs, tailored to the NWChemEx organization, is -given in the :ref:`nwx_github_pull_requests` section. - -******************* -Why do We Need PRs? -******************* - -The master branch of each repo is considered the "single source of truth." As -a community we need to do our best to make sure this branch is the best it can -be and conforms to the design and vision of the project. Bluntly speaking, the -primary point of a PR is to make sure contributions do not invalidate the single -source of truth by breaking the code or moving the code in an inconsistent -direction. That said, particularly in a large project like NWChemEx, it can be -almost impossible for any one person to fully understand what can break any -given component or for any one person to comprehend the entire design and -vision. The point being, while PRs do protect against malicious attacks, they -are primarily meant to avoid accidental breakages. Part of this is through -automated continuous integration pipelines (making sure the code builds and -tests pass, etc.) and part of this is through manual code review, *i.e.*, -having people read your code. - -Modern PRs are about more than just code review, they also are meant to be -learning opportunities for both experienced and inexperienced coders. Again, -no one person knows every aspect of a code, so when you make a PR it may turn -out that the reviewer knows a better way to do something. This works both ways -and reviewers often learn new techniques or discover previously unknown -features by reviewing code. - -PRs are also about staking a claim. When you open a draft PR you're telling -people that you are going to work on resolving a bug etc. This tells other -people not to duplicate the effort and/or gives them a chance to join the -cause. - - -***************** -PR Considerations -***************** - -This section lists considerations for authors and/or reviewers of PRs. -Following semantic versioning, we can think of each PR as addressing one of -three use cases: - -#. API breaking changes - - - Any change to a public-facing API which breaks previously working code - -#. New features - - - Introduces new code without breaking the API - - New alternative APIs - - Allows the code to compute new things - - Quality of life improvements (e.g., extensive optimization) - - Entirely new documentation sections - -#. Patches - - - Largely modifies existing code - - Bug fixes, typos, documentation tweaks - - Performance optimizations spanning a relatively small amount of code - -In general the PR considerations are going to be highly tied to what the PR -wants to accomplish, the following subsections group considerations by use cases -and assume archetypal PRs. In other words, not all points are going to be -relevant to every PR. If they're not relevant for a specific PR they should be -ignored. - -General Considerations -====================== - -#. Making a PR should be easy. - - - If it's too hard to make a PR people won't do it. - - Setting the bar too high discourages new contributors. - -#. It should be possible to open the PR early. - - - Channel for discussion between reviewers and the PR author. - - Gets work on radar of reviewers and other developers. - - Time to hash out what is and is not in scope before time is wasted. - -#. The PR's lifetime should be short. - - - Shoot for merging in less than two weeks. - - - Long-lived PRs are typically overlooked in ongoing design. - - Easy for new changes to break correctness/performance of long-lived PR. - - Others can't leverage your feature if it's a PR. - - PR author needs to keep PR up to date with the rest of the code, which can be a lot of time if the - PR is long-lived. - - Hard to remember subtleties over life of long-lived PRs (*e.g.*, why - something was/wasn't done). - - The longer the PR lives, the more code it tends to contain, and the harder - to review. - - Long-lived PRs tend to increase the amount of technical debt by seemingly - justifying the "let's just merge this" mentality. - - - Merge function by function if necessary. - - See :ref:`using_issues_to_track_progress` for tracking progress. - -#. Code submitted as PRs should adhere to the organization's standards. - - - Important for continuity - - Makes code reviews easier - - Current standards: - - - :ref:`cxx_conventions`. - - :ref:`python-coding-conventions`. - - :ref:`rest_conventions`. - - :ref:`doxygen_conventions`. - -#. PRs should contain code of high-caliber. - - - NWChemEx strives to be an exemplar package - - Easier to maintain good code - - High-quality is especially important for senior developers as new - developers look to your code for examples - - There is a time and place for "just get something working", but should - ideally be avoided - -API Breaking Changes -==================== - -#. Breaking API should be a last resort. - - - Maintaining stable APIs leads to users and developers instilling trust - in us. - - Need to document what was tried to avoid the break. - -#. Need a plan to avoid breaking the APIs again. - - - Determine breakage points. - - Update design documentation relying on old API. - - Carefully plan design of new API to avoid another break. - - Test new API. - -Features -======== - -#. Need to avoid the "Hit by a bus" scenario. - - - The NWChemEx code base needs to be maintainable by multiple developers. - - Knowledge needs to be discoverable and shared. - - Design Documentation helps other developers understand the feature. - - User documentation makes sure users can use the feature without needing to - read the code/ask a developer. - - Developer documentation for technical aspects, avoids the costly exercise - of reverse engineering how algorithms work. - -#. Features need to be tested. - - - As a scientific code we need to be reliable and reproducible. - - NWChemEx is a big project, so it can be very difficult to understand - ramifications of a change. These changes can be caught by appropriate - testing. - - -Patches -======= - -#. Patches are often small and ready to go upon opening PR. - - - Don't require PR to be opened in advance. - -#. Not all feature considerations are applicable to patches. - - - Documentation usually not needed for bug fixes. - - Need tests to ensure bug doesn't appear again. - - New documentation usually doesn't need new tests. - - Snippets added to documentation do need to be tested. - - Performance updates may require updating documentation if it affects - behavior and/or use cases, *e.g.*, the method's scope may have expanded. - - -***************** -Current PR Policy -***************** - -Based on the above considerations our current PR policies are listed below. - -Pull Request Template -===================== - -.. note:: - - GitHub supports PR templates (although as of this writing 12/8/2022) they do - not seem to support the same feature set as issue templates (and some of the - information seems outdated, like being able to have a separate directory). - Should this get fixed we should look into multiple PRs for the different use - cases. - -We have written a PR template to streamline the process of opening PRs. The -template is designed to have meaningful prompts that can be filled out quickly. -The prompts ask the author to: - -#. specify what sort of PR this is (major, minor, or patch), -#. describe what's in scope for the PR, -#. describe what's not in scope for the PR, -#. confirm that they have done documentation, etc., and -#. (for drafts only) listing what still needs to be done. - -Why these prompts? The first prompt is for categorizing the PR (and -automating the resulting semantic versioning that needs to happen). The next -two relate to ensuring that the reviewer knows what is supposed to be in the PR -and what is not. The fourth prompt is to hopefully avoid the reviewer needing -to explicitly ask for documentation, etc. And the fifth is to give a rough -idea of what still needs to be done before the PR can be merged. - -The template contains comments which explain the prompts in more detail. - -PR Author Process -================= - -.. note:: - - The contents of this section provide the motivation for - :ref:`nwx_github_pull_requests`. - -Once an author has decided to work on a feature or patch they should open a PR. -This entails: - -#. Start a branch ``b`` for the PR. -#. Initiate a draft PR from ``b`` to the target branch (usually master/main). -#. Fill out the PR template GitHub prompts with. -#. Continue to push changes to the branch (checking off tasks as appropriate). - - - Generally speaking changes should clearly identify todos raised by the - change, *e.g.*, if you add a function, but don't document it. Put - ``TODO:document me``. - - This helps reviewers know what you've overlooked vs. what you just haven't - gotten around to. - -#. Notify the reviewers when the author thinks that ``b`` is ready to merge - by messaging ``r2g`` (or something similar) in the PR conversation. -#. Respectfully address any reviewer concerns. Marking each one as resolved when - it has been addressed. -#. If the PR has changed return to item 5. -#. The last approving reviewer merges the PR after all CI workflows pass. - -.. note:: - - For PRs whose description requires more than a couple sentences. The author - should open a corresponding issue with the full description. The issue is - for tracking the design, scope, concerns, etc. that the PR should address. - The PR itself is for discussing how the PR author literally chose to - implement the feature, patch, etc. - - -Review Process -============== - -.. note:: - - GitHub allows reviewers to suggest changes. This is very useful when there's - a typo, formatting error, etc. Please use this feature rather than - writing comments like "should be capitalized". - -Reviewers of a PR are expected to: - -#. Understand what the PR is supposed to accomplish. -#. If necessary, the reviewers should help the author refine the PR contents. - - - Should the PR (and corresponding issue) be split into multiple issues/PRs? - - Did the author miss any obvious concerns? - -#. Keep an eye on the PR as it progresses. The frequency of "check-ins" should - be inversely proportional to the author's familiarity with the process, - *i.e.*, keep a closer eye on newer authors than seasoned veterans. -#. Comment on the code when issues are spotted. - - - Is the code using existing infrastructure to the extent possible? - - Is the code accruing technical debt? - - Is the formatting consistent? (Don't worry about formatting which CI will - fix) - -#. When the PR is marked as ready to go, complete a final pass through the code - flagging any potential issues. -#. If issues arise, work with the author to resolve them. Repeating the previous - steps as necessary. -#. If you are the last reviewer to approve a PR then merge it (assuming all - CI workflows have passed). - -Notes on PR Quality -=================== - -.. note:: - - The contents of this section are written assuming a 1.0 has occurred. We - admittedly have not lived up to the lofty standards of this section and - part of getting to a 1.0 is making sure existing code meets or exceeds - these standards. - -.. note:: - - Occasional contributors from outside the project are not the target of this - section. This section is targeting developers who are regular contributors - to the code (part of the team). - -NWChemEx is designed to be a modular code. The vast majority of electronic -structure development occurs in modules. Each of these modules are disjoint, -and can be separately hosted. The checklist on the PR template is admittedly -asking a lot of the author. If you are working on new research (as opposed to -say adding a well known feature) then, you can (and should) go through the -"just get something working" phase outside of the NWChemEx repositories. Once -you have hashed out your design, and decided that the feature is worth -contributing back, then you should begin the PR process, *i.e.*, rapid -prototyping should be done external to NWChemEx. - -When you open a (draft) PR for adding a module into an NWX repository you are -saying that you think that the module will be useful, should be supported, and -that you are willing to get the first version of the module up and running. -This does not necessarily mean that upon merging the PR the module is as -performant as it is going to get, or that the module is fully featured (both -of which can be addressed in subsequent PRs). Once the module is merged it -becomes available to users, and since taking it back would break any code that -uses the module, we as a project are obligated to support that module (or -break an API to retract it). The point being, before merging the PR we expect -the module to be fully documented, tested, and to adhere to the organization's -standards so that we can begin stewardship of the module. As a slight aside, -many electronic structure features take a while to implement. If this is the -case for your feature, open an issue to track progress (see -:ref:`using_issues_to_track_progress`) and break the module implementation down -into pieces, *e.g.*, PR one is design, PR two is some low level functions, PR -three combines the functions, etc. - -For PRs addressing infrastructure, the requirements are a bit different. -When developing a module, the stability of the property type APIs helps ensure -that your module will remain compatible with the rest of NWChemEx, even if it -takes you a while to develop the module. Property types do not exist for -infrastructure, and infrastructure necessarily needs to be developed in a much -more coupled manner. To facilitate rapid merging of infrastructure, we thus -allow some technical debt, as long as the developer is willing to repay that -technical debt, and makes a plan for repaying it. In practice what this means -is, say you really need a new type of cache to complete a run. We'll let you -merge that cache, say without documentation, as long as you open an issue -tracking that documentation is still needed. Developers are expected to repay -technical debt in a relatively timely manner. That said, since the -infrastructure is going into the main repository, it still needs to be vetted -before it can be merged. In turn, infrastructure cannot still be in the -design phase, nor can it be untested. - - -********************* -Future Considerations -********************* - -As of 12/8/2022, GitHub is overhauling the issue templates and adding issue -forms. We anticipate that PR templates will get the same treatment. If this -happens, we should revisit the template and try to make it mesh better with -CI. For example: - -- Automate tagging for versioning. -- Having content of the template update/change based on user feedback. -- Auto-assigning reviewers. -- Not marking a PR as ready to go until all items have been addressed (I'm - thinking the author needs to confirm they've added documentation etc. before - the PR can be made ready to go). -- Ideally we should automate as much of the required checklist as possible. diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 8ba49cf3..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,169 +0,0 @@ -# -*- coding: utf-8 -*- -# Copyright 2025 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. - -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -import os - -# -- Project information ----------------------------------------------------- - -project = "Developer Documentation" -copyright = "2020, NWChemEx Team" -author = "NWChemEx Team" - -# TODO: get version from git -version = "1.0.0" - -# The full version, including alpha/beta/rc tags -release = version - -############################################################################## -# Shouldn't need to change anything below this point # -############################################################################## - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.intersphinx", - "sphinx.ext.todo", - "sphinx.ext.coverage", - "sphinx.ext.mathjax", - "sphinxcontrib.bibtex", - "sphinx_tabs.tabs", -] -dir_path = os.path.dirname(os.path.realpath(__file__)) -doc_path = os.path.dirname(dir_path) -root_path = os.path.dirname(doc_path) - -# Add any paths that contain templates here, relative to this directory. -# templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = "en" - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -numfig = True - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -html_theme_options = {"vcs_pageview_mode": "edit"} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - -# Allows the edit on GitHub button to make editing the docs easier. -html_context = { - "display_github": True, - "github_user": "NWChemEx", - "github_repo": ".github", - "github_version": "master/docs/source/", -} - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = project + "doc" - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# -- Extension configuration ------------------------------------------------- - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = { - # 'python': ('https://docs.python.org/3', None) -} - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - -# -- Options for bibtex ------------------------------------------------------ - -bibtex_bibfiles = ["bibliography/software.bib"] -bibtex_reference_style = "super" -bibtex_default_style = "plain" diff --git a/docs/source/continuous_deployment/ci_maintainer_notes.rst b/docs/source/continuous_deployment/ci_maintainer_notes.rst deleted file mode 100644 index a6eefbec..00000000 --- a/docs/source/continuous_deployment/ci_maintainer_notes.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. Copyright 2025 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. - -******************************************* -How NWX's Continuous Integration (CI) Works -******************************************* - -The purpose of this page is to document various aspects of NWX's CI. - -NWX has a lot of repositories. And more repositories will be added into NWX. To -make the CI of NWX generic and re-useable, we've used `reuseable workflows -`__ and -`composite actions -`__ -for designing our CI architecture. The goal of this design was to ensure -maximum re-use of CI components across multiple repositories. - -Here are a few useful tutorials on workflows in GitHub: - -- `Quickstart for GitHub Actions `__ -- `GitHub Actions Tutorial, From Zero to Hero in 90 minutes - `__ - -Currently the following repositories in ``NWChemEx`` follow the methods -outlined here: - -#. ``.github`` (This is our configuration repository) -#. ``ChemCache`` -#. ``Chemist`` -#. ``Integrals`` -#. ``Mokup`` -#. ``NWChemEx`` -#. ``ParallelZone`` -#. ``PluginPlay`` -#. ``SimDE`` -#. ``SCF`` -#. ``TensorWrapper`` -#. ``Utilities`` - -Common and Repo-Specific Workflows -================================== - -The ``.github/workflow`` directory in the ``NWChemEx/.github`` repo -houses both the set of workflows specific to the ``.github`` repo and the set -of reusable workflows that should be used throughout the NWX stack. Generally, -these reusable workflows should be named in a way that describes what kind of -effect they should achieve, e.g. ``tag.yaml`` or ``check_formatting.yaml``. -These common workflows represent the reoccurring GitHub Actions operations -required by the NWX repos, e.g tagging a newly merged commit or checking -formatting. The common workflows currently available include: - -* ``check_formatting.yaml`` - performs common formatting and licensing checks -* ``deploy_nwx_docs.yaml`` - deploys the docs for an NWX library to GitHub pages -* ``tag.yaml`` - updates the version tag for a commit, used after merging into ``master`` -* ``test_nwx_docs.yaml`` - ensures the documentation of an NWX library builds properly -* ``test_nwx_library.yaml`` - ensures an NWX library builds and passes its tests - -Aside from the common workflows, there are the repo-specific workflows with the -naming convention ``{trigger event}.yaml``. Where needed, a version of these -workflows can be added in each repo. Here's an example of a repo-specific -``pull_request.yaml``: - -.. code-block:: yaml - - name: Pull Request Workflow - - on: - pull_request: - branches: - - master - - jobs: - check_formatting: - uses: NWChemEx/.github/.github/workflows/check_formatting.yaml@master - with: - license_config: ".github/.licenserc.yaml" - - test_nwx_docs: - uses: NWChemEx/.github/.github/workflows/test_nwx_docs.yaml@master - with: - doc_target: "tensorwrapper_cxx_api" - - test_library: - uses: NWChemEx/.github/.github/workflows/test_nwx_library.yaml@master - with: - compilers: '["gcc-11", "clang-14"]' - - unique_job: - # Other steps unique to the individual repos can be added as Jobs - -And here is an example of the repo-specific ``merge.yaml``: - -.. code-block:: yaml - - name: Merge Workflow - - on: - push: - branches: - - master - - jobs: - tag-commit: - uses: NWChemEx/.github/.github/workflows/tag.yaml@master - secrets: inherit - - deploy_nwx_docs: - uses: NWChemEx/.github/.github/workflows/deploy_nwx_docs.yaml@master - with: - doc_target: "XYZ_cxx_api" - secrets: inherit - - unique_job: - # Other steps unique to the individual repos can be added as Jobs - -Generally, these workflows are expected to call to the necessary reusable -workflows to handle the reoccurring tasks and then locally implement any unique -automations. - -NWX Build Environment Image -=========================== - -To avoid rebuilding costly dependencies for the various repos in the NWX stack, -the building and testing steps in the common workflows run in containers built -on the image ``ghcr.io/nwchemex/nwx_buildenv:latest``. This image -defines an Ubuntu based environment where the various dependencies of the stack -(such as compilers, math libraries, MPI, and other C++ libraries outside) have -been pre-installed. The files used to build this image are found in -``NWChemEx/.github/nwx_build_environment``, along side the -``buildenv.sh`` script which builds the image through consecutive Docker calls. diff --git a/docs/source/continuous_deployment/debugging.rst b/docs/source/continuous_deployment/debugging.rst deleted file mode 100644 index e4f6ab87..00000000 --- a/docs/source/continuous_deployment/debugging.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. Copyright 2025 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. - -############################## -How to Debug CI Issues Locally -############################## - -.. note:: - - When you try to Google "how to debug Github Actions locally" you will find - a tool called `Act `__. In our experience, - we seem to always be in th 10% of edge cases that Act cannot faithfully - reproduce locally, i.e., feel free to try it, but it probably won't work. - -************************* -Building the Docker Image -************************* - -Prerequisites -============= - -- Have Docker installed. - - We recommend using `Docker Desktop `__. -- Have the Docker daemon running. - - If you are using Docker Desktop, just make sure the app is open. - -Steps -===== - -1. In a terminal run ``docker pull ghcr.io/nwchemex/nwx_buildenv:latest``. - - - This will download the Docker image we use in our CI workflows. - - It's somewhat big and will probably take a while to download. - -2. Run the image: ``docker run -it ghcr.io/nwchemex/nwx_buildenv:latest``. -3. Clone the branch you want to debug. - - - ``git clone https://url/of/repo/your/branch/is/part/of.git`` - - ``cd /directory/where/repo/was/cloned`` - - ``git fetch`` - - ``git checkout your_branch_name`` - -3. You now need to manually run the commands that are in the workflow - you want to debug. Workflows can be found in the ``.github`` - `repository `__ in the - ``.github/workflows`` directory. - - - If you are building a library that uses CMake follow the - ``test_nwx_library.yaml`` workflow. - -4. (Optional) After you are done building we recommend saving the state of the - container as a new image. This way you don't have to repeat steps 2-3 if the - container is stopped/closed for whatever reason. - - - From another terminal run - ``docker commit nwchemex_debug_image`` to create the - image. - -**** -FAQs -**** - -- When trying to run an executable in a Docker container under lldb, I get an - lldb error: ``lldb error: 'A' packet returned an error: -1``. - - - This means lldb was not allowed to start debugging the executable. - - If you have Apple silicon you may not be able to debug x86_64 binaries - (`source `__). diff --git a/docs/source/continuous_deployment/documentation.rst b/docs/source/continuous_deployment/documentation.rst deleted file mode 100644 index e6e8e0c4..00000000 --- a/docs/source/continuous_deployment/documentation.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. Copyright 2025 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. - -************************ -Documentation Deployment -************************ - -Overview -======== - -NWX uses a two-pronged approach to documentation: Doxygen and Sphinx. Doxygen is -the *de facto* standard for writing and generating C++ API documentation. Sphinx -is the *de facto* standard for generating Python documentation. Unfortunately, -Sphinx and Doxygen do not play so well together (there a number of efforts out -there to bridge the gap, but most seem to leave plenty to be desired). - -How NWX's Documentation Actually Works -====================================== - -C++ ---- - -As developers write C++ they are expected to document the APIs of classes and -functions. The C++ API documentation should be written using Doxygen's native -markdown (markup?) language. The Doxygen documentation is built using CMake's -Doxygen module. Using CMake's Doxygen module is fairly cookie-cutter so NWChemEx -provides the ``nwx_cxx_api_docs.cmake`` CMake module to avoid code duplication. -The master version of ``nwx_cxx_api_docs.cmake`` lives in the -``MWChemEx/NWXCMake`` repo and is downloaded along with the other scripts in -that repo by the CMake module ``get_nwx_cmake.cmake`` found in most repositories -in this organization. Downstream repos need only include the following two lines -in their top-level ``CMakeLists.txt`` file: - -.. code-block:: cmake - - include(nwx_cxx_api_docs) - nwx_cxx_api_docs(/path/to/cxx/source_dir1 /path/to/cxx/source_dir2 ...) - -(obviously use the actual paths to your C++ source directories). It's best that -this is included near the top of the ``CMakeLists.txt`` file as the module -includes a mechanism for avoiding much of the CMake configuration in the event -that we are only trying to build the documentation (a common CI scenario). Once -the C++ API documentation is generated it will reside in the build directory. - -Sphinx ------- - -Tutorials, detailed background, and other narrative-based documentation is -written most easily in Sphinx's flavor of reStructuredText. This also has the -benefit of resulting in far prettier documentation than Doxygen's equivalent. -This documentation should be kept with the repository it pertains to (if it -applies project-wide it should live in the DeveloperTools repo) in the repo's -``docs`` directory. This directory should have a typical Sphinx setup:: - - docs/ - ├-source/ - | ├-section1/ - | | └-index.rst - | ├-section2/ - | | └-index.rst - | ├-conf.py - | └-index.rst - └-Makefile - -If the repository has C++ API documentation it will be generated at -``docs/build/html/x_cxx_api/index.html`` where ``x`` is the project name -provided in ``CMakeLists.txt``, in lowercase. It can be linked to in your main -``index.rst`` file like: - -.. code-block:: rest - - `C++ API `_ - -(substituting in the project name for the first ``x``. When Sphinx is run the -index of the resulting documentation will be located at -``docs/build/html/index.html``. diff --git a/docs/source/continuous_deployment/index.rst b/docs/source/continuous_deployment/index.rst deleted file mode 100644 index bf3ca10c..00000000 --- a/docs/source/continuous_deployment/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. Copyright 2025 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. - -##################### -Continuous Deployment -##################### - -The topics in this section focus on the workflows and other automation -techniques used to ensure that changes to NWChemEx's repos happen in as -reliable of a manner as possible. Strictly speaking this automation covers -both merging the software into the master branch (continuous integration), and -deploying the master branch (continuous deployment). - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - ci_maintainer_notes - documentation - debugging diff --git a/docs/source/conventions/assets/docs_files.png b/docs/source/conventions/assets/docs_files.png deleted file mode 100644 index c79c9442..00000000 Binary files a/docs/source/conventions/assets/docs_files.png and /dev/null differ diff --git a/docs/source/conventions/assets/github_files.png b/docs/source/conventions/assets/github_files.png deleted file mode 100644 index 91d0a12d..00000000 Binary files a/docs/source/conventions/assets/github_files.png and /dev/null differ diff --git a/docs/source/conventions/assets/root_files.png b/docs/source/conventions/assets/root_files.png deleted file mode 100644 index 65db3f0f..00000000 Binary files a/docs/source/conventions/assets/root_files.png and /dev/null differ diff --git a/docs/source/conventions/cxx_conventions.rst b/docs/source/conventions/cxx_conventions.rst deleted file mode 100644 index 7388684b..00000000 --- a/docs/source/conventions/cxx_conventions.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. Copyright 2025 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. - -.. _cxx_conventions: - -********************** -C++ Coding Conventions -********************** - -This page introduces the NWX team's coding conventions for writing C++. All pull -requests are expected to adhere to these conventions. When possible -``clang-format`` will be used to enforce them; however, it is not possible to -automatically enforce all of these conventions. This page is primarily targeted -at conventions which you must manually adhere to, while -``ci/lint/clang-format.in`` is -the linting file used and should be consulted for the conventions which will be -automatically enforced. - -Capitalization -============== - -C++ is a case-sensitive language. For this reason it is extremely useful for all -coders on a project to use the same capitalization conventions, doing so avoids -needing to remember how a method, file, *etc.* is capitalized. - -.. note:: - - When describing capitalization formats the common choices are - - - snake_case : All lowercase, underscores used to separate words - - (upper) CamelCase : Each word is capitalized, no spaces - - (lower) camelCase : Upper CamelCase that does not capitalize the first word - - ALL_CAPS : All letters are capitalized, underscores separate words - -The common elements of a C++ code are listed below as well as how they should be -capitalized. - -=================== ========== -Code Element Case -=================== ========== -files snake_case -namespaces snake_case -classes CamelCase -functions snake_case -class members snake_case -template parameters CamelCase -typedefs snake_case -macros ALL_CAPS -=================== ========== - -The rationale behind these conventions is largely to match common C++ practices -such as those used by Boost and the STL. The only exception to this statement is -the decision to use CamelCase for class names. This decision stems from wanting -to distinguish between built-in types/classes from standard libraries and domain -specific classes. diff --git a/docs/source/conventions/doxygen_conventions.rst b/docs/source/conventions/doxygen_conventions.rst deleted file mode 100644 index cfb9ceaf..00000000 --- a/docs/source/conventions/doxygen_conventions.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. Copyright 2025 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. - -.. _doxygen_conventions: - -************************************* -Using Doxygen in the NWChemEx Project -************************************* - -The purpose of this page is to give you a (likely less than 10 minute) primer on -how to use Doxygen particularly with respect to the NWChemEx project. The -NWChemEx project uses Doxygen to document C++ code. For documenting Python or -writing documentation pages like this one the project uses Sphinx's ReST flavor. - -Intro To Doxygen -================ - -Doxygen allows you to document your C++ code in a minimally invasive manner. It -does this by requiring you to write your C++ comments using Doxygen's markup -language. Bare-bones this looks like: - -.. code-block:: c++ - - /// This is a Doxygen, single-line comment for the following function - void function1(); - - /** For more extened documentation block comments are preferred. - * - * This line is also part of the comment. - */ - void function3(); - -Doxygen supports other conventions; however, the two above are the approved -conventions for the NWChemEx project. For consistency please use them. - -Doxygen has two types of comments: brief and detailed. Brief comments are -primarily used to give a reader a quick, one-line summary of a function, class, -*etc.*. By convention single line comments are always briefs, whereas the first -line (up to the first period)of a multi-line comment is the brief and the -remaining lines are the detailed description. When making multi-line comments -it is good practice to start the brief with ``@brief``. This will ensure that -the brief continues until the first blank line and will prevent surprises from -forgetting the period convention. ``@brief`` is an example of a Doxgyen keyword. -Keywords are signaled by the ``@`` symbol (there's another convention too, but -this is the one approved for NWChemEx) and have a special meaning to Doxygen. -There's a lot of -`keywords `_ and the -next section acquaints you with the minimum set of keywords that you must use -when documenting C++ code for use with NWChemEx. - - -Minimal Documentation Standards -=============================== - -By far the most useful keywords are shown in the following code example. For -documenting a function this should be considered as a minimal acceptable -amount of documentation. For documenting data members and types a single line -comment is often fine (just describing what it is). - -.. code-block:: C++ - - /** @brief This is the brief description of fake function 1. - * - * Fake function 1 demonstrates the bare minimal documentation standards. - * What you are currently reading, is the detailed description that will - * show up in the documentation. The "*" border is optional, but - * encouraged. - * - * @tparam T The type this function takes. The documentation should tell - * you what concept it satisfies. - * @param[in] Param1 The first parameter; it's read-only. - * @param[out] Param2 The second parameter; it's going to be written to. - * @param[in,out] Param3 The third parameter; it's going to be read from - * and written to. - * @returns Whatever this function returns. - * - * @throws std::runtime_error Tell you when it throws and what exception - * guarantee is afforded. - */ - template - int function1(int Param1, int& Param2, int& Param3); - - Obviously the real documentation should be more helpful, but this illustrates - the key things to document: brief, detailed description, input/output - parameters, return value, template type (or non-type) parameters, and - exceptions that are thrown (as well as the level of exception guarantee). - - Other useful commands to be aware of: - -- ``@file`` for documenting files (particularly useful for files containing - many functions) -- ``@defgroup`` used to define groups for organizational reasons -- ``@ingroup`` for associating a file, class, member, *etc.* with a particular - group -- ``@f$ @f$`` for adding on line Latex formulae -- ``@f{eqnarray}{`` for starting a Latex ``eqnarray`` (change the environment - name to get other environments), this environment is ended by ``@f}`` -- ``@note`` for starting a note -- ``@warning`` for displaying a warning to the reader -- ``@bug`` for letting the reader know about a known bug -- ``@relates`` for free-functions associated with a particular class diff --git a/docs/source/conventions/file_structure.rst b/docs/source/conventions/file_structure.rst deleted file mode 100644 index fbe49943..00000000 --- a/docs/source/conventions/file_structure.rst +++ /dev/null @@ -1,145 +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. - -######################################## -File Structure for NWChemEx Repositories -######################################## - -To the extent possible, we want all NWChemEx repositories to follow the same -file structure. Since each repo in the organization is ultimately different, -it will in general not be possible for every repo to be laid out exactly the -same; however, we strive to only deviate from the standard layout when -absolutely necessary. - -***************************************************** -Why Do We Need to Standardize the Repository Layouts? -***************************************************** - -Admittedly, the repository layout adopted by all repositories in the NWChemEx -organization was chosen based on personal preference of the lead developers. -However, now that a standard has been agreed upon it is important that we -adhere to it. In particular, by standardizing the file layout of each -repo we are able to facilitate: - -- Confidence. Well laid out repositories instill a more professional impression - on anyone viewing the repository's files. -- Finding files. Users/developers familiar with the layout of one NWChemEx - repository can quickly and easily find files in another. -- Automation. If all the repositories are laid out the same it is much easier - for CI/CD to maintain them. -- On-boarding new developers. Where possible our layouts adhere to wider - file system standards, standards which are familiar to many developers outside - the NWChemEx organization. By adhering to such standard we lower the barrier - to entry for new developers. - -*********************** -File Naming Conventions -*********************** - -- To avoid pitfalls related to differences in operating system behavior, all - files should be "lower_snake_case", i.e., all lowercase letters, underscores - for separating words. -- It is strongly recommended you stick to letters, numbers, and underscores - only. Notably avoid symbols like ``*``, ``?``, ``(``, ``)``, ``'``, - and ``"``. - -Extensions -========== - -- C++ header files end with ``*.hpp``, e.g., ``file_name.hpp``. -- C++ source files end with ``*.cpp``, e.g., ``file_name.cpp``. -- C++ inline implementation files end with ``*.ipp``, e.g., ``file_name.ipp``. -- CMake modules end with ``*.cmake``, e.g., ``file_name.cmake``. -- (GitHub-flavored) Markdown end with ``*.md``, e.g., ``file_name.md``. -- Python source files end with ``.py``, e.g., ``file_name.py``. -- ReStructured Text files end with ``.rst``, e.g., ``file_name.py``. - - -Exceptions -========== - -The following exceptions to the above file naming conventions are allowed: - -- CMake build systems should be stored in one or more ``CMakeLists.txt``. - - Reason for exception: CMake convention. - - -********************* -Files and Directories -********************* - -In this section we provide a top-down tour of a typical NWChemEx repository's -file structure. - -Root Level -========== - -.. _fig_root_level_files: - -.. figure:: assets/root_files.png - :align: center - - How most (although ideally it should be all) repositories in the NWChemEx- - Project organization look at the root level. - -At the root level, most (although it should ideally be all) repositories in the -NWChemEx organization conform to the layout shown in -:numref:`fig_root_level_files`. As a quick internet search will show (see for -example `here `__) this layout is fairly standard, albeit -universal. We note that using our layout, the only files residing at the -root-level of the repository are there either because they must live at the -root-level (*e.g.*, ``.clang-format``), or are present at the root-level to -emphasize they apply repository wide (*e.g.*, ``LICENSE``). - -.. note:: - - A notable (well explained) argument against our chosen layout can be found - `here - `__. - - -.github Directory -================= - -.. _fig_github_files: - -.. figure:: assets/github_files.png - :align: center - - Basic structure of the ``root/.github/`` directory in most NWChemEx - repositories. - -:numref:`fig_github_files` shows the layout of the ``.github/`` directory in -nearly every repository owned by the NWChemEx organization. The layout -and naming conventions are dictated by GitHub and are thus commonly found in -most GitHub projects. - -docs/ Directory -=============== - -.. _fig_docs_files: - -.. figure:: assets/docs_files.png - :align: center - - Basic structure of the ``root/docs/`` directory in most NWChemEx - repositories. - -The set-up of the directory is driven by Sphinx, which by default assumes all -documentation source lives in ``root/docs/source/``, the configuration file for -Sphinx resides at ``root/docs/source/conf.py``, and automatically creates the -``root/docs/Makefile`` file to facilitate building the documentation. The -remaining files, ``root/docs/requirements.txt`` and ``root/docs/README.md`` are -to respectively facilitate obtaining the dependencies of the documentation and -to instruct the reader on how to build the documentation. diff --git a/docs/source/conventions/index.rst b/docs/source/conventions/index.rst deleted file mode 100644 index 80f80593..00000000 --- a/docs/source/conventions/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. Copyright 2025 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. - -################################# -NWChemEx Organization Conventions -################################# - -The NWChemEx organization consists of a multitude of developers, spread out -across a number of geographic locations. In an attempt to provide a unified -development experience it is important that all developers strive to adhere -to same conventions. The topics in this section cover conventions for writing -code (*i.e.*, coding conventions), and structuring a GitHub repository (*i.e.*, -repository conventions). For organization maintainers, some internal notes on -organizational decisions can be found in the NWChemEx Google Drive folder. - -****************** -Coding Conventions -****************** - -.. toctree:: - :maxdepth: 2 - - cxx_conventions - python_conventions - doxygen_conventions - rst_conventions - pre_commit - -********************** -Repository Conventions -********************** - -.. toctree:: - :maxdepth: 2 - - file_structure diff --git a/docs/source/conventions/pre_commit.rst b/docs/source/conventions/pre_commit.rst deleted file mode 100644 index 9608370d..00000000 --- a/docs/source/conventions/pre_commit.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. Copyright 2025 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. - -.. _pre-commit-configuration: - -###################################### -pre-commmit Configuration for NWChemEx -###################################### - -`pre-commmit `__ is a tool for configuring and -automating `githooks `__, which are a series -of hooks for inserting custom automations into git's operations. The pre-commit -tool takes its name from arguably the most commonly used githook, the pre-commit -hook, that runs when a user attempts to commit changes. The pre-commit tool -provides a simplified syntax for configuring githooks, and has a community of -defined hooks from which to draw. To simplify the process of formatting/linting, -we advise developers to use pre-commit as outlined in the following when working -within the NWX stack. - -The NWX configuration for pre-commit (``.pre-commit-config.yaml``) lives in -`NWChemEx/pre-commit-config `__. -Normally, this YAML file would be expected to live in the root directory of the -repository where pre-commit would be used. NWX is made up of a number of -different libraries in different repositories, so we find it helpful to keep -the configuration file in a centralized location. This methodology does cause -some deviation from the default usage of pre-commit, but not excessively so. - -The first step is to clone NWChemEx/pre-commit-config - -.. code-block:: bash - - git clone https://github.com/NWChemEx/pre-commit-config.git - -It is recommended to use a Python virtual environment when developing NWX -libraries (see :ref:`development_python_development_workflow` for more details). -In a new or existing Python virtual environment, install the required packages -for pre-commit: - -.. code-block:: bash - - cd pre-commit-config - # Make a virtual environment if one doesn't already exist - python3 -m venv .venv - # Activate the virtual environment and install the requirements - . .venv/bin/activate - pip install -r requirements.txt - cd ../ - -When you clone a new repository, you will need to install the pre-commit hooks -for them to take effect. Assuming for the moment that you want to develop code -within the `PluginPlay `__ library, you -would clone that repo and install the pre-commit hooks as follows: - -.. code-block:: bash - - # Clone PluginPlay - git clone https://github.com/NWChemEx/PluginPlay.git - - # Activate a Python virtual environment where pre-commit is installed - . {path/to/}.venv/bin/activate - - # Navigate into the repository where you want to install the hooks - cd PluginPlay - - # Finally, install the pre-commit hooks - pre-commit install -c {path/to/}pre-commit-config/.pre-commit-config.yaml - -At this point, the pre-commit hooks are installed and will run when a ``git -commit`` is attempted. If all hooks pass successfully, the commit should finish -successfully and you should see an output similar to the following: - -.. code-block:: bash - - trim trailing whitespace.................................................Passed - check for added large files..............................................Passed - check python ast.....................................(no files to check)Skipped - check json...........................................(no files to check)Skipped - check for merge conflicts................................................Passed - check xml............................................(no files to check)Skipped - check yaml...........................................(no files to check)Skipped - debug statements (python)............................(no files to check)Skipped - fix end of files.........................................................Passed - fix requirements.txt.................................(no files to check)Skipped - mixed line ending........................................................Passed - yapf.................................................(no files to check)Skipped - clang-format.........................................(no files to check)Skipped - license-eye..............................................................Passed - -When one or more hooks fail, the commit will fail and the failing hooks will be -noted in the printout: - -.. code-block:: bash - - trim trailing whitespace.................................................Failed - - hook id: trailing-whitespace - - exit code: 1 - - files were modified by this hook - - Fixing docs/source/conventions/pre_commit.rst - - check for added large files..............................................Passed - check python ast.....................................(no files to check)Skipped - check json...........................................(no files to check)Skipped - check for merge conflicts................................................Passed - check xml............................................(no files to check)Skipped - check yaml...........................................(no files to check)Skipped - debug statements (python)............................(no files to check)Skipped - fix end of files.........................................................Failed - - hook id: end-of-file-fixer - - exit code: 1 - - files were modified by this hook - - Fixing docs/source/conventions/pre_commit.rst - - fix requirements.txt.................................(no files to check)Skipped - mixed line ending........................................................Passed - yapf.................................................(no files to check)Skipped - clang-format.........................................(no files to check)Skipped - license-eye..............................................................Passed - -When most hooks fail, they will also make the requisite changes to the -corresponding files to allow them to pass. These new changes will need to be -staged for commit via ``git add .`` or equivalent, at which time the commit can -be attempted again. - -It is also possible to manually run the pre-commit hooks: - -.. code-block:: bash - - # With appropriate virtual environment active - pre-commit run --all-files -c {path/to/}pre-commit-config/.pre-commit-config.yaml - -Note, it is required to pass the -``-c {path/to/}pre-commit-config/.pre-commit-config.yaml`` flag each time this -command is run, even if the pre-commit hooks have already been installed. To -simplify this call, the developer may want to define an alias for this command -in their shell configuration. For the bash shell, this could be - -.. code-block:: bash - - alias run_nwx_precommit="pre-commit run --all-files -c {path/to/}pre-commit-config/.pre-commit-config.yaml" - -If at any point you want to remove the installed pre-commit hooks, you can run -``pre-commit uninstall`` within the repo where you want to remove the hooks. diff --git a/docs/source/conventions/python_conventions.rst b/docs/source/conventions/python_conventions.rst deleted file mode 100644 index 887af3d4..00000000 --- a/docs/source/conventions/python_conventions.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. Copyright 2025 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. - -.. _python-coding-conventions: - -************************* -Python Coding Conventions -************************* - -This page tentatively introduces the NWX team's coding conventions for writing -Python. - -.. All pull requests are expected to adhere to these conventions. - -Code Formatting -=============== - -When possible, ``yapf`` (`PyPI link `__) will -be used to enforce code conventions. In general, Python code should be -`PEP 8 compliant `__. - -Docstrings -========== - -A general description of a docstring and standardized conventions are described -in `PEP 257 `__. Docstrings in -NWChemEx are written using the ``Sphinx`` format, described -`here `__. - -Docstrings should be used to sufficiently document Python modules, classes, -and functions, similar to the expectation that C++ code be documented -sufficiently through Doxygen documentation blocks. - -.. note:: - - For IDE tools to help with these conventions, see :ref:`nwx-ide-development`. diff --git a/docs/source/conventions/rst_conventions.rst b/docs/source/conventions/rst_conventions.rst deleted file mode 100644 index eaf6223b..00000000 --- a/docs/source/conventions/rst_conventions.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. Copyright 2025 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. - -.. _rest_conventions: - -########################################## -Conventions for Writing reST Documentation -########################################## - -***** -Style -***** - -The style of reST pages follows Python's -`conventions `__. -In particular: - -- Follow the usual practice of at most 80 characters per line -- Indentation in reST is 3 spaces **NOT** 4 - - - 3 spaces is natural for reST as this aligns with directives - -******** -Sections -******** - -Python's reST -`conventions `__ -for denoting sections are: - -- ``#`` with overline should be used for parts -- ``*`` with overline is for chapters -- ``=`` for sections -- ``-`` for subsections -- ``^`` for subsubsections -- ``"`` for paragraphs - -The exact distinction between "parts", "chapters", *etc*. seems to be based -largely on how nested in the documentation a file is. For example, "parts" would -be topics in the top-level table of contents; in the case of DeveloperTools' -documentation the parts are: Project Conventions, Design Documentation, *etc.*. -Chapters are topics within one of the parts (*e.g.* this page is a chapter in -the Project Conventions part). - -The definitions of parts, chapters, etc. are a bit annoying as they require -changing under/overlines in a potentially large number of documentation files if -andy refactoring occurrs. To avoid this, the NWX project adopts the convention -that definitions of parts, chapters, etc. are file specific. In other words, -the first title in a particular reST file should be considered the title of a -part; the first title within that part is considered a chapter, *etc.*. As a -more concrete example see the raw source for this file. diff --git a/docs/source/design/assets/nwx_developer_install.png b/docs/source/design/assets/nwx_developer_install.png deleted file mode 100644 index af30fc50..00000000 Binary files a/docs/source/design/assets/nwx_developer_install.png and /dev/null differ diff --git a/docs/source/design/energy_workflow.png b/docs/source/design/energy_workflow.png deleted file mode 100644 index 0584601c..00000000 Binary files a/docs/source/design/energy_workflow.png and /dev/null differ diff --git a/docs/source/design/energy_workflow.rst b/docs/source/design/energy_workflow.rst deleted file mode 100644 index 209320ce..00000000 --- a/docs/source/design/energy_workflow.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. Copyright 2025 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. - -*************** -Energy Workflow -*************** - -Arguably the most common calculation performed in an electronic structure -package is the computation of a chemical system's energy. The point of this -page is to discuss the design of how NWChemEx handles the energy workflow. - - -.. figure:: energy_workflow.png - :figwidth: 100 % - :align: center - - Schematic of how NWChemEx computes an energy. diff --git a/docs/source/design/faqs.rst b/docs/source/design/faqs.rst deleted file mode 100644 index 27e59b4b..00000000 --- a/docs/source/design/faqs.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. Copyright 2025 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. - -#### -FAQs -#### - -This page collects frequently asked questions pertaining to NWChemEx's Design. - -************** -Overall Design -************** - -Why So Many Repos? ------------------- - -When transitioning from developing a more traditional electronic structure -package to NWChemEx, one of the first observations developers make is that there -are a lot of repos. The motivation behind this is a separation of concerns and -to enforce a decoupled nature to the source code. Each repo is designed to be a -reusable component. It is our hope that such a code factorization will -facilitate adoption of these components by other codes. Even if our components -are never adopted by other codes, a component-based design still benefits us by -making it easier to refactor if need be. - - -******* -General -******* - -So Where's "NWChemEx"? ----------------------- - -Having a bunch of individual repos is great for developers, but confusing to -users. Users only need to build the ``NWChemEx`` repo. Building this repo will -build all dependencies which are required to have the complete NWChemEx -electronic structure package. The result of building ``NWChemEx`` is a set of -Python bindings. There is no "NWChemEx" executable, rather users use the Python -module. diff --git a/docs/source/design/index.rst b/docs/source/design/index.rst deleted file mode 100644 index de3d143d..00000000 --- a/docs/source/design/index.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. Copyright 2025 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. - -#################### -Design Documentation -#################### - -This section focuses on documentation relating to the overall design philosophy -and implementation of the NWChemEx package. The documentation is laid out to -give you a top-down approach to the design. That is to say it starts very -general and high-level, and as you progress through the design more details are -added. The design documents in this section describe the overall project design, -but do not specify how the components are designed. Consult the documentation of -the individual components for details pertaining to their respective designs. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - philosophy - vision - nwx_ecosystem - overall_design - overall_justifications/index - energy_workflow - ui_design - faqs diff --git a/docs/source/design/nwx_ecosystem.png b/docs/source/design/nwx_ecosystem.png deleted file mode 100644 index 16fda8bf..00000000 Binary files a/docs/source/design/nwx_ecosystem.png and /dev/null differ diff --git a/docs/source/design/nwx_ecosystem.rst b/docs/source/design/nwx_ecosystem.rst deleted file mode 100644 index 5ee00e94..00000000 --- a/docs/source/design/nwx_ecosystem.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. Copyright 2025 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. - -################## -NWChemEx Ecosystem -################## - -In this section we spec out the use cases for NWChemEx and how it fits into the -broader computational chemistry ecosystem. - -****************** -NWChemEx Use Cases -****************** - -Generally speaking we see NWChemEx being used for: - -- electronic structure calculations on the largest supercomputers in the world -- day-to-day electronic structure calculations -- as part of high-throughput workflows -- as a research platform for developing new theories - -At this stage of design we are not concerned with capabilities (e.g. -single-point energies, thermodynamic analysis, molecular dynamics) those will be -handled at a lower level of design. Rather we're interested in what sort of -design requirements need to be built into the highest level APIs. From these -use cases we can establish the following concerns: - -- performance (needed to make running on supercomputers worthwhile) -- high-quality linear algebra (electronic structure involves lots of - linear algebra) -- ease of use (too high of a barrier will inhibit use cases where there are - other choices) -- library instead of program mentality (we shouldn't assume we are driving the - workflow) -- extensibility (adding new theories should be easy) -- varying levels of programming expertise (research is done by undergraduates, - graduates, post docs, scientists/professors from a multitude of backgrounds) - -These concerns are not orthogonal (for example ease of use and varying levels of -programming expertise are related). - -************************** -Overall Software Ecosystem -************************** - -The following figure serves as a brief introduction to how NWChemEx addresses -the aforementioned concerns as an organization, how the key pieces of the -NWChemEx design fit together, and how the NWChemEx organization fits into the -broader software ecosystem. - -.. figure:: nwx_ecosystem.png - :figwidth: 100% - :align: center - - Coarse overview of the NWChemEx software stack and its connections to other - key stake holders in the broader community. - -As a disclaimer, this figure is very coarse. A lot of the stack's complexity is -swept up into each of the boxes (particularly the "Internal Module Collections" -box, which includes pretty much every electronic structure method that NWChemEx -supports). - -Performance key points: - -#. Internal components of NWChemEx written in C++ to take advantage of the - growing HPC support for C++ and to provide developers a performance focused - coding language. -#. Performance is treated as a fundamental concern entering into the stack as - part of the low level ParallelZone component. -#. ParallelZone acts as a sort of domain-specific language (DSL) for the rest of - the NWChemEx stack, abstracting away much of the implementation details -#. Much of the actual scheduling, data movement, etc. is handled by the - externally maintained MADNESS runtime and the libraries underlying it. - -Linear algebra key points: - -#. Linear algebra is the among the second lowest components of the stack, - entering via Chemist. -#. Like ParallelZone, Chemist provides abstractions which allow the rest of the - stack to express its linear algebra needs in a sort of DSL without worrying - about the underlying details. -#. Efficient and performant linear algebra and tensor-related operations are - provided by TiledArray. - -Ease of use key points: - -#. The tiered stack makes it easier to hide details. -#. The focus on DSLs at each layer lowers the barrier to entry as code looks - more like what its modeling and less abstract. - - -Component mentality key points: - -#. User facing APIs are written in Python to take advantage of its popularity in - scientific software (particularly in workflows) -#. PluginPlay provides NWChemEx's abstractions for interacting with software - components. -#. The bulk of NWChemEx's capabilities are provided by its internal module - collection, which PluginPlay can run. -#. Other chemistry codes can link to any of our internal module collections and - use any module in that collection. - -Extensibility key points: - -#. Developers outside the organization can write modules, which can then be - immediately used with the NWChemEx software stack via PluginPlay. -#. Adding modules does not require modifying NWChemEx - -Varying programmer expertise key points: - -#. The focus on abstraction allows each layer to hide many of the technical - details of the layer below it. These details are not lost, they are rolled up - into opaque objects which get unrolled as they traverse the stack. -#. By time someone considers a layer like SimDE they are typically using objects - like wavefunctions, molecules, and orbitals to express their computation - rather than tensor ops or MPI calls. diff --git a/docs/source/design/overall_design.png b/docs/source/design/overall_design.png deleted file mode 100644 index 17cc468b..00000000 Binary files a/docs/source/design/overall_design.png and /dev/null differ diff --git a/docs/source/design/overall_design.rst b/docs/source/design/overall_design.rst deleted file mode 100644 index 688b3ab3..00000000 --- a/docs/source/design/overall_design.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. Copyright 2025 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. - -############## -Overall Design -############## - -The point of this page is to explain the philosophy, organization, and overall -design of the NWChemEx software stack. - -****************************** -NWChemEx Organization Overview -****************************** - -The NWChemEx organization manages a lot of repositories. Generally speaking -those repositories fall into one of two groups: the framework known as the -simulation development environment, or SimDE for short, and the NWChemEx -electronic structure package. The breakdown is shown in the following figure: - -.. figure:: overall_design.png - :figwidth: 100 % - :align: center - - Diagram of the overall NWChemEx Design - -It's worth noting that each repo is capable of being used as an independent -product (aside from the repos it depends on). Generally speaking, however, we -anticipate most people will interact with the stack in one of three ways: - -#. They are writing an external module, in which case they will pull the SimDE - repo and use it as a dependency; -#. They are writing an internal module, in which case they will pull the - NWChemEx repo and the module collection they are adding the module to; or -#. They are running NWChemEx, in which case they will only pull the NWChemEx - repo. - -These three use cases underlie why we have place an emphasis on the SimDE and -NWChemEx repos. The following subsections describe the SimDE and NWChemEx groups -of repos in more detail. - -SimDE -===== - -SimDE encapsulates the infrastructure required to: -- interact with the hardware, -- manage and run modules, -- model and express commonly occurring computational chemistry concepts, and -- define the APIs used to compute properties - -SimDE is intended to have APIs that are long-term stable. This is important for -ensuring modules remain interoperable with the framework for a long time. The -goal is to get SimDE to a point where most developers will only interact with -SimDE, and will not need to perform development on it. The main exception being -the addition of standardized APIs for new properties. - -Conceptually you can think of SimDE as being akin to a typical smartphone -operating system, but targeting computational chemistry. Like a smartphone OS, -SimDE manages a bunch of apps (which we call modules), takes care of inter-app -communication (passing data among the modules), and automates more mundane tasks -(like logging and saving results). SimDE is extensible in that new modules and -communication protocols can be added downstream from it, even at runtime. -Specifically the design of SimDE is such that downstream developers don't need -to modify any source code of SimDE to extend it. - -This generality and flexibility comes at the cost of complexity. While design -efforts have striven to make SimDE as simple as possible, the reality is that it -is still quite verbose from a typical electronic structure user's perspective. -It is the responsibility of whatever sits on top of SimDE to provide more -user-friendly APIs (in addition to the module functionalities). More complicated -workflows can always directly access SimDE for finer-grained control. - -The main components of SimDE are summarized in the following table: - -============== ====================================================== -Repository Description -============== ====================================================== -Utilities General classes/functions, i.e. our own personal Boost -ParallelZone The runtime abstraction layer -PluginPlay Framework for working with plugins -Chemist Chemistry specific classes, used to define APIs -SimDE Definitions of APIs, top-level repo for SimDE -============== ====================================================== - - -NWChemEx -======== - -The NWChemEx electronic structure theory package is itself made up of two main -components: a series of modules for use with SimDE and a user-friendly API for -running those modules. If we continue the smartphone analogy, the modules -provided by NWChemEx are first-party apps (for Android users think GMail, Google -Calendar, Chrome, *etc.*; iPhone users think Mail, iCal, Safari, *etc.*). SimDE -doesn't limit you to the modules which come from NWChemEx, and developers are -free to write their own modules to use with the NWChemEx package. From the -perspective of SimDE, where a module comes from doesn't matter, *i.e.*, modules -that are part of NWChemEx are treated no differently than modules that are not -part of NWChemEx. - -Finally in the smartphone analogy, the user-friendly API of NWChemEx is similar -to the graphical user interface your phone provides. When you click on a street -address in an email app and it brings up the location in your map app, you don't -really think about how the apps communicated or what library calls were needed -to make that happen. Similarly, when you tell NWChemEx to compute the energy of -a molecule, through the user-friendly API, you don't have to think about how -that request gets dispatched through the modules and libraries underlying -NWChemEx. - -The main components of NWChemEx are summarized in the following table: - -============== ======================================================= -Repository Description -============== ======================================================= -Mokup Hard-coded tensorial data used for unit testing -Integrals Modules for computing integrals with AOs -SCF Modules related to Hartree-Fock and DFT -MP2 Modules related to Moller-Plesset perturbation theory -TAMM-SDE An assortment of modules which use TAMM instead of TA -ChemCache Hard-coded physical data and basis sets -NWChemEx The top-level repo which provides the user-friendly API -============== ======================================================= - -Miscellaneous Repositories -========================== - -The NWChemEx organization contains a number of additional "meta" -repositories that are not directly required for building NWChemEx. These repos -are typically associated with a particular research project, provide CI -infrastructure, or in some other way support the project without being source -code. The following table summarizes these repositories. - -============== ========================================================== -Repository Description -============== ========================================================== -DeveloperTools Developer documentation and tools for maintaining NWChemEx -Publications Manuscripts written by the NWChemEx team about NWChemEx -============== ========================================================== diff --git a/docs/source/design/overall_justifications/assets/plugin_exposure.png b/docs/source/design/overall_justifications/assets/plugin_exposure.png deleted file mode 100644 index 8b48a9fe..00000000 Binary files a/docs/source/design/overall_justifications/assets/plugin_exposure.png and /dev/null differ diff --git a/docs/source/design/overall_justifications/assets/simde_exposure.png b/docs/source/design/overall_justifications/assets/simde_exposure.png deleted file mode 100644 index 95cf0048..00000000 Binary files a/docs/source/design/overall_justifications/assets/simde_exposure.png and /dev/null differ diff --git a/docs/source/design/overall_justifications/assets/user_api.png b/docs/source/design/overall_justifications/assets/user_api.png deleted file mode 100644 index ab19a716..00000000 Binary files a/docs/source/design/overall_justifications/assets/user_api.png and /dev/null differ diff --git a/docs/source/design/overall_justifications/index.rst b/docs/source/design/overall_justifications/index.rst deleted file mode 100644 index 18888a2d..00000000 --- a/docs/source/design/overall_justifications/index.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. Copyright 2025 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. - -############################ -Overall Design Justification -############################ - -Now that we have introduced the overall design, the topics in this part attempt -to justify the major decisions. If you don't care why the decisions were made -the way they were, feel free to skip these sections. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - why_oop - will_this_perform - why_cxx - why_python - py_bindings - one_repo_vs_many - why_pluginplay - why_simde - why_chemcache - why_mokup - why_this_partitioning - why_two_tensor_libraries diff --git a/docs/source/design/overall_justifications/one_repo_vs_many.rst b/docs/source/design/overall_justifications/one_repo_vs_many.rst deleted file mode 100644 index 79a96441..00000000 --- a/docs/source/design/overall_justifications/one_repo_vs_many.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. Copyright 2025 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. - -################################# -Why not Just Have One Giant Repo? -################################# - -Most of the electronic structure packages in the field have a single monolithic -code base. When transitioning to NWChemEx from one of those packages it is not -uncommon to be taken aback by the number of repositories that NWChemEx -maintains. Surely this just complicates things right? - -As you can probably guess, we argue that it does not add any additional -complexity (at least in the long run). While it may take you some time to come -up to speed with what's in each repo, we argue you have to do the same thing -with a monolithic code base too. In the case of a well organized, but single -repo electronic structure package, you have to learn what's in each library -(or module for Python packages). Repos in the NWChemEx project map to the -same level of granularity. Basically they collect a set of related -functionalities into a single component. - -The motivation for going beyond separate libraries to separate repos is to -automate, to an extent, the enforcement of our library separation. Basically -since each repo must compile and pass CI, given only its immediate dependencies -we know that we have not introduced a cross-coupling between what are supposed -to be independent components. If they were simply libraries, which we linked -into one executable, then its possible for someone to break the separation by -say calling PluginPlay from Chemist. The resulting code would still compile and -unless it was caught in the code review process, we'd have an unexpected -dependency. It's of course possible to make Chemist call PluginPlay with our -design, but to do so would require a significant amount of additional work ( -versus just adding a header file). - -With the guarantee that our components really our separate components, we can -market them as individual products. This is useful for collaborative work, -where someone may just want say our SCF algorithm, but not the rest of the code. -By only pulling what they want, they avoid introducing a lot of extra code -bloat (the MP2, coupled-cluster, etc.). Sure it's possible to accomplish the -same thing with build system logic, but once you've spent an extensive amount of -time writing build system logic, you try to avoid complicating it any more than -you need to. - -Another advantage to our multi-repo set-up is that we have orthogonal -workspaces. This is useful for organizing documentation, conversations, bug -tracking, issues, etc. It ultimately keeps the discussion closer to the code -versus having it all in a single place. In our opinion this also makes things -less daunting. diff --git a/docs/source/design/overall_justifications/py_bindings.rst b/docs/source/design/overall_justifications/py_bindings.rst deleted file mode 100644 index 135ddab0..00000000 --- a/docs/source/design/overall_justifications/py_bindings.rst +++ /dev/null @@ -1,492 +0,0 @@ -.. Copyright 2025 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. - -######################################### -Design of the Python Binding Architecture -######################################### - -Section :ref:`why_is_the_nwchemex_api_written_in_python` discusses why we want -a Python API for NWChemEx. This page records the decisions which went into -designing NWChemEx's Python bindings. - -************************* -What are Python bindings? -************************* - -Presently, by "Python bindings" we are specifically referring to code forming -an interoperability layer between C/C++ code and Python. This layer allows -Python objects, functions, data, etc. to seamlessly interact with C++ objects, -functions, data, etc. and vice versa. - -******************************* -Why do we need Python bindings? -******************************* - -Following from the design discussion in -:ref:`why_is_the_nwchemex_api_written_in_python`, NWChemEx's high-level API is -assumed to be Python-based, but the guts of NWChemEx are written in C++. Hence, -to expose the C++ guts to Python we will need to write Python bindings. - -.. _pb_considerations: - -***************************** -Python Binding Considerations -***************************** - -In creating our Python bindings, and choosing the library to help us create the -bindings, we have identified the following considerations: - -.. _pb_diff_lang: - -Different languages - Fundamentally Python and C++ are different coding languages. They rely on - different assumptions, have different designs, are fundamentally - implemented different, and embrace different coding paradigms. The point is - there is no perfect one-to-one mapping between C++ and Python and the - developer may need to step in to ensure the conversion happens in the manner - best aligned with the specific interface. - - - While Python and C++ have no one-to-one mapping, the reality is that there - is a "pretty obvious" mapping for many of the features. Our solution should - be easy to apply, if not automatic, for such features. - -.. _pb_features: - -Full featured - We expect that C++ developers will use the full extent of the C++ language - and that Python developers will too. We thus reject solutions which require - the developer to limit the features they use throughout the code. - - - Combined with :ref:`pb_diff_lang` we must also acknowledge that at the - C++/Python API we may need to limit language features in order to perform - the handoff. Once the handoff is accomplished, solutions which satisfy - :ref:`pb_features` will allow users to resume using the full feature set - of the respective language. - -.. _pb_native_apis: - -Native APIs - C++ APIs should be defined purely using C++, and Python bindings should be - defined purely with Python. Any conversions needed to go from one language to - the other should happen under the hood. - - - In practical terms, this means that Python users should not need to worry - about pointers, templates, references, etc. and C++ users should not - have to worry about the GIL (Python's global interpreter lock), garbage - collection (on the Python side), etc. - -.. _pb_minimally_invasive: - -Minimally invasive - Ideally Python bindings should be created in the least invasive manner - possible. The ideal solution will live organically with the existing C++ - source files or exist in Python. Namely we want to avoid solutions which - require us to rely on too many external tools, or intermediate markup - languages. - - - We particularly want to avoid source-to-source translators as they have a - tendency to have underwhelming performance and limited feature sets. - - As a corollary, it is fine if the tool internally uses an intermediate - representation; :ref:`pb_minimally_invasive` is really focused on avoiding - making the developer produce a representation of the code in a language - other than C++ or Python. - -.. _pb_maintainable: - -Easily maintained - As NWChemEx grows we expect the API to grow as well. Python bindings will - need to be created for the new APIs and ideally whatever Python binding - solution we go with should be accessible to developers and easily extendable. - -.. _pb_supported: - -Active support - Our goal is for the Python bindings of NWChemEx to live for as long as the - NWChemEx project does. This requires our Python binding solution to also be - maintained over the course of this time period. The ideal solution should be - well supported, not only in terms of development, but also in terms of - documentation and/or StackOverflow-like help. - -.. _pb_existing_choices: - -**************** -Existing Choices -**************** - -Writing bindings directly with Python's C API is a tedious task. For that -reason, a variety of software libraries/packages have been created with the -intent of aiding in generating Python bindings. They are listed below (in -alphabetical order) along with brief summaries. - -.. note:: - - Obligatory disclaimer. We are NOT experts in all of the packages listed in - this section. The summaries have been assembled based on documentation and - examples provided by the packages. We have done our best to accurately - reflect the state of these packages, but it is possible that what we have - inferred does not actually represent the state of the packages. We also - acknowledge that the descriptions for packages we have used are heavily - biased based on our experiences with those packages. - -Boost.Python -============ - -- GitHub: https://github.com/boostorg/python - - - 28 watchers - - 396 stars - -- Docs: http://boostorg.github.io/python/doc/html/index.html - -Boost.Python was one of the "OG" binding libraries to rely on template meta- -programming to dramatically simplify the process of binding C++ code. Its -inclusion in the Boost libraries makes it a very heavy dependency (if your code -does not already use Boost). At this point in time, the C++ community -overwhelming seems to prefer :ref:`pybind11` over Boost.Python, but Boost.Python -continues to be maintained largely for backwards compatibility. - -Pros: - -- Part of the Boost libraries (not going anywhere any time soon). -- Very robust library. - -Cons: - -- Part of the Boost libraries (heavy dependency). -- Performance. :ref:`pybind11` (an admittedly very biased source) seems to - suggest that in order to live up to Boost's lofty standards the performance - of the bindings suffer. - -C Foreign Function Interface (CFFI) -=================================== - -- Docs: https://cffi.readthedocs.io/en/latest/ - -TODO: Look at CFFI - -.. _cppyy: - -Cppyy -===== - -- GitHub: https://github.com/wlav/cppyy - - - 9 watchers - - 255 stars - -- Docs: https://cppyy.readthedocs.io/en/latest/index.html - -Cppyy :cite:`cppyy16` piggybacks off of the LLVM suite of tools to fully -automate the creation of dynamic Python bindings. In practice, the automatic -bindings are created using Cppyy's own one-to-one mapping between C++ and -Python. It is worth noting, that because of :ref:`pb_diff_lang`, this one-to-one -mapping is not unique and represents the preferences of the Cppyy maintainers. - -Pros: - -- Bindings are generated automatically. No boilerplate!! -- Use of LLVM makes it future-proof (bindings evolve with the compilers). -- Supports packaging bindings for distribution. -- Used by a number of high-profile projects at CERN. - -Cons: - -- Appears to have more or less a single maintainer. -- Tied to LLVM. If underlying C++ is not compiled with LLVM, you are forced - to mix compilers. -- Automatically generated bindings are not Pythonic. - - - Bindings are in ``cppyy.gbl`` namespace, not the package's namespace. Must - be extracted as part of the package's initialization. - - Leaks purely C++ concepts like pointers, references, and templates into - Python. Package maintainers must write Python wrappers around the bindings - to avoid leaking these concepts to the user. - -- Bindings learned from inspecting headers, which, especially for template - classes/functions, have a tendency to leak a lot of low-level APIs (take a - look at how much code is included just by doing ``#include ``). -- The exact process of how Cppyy forms its one-to-one mapping between C++ and - Python is not easily grasped without familiarity with LLVM's internal - representation. - - - As a corollary, determining when Cppyy's binding decisions need to be - overridden is tricky for most package maintainers and in practice requires - extensive unit, integration, and acceptance testing of the generated - bindings in order to determine when expectations differ. - -- Choosing what gets exposed needs to be done on a per file basis, *i.e.*, if - you don't want the contents of a file to be exposed to Python, don't let - Cppyy process that file. This may require refactoring C++ source code in - order to hide files. - -- Packaging bindings, so they do not need to be generated on-the-fly each run - and can be reliably distributed is complicated and somewhat poorly documented. - - - It appears to require using rootcling (a seemingly niche tool), or genreflex - (which appears to be a wrapper around rootcling). This process is somehow - related to "Dictionaries" (not in the Python sense), XML selection files, - and rootmap files. How this all comes together is not really clear. - -- Cppyy seems to acknowledge the packaging problems (see - `here `__) and - provides a CMake solution; however, it is not compatible with modern - CMake practices (namely target-based build systems). - -ctypes -====== - -- Docs: https://docs.python.org/3.8/library/ctypes.html - -TODO: Look ctypes over. - - -Cython -====== - -- Docs: https://cython.org/ - -TODO: Look Cython over - -nanobind -======== - -- GitHub: https://github.com/wjakob/nanobind - - - 27 watchers - - 1.4K stars - -- Docs: https://nanobind.readthedocs.io/en/latest/ - -nanobind :cite:`nanobind` is from the original author of pybind11 and was -started because he wanted to create a more streamlined, more performant python -binding library, while still supporting pybind11. The API and usage of -nanobind is largely the same as pybind11 - -Pros: - -- Better performance compared to Boost.Python and pybind11. -- Essentially a subset of pybind11 (if nanobind becomes vaporware, can easily - fall back to pybind11) - -Cons: - -- Same as pybind11: verbose boilerplate and manual exposure of C++. -- Relatively new project, could turn into vaporware. -- At present expects you to install via pip (does not easily integrate with - CMake). - - -.. _pybind11: - -pybind11 -======== - -- GitHub: https://github.com/pybind/pybind11 - - - 244 watchers - - 12.6K stars - -- Docs: https://pybind11.readthedocs.io/en/stable/ - -pybind11 :cite:`pybind11` has largely replaced Boost.Python as the predominant -mechanism for exposing C/C++ code to Python. The API of pybind11 is modeled -after that of Boost.Python, but is significantly simpler on account of pybind11 -requiring minimum C++11 (Boost.Python is based on C++03). More specifically, -using C pre-processor macros, users register the C++ classes and functions they -want to expose to Python. pybind11 then creates the Python bindings based -on the information provided during the registration process. - -Pros: - -- Heavily used, widely supported. -- Used in Tensorflow and PyTorch. -- More lightweight than Boost.Python. -- Header-only. -- Bindings are rolled into C++ library for easy packaging. - -Cons: - -- Verbose C++ boilerplate for exposing C++. -- Exposing C++ classes and functions must be done manually. -- Template-based API may be off putting to inexperienced C++ developers. - -PyBindGen -========= - -- Docs: https://pybindgen.readthedocs.io/en/latest/ - -TODO: Analyze - -Shiboken -======== - -- Docs: https://doc.qt.io/qtforpython-6/shiboken6/index.html - -TODO: Analyze. - -SIP -=== - -- Docs: https://www.riverbankcomputing.com/static/Docs/sip/introduction.html - -TODO: Take a better look at SIP - -SWIG -==== - -- Website: https://swig.org/ - -TODO: Look into SWIG. - - -******************************** -NWChemEx Python Binding Strategy -******************************** - -This section describes the evolution of the NWChemEx design strategy for Python -bindings. - -Original Design -=============== - -pybind11 was the original choice and was preferred to Boost.Python on account -of the fact that, at the time, the NWChemEx team was trying to avoid -adding Boost to the stack. A number of team members, had had previous -experience with pybind11 which facilitated the decision. - -Migration to Cppyy -================== - -After work had begun on the initial bindings, the existence of Cppyy was noted -and the decision was then made to switch to Cppyy to take advantage of its -automatic bindings. The initial design was relatively simple, a CMake module -was written that takes as input a target to expose. The CMake module then -traverses the include tree discovering the C++ API of the library, and generates -a ``__init__.py`` file for the library. A simple Python ``import`` statement -is then all that is necessary to use the library from Python. - -Combined Pybind11/Cppyy -======================= - -In practice, trying to manage Cppyy through a generated ``__init__.py`` file -led to a somewhat substantial amount of CMake infrastructure aimed at performing -introspection of the C++ project. Furthermore, despite several years of -development, this CMake infrastructure still did not satisfy all of the -considerations raised in :ref:`pb_considerations`. Notably, the CMake -infrastructure did not satisfy :ref:`pb_native_apis`. In practice, Cppyy -suggests two mechanisms for addressing :ref:`pb_native_apis`: pythonizations -and writing a wrapper layer. Neither of these solutions are CMake-based -(pythonizations are C++-based and the wrapper layer is Python-based). - -The need to write C++-based, or Python-based, binding code somewhat negates the -main benefits of Cppyy over projects like pybind11. Combined with the NWChemEx -team's poor understanding of the LLVM stack, and tools like rootcling, it was -decided that to make progress in a timely manner we would adopt a two-tiered -solution to Python bindings. For the parts of the stack where Cppyy would need -to be wrapped (either by pythonizations or by a Python wrapper layer) we -instead opted to expose those parts with pybind11 (which we were already -familiar with). For the remainder of the stack we will continue to use Cppyy. -This is summarized below. - -SimDE Bindings --------------- - -.. _fig_simde_exposure: - -.. figure:: assets/simde_exposure.png - :align: center - - Current status of pybind11 Python bindings for SimDE. - -:numref:`fig_simde_exposure` summarizes the binding status of SimDE as of this -writing. At the lowest level of the stack, ParallelZone, Python users are able -to see -the available hardware resources, get/set an MPI communicator, and access the -logger. All other ParallelZone operations, such as using the object-oriented -MPI bindings and the task scheduler are currently restricted to the C++ side of -things (it is assumed at present that Python users will want to use MPI4Py for -their Python MPI needs, which handles many of the nuances of HPC Python). -At the PluginPlay level we have exposed ``ModuleBase`` (and thus the -ability to create modules from Python), the fields (the inputs/results to the -module), the ``ModuleManager``, and the API for loading plugins. At the Chemist -level we have right now only exposed the classes related to the chemical -system (``Atom``, ``Nucleus``, ``Molecule``, ``Nuclei``, and -``ChemicalSystem``). The plan is to eventually expose all classes in Chemist to -Python. Finally, in SimDE we expose each property type. It is worth noting that -exposing a property type can be largely automated and PluginPlay provides a -macro to automate this process; in order to work, the macro only needs the C++ -type of the property type (assuming the types comprising the property type's -API are already exposed, which they will be if they are in Chemist). - -Plugin Bindings ---------------- - -.. _fig_plugin_exposure: - -.. figure:: assets/plugin_exposure.png - :align: center - - Summary of how plugins are exposed to Python/C++. - -:numref:`fig_plugin_exposure` shows the proposed mechanism for exposing plugins -based on SimDE. C++/Python plugins are interoperable with Python/C++ via the -plugin API PluginPlay exposes. This API amounts to a single line of code that -the plugin must call in order for the plugin's API to be exposed to both C++ -and Python. As for the modules in the plugin, PluginPlay only interacts -with a module through ``ModuleBase`` and the property type the module satisfies. -Given that ``ModuleBase`` has been exposed to Python already, this means that -as long as the property type has been exposed to Python (which in turn requires -exposing the classes defining the API), the module is callable from Python or -C++ regardless of what language it is written in. In summary, for many C++ -plugins Python bindings can be automatically generated with a single line of -code. - -User API --------- - -.. _fig_user_api: - -.. figure:: assets/user_api.png - :align: center - - Summary of user API interactions with Python bindings. - -PluginPlay, and the plugins built on it, are meant as a developer/power-user -API. The module system gives the user full control over the computation. For -many use cases, this level of control is very daunting, and it is in NWChemEx's -best interest to provide an end-user-friendly API which hides the full -complexity of PluginPlay. The full details of the UI are beyond the scope of -this page, here what we focus on is how that UI will interact with the rest of -NWChemEx. - -The core of NWChemEx interacts with the UI according to :ref:`fig_user_api`. -Here the UI is simply labeled as driver, but it need not actually be a driver -in the classical sense. As :ref:`fig_user_api` shows the UI is envisioned as -being written entirely in Python. It therefore can only interact with the rest -of NWChemEx through the Python bindings. Relevant to the UI, the Python bindings -of SimDE will expose: ``ModuleBase``, ``ModuleManager``, and property types for -commonly requested quantities. The UI is thus responsible for going from -traditional inputs (think cartesian coordinates, atomic basis set, and some -basic parameters), to a call graph, to the result of executing the call graph. -The UI could then conceivably be used to power an instance of MolSSI's QCEngine. -An alternative would be to use QCEngine as the UI and not write the driver at -all. - -*********************************** -References and Additional Resources -*********************************** - -- `This `__ tutorial covers - some of the other options available in more detail and was used to partially - populate the list in :ref:`pb_existing_choices`. diff --git a/docs/source/design/overall_justifications/why_chemcache.rst b/docs/source/design/overall_justifications/why_chemcache.rst deleted file mode 100644 index 579c2fa2..00000000 --- a/docs/source/design/overall_justifications/why_chemcache.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. Copyright 2025 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. - -######################### -Why Do We Need ChemCache? -######################### - -Inevitably NWChemEx will need access to hard-coded data. Typically this data is -physical data (for example fundamental constants, atomic masses, etc.) or model -parameters (for ab initio calculations the atomic basis sets). We have opted to -store such data in the ChemCache repo. This section describes this decision in -more detail. - -The need for ChemCache is fueled by several points: we want all of the -hard-coded data used in NWChemEx to come from a single source of truth, users -may want to use their own hard-coded data, and we want to version control the -hard-coded data we use. diff --git a/docs/source/design/overall_justifications/why_cxx.rst b/docs/source/design/overall_justifications/why_cxx.rst deleted file mode 100644 index 178d985d..00000000 --- a/docs/source/design/overall_justifications/why_cxx.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. Copyright 2025 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. - -.. _why_is_cxx_the_primary_language_of_nwchemex: - -############################################ -Why is C++ the Primary Language of NWChemEx? -############################################ - -:ref:`why_object_oriented_programming` explained our justification for using -object-oriented programming paradigms. This limits our choice of primary coding -languages to those which support OOP practices. We ultimately chose to go with -C++, in short because it is the popular language which still allows us to -achieve performance. This subsections below provide more details. - -**************** -Why Not Fortran? -**************** - -Fortran 2003 added support so that derived types can encapsulate both data and -features; furthermore derived types support inheritance. That's all the basic -underpinnings of OOP. The original NWChem was written in Fortran so writing -NWChemEx in Fortran would allow us to reuse NWChem source in NWChemEx and still -have OOP. Hence the titular question, why not Fortran? - -The answer is going to ruffle some feathers, but Fortran (and FORTRAN; if you're -unaware FORTRAN distinguishes the legacy use of the language, typically defined -as before the 1990 revision, from Fortran, the modern use of the language) has -become a bit of a niche language. At this point saying Fortran is dying is -perhaps an overstatement since inertia seems to be preventing Fortran use -from declining further, hence preventing it from truly dying. That said, there -is not a large flux of incoming Fortran programmers. Most computer science -students have not learned it, and a growing number have never even heard of it. -For what it's worth students right now are typically learning Java, Python, -and/or C/C++. Vendor support is waning, as vendors right now are primarily -interested in ensuring legacy codes run, rather than spending large efforts -optimizing the compiled code. Even the champions of Fortran, the HPC community, -are moving away from it (e.g. look at the number of Exascale Computing Projects -which use C/C++ vs. Fortran). - -Even if the previous paragraph doesn't dissuade you from the merits of writing -NWChemEx in Fortran, the reality is there is a severe lack of third-party -libraries written in Fortran. Particularly missing are Fortran libraries -supporting OOP. Thus we would need to reinvent a large number of wheels just to -use OOP and Fortran. Admittedly, compared to Java or Python, the number -of third-party C++ libraries is also not great, but support seems to be there -for most needs. - -*************** -Why Not Python? -*************** - -Python is right now one of the most popular languages, if not the most popular -language, in the world. With it's easy to learn syntax, abundance of tutorials, -and its plethora of modules, what's not to love? Furthermore Python is quickly -becoming the de facto language of choice for most scientific workflows and tools -that are not performance driven. So why not the lovable Python? - -The big reason is our focus on HPC. At the moment anecdotal evidence suggests -that Python is about 100x slower than C++. Of course this depends on the exact -problem, the programmer's competency level, the Python implementation, the -C++ compiler, etc., but the point remains there's a significant overhead for -using Python versus C++. For a workflow that could be run in a millisecond in -C++, do most people care if in Python it now takes a tenth of a second? No, it's -almost imperceptible. However, if you have to do that call a million times -you've now made something which should take about 15 minutes, take over a day. -It's for this reason that a lot of performance critical pieces of Python still -rely on compiled code under the hood (e.g. NumPy). Even PySCF, the champion of -Python in computational chemistry, contains a significant amount of C under the -hood. So the point remains that Python just isn't at a point where it's suitable -for HPC, at least at the moment. Who knows, in 10 years this might change. - -************* -Why Not Java? -************* - -Like Python, Java is also one of the most popular languages in the world right -now. It's one of the most taught, if not the most taught language in the world. -Pretty much every computer science student knows Java. So why did we decide to -not go with Java? - -The short answer is Java never seemed to catch on in HPC or scientific computing -for whatever reason (at least in the computational chemistry circles), and we -don't have any motivation to go against this trend. As for why Java hasn't -caught on, we can wager a guess that because FORTRAN to C isn't a big jump, when -people started shedding FORTRAN, C seemed welcoming. If you want to go a step -further and embrace OOP, then C++ is the next logical jump from C. Which may be -why C/C++ seem to be emerging as the HPC languages of choice. It probably also -helps that C++ came out about a decade before Java, so by time Java came out -there was already investment in C++. Particularly from the HPC perspective, Java -also leaves a lot to be desired as the underlying runtime is quite heavy. - -************ -Why Not XXX? -************ - -Look, there's a ton of other languages. We're not going to claim that we -evaluated every single one of them and ultimately decided that C++ was the best. -It's entirely possible that in 10 years we're going to regret our C++ decision -and really wish we went with Julia or something. We took a look at the languages -commonly being used in HPC (Fortran, C, C++, and Python) and based on the -explanations in the previous sub-sections we opted for C++. diff --git a/docs/source/design/overall_justifications/why_mokup.rst b/docs/source/design/overall_justifications/why_mokup.rst deleted file mode 100644 index 7a5d79cf..00000000 --- a/docs/source/design/overall_justifications/why_mokup.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. Copyright 2025 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. - -##################### -Why Do We Need Mokup? -##################### - -Basically, why not just call a module? diff --git a/docs/source/design/overall_justifications/why_oop.rst b/docs/source/design/overall_justifications/why_oop.rst deleted file mode 100644 index 389abc40..00000000 --- a/docs/source/design/overall_justifications/why_oop.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. Copyright 2025 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. - -.. _why_object_oriented_programming: - -################################ -Why Object-Oriented Programming? -################################ - -The decision has been made to use object-oriented programming (OOP) throughout -NWChemEx. This page explains why. - -The summary: OOP is, in our opinion, easier to use for encapsulation and -extending the code. - -Dating back to the earliest electronic structure codes, there has been a strong -propensity for using functional programming (FP) paradigms. Even some of the -modern codes which purport to adhere to OOP have very strong FP components (vide -infra). Furthermore, FP is the work horse of high-performance computing (HPC). -So why go against the grain? - -********* -FP vs OOP -********* - -Let's start with the difference between FP and OOP. For this purpose let's -consider a simple application. We want: - -- A general API for computing the area of a shape -- For simplicity we only worry about squares and triangles, but the design - should be extensible. -- Computing the area should be a separate concern from determining which formula - to use (if computing the area was harder this would make it easier to optimize - a specific area formula without disturbing the rest of the code). - -The FP approach may come up with something like: - -.. code-block:: c++ - - double triangle_area(double base, double height) { - return 0.5 * base * height; - } - - double square_area(double base, double height) { - return base * height; - } - - double compute_area(int n_sides, double base, double height) { - if(n_sides == 3) return triangle_area(base, height); - if else(n_sides == 4) return square_area(base, height); - /* if you get here raise an error in your favorite way (error code, or - crash)*/ - } - -and the OOP approach might come up with: - -.. code-block:: c++ - - struct Shape{ - Shape(double base, double height) : m_base(base), m_height(height) {} - virtual double compute_area() = 0; - - double m_base; - double m_height; - }; - - struct Triangle : Shape { - Triangle(double base, double height) : Shape(base, height) {} - double compute_area() { return 0.5 * m_base * m_height; } - }; - - struct Square : Shape { - Square(double base, double height) : Shape(base, height) {} - double compute_area() { return 0.5 * m_base * m_height; } - }; - -The primary difference between the approaches is that in the FP approach the -problem is solved primarily by using functions, whereas in the OOP approach its -solved by defining and implementing objects. - -Comparing the two examples one may note: - -- Both succeed in achieving the desired encapsulation -- Extending either approach is about the same amount of work (define a new - function, register it) -- The FP approach is arguably simpler (less lines, no abstractions) -- The OOP is less-coupled (can just derive a new class, no need to - change ``Shape``). The FP approach requires modifying the ``compute_area``. - -Admittedly one may try to dismiss the last point by pointing out that -``compute_area`` could be modified to take a list of callbacks and a list of -what shape those callbacks are for. This is a valid point; however, it's perhaps -worth nothing this is basically a manual implementation of inheritance and -arguably brings with it the complexities of OOP most FP programmers are trying -to avoid in the first place. - - -Additional FP vs. OOP Remarks -============================= - -Particularly if you look at an article like -`this one `__, -you may see a number of additional FP vs. OOP comparisons. Largely based on the -aforementioned article some of the other comparisons between FP and OOP are: - -- OOP languages tend to have more language options -- OOP tends to have shared mutable state -- OOP is harder to refactor -- OOP is harder to unit test - - -*********** -So Why OOP? -*********** - -The discussion above is heavily biased against OOP, so why would we still -want to use it vs. FP? - -First, it is worth noting that design plays a huge role in how good a code is. -A well thought out design avoids many of the OOP criticisms stated above. As -evidenced by many of the legacy codes in the field of electronic structure -theory, FP alone will not make up for bad (or lack of a) design. For example, -many of the legacy electronic structure codes have resorted to shared state to -avoid massive refactoring efforts (keep in mind files are shared state...) and -many of them have gotten so coupled that refactoring is impractical. Perhaps -you might argue that it's harder to design a code which relies on OOP than on -FP. At least for our purposes, this is a bit of a moot point, since if you're -reading this then you don't have to worry about designing NWChemEx because it's -already been designed (and we'll toot our own horn and claim that the design is -good). - -Despite criticisms to the contrary, the main reason we have opted for OOP is -that we feel that using OOP it is far easier to encapsulate state than with FP. -At the end of the day, there is some set of inputs that each underlying -algorithm needs in order to function. As the underlying algorithm evolves that -set of inputs may change (think targeting new platforms, better approximations, -etc.). With strict FP the only way for the function to get that additional state -is to modify the call signature (or use some shared state, which we want to -avoid); unfortunately, if you modify the signature of a low-lying function you -often need to modify the signatures of all of the calling functions. With OOP -you can simply add a member variable to the object and be on your way. The -caveat is that it should make sense to add that member to one of the objects, -e.g. letting a triangle forecast the weather doesn't make much sense from a -design standpoint; if your function takes triangles and needs to forecast the -weather then you probably should just admit that the original design missed a -use case and add another field to the function. But doesn't that make it more -complicated? Strictly speaking, it's not any more complicated than the FP -approach. You now have one additional piece of data and each function touching -that data can choose to use it or ignore it. - -Another major reason for opting for OOP is ease of extension. We want -NWChemEx to be extendable. Science is continually evolving and the code needs to -evolve with it. Inheritance is minimally invasive and can be done without -modifying the source code. When combined with the encapsulation point, this -means extension is easier because developers only need to worry about -implementing the function they are overriding in the context of the provided -state. - -Some other reasons: - -- For better or worse OOP is also familiar to the current generation of - programmers. -- In HPC there is a move to C++/Python which are object-oriented languages. - Using C++/Python lets us better capitalize on other libraries - -That all said, most developers of NWChemEx will be writing plugins; since -plugins can be written in either C++ or Python (and both languages support OOP -and FP) those developers can use OOP or FP paradigms in their plugin. The point -being the decision to use OOP primarily affects the developers of the NWChemEx -infrastructure, not plugin developers who are free to make their own decisions -(although the latter do have to contend with it at the APIs). diff --git a/docs/source/design/overall_justifications/why_pluginplay.rst b/docs/source/design/overall_justifications/why_pluginplay.rst deleted file mode 100644 index bbdd2f77..00000000 --- a/docs/source/design/overall_justifications/why_pluginplay.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. Copyright 2025 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. - -.. _why_do_we_need_pluginplay: - -########################## -Why Do We Need PluginPlay? -########################## - -NWChemEx relies heavily on a module system. This section explains why we went -this route. - -************************************************************** -How Most Electronic Structure Codes Work (and Why That is Bad) -************************************************************** - -Back in my day...Seriously though there is a long history of electronic -structure codes being executables that can only be controlled by changing a -text input. The executable's functionality could not be extended without opening -the source code, adding the new functionality, and then recompiling. This is -fine when you have a tight-knit group of developers all working on the same -code, but what happens when someone outside the circle wants to extend the code? -One way or another their contributions need to make it into your source. Maybe -they make a library, and you add a hook to call that library, or maybe they just -directly add the functionality to the source code. Either way the source needs -to change. By modern standards this isn't very extensible. If I can't access the -source code, then I can't extend it. - -So why is this bad? First, science by its very nature is dynamic. New methods -are always coming out. Algorithms are improving. Theories are developed while -others are retired. Anytime one of these events happen your code needs to change -to keep up. Second, hardware isn't static. New hardware typically requires new -optimizations and considerations. In an ideal world once someone optimizes some -code, or develops a new theory they would release it as a library. Your code -would then be ready to absorb those changes, and propagate them throughout, -whenever the library is made available. Ideally this would be done in an -interoperable manner (meaning you literally do not have to change your code to -use the library). For the vast majority of electronic structure codes true -interoperability is impossible as the code needs to be changed to take advantage -of the new library. If it required only minor changes to add a library, this -would perhaps be a moot point. In practice, the aforementioned design means that -a tremendous amount of developer time needs to be spent to incorporate the -library (especially if it needs to be incorporated in multiple places). - -****************************** -The Current State of the Field -****************************** - -Admittedly, we're a long ways away from the ideal world described above, but we -are moving closer to it. It's not uncommon for developers to create stand alone -libraries with new and/or optimized functionality. Funding opportunities are -routinely making this a requirement. At the moment, true interoperability is a -pipe dream since no standards exist. Less glim, existence of these libraries -suggests that with the right code design it should be possible to leverage, and -propagate, the new functionality by wrapping it. - -Another somewhat recent development is that team sizes are increasing, and -becoming spatially distributed. This means you have a lot of disparate -developers trying to work on the same package at the same time. The reality is -there is minimal communication among these developers (no stand-ups, rarely are -design sessions held, etc.). Without communication, the likely hood for -conflicts (both code and interpersonal) increases. While version control like -``git`` helps when developers try to change the same line of code, it doesn't -help when developers come up with competing designs. - -************************* -How PluginPlay Fixes This -************************* - -The full design of PluginPlay is beyond our present scope (see the PluginPlay -documentation for design details). Instead what we are after here is how the -concept of PluginPlay, namely building a software package on top of a framework -where all major functionality is contained in modules, helps rectify the above -problems. - -Modules are essentially opaque functions. When something calls a module, they -know what it takes as input and what it returns. How it goes from inputs to -results doesn't matter. This is why the module system helps out with extending -the package. Basically, the package only couples to the API of the module not -the implementation. So if you wrap the library in a module, that module can -immediately be used throughout the code. By insisting that all functionality be -modules, it places all functionality on the same footing (the code doesn't -have to distinguish between internal and external calls). This is the key to -getting the functionality to automatically propagate throughout the code. Since -every time you want to do X, you get a module from PluginPlay, and then you -call the module given to you. PluginPlay can swap out the module you're about to -call for the new one, automatically (automatically in the sense that you don't -have to modify the calling code; it's not automatic in the sense that PluginPlay -magically knows which module the user wants to call). - -This disconnect between API and implementation is also the key to helping -disparately developed codes work together. Basically, each module is a sandbox -in which the developer is free to go from inputs to results however they want. -In turn it's up to the developer to: - -- enforce their own coding standards/style (although modules which are part of - NWChemEx are expected to abide by the community standards/style) -- choose to implement in Python or C/C++ -- decide what dependencies to use -- optimize for specific architectures -- choose what their module exposes (beyond that required by the API) - -Keep in mind that module developers are under no obligation to commit their -modules back to the main NWChemEx repos. While many codes may boast this, the -reality is since they treat the outside contributions differently, than internal -contributions, it becomes more likely for compatibility to break (often -requiring the external developer to perform maintenance to restore the -compatibility). Being able to maintain the modules in a separate location is -particularly useful for: - -- maintaining code ownership -- in some cases, avoiding licensing issues -- working on new methods privately -- individual tracking metrics -- collaborating with other projects besides NWChemEx -- demonstrating the component nature of the code to funding agencies diff --git a/docs/source/design/overall_justifications/why_python.rst b/docs/source/design/overall_justifications/why_python.rst deleted file mode 100644 index 4b8534a8..00000000 --- a/docs/source/design/overall_justifications/why_python.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Copyright 2025 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. - -.. _why_is_the_nwchemex_api_written_in_python: - -########################################## -Why is the NWChemEx API Written in Python? -########################################## - -The previous section, :ref:`why_is_cxx_the_primary_language_of_nwchemex`, -explained the decision to write the majority of NWChemEx in C++. The decision -has also been made to ensure that all of NWChemEx's APIs are available from -Python. This section explains why. - -If you read the previous section, you may recall that Python is one of the most -popular programming languages, if not the most popular programming language, in -the world. This popularity has also seeped into computational science, where -workflows are increasingly written in Python, and rely on tools accessible from -Python. If we want NWChemEx to be part of this ecosystem it is essential that -we ensure that we have Python bindings. - -At this point, it is perhaps worth noting that nothing prevents us from having -bindings to other languages (we actually also trivially have C++ bindings). So -if down the road we want Julia or Go bindings they can coexist with the Python -bindings. In fact, because of its popularity, Python already has the ability to -interface with a number of other languages; meaning using existing Python -modules its entirely possible to ignore that NWChemEx is written in C++, and -call it from say Rust, by relying on a tool like PyO3 (which lets you call -Rust from Python and vice versa). - -The other major reason for having Python bindings is for plugin system. When a -user develops a plugin, that plugin depends on the SimDE, but otherwise is an -independent piece of code from NWChemEx. So how does someone running NWChemEx -use that plugin? One way would be to link NWChemEx against the plugin at compile -time, but this kind of defeats the purpose of the plugin in the first place (and -is somewhat undesirable from the NWChemEx team's standpoint as we may end up -having to maintain the plugin as it will likely be absorbed by the code). The -typical C++ strategy for runtime linking is via ``dlopen``. While a number of -packages use ``dlopen`` to great success, its notoriously fickle. Enter Python. -If both NWChemEx, and the plugin, have Python bindings, linking is as simple as -``import plugin``. The reality is there's no magic here; Python simply does the -runtime linking for us. However, Python's runtime linking is extremely well -vetted and reliable (plus we don't have to maintain it!!!!). diff --git a/docs/source/design/overall_justifications/why_simde.rst b/docs/source/design/overall_justifications/why_simde.rst deleted file mode 100644 index bcb9dca2..00000000 --- a/docs/source/design/overall_justifications/why_simde.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. Copyright 2025 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. - -##################### -Why Do We Need SimDE? -##################### - -In :ref:`why_do_we_need_pluginplay` we explained the decision to build NWChemEx -on top of a modular framework. The actual design of SimDE goes beyond just using -modules, to decoupling the APIs of those modules from the guts of the framework. -This section explains why we wanted to keep the framework chemistry agnostic. - -PluginPlay is designed to be a relatively generic framework. There is no -chemistry concepts tied to PluginPlay. In theory, this allows PluginPlay to be -used by other projects which are not chemistry specific. In practice, it is -probably somewhat unlikely that another project will pick up PluginPlay. Our -decision to separate the APIs from the framework is primarily based off the -realization that there needs to be a way to extend the types of modules that the -framework can use, without changing the framework's source code. This is where -the remainder of the SimDE comes in. - -SimDE defines the module APIs we use throughout NWChemEx. These APIs have two -parts: the classes representing the chemistry concepts (primarily stored in -Chemist) and the actual property types. Barring the emergence of community -standards, NWChemEx will continue to use the APIs and classes within SimDE -as our standard. However, our standards do not cover every property that may be -of interest to a computational chemistry simulation (for example we are very -focused on ab initio methods and have not attempted to standardize molecular -mechanics properties). Thus we need a mechanism for developers to extend the -set of properties which can be computed. The property type system allows other -developers to define whatever APIs they like (using whatever classes they like -as well) and have PluginPlay be capable of using the resulting modules, all -without having to modify PluginPlay's source. diff --git a/docs/source/design/overall_justifications/why_this_partitioning.rst b/docs/source/design/overall_justifications/why_this_partitioning.rst deleted file mode 100644 index 95eb29f8..00000000 --- a/docs/source/design/overall_justifications/why_this_partitioning.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. Copyright 2025 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. - -############################################## -Why are the Repositories Partitioned this Way? -############################################## - -Some of the other discussions in this justification chapter touched on why -specific repositories exist. The point of this section is to explain why the -remaining repositories are partitioned the way they are. diff --git a/docs/source/design/overall_justifications/why_two_tensor_libraries.rst b/docs/source/design/overall_justifications/why_two_tensor_libraries.rst deleted file mode 100644 index 2db46fca..00000000 --- a/docs/source/design/overall_justifications/why_two_tensor_libraries.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Copyright 2025 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. - -############################################### -Why Does NWChemEx Rely on Two Tensor Libraries? -############################################### - -At the moment NWChemEx has two tensor libraries: TiledArray (TA) and TAMM. TA is -used to define all of the APIs by virtue of being under the hood of the -TensorWrapper component of Chemist. TAMM is used throughout the TAMM-SDE repo. -Developers new to the project may wonder why this is and this page does its best -to explain how this decision came to be. - -So why do we not just use TA everywhere? The answer here is historical more -than anything else. Basically TAMM was originally supposed to be the tensor -library used throughout NWChemEx, but the initial developers of SCF and MP2 had -difficulty implementing SCF and MP2 routines (particularly the local versions) -with TAMM. Owing to time constraints, the decision was made to use TA to -implement SCF and MP2. This also required solidifying a number of APIs, which is -why TA (under the hood of TensorWrapper) became the default library. - -While the above was going on, the TAMM team was hard at work on an HPC -implementation of CCSD and CCSD(T), which relied on TAMM. These implementations -underlie the modules in the TAMM-SDE repo. - -Long-term the use of multiple tensor libraries in the community is a real -hurdle to interoperability and use of SimDE. This is part of the reason why we -introduced TensorWrapper. It is our hope that the various tensor libraries in -use can learn to communicate under the hood of TensorWrapper so that module -developers can use their tensor library of choice. Whether this is possible -remains to be seen. diff --git a/docs/source/design/overall_justifications/will_this_perform.rst b/docs/source/design/overall_justifications/will_this_perform.rst deleted file mode 100644 index dcf7b35d..00000000 --- a/docs/source/design/overall_justifications/will_this_perform.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. Copyright 2025 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. - -############################################### -Sure it Looks Pretty, But is it Going to Scale? -############################################### - -:ref:`why_object_oriented_programming` explained why we opted for an OOP -paradigm. To some extent this section continues that discussion, but in the -context of whether or not OOP is just "syntactic sugar" or if it actually allows -one to write performant code, that looks nice too. Put another way, this section -justifies why we can adopt a top-down philosophy (design the pretty API, then -worry about performance) and expect it to perform well. - -The short answer is, OOP really is just "syntactic sugar". We proposition, -without proof, that everything on this page can be accomplished with functional -programming (FP) as well. By this we mean: it is possible to design an FP -interface that could accomplish the same tasks, in a similar number of code -statements (as a hand-wavy proof realize that class methods are basically just -functions whose first argument is the object they were called on). However, -without defining new types for that FP interface, the result would look much -nastier, e.g., there would be 10s of (if not 100s of) input parameters (yes -there's a lot rolled up into a class, but with the right design you don't need -to worry about all the state), and several nested functions per call. That said, -historically, at least within electronic structure theory, code written using FP -does not attempt to reach the level of generality we discuss here (likely -because of how unwieldy the API would be). This is another perk of OOP, -through abstraction, we can tackle very complicated problems by relatively -straightforward means. - -One of the first things to keep in mind is that there are layers to the program. -There are a lot of layers separating the user's input from functions like -``dgemm``. As input traverses the layers it gets upacked and processed. By time -you get to something like ``dgemm`` you've handled all of the other concerns -aside from the needed matrix multiplication. This is important to note because -the appearance a high-level object is designed to give off can be very different -than what it actually maps to. Case in point are tensors. With the way our -tensors work you can write building J and K like: - -.. code-block:: c++ - - simde::tensor_t P, I, J, K; //Assume P and I are initialized - J("mu,nu") = P("lambda,sigma") * I("lambda,sigma,mu,nu"); - K("mu,nu") = P("lambda,sigma") * I("lambda,nu,mu,sigma"); - -For readers familiar with the intricacies of J and K builds, you may say "sure -you can write it that way, but it's not efficient". Turns out, through the magic -of abstraction, the code above is capable of being used as a(n): - -- in core build (all tensors explicitly formed and stored in memory) -- disk build (all tensors explicitly formed, but ``I`` is stored on disk) -- core-disk hybrid (all tensors explicitly formed, only some pieces of ``I`` are - put on disk) -- direct build (``I`` is not explicitly formed, blocks are formed on the fly) -- semi-direct build (expensive parts of ``I`` are stored in memory, cheap are - recomputed on the fly) -- some hybrid of all of the above - -Furthermore, the code is actually capable of: - -- fully exploiting symmetry -- fully exploiting sparsity -- running in a distributed fashion -- running asynchronously -- running on CPUs and/or GPUs, -- being optimized for other architectures (e.g. FPGAs) - -(Disclaimer: as of writing this, the code above does not actually have all of -the aforementioned properties. However the properties described can be added to -the tensor library in such a manner that the code benefits from them without -needing to be rewritten. Furthermore, when the additional considerations are -added to the tensor library they will not only be available to the J/K build, -but throughout other modules as well.) - -So how can one little snippet of code do so much? We're not going to go into all -of the details, but here's the highlights: - -- The calls above actually build a task graph, before any real work is done -- From the size of the tensors we know how much work each task requires -- By having runtime information about the computer we know the amount of - resources (nodes, CPUs, GPUs, memory, disk, etc.) available to us -- Using the above information the task graph can be inspected and optimized - -One of the criticisms commonly leveraged about the above is that the complexity -is still there, it's just hidden. This is true. There really is a code path -which unrolled looks like a direct J/K build would in an FP code, i.e. something -like: - -.. code-block:: c++ - - // This is pseudocode that omits some details, like the prefactor - for(auto IJ : screened_shell_pairs){ - for(auto KL : screened_shell_pairs){ - if(KL > IL) continue; - auto I = compute_shell_quartet(IJ, KL); - if(I == 0) continue; // integral screening - for(auto mn : IJ){ - for(auto ls: KL){ - if(ls > mn) continue; - - J[mn] = P[ls] * I[mnls]; - J[ls] = P[mn] * I[mnls]; - K[ml] = P[ns] * I[mnls]; - K[vl] = P[ms] * I[mnls]; - K[ms] = P[nl] * I[mnls]; - K[ns] = P[ml] * I[mnls]; - } - } - } - } - -However, instead of the user having to explicitly write such a pattern, our -objects automatically dispatch to this pattern based on resources available, the -symmetry of the tensors, which tiles are important, the fact that ``I`` is being -recomputed each time it's called (so we want to fully utilize a block before -throwing it away), and the equations for the target results (J and K). The point -is that while the complexity is still there, we argue it is easy for users to -use (the DSL makes it look like a tensor expression versus nested loops) and the -implementation is more general and extendable (being applicable to, for example, -the four-index transform of correlated methods). - -The other concern one may have is what about object overhead? It is true, there -is a cost for inheritance, the increased number of function calls, and the other -OOP practices. More often than not, our experience shows that worrying about -such things is a premature optimization. With aggressive optimizations, -compilers have gotten really good at eliminating the overhead associated with -OOP. That said, in C++ one can usually resort to template meta-programming -techniques to remove much of the remaining runtime overhead (albeit at the cost -of longer compile times and larger binaries). Furthermore, the layered approach -means that we can merge two layers if need be, without having to rewrite all of -the layers on top of or under those layers (assuming APIs remain constant). - -Finally we note that in this section we focused on tensors, primarily for their -easy to grasp DSL. The same logic applies to all objects. By considering the API -and implementation of each object to be two different things, one essentially -gets a series of layered DSLs. Each DSL allows you to expresses the intent of -the computation divorced from how the computation is actually done. This makes -it easier for the people above the DSL to interact with that layer, while still -providing the developers of that layer all the necessary resources to optimize -that layer. diff --git a/docs/source/design/philosophy.rst b/docs/source/design/philosophy.rst deleted file mode 100644 index 68d99bb8..00000000 --- a/docs/source/design/philosophy.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. Copyright 2025 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. - -.. _philosophy: - -################### -NWChemEx Philosophy -################### - -NWChemEx, the software package, strives to be the *de facto* choice for running -high-performance quantum chemistry calculations on platforms ranging from -laptops to the world's largest supercomputers. This requires a software package -which is: - -- portable, -- user and developer friendly, -- and above all else performant. - -The above will not happen by accident and require careful planning and community -efforts. To accomplish this goal, NWChemEx's overall design has adopted two -philosophies: - -- Separation-of-concerns: We strive to decouple pieces to the extent possible. -- Top-down: APIs at each level are designed to only expose what that level - needs, details needed by lower levels are hidden. - -Admittedly these philosophies may seem at odds with our driving goal. After all -there is a long history of achieving performance using tightly coupled code with -little to no abstraction. However many of the legacy high-performance codes were -designed over 30 years ago. Since then the computational chemistry community -has: - -- greatly improved their software engineering skills, -- recognized the importance of good software infrastructure, and -- embraced object-oriented programming (OOP) - -The latter in particular is a key component to achieving our philosophy as it -allows us to pretty much have whatever API we want and hide the details in -otherwise opaque objects. Admittedly, heavy usage of OOP abstractions come with -their own costs: - -- design complexity, -- higher learning curves, and -- compiling costs - -Our design attempts to place the brunt of these costs on the more experienced -developers, leaving the more novice developers to use the objects like a domain -specific language. In this scenario everybody wins; developers wanting to test -out new chemistry can do that easily, whereas developers wanting to improve -performance can do so without impacting the chemistry development. diff --git a/docs/source/design/ui_design.rst b/docs/source/design/ui_design.rst deleted file mode 100644 index ee9119a6..00000000 --- a/docs/source/design/ui_design.rst +++ /dev/null @@ -1,371 +0,0 @@ -.. Copyright 2025 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. - -###################### -User Interface Design -###################### - -This document outlines the design principles and guidelines for the user -interface (UI) of NWChemEx. Our main goal is to provide a user-friendly and -intuitive interface that enables users to carry out a variety of quantum -chemistry calculations seamlessly. Please note that a graphical user interface -(GUI) is not part of the current UI design. Other possible UI elements that are -not part of the current design are noted here :ref:`not-in-scope`. - -****************** -Design Principles -****************** - -Pythonic -========= -While NWChemEx is mainly written in C++ for performance, the UI is designed for -and implemented in Python, which is arguably one of the most intuitive and -widely-used programming languages in scientific computing. This removes the -burden from our users to learn a special syntax, a new domain specific language, -or dealing with customized parsers for extracting data. Moreover, Python's -extensive ecosystem and user-friendly syntax allow for quicker prototyping and -easier integration with external tools, making it an ideal choice for this -interface. Adhering to the Pythonic style of programming is preferred due to its -emphasis on code readability and simplicity, as described in the Zen of Python -(PEP 20) _. A more in depth discussion of the -implementation language choices can be found in -:ref:`why_is_the_nwchemex_api_written_in_python`. - -Performant -========== -Performance is critical for NWChemEx with kernels supporting optimized MPI -parallelization and GPU offloading. The UI is designed to uphold this -performance standard and to provide the user with critical control elements to -achieve high performance. This requires keeping the overhead of UI as minimal as -possible by avoiding unnecessary copies or data movements and enabling user to -access and modify the MPI communicator and toggle between CPU-based/GPU-offloaded algorithms. - -Light weight -============ -Following from performance, the UI should shuttle data into C++ as quickly as -possible.For user convenience some conversions may be necessary (*e.g.*, our -`Molecule` class is never going to do string parsing), but the set of such -conversions should be minimal, or limited to those supported by some other -library (which we agree to take on as a dependency). - -User-friendly -============= -We aim to make our UI intuitive and simple particularly for the most common use -cases to minimize the learning curve for beginners. The UI is also designed to -provide user-friendly error handling, offering clear and actionable feedback -when something goes wrong, guiding users to resolve issues effectively. - -Tool-friendly -============= -In some workflows, NWChemEx can be used as a library driven by another code, -rather than directly by a user. Therefore, our UI needs to avoid assuming that -it is the top layer in order to better integrate into external tools. - -The ability to take an MPI communicator is one particularly important UI design -element implied by this combined with the performance consideration. Python-based -interface is also useful to support many external tools easily. - -Minimal I/O -=========== -Many quantum chemistry codes are designed to use input/output (I/O) files as -their primary (sometimes only) user interface. Users are expected to provide -input files in certain format and parse output files to extract the information -required. This is not only cumbersome but also can hinder performance -particularly when the code is used as a library by an external code in -high-throughput mode. The UI should avoid or minimize the I/O by providing the -user with the ability to pass the input and output data directly to the code. -This enables better interactivity and allows for more efficient use of the code -as a library. - -Interactive -============ -The UI should support interactivity, allowing users to run the code in a Jupyter -notebook or IPython shell. This is particularly important for beginners who are -not familiar with the code and want to explore its capabilities and for -education. It is also important for visualization and for workflows supporting -machine learning applications. - -Limited results -=============== -In theory, there's a very large set of results a user could want. Thankfully -most users target the same quantities. The UI should focus on those quantities. - -The most common quantities are: energy, molecular-orbital coefficients, -gradients, vibrational frequencies, and geometries (including minimum energy, -transition states, reaction paths, etc.). - -Limited inputs -============== -Generally speaking the inputs required for the aforementioned results tend to be -the molecule, level of theory (method plus basis set), and method parameters. -While the set of potential parameters is huge, again there are only a handful of -commonly used parameters. - -Primary targets are: algorithm variations (e.g. density fitting), number of -iterations, and convergence criteria. - -Focus on common tasks -===================== -The UI targets the most common use cases (see :ref:`common-tasks`), but should -try to be flexible. At some point, harnessing the full power of the code -requires forgoing the UI and dropping down to PluginPlay's API. - -Minimal dependencies -==================== -The UI is designed to be a thin-layer on top of the PluginPlay API and should -have minimum number of dependencies. This improves maintainability and reduces -the risk of breaking the code due to changes in the dependencies. - -Archiving and reproducibility -============================= -The UI should support archiving and reproducibility by providing the user with a -way to save the input and output data for each calculation. This not only serves -as a tool for managing and organizing data but also plays an integral role in -facilitating reproducibility. - -.. _common-tasks: - -************************************* -Common Quantum Chemistry Calculations -************************************* - -As described in the design principles, the UI should enable users to conduct -commonly used quantum chemistry calculations such as single-point energies and -geometry optimizations in as few steps as possible. It should also be flexible -enough to allow for more complex workflows using the helper/driver functions and -PluginPlay modules. Users can execute these calculations either via Python -scripts or interactively using Jupyter notebooks. For those who desire a -fine-grained control of their workflow, they can utilize the Python and/or C++ -API. - -1. **Single Point Energy** - - In these calculations total energy is computed for a fixed geometry of the - molecule (arrangement of atomic nuclei) corresponding to a single point in - the potential energy surface. While energy calculation is the most common - case, the user might be interested in obtaining the wave function, - derivatives, or other properties (dipole moment, electron density, etc.) for - this specific geometry. - -2. **Geometry Optimization** - - This is a procedure to find the arrangement of atomic nuclei that corresponds - to a stationary point in the potential energy surface. This procedure - generally requires the calculation of the gradients and Hessian (first and - second order partial derivatives of the energy with respect to nuclear - coordinates, respectively) at many different geometries. - -3. **Vibrational Frequency Calculation** - - These calculations provide the vibrational modes of a molecule and their - corresponding frequencies. The procedure requires Hessian calculation at the - equilibrium geometry. - -4. **Molecular Dynamics Simulation** - - These calculations allow for the study of the trajectory of atoms and - molecules over time using classical dynamics. Gradient calculations are - required to compute the forces acting on the atoms. - -We will initially focus on the UI design of the "single point energy" -calculations in this document since other types of calculations (geometry -optimization, vibrational frequency calculation, etc.) require similar inputs. - -Before we delve into the specifics of the NWChemEx UX, we provide examples of -restricted Hartree--Fock (RHF) energy calculations for a hydrogen molecule using -PySCF, PSI4, and MolSSI QCEngine. Finally, we will provide an NWChemEx example -and discuss about the choices made. - -************************** -Existing Python-based UIs -************************** - -PySCF -====== -PySCF is a Python-based open-source quantum chemistry package distributed under -the Apache License 2.0. The code is written mostly in Python (~90%), while -computational hot spots are written in C following C89 standard. Most functions -are pure (exceptions are named with a suffix underscore) and functional -programming is preferred over object oriented style as described in their `code -standard `_. - -Below you can find how to run an RHF calculation for a hydrogen molecule using -PySCF. - -.. code-block:: python - - from pyscf import gto, scf - mol = gto.M(atom='O 0 0 0; H 0 1 0; H 0 0 1', basis='sto-3g') - rhf = scf.RHF(mol) - energy = rhf.kernel() - -Here, mol is the object (type ``pyscf.gto.mole.Mole``) representing the molecule -and integrals with the given basis set and rhf is the object (type -``pyscf.scf.hf.RHF``) that holds method specific information. The energy is -computed using the ``kernel()`` function. - -PSI4 -==== -PSI4 is a C++/Python (70%/30%) open-source quantum chemistry package distributed -under the LGPL3 license. PSI4 provides two different types of UI referred to as -Psithon and PsiAPI modes. In the Psithon mode, the user writes an input file in -a domain specific language similar to Python. In the PsiAPI mode, the user can -write a pure Python script that interacts with PSI4 as a Python module. Since -the latter is more relevant to our design, we show below how to run an RHF -calculation for a hydrogen molecule using the PsiAPI mode. - -.. code-block:: python - - import psi4 - mol = psi4.geometry('H 0. 0. 0. \n H 0. 0. 1.') - energy= psi4.energy('scf/sto-3g') - -Here, mol is the molecule object, which is created using the ``psi4.geometry()`` -function and the energy is computed using the ``psi4.energy()`` function, which -takes the method name as the required argument. Note that the user do not need -to pass the molecule object explicitly to the subsequent energy calculation. By -default energy is computed for the last molecule defined with the -``psi4.geometry()`` function. Additional options can be set with the -``psi4.set_options()`` function, which takes a Python dictionary as the required -argument. - -QCEngine -======== -QCEngine is a general purpose quantum chemistry program interface. It is a -Python library that provides a common API for quantum chemistry programs. -QCEngine is an open-source package distributed under the Apache License 2.0. - -Below you can find how to run an RHF calculation for a hydrogen molecule using -QCEngine. - -.. code-block:: python - - import qcengine as qcng - import qcelemental as qcel - mol = qcel.models.Molecule.from_data('H 0. 0. 0. \n H 0. 0. 1.') - out = qcng.compute({"molecule": mol, "driver": "energy", "model": {"method": - "SCF", "basis": "sto-3g"}}, "NWChemEx") - energy = out.return_result - -Here, mol is the molecule object (type -``qcelemental.models.molecule.Molecule``), which is created using the -``qcel.models.Molecule.from_data()`` function from QCElemental package. The RHF -energy is computed using the ``qcng.compute()`` function, from QCEngine package. -Note that, the input for the ``qcng.compute`` function is a Python dictionary -with a schema defined by QCElemental. - -******************** -Current NWChemEx UI -******************** - -The backbone of the current NWChemEx UI is the `calculate()` function. This -function enables users to run quantum chemistry methods implemented in NWChemEx, -with a very simple interface. The signature of this function is given below. - -.. code-block:: python - - def calculate(molecule: Union[str, Dict[str, Any], chemist.Molecule], - method: str, basis: Union[str, chemist.AOBasisSet, simde.type.ao_space], - task: Literal["energy", "gradient", "wavefunction"] = "energy", options: Dict[str, - Any] = None, **kwargs) -> Dict[str, Any]: - -In this function, there are three required arguments. First one is the molecule, -which can be given as a Python string or a dictionary-like object (composed of -key-value pairs) that contains the information required to create a -``chemist.Molecule`` object. The user can also pass a ``chemist.Molecule`` -object directly. The second required argument is the ``method``, which is a -Python string that corresponds to one of the quantum chemistry methods -implemented in NWChemEx. The third required argument is the ``basis``, which can -be given as a Python string or a ``chemist.AOBasisSet`` object or a -``simde.type.ao_space`` object. The ``calculate()`` function also takes optional -arguments. ``task`` argument enables users to choose the type of calculation, -which can be ``energy`` (default), ``gradient``, or ``wavefunction`` currently, -but this list is expected to grow as more functionalities are added to NWChemEx. -``options`` argument enables users to customize the calculation further by -modifying different parameters related to the selected ``method`` and ``task``. At -this point, it is an opaque type (to be designed later in coordination with -PluginPlay `#308 `_), -which is capable of holding key/value pairs for inputs similar to a Python -dictionary. Alternatively, key/value pairs can be passed directly to the -function call as ``kwargs``. The return type of the ``calculate()`` function is -also an opaque type that can hold key/value pairs. - -With the ``calculate()`` function, a user can run the RHF example by -specifying only the required arguments as shown below. - -.. code-block:: python - - import nwchemex as nwx - result = nwx.calculate(molecule = 'H 0. 0. 0. \n H 0., 0. 1.', method='scf', basis = 'sto-3g') - -Here, ``method = 'scf'`` will default to the RHF energy calculation since the -molecule is a closed-shell system and default value for the ``task`` is a single -point energy calculation. - -Parallel calculations -===================== - -NWChemEx also provides a simple interface to run calculations in parallel. Here, -we provide an example where the user wants to run a potential energy surface -scan, which is basically an embarrassingly parallel workflow composed of single -point energy calculations at different geometries. The user can run this -workflow in two different ways: - -.. code-block:: python - - # Initialize the parallel environment with mpi4py - from mpi4py import MPI - comm = MPI.COMM_WORLD - rank = comm.Get_rank() - - # Use one rank per sub-communicator - sub_comm = comm.Split(rank) - # Define the distance between atoms based on the global rank - d = 1. + rank * 0.1 - - # Alternative 1 - # Initialize NWChemEx runtime with the sub-communicator - nwx_comm = nwx.initialize(sub_comm) - result = nwx.calculate(molecule = f'H 0. 0. 0. \n H 0. 0. {d}', method = 'scf', basis = 'sto-3g') - print(f'Energy calculated by rank: {rank} for distance: {d} is {result.scf_energy}') - - # Alternative 2 - # Initialize NWChemEx runtime inside the function call - # Sub-communicator can be passed directly or through the options argument - result = nwx.calculate(molecule = f'H 0. 0. 0. \n H 0. 0. {d}', method = 'scf', basis = 'sto-3g', communicator = sub_comm) - print(f'Energy calculated by rank: {rank} for distance: {d} is {result.scf_energy}') - -.. _not-in-scope: - -************* -Not In Scope -************* - -**Graphical user interface (GUI)** - -Arguably a GUI represents the pinnacle of UX; however, we presently are focused -on a programmatic UI. Implementing a GUI is an orthogonal task that can benefit -from the existence of the programmatic UI. - -**Interfaces for driving NWChemEx** - -While we want NWChemEx to be part of an ecosystem, the design on this page is -purely focused on a UI which uses a combination of native NWChemEx and Python -objects. - - - With a NWChemEx UI in place driving NWChemEx from other packages becomes easier. - - Ideally such interfaces should be maintained on the driver's side, and not - by us, in order to avoid needing to weigh down NWChemEx with additional - dependencies. Note that making a dependency optional for a user does NOT - negate this as NWChemEx developers must support all optional features. diff --git a/docs/source/design/vision.rst b/docs/source/design/vision.rst deleted file mode 100644 index 9d66243e..00000000 --- a/docs/source/design/vision.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. Copyright 2025 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. - -################ -NWChemEx Visions -################ - -The overall philosophy/motivation of the NWChemEx software package was -discussed in the :ref:`philosophy` section. Achieving and adhering to that -philosophy is ultimately a lofty, moving target. To facilitate development of -NWChemEx in a direction consistent with the project's philosophy, the NWChemEx -board, in coordination with the overall NWChemEx community, will maintains a -shared vision. Unlike traditional milestones/goals, "visions" are intentionally -more vague and less SMART (specific, measurable, achievable, relevant, and -time-bound) so as to only define the scope of work, not the objectives of the -work. - -This page is envisioned as collecting the visions of the NWChemEx project over -its lifetime. - -************** -Vision for 1.0 -************** - -At the end of DOE's Exascale Computing Project (ECP) the NWChemEx community had -developed: - -- infrastructure for writing modular scientific software, -- a performant tensor library, and -- performant implementations of fundamental computational chemistry methods. - -These three pieces remain somewhat disconnected. The vision for the initial -release of NWChemEx, i.e., the 1.0 is to connect these three pieces in a unified -manner. This requires: - -- 1.0 releases of all infrastructure (i.e., ParallelZone, PluginPlay, Chemist, - SimDE, and ChemCache). -- Modularization of fundamental computational chemistry methods. -- Reliance on stable SimDE-based user APIs. -- 1.0 of FriendZone. - -The reliance on stable SimDE-based APIs means that we will focus on minimal -inputs (i.e., chemical systems, basis sets, and classes needed to implement the -chemical system and basis sets). Modularity will be coarse-grained and limited -to data-exchange using stable Chemist types. Of note this means we will not -expose the tensor library at the 1.0 stage, and instead consider it an -"under-the-hood" implementation detail. The 1.0 of FriendZone is included to -round out NWChemEx's functionality, as ECP development primarily focused on DFT -and coupled cluster. - -********************** -Vision for End of 2024 -********************** - -TODO: Determine if this time frame is right. - -The vision for post-1.0 release has not been discussed yet and will not be -discussed until the 1.0 release has happened. However, the 1.0 vision leaves -some obvious directions which we list here so that people know they have not -been forgotten. - -- exposure of tensors -- more Chemist classes (e.g., operators, vector spaces, and wavefunctions) -- more fine-grained modularization (using types from chemist) -- more user-friendly API. -- interfaces to other packages. diff --git a/docs/source/documenting/contributing_to_documentation.rst b/docs/source/documenting/contributing_to_documentation.rst deleted file mode 100644 index de026632..00000000 --- a/docs/source/documenting/contributing_to_documentation.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. Copyright 2025 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. - -.. _contributing_to_documentation: - -************************************** -Contributing to NWChemEx Documentation -************************************** - -In this section we explain the basic orgnization of the NWChemEx documentation -system and present instructions on how to contribute to the documentation. - -Structure of NWChemEx Documentation -=================================== - -In the repo of every NWChemEx package, there is a ``docs`` directory. Under -this diretory there is a ``source`` subdirectory which contains all .rst -source files of the documentation (recursive subdirectory structures may -exist). The files ``Makefile`` and ``requirements.txt`` are for generating -formatted files of the documentation, and will be explained below. The -``README.md`` file briefly decscribes the documentation and how to generate -the documentation files. - -How to Contribute to NWChemEx Documentation -=========================================== -Suppose one plans to update the documentation of the package PluginPlay. -First, one should create a local working copy of the PluginPlay repo using -``git clone``, then edit the existing .rst files or create new .rst files -under the ``doc`` directory. -Remember, when new .rst files are added, one needs to add the names of the -new files into the toctree list in the ``index.rst`` file under the same -directory. -When all editing work is done one needs to generate a local copy of the -documentation (see below), usually in html format, and check the .html files -in a browser to make sure everything is displayed properly. Finally one can -open a pull request to the PluginPlay repo and merge the updated documentation -to master. - -Note: the developer documentation of NWChemEx resides in the .github repo. - - -How to Generate a Local Copy of the Documentation -================================================= - -NWChemEx uses `Sphinx - a Python documentation generator -`_ to transform the -source files (.rst, .md. etc) into documentation files in various formats -(.html, .pdf, etc). One can see the content of the file ``requirements.txt`` -with the linux command ``vi``: - -.. code-block:: console - - docutils<=0.19 - sphinx - sphinx_rtd_theme - -This list contains the required Python packages to install. We recommend to -install these packags into a Python virtual environment, in order to avoid -possible conflicts in the base environment. One can run the linux commands - -.. code-block:: console - - python3 -m venv venv - . venv/bin/activate - pip3 install -r requirements.txt - -to create a virtual environment ``venv``, activate it, and then install the -required packages into it. -Note: during the installation of the packages, one may see an error message -like "*ERROR: sphinx-rtd-theme 1.2.0 has requirement docutils<0.19, but you'll -have docutils 0.19 which is incompatible.*". This is a known issue, but not -affecting documentation generation. - -After all packages are successfully installed, one can run - -.. code-block:: console - - make html - -under the directory of ``docs`` to generate the documentation in .html format. -One can also choose other formats, for example, .pdf, for the generated -documentation files by running - -.. code-block:: console - - make latexpdf - -In this case the installation of additional packages such as ``latexmk`` might -be necessary. -After successfully running these ``make`` commands, a directory of ``build`` -would be created under ``docs``. So one can go to the subdirectories ``html`` -or ``latex`` to check whether generated .html or .pdf files are correct or not. diff --git a/docs/source/documenting/index.rst b/docs/source/documenting/index.rst deleted file mode 100644 index 7e589963..00000000 --- a/docs/source/documenting/index.rst +++ /dev/null @@ -1,32 +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. - -#################### -Documenting NWChemEx -#################### - -The topics below are tutorials and best practices to follow when documenting -NWChemEx. While writing documentation please be familiar with the -documenation conventions for reStructuredText :ref:`rest_conventions` and -Doxygen :ref:`doxygen_conventions`. - -.. toctree:: - :maxdepth: 1 - - writing_design_documentation - writing_api_documentation - writing_developer_documentation - writing_tutorials - rst_cheatsheet - contributing_to_documentation diff --git a/docs/source/documenting/rst_cheatsheet.rst b/docs/source/documenting/rst_cheatsheet.rst deleted file mode 100644 index e32bcb8f..00000000 --- a/docs/source/documenting/rst_cheatsheet.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. Copyright 2025 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. - -**************** -reST Cheat Sheet -**************** - -The purpose of this page is to provide a convenient resource for quickly -becoming familiar with ReStructured text (reST) as commonly needed in -documenting NWChemEx. - -Terminology -=========== - -reST is an extensible markup language, which means it's a bit more complicated -than say Markdown. This complication comes from some additional concepts. - -- roles: These are the qualifiers on inline text - - - *e.g.*, ``:math:\alpha`` - -- directives: These markup blocks of text - - - *e.g.*, ``.. math::`` - -Basic Text Formatting -===================== - -- Italics: ``*text to italicize`` - - - Result: *text to italicize* - -- Bold: ``**text to bold**`` - - - Result: **text to bold** - -Math -==== - -To write inline math use the ``:math:`` role: - -.. code-block:: rest - - The area, :math:`a`, of a circle of radius :math:`r` is :math:`a=\pi r^2` - -Result: - - The area, :math:`a`, of a circle of radius :math:`r` is :math:`a=\pi r^2` - -To make a block of math use the ``.. math::`` directive: - -.. code-block:: rest - - .. math:: - - a = \pi r^2 - -Which renders as: - -.. math:: - - a = \pi r^2 - - -Equations in a math block can be aligned in the usual LaTeX way (*i.e.*, with -``&``): - -.. code-block:: rest - - .. math:: - - \widehat{H}\Psi &= E\Psi \\ - \widehat{H} &= -\frac{1}{2}\sum_{i} \bigtriangledown^2_i - - \sum_i \sum_A \frac{Z_A}{\mathbf{r}_{iA}} + - \sum_{i > j} \frac{1}{\mathbf{r}_{ij}} + - \sum_A \sum_B \frac{Z_AZ_B}{\mathbf{R}_{AB}} - -which shows up as: - -.. math:: - - \widehat{H}\Psi &= E\Psi \\ - \widehat{H} &= -\frac{1}{2}\sum_{i} \bigtriangledown^2_i - - \sum_i \sum_A \frac{Z_A}{\mathbf{r}_{iA}} + - \sum_{i > j} \frac{1}{\mathbf{r}_{ij}} + - \sum_A \sum_B \frac{Z_AZ_B}{\mathbf{R}_{AB}} - -To simplify writing complicated math equations you can define LaTeX commands in -a math directive: - -.. code-block:: rest - - .. math:: - - \newcommand{\bra}[1]{\left\langle{#1}\right|} - \newcommand{\ket}[1]{\left|{#1}\right\rangle} - - \bra{\psi} = \left(\ket{\psi}\right)^\dagger - -which renders as: - -.. math:: - - \newcommand{\bra}[1]{\left\langle{#1}\right|} - \newcommand{\ket}[1]{\left|{#1}\right\rangle} - - \bra{\psi} = \left(\ket{\psi}\right)^\dagger - -Commands defind in a math directive are good for the page, so: - -.. code-block:: rest - - .. math:: - - \ket{i} = \sum_{\mu}C_{\mu i}\ket{\mu} - -renders as: - - .. math:: - - \ket{i} = \sum_{\mu}C_{\mu i}\ket{\mu} - -without needing to redefine the ``\ket`` command. - -To make aliases for inline math the best solution I have found is to do: - -.. code-block:: rest - - .. |fock_matrix| replace:: :math:`f_{\mu\nu}` - - The :math:`\mu\nu`-th element of the fock matrix is |fock_matrix|. - -Which renders as: - -.. |fock_matrix| replace:: :math:`f_{\mu\nu}` - -The :math:`\mu\nu`-th element of the fock matrix is |fock_matrix|. - -Code Blocks -=========== - -Code blocks are done with the ``.. code-block::`` directive. To get syntax -highlighting you can specify the language after the ``::``. For example: - -.. code-block:: rest - - .. code-block:: python - - import os - print("The current directory is: " + os.getcwd()) - -which renders as: - -.. code-block:: python - - import os - print("The current directory is: " + os.getcwd()) - - -Figures -======= - -To add a figure to a page: - -.. code-block:: rest - - .. _label_for_figure: - - .. figure:: relative/path/to/image.png - :align: center - - The figure's caption goes here. - -You can refer to the figure with ``:numref:`label_for_figure```. Note the -underscore on the declaration of the label, which is not present when referring -to the label. - -.. note:: - - The ``:numref:`` role will automatically include "Fig." in addition to the - number. - -.. note:: - - If when you try to build the documentation you get a warning like: - - .. code-block:: text - - /path/to/file.rst:line_number: WARNING: numfig is disabled. :numref: is ignored - - then you need to add ``numfig = True`` to the ``conf.py`` file. - -FAQs -==== - -#. How do I have URLs with the same generic link text? - -For example the following reST will give rise to -the warning ``WARNING: Duplicate explicit target name: "here"``: - -.. code-block:: rest - - See `here `_ or - `here `_ for a really - cool repo. - -This problem is caused by the fact that Sphinx automatically creates a -target for your link based on the link text. To avoid this problem you -can make the link have an anonymous target. This is done by using two -underscores at the end like: - -.. code-block:: rest - - See `here `__ or - `here `__ for a really - cool repo. - -#. How do I insert line breaks into long URLs to satisfy the 80 character - limit? - -At this point I can not find a reST-based solution for this problem; however, -a widely applicable solution to this problem is to use websites like -`TinyURL `__ or `Bitly __` to -shorten the URL. diff --git a/docs/source/documenting/writing_api_documentation.rst b/docs/source/documenting/writing_api_documentation.rst deleted file mode 100644 index c9b25d4e..00000000 --- a/docs/source/documenting/writing_api_documentation.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. 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. - -.. _writing_api_documentation: - -######################### -Writing API Documentation -######################### - -TODO: Write me!!!! diff --git a/docs/source/documenting/writing_design_documentation.rst b/docs/source/documenting/writing_design_documentation.rst deleted file mode 100644 index 35186084..00000000 --- a/docs/source/documenting/writing_design_documentation.rst +++ /dev/null @@ -1,163 +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. - -.. _writing_design_documentation: - -############################ -Writing Design Documentation -############################ - -Many NWChemEx developers, particularly if they come from the chemistry side of -things, are likely not familiar with design documentation. This page is -intended to provide a gentle introduction to what design documentation is and -to establish what the NWChemEx team is looking for in design documentation. - -.. _what_is_design_documentation: - -***************************** -What is Design Documentation? -***************************** - -`Wikipedia `__ -defines design documentation as: - -.. pull-quote:: - - *...a representation of a software design that is to be used for recording - design information, addressing various design concerns, and communicating - that information to the design’s stakeholders.* - -************************************ -Why Do We Need Design Documentation? -************************************ - -The NWChemEx project is a massive undertaking and involves a large number of -developers. One of the primary reasons we need design documentation is to -outline the software infrastructure. This includes outlining the overall project -(design documents in this repo) and each sub-project (design documents in the -respective sub-repo). In theory, a new developer (or an established developer -who needs refreshers) should be able to start from the design documentation in -this repo and find their way to the source code component of interest purely -by reading the design documentation, *i.e.*, without having to read the source -code. - -The other reason we need design documentation is to communicate the shared -vision of the project. NWChemEx is a large project and no one person is -expected to know every aspect of it. Design documentation provides a -mechanism for a developer new to NWChemEx, or to a piece of NWChemEx, to come -up to speed with the motivation, considerations, and decisions pertaining to -a piece of the project without having been part of the original design -discussions. Hence the design documentation communicates the shared vision of -the project. - -***************************************** -What Should Design Documentation Include? -***************************************** - -Ideally design document should document every decision made in structuring the -software. This ranges from repository structure to class hierarchies. Admittedly -this is a tall order. We strive to have design documentation for as much of the -NWChemEx project as possible, but realize that most of us are not getting paid -to write it. If you run into a piece of NWChemEx without design documentation -consider adding it (spoiler alert much of the present design documentation was -actually written after the code was implemented). - -.. note:: - The outline below is a recommendation, and not all parts are relevant for all - design stages. So use your best judgment. - -As for the literal contents of a design document consider an outline like: - -1. Define the component, feature, class - - - This is a section making sure everyone's on the same page about what design - aspect is being documented. - - For example consider the :ref:`what_is_design_documentation` section - above, which defines design documentation. - -2. Statement of Need - - - Once you have defined the component, feature, class, or whatever explain - why we need it. - - A lot of NWChemEx was designed top-down. So often the statement of need - is more or less the feature above us kicked the can down the road to this - component. - -3. Considerations - - - When a stakeholder interacts with this component, feature, class, or - whatever, what should they expect? - - Ideally the considerations should be at the same granularity as the feature. - For example when discussing the repo structure of NWChemEx it doesn't make - sense to explicitly consider that we'll need to be able to build a - two-center integral between f-orbitals. - -4. Existing Options - - - For large components, extravagant features, or detailed classes consider - using a library which provides that feature. - - Once you're in the nitty-gritty, discussing existing options usually - doesn't make as much sense because you're now worried about designing a - component which works with infrastructure largely provided by the NWChemEx - project, i.e., there usually won't be an existing implementation. - -5. Strategy - - - Now that you've laid out what you're trying to do, and why, describe how - you're going to do it. - - For C++ code Doxygen can automatically generate API documentation, call - graphs, callee graphs, and UML diagrams, so there's no need to write - these explicitly. It usually suffices to show what components are under the - hood to give an idea of what functionality stakeholders can expect. - - This is a good place to work through complicated scenarios which may arise - and explain how the component should respond. - -6. Further Considerations - - - What's been left out of the design. - - What's the current state of the implementation? - - What has been tried, but failed? - -********************************************* -Contributing Design Documentation to NWChemEx -********************************************* - -Now that you know what design documentation is, why we need it, and what it -should include, the last step according to the last section is to explain how -it will work (I know pretty meta how this page follows the outline it suggests). -We strongly suggest that developers write design documentation for -contributions which implement new: - -- repositories (it's important to know how these repos integrate) -- (extensive) features -- (complex) classes - -Keep in mind, you may also need to modify the design documentation of the -architecture components above and below your component so it reflects the -existence of your new contribution. - -.. note:: - - What constitutes an extensive feature or a complex class is up for debate, - but as a rule of thumb if someone isn't going to figure out how your - feature/class works from the API and a couple seconds of perusing the - source, you probably need design documentation. - -Project-wide design documentation lives in this repo's documentation. This -includes documentation governing how the GitHub organization interacts with -various stakeholders and how the repositories in the organization interact. -Design documentation for features/classes that live in a specific repository -should be added to the documentation of that repository. All repositories -presently contain a ``docs/source/design`` directory where design documentation -should be placed. diff --git a/docs/source/documenting/writing_developer_documentation.rst b/docs/source/documenting/writing_developer_documentation.rst deleted file mode 100644 index 897d833d..00000000 --- a/docs/source/documenting/writing_developer_documentation.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. 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. - -.. _writing_developer_documentation: - -############################### -Writing Developer Documentation -############################### - -TODO: Write me!!!! diff --git a/docs/source/documenting/writing_tutorials.rst b/docs/source/documenting/writing_tutorials.rst deleted file mode 100644 index 742ec3a6..00000000 --- a/docs/source/documenting/writing_tutorials.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. Copyright 2025 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. - -***************** -Writing Tutorials -***************** - -.. TODO:: - - Show how the ``.. literalinclude::`` directive can be used to selectively - include pieces of a source file. The source file can reside in the testing - directory and be built as part of the test suite ensuring the documentation - stays up to date. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 6032c6c2..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. Copyright 2025 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. - -################################## -NWChemEx's Developer Documentation -################################## - -This documentation is aimed primarily at developers of NWChemEx. Broadly -speaking this documentation focuses on: - -- Project-wide design decisions -- Project-wide conventions -- Tips and tricks for developing with NWChemEX -- Tutorials related to tools closely associated with NWChemEx (e.g. git) - -This documentation is meant to be a living document so please feel free to -contribute. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - community/index - design/index - documenting/index - conventions/index - coding/index - testing/index - continuous_deployment/index - resources/index - bibliography/bibliography diff --git a/docs/source/resources/github/git_tutorial.rst b/docs/source/resources/github/git_tutorial.rst deleted file mode 100644 index 4d4b0bff..00000000 --- a/docs/source/resources/github/git_tutorial.rst +++ /dev/null @@ -1,361 +0,0 @@ -.. Copyright 2025 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. - -.. _Git and GitHub Procedures: - - -Git and GitHub Procedures -************************* - -The purpose of this page is to document typical Git and GitHub workflows and to -serve as a cheat sheet for remembering the commands. This page only covers the -basic aspects related to Git version control and how one uses GitHub to -contribute code. - -Git and GitHub Background -========================= - -As a code base evolves it will have existed in many versions. Almost all modern -codes use some form of what is termed "version control" (VC) to manage these -versions. Rather than attempting to do VC manually, most developers typically -employ some form of VC software. Broadly speaking VC software provides two -main services: - -1. Management of a code's history - - Sophisticated "undo" feature -2. Merging disparate contributions into one code base - - Manually merging contributions from different developers is error-prone - - Good VC can merge code automatically by utilizing the common code history - -Superficially all VC software follows a similar workflow. When a developer -wants to work on a version controlled code base (called a repo), they: - -1. Copy the repo -2. Modify the copy -3. Merge the copy back with the repo - -Exactly how this process is done depends on the model adopted by the VC -software managing the repo. Originally, most VC packages (like CVS and SVN) -utilized what is called a centralized repo model. In a centralized model -there is only one repo. Copies of that repo are intimately linked to the -original repo. More modern VC packages, like Git and Mercurial, instead use -what is called a distributed repo model. In this model, all copies of the -original repo are perfectly legitimate repos on their own. Conceptually this -means that any notion of "authoritative repo" is purely a social convention. -The distributed repo model has a number of advantages compared to the -centralized repo model: - -- Faster operations - - - No need to communicate with original (typically remote) repo - - Encourages code-base to be saved more often -- Easy collaboration - - - No need for messy three-way (original, and two copies) synchronization, - only worry about copy to copy synchronization - - Copies have access to all VC commands, which makes it much easier to share - changes without going through original repo -- Each repo is essentially a "back-up", the original repo's full history is in - each copy - -Given `GitHub `_'s current popularity as a social coding -platform it's easy to lose sight of GitHub's actual role in the VC process. -GitHub itself is really nothing more than a website which hosts Git repos. -Consequentially, there's nothing special (from the perspective of Git) about the -repo that lives on GitHub versus a copy of that repo living on any other -computer. That said, given that GitHub is easily accessed by all developers and -potential users, it's typical to, by social convention, treat the GitHub repo as -the "official" repo. GitHub's popularity is largely fueled by the fact that -in addition to being a place to host Git repos it also strives to encompass -and simplify many other aspects of the development process (such as continuous -integration and code-review). The following sections detail common Git -commands and the typical GitHub workflow purposed for the NWChemEx project. - -Common Git Commands -=================== - -For the purposes of this tutorial we'll assume that you're working with an -existing Git repo (if you're not, the easiest way to make a repo is to do so on -GitHub and then follow GitHub's prompts). Once you know which repo you want -to work on, the first step is to get your own copy (the copy is termed a clone -in Git lingo). The command to clone a repo is: - -.. code-block:: bash - - git clone [] - -This will checkout a repo that is located at ``path_to_repo`` and optionally -put it in a folder named ``where_to_put_repo`` (if you don't specify -``where_to_put_repo``, the clone will be placed into a folder with the -same name as the repo you are cloning). It's important to realize that -``path_to_repo`` can be either a file path, to say clone a repo on your -internal network, or a website like GitHub. The remainder of the commands in -this section assume you are inside the resulting directory (Git will try to -access settings that are hidden in ``.git/`` folders and will complain if said -folders don't exist). - -Typically one thinks of the code itself as having a single state. This state -evolves as features are added to the code. The timeline of the code's state is -termed the "master branch" (history in Git is thought of as tree-like). By -default the clone you get only has the master branch. A widely adopted -convention of the Git community (adherence to which will make your life easier -long term) is that the master branch should always be deployable (*i.e.* work -and be relatively bug-free). This convention is easy to meet if we always -keep this branch clean (*i.e.* don't make your changes to it) and we keep it -up to date. In an effort to keep the master branch clean the first -thing you should do is thus make a new branch. This is done by: - -.. code-block:: bash - - git checkout -b - -where ``branch_name`` is the name of the branch you'll be working on. The -``-b`` flag tells Git to make the branch (Git will yell at you if the branch -exists and you use the ``-b`` flag). The resulting branch starts a new timeline -that diverges from the master branch's current state. All of your development -will occur on this branch. Since the branch has diverged from the master branch -it is safe to routinely track your changes, even before they're ready to be -merged back into master. - -At this point you begin developing your great new feature on your new branch. -As time goes by and you write more and more code, you'll reach a point where -you'll want to save the branch's state with Git so that you can revert if -something goes horribly wrong. To do this, first you have to tell Git what -files you want to save: - -.. code-block:: bash - - git add - -where ``files_to_save`` is one or more files to save (Linux wild cards work, -*e.g.* ``git add *.cpp`` will save all C++ source files in the current directory). -After this command, the state of the files is not saved yet (they are what is -typically referred to as staged). The staging phase makes it easier for you to -fine tune what gets saved and what doesn't. You can run ``git add`` as many -times as you want and keep amassing files to save. It's useful to note that -you can get a wealth of information about the current repo's state via: - -.. code-block:: bash - - git status - -Among other things, this command will tell you which files are not versioned, -which versioned files are changed, but not staged, and which versioned files -are staged. Once you're happy with the set of staged files, you "commit" them -via: - -.. code-block:: bash - - git commit -m "" - -This command will save all staged files to your branch and log the commit -with some (hopefully descriptive) message (if you omit the ``-m`` flag and the -message it'll bring up your text editor of choice so that you can type one). -After running this command your code's state is saved; however, the files are -only saved to your current branch, they are not saved to any other branch -(other branch notably including the master branch) or repo yet. - -At some point you'll want to move your feature to another repo. Typically this -other repo is the original repo you cloned. Because we are now attempting to -partially synchronize two repos, there's a lot of possibilities for how we want -to do this. In an effort to keep this simple, we note that 99.9% of the time, -using the GitHub workflow laid out below we want to synchronize a single branch -of each repo. Moreover we want to synchronize the same branch (that is we -typically will not be directly merging into master as explained below). For -simplicity we assume our current repo is on the branch we currently want to -synchronize (if you're not ``git checkout ``) and all changed -files have been committed. Before we can synchronize, we have to make sure we -have all of the changes on the original repo's branch (if the original repo -doesn't have this branch yet, *i.e.* your commit will make it, skip this step; -as with most things Git will yell at you if you attempt to synchronize with a -non-existent branch or if that branch is ahead of yours). The command to "pull" -the other branch's changes is: - -.. code-block:: bash - - git pull origin - -``origin`` is an alias Git automatically defines for you, which points to the -original repo you cloned (obviously change origin if you're not synchronizing -with the original repo). ``branch_name`` should be both the name of your current -branch and the name of the other repo's branch. It is possible for conflicts to -occur at this point, so it's worth discussing them now. Git's pretty good about -merging contributions from multiple developers automatically. Nevertheless -conflicts do occur. If during a merge a conflict does occur, you'll have to -correct it manually. To do this take note of the conflicting files (if you -forget you can get the list again by running ``git status``). For each file -you'll need to fix all conflicts contained within it. Within the file, Git -will add three delimiters. The conflicting lines of code will start with -``<<<<<<< HEAD`` and end with ``>>>>>>> branch_name`` delimiters. In between -these delimiters ``=======`` will separate your changes (top half) from the -other repo's changes (bottom half). To fix the conflict, you'll need to delete -the delimiters and manually merge the changes. Once you've done that you -stage and then commit the file. Finally, once all conflicts are fixed (if any -existed) you "push" your changes to the other repo: - -.. code-block:: bash - - git push origin - -While it's essential to keep the master branch of your repo clean, it's also -good practice to keep it synchronized with that of the repo you cloned (we'll -get to why in a moment). Synchronization of the the master branch is akin to -the first half of the procedure we just outlined. First (assuming you're -on your development branch and not the master branch) change to your master -branch: - -.. code-block:: bash - - git checkout master - -then pull the original repo's master branch via: - -.. code-block:: bash - - git pull origin master - -Since you're following this tutorial there'll be no problems with the merge -and everything will go swimmingly. With your master branch up-to-date you'll -want to merge those changes into your active development branch. To do this, -check-out your development branch and run: - -.. code-block:: bash - - git merge master - -This will merge the contents of your repo's master branch into your current -branch. Depending on how master has changed conflicts may occur; if they do, -you simply deal with them as we did above. - - -GitHub Workflow -=============== - -The commands from the previous section are complemented by several GitHub -extensions. We explain these extensions in this section. For the purposes -of this tutorial, let's say you want to contribute to a very creatively named -repo on GitHub called "GitHubRepo". Well we've got two problems. First, the -maintainers of "GitHubRepo" probably don't want you directly committing to -their code base without them first looking at your contribution ("looking at" is -typically automated to some extent). Hence, they'll need to pull your changes -into a sandbox area and assess them before committing them. This leads to the -second problem, you probably don't want them accessing your computer. GitHub has -purposed a solution, it's called forking. Alls it is, is a fancy clone -procedure. During forking GitHub clones "GitHubRepo" to your account (thereby -hosting the clone on GitHub itself). We'll call the resulting clone -"GitHubFork". Basically "GitHubFork" is a buffer repo that you both can -access comfortably (as in the spirit of Git itself each fork is a legitimate -GitHub repo itself and can be forked too, great for allowing the workflow -described here to be done recursively for collaborations). As for how to -fork, on "GitHubRepo"'s GitHub page just click the fork button at the top. - -After forking, the Git procedure continues like normal. You clone -"GitHubFork" to your local machine and checkout a new branch preserving -master. To save yourself some typing later you'll want to define an alias for -"GitHubRepo" (origin will be set to "GitHubFork"). Typically this alias is -called "upstream". To make this alias the command is: - -.. code-block:: bash - - git remote add upstream - -It is polite at this point to notify the maintainers of "GitHubRepo" that you're -going to work on this feature. To do this you first push your development -branch to "GitHubFork". Then on "GitHubFork"'s GitHub page you should see a -box pop up that says your branch's name and "compare and pull request" (if -not you can go to the branches tab and manually start a pull request). A -pull request is just that, it's a request for the maintainers of "GitHubRepo" to -pull the specified branch into their repository. Since you're opening this -PR (that's short for pull request and is a very prevalent abbreviation on -GitHub, so learn it) before finishing the code, it's customary to title the PR -something like "[WIP] Descriptive Title". Here "WIP" stands for "work in -progress" (again common abbreviation) and tells the maintainers that it's not -ready yet. You'll also need to provide a description of what your feature -does (many repos will provide a template that you should fill out to the best -of your ability). Starting the PR early is a good idea as it provides you a -means of getting feedback along the way ranging from "don't bother doing -this, we don't want your feature" to "that's great, let us know if there's -any way we can help you get that implemented". It also will be the place -where a code-review (the maintainers of the repo look at your code and make -comments on it) will occur. By starting early the code-review can be done in -stages (assuming you regularly update "GitHubFork"). - -For the most part the remainder of the development cycle is pretty -standard. The big exception is staying synchronized with "GitHubRepo". Since -other developers who contribute to "GitHubRepo" aren't going to be nice -enough to push their changes to your fork of the repo, you can't just run the -pull command from the last section. Hence, in order for you to stay -up-to-date with "GitHubRepo" you'll need to pull changes from its master -branch into your local master branch. The command is similar (and the reason -we defined the "upstream" alias): - -.. code-block:: bash - - git pull upstream master - -With your local master branch synched, you'll then want to synch -"GitHubFork"'s master branch. To do this you'll push the local changes to -"GitHubFork". The command is: - -.. code-block:: bash - - git push origin master - -Although not strictly necessary, this step makes it easier for you to recover -should anything go wrong. In particular let's say you accidentally modify your -local master branch. By ensuring your "GitHubFork" master branch is a clean -copy of the "GitHubRepo"'s at some point in its history you can run (on your -master branch): - -.. code-block:: bash - - git reset --hard origin/master - -This command will delete all changes made to your current master branch, and -make it exactly equal to the state of "GitHubFork"'s master branch. YOU WILL -ALMOST CERTAINLY LOSE WORK BY DOING THIS. It's thus best to first checkout a -new branch, that is a copy of the current master branch, before executing this -command. - -Once you're done developing you need to notify the "GitHubRepo" maintainers. -This is typically done in two ways. First, the "[WIP]" tag is removed from -the title of your PR. As this is easy to miss, you typically will also comment in -the PR "r2g" (short for ready to go). Comments are a lot harder to miss. At -this point the ball's in the maintainers court to accept your PR or provide -additional feedback of things that need fixing (which assuming you were -pushing to "GitHubFork" regularly, will hopefully not be a long list). Once -the PR is approved either you or the maintainers will click on the "merge" -button provided by GitHub and your code will be merged. That's it, your -feature is merged, the PR is closed, and you can delete your branch. It is -recommended that the contributor clicks merge in order to avoid premature -merging (simply because the reviewer has accepted what's there doesn't mean -that the contributor is done contributing via that PR). - -The image below summarizes the discussion above. The left side of the red -line is the GitHub "official" repo. On the right side of the red line are -the repos that you (the developer) own. Above the black dotted line are the -repos on GitHub and below the black line are the repos that live locally on your -own computer (or other computers you are using). - -.. image:: github_workflow.png - -Further Information -=================== - -There is much more to both GitHub and Git itself. The following is a collection -of tutorials offering additional information on certain topics. - -- `The Git Command `_ -- `GitHub Workflow `_ -- `Forking a Repo on GitHub `_ diff --git a/docs/source/resources/github/github_workflow.png b/docs/source/resources/github/github_workflow.png deleted file mode 100644 index d0554ebb..00000000 Binary files a/docs/source/resources/github/github_workflow.png and /dev/null differ diff --git a/docs/source/resources/github/index.rst b/docs/source/resources/github/index.rst deleted file mode 100644 index e08440f6..00000000 --- a/docs/source/resources/github/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. 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. - -.. _nwx_github_tutorials: - -########################## -Using GitHub with NWChemEx -########################## - -The tutorials in this section cover how to use GitHub. Unlike general GitHub -tutorials on the web, the ones in this section are specifically tailored to -the NWChemEx project. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - git_tutorial - issue - pull_request diff --git a/docs/source/resources/github/issue.rst b/docs/source/resources/github/issue.rst deleted file mode 100644 index 8801090c..00000000 --- a/docs/source/resources/github/issue.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. 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. - -.. _nwx_github_issues: - -################################# -Using GitHub Issues with NWChemEx -################################# - -TODO: Write me!!! - -.. _using_issues_to_track_progress: - -****************************** -Using Issues to Track Progress -****************************** - -TODO: Write me!!! - -*************** -Further Reading -*************** - - - `Quickstart for GitHub Issues ` diff --git a/docs/source/resources/github/pull_request.rst b/docs/source/resources/github/pull_request.rst deleted file mode 100644 index 72da3ff8..00000000 --- a/docs/source/resources/github/pull_request.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. 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. - -.. _nwx_github_pull_requests: - -######################################## -Using GitHub Pull Requests with NWChemEx -######################################## - -TODO: Write me!!! - - -*************** -Further Reading -*************** - -- GitHub's `Creating a pull request `__ diff --git a/docs/source/resources/index.rst b/docs/source/resources/index.rst deleted file mode 100644 index 1bee0faa..00000000 --- a/docs/source/resources/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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. - -.. _additional_developer_resources: - -############################## -Additional Developer Resources -############################## - -The documentation in this section are tutorials and notes assembled by NWChemEx -developers designed to help other developers come up to speed with the tools -used for developing NWChemEx. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - github/index - recommended_development_resources diff --git a/docs/source/resources/recommended_development_resources.rst b/docs/source/resources/recommended_development_resources.rst deleted file mode 100644 index 89aed659..00000000 --- a/docs/source/resources/recommended_development_resources.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. Copyright 2025 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. - -################################# -Recommended Development Resources -################################# - -The point of this page is to collect a list of recommended programs, -applications, and websites for performing development tasks. - -************************** -Naming Libraries and Repos -************************** - -https://namelix.com - Namelix uses AI to generate possible names for your package. You provide - keywords about your package, tweak some options, and it returns tons of - results. You can customize the length and style (mispellings, rhyming words, - *etc.*) of the generated names. - -****************************** -Drawing Documentation Diagrams -****************************** - -https://excalidraw.com - Excalidraw has an easy to use API which allows you to quickly draw UML-like - diagrams. You can export the diagram as a PNG or SVG (embedding the code - for the diagram in the image so you can modify it later). Another cool - feature is that you can share the diagram with other people and you can all - work on the diagram in real time. - -************************************** -Creating ASCII File Structure Diagrams -************************************** - -https://ascii-tree-generator.com/ - This is a simple web app which provides a GUI that acts like a file browser. - In the GUI you can create folders and files and drag them around to nest - them. The app then generates an ASCII representation of the file system which - you can then copy/paste into documentation (or wherever else you want to - put the diagram). diff --git a/docs/source/testing/assets/DependencyChart.png b/docs/source/testing/assets/DependencyChart.png deleted file mode 100644 index 023a5671..00000000 Binary files a/docs/source/testing/assets/DependencyChart.png and /dev/null differ diff --git a/docs/source/testing/assets/DependencyChartExtended.png b/docs/source/testing/assets/DependencyChartExtended.png deleted file mode 100644 index 37f79cbc..00000000 Binary files a/docs/source/testing/assets/DependencyChartExtended.png and /dev/null differ diff --git a/docs/source/testing/index.rst b/docs/source/testing/index.rst deleted file mode 100644 index 369bd2ed..00000000 --- a/docs/source/testing/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. 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. - -.. _testing_nwx: - -################ -Testing NWChemEx -################ - -The topics below relate to testing NWChemEx. - -.. toctree:: - :maxdepth: 1 - - unit - integration - performance diff --git a/docs/source/testing/integration.rst b/docs/source/testing/integration.rst deleted file mode 100644 index 62361c74..00000000 --- a/docs/source/testing/integration.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. 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. - -.. _writing_integration_tests: - -###################################### -Writing Integration Tests for NWChemEx -###################################### - -NWChemEx is a modular ecosystem designed with separation of concerns as a key -design point. An example of this separation can be found with the -SCF, integrals, ChemCache libraries. These components of NWX are linked by -SimDE and are intended to be used together, but are not explicitly required for -the development of the other (see :numref:`fig_deps_chart`). The unit tests for -these libraries are intended to ensure basic functionality and correctness, -which can usually be accomplished with simple test data that allow the unit -tests to run quickly. - -.. _fig_deps_chart: - -.. figure:: assets/DependencyChart.png - :align: center - :scale: 50 % - - A simplified diagram of the NWChemEx dependency structure. Note that plugins - depending on SimDE are parallel to one another, and are integrated together - within NWChemEx. Arrows point from a dependency to the dependent library. - - -With that said, the initial development and testing of the SCF becomes very -awkward when one is unable to easily acquire real integrals for real molecular -systems. Additionally, changes to the integrals code could have deleterious -effects on the SCF code, which we would like to detect before merging. For these -(and other) reasons, it can be useful to implement integration tests to ensure -the continued interoperability of the isolated components of the NWX stack. -Because the tests are built on top of the plugins, it is simple to include -NWChemEx itself as a dependency of the test (see :numref:`fig_integration_chart`). -This way, changes at the plugin level can be screened to guarantee that they -don't break interoperability with the others. - -.. _fig_integration_chart: - -.. figure:: assets/DependencyChartExtended.png - :align: center - :scale: 50 % - - A diagram illustrating the relationship between the integration tests, the - library they test, and the top-level NWChemEx library. Arrows point from a - dependency to the dependent library. - - -CMake for Integration Testing -============================= - -The following code-block provides an example for how one can add the option for -an integration test to a project that uses the NWX ecosystem. - -.. code-block:: CMake - - # Include option - cmaize_option_list( - BUILD_INTEGRATION_TESTS ON "Build the integration tests?" - ) - - # How to build the integration tests - if("${BUILD_INTEGRATION_TESTS}") - include(nwx_pybind11) - # Set relevant test directories - set(CXX_INCLUDE_DIR /path/to/cxx/includes) - set(CXX_TEST_DIR /path/to/cxx/integration/tests) - set(PYTHON_TEST_DIR /path/to/python/integration/tests) - - # Build NWChemEx for the test - cmaize_find_or_build_dependency( - nwchemex - URL github.com/NWChemEx/NWChemEx - VERSION master - BUILD_TARGET nwchemex - FIND_TARGET nwx::nwchemex - CMAKE_ARGS BUILD_TESTING=OFF - BUILD_PYBIND11_PYBINDINGS=ON - ) - - # Add integration tests - nwx_pybind11_tests( - py_test_integration_scf - "${PYTHON_TEST_DIR}/test_main.py" - SUBMODULES parallelzone pluginplay chemist simde chemcache friendzone nwchemex - ) - endif() - -Integration Tests -================= - -Building on the description provided in :ref:`writing_unit_tests`, integration -tests are written in the same manner. Below is an example of how to use NWChemEx -in our new integration test to acquire input values and submodules that may be -needed by a module in our project. - -.. code-block:: python - - import unittest - import nwchemex - import scf - from pluginplay import ModuleManager - from simde import AOEnergy - from simde import MoleculeFromString - from simde import MolecularBasisSet - - class TestIntegration(unittest.TestCase): - - def test_scf_module(self): - # Module we want to test - key = "SCF Module" - - # Property Types from SimDE - molecule_pt = MoleculeFromString() - basis_set_pt = MolecularBasisSet() - energy_pt = AOEnergy() - - # Can use NWChemEx modules to get inputs - mol = self.mm.run_as(molecule_pt, "NWX Molecules", "water") - bs = self.mm.run_as(basis_set_pt, "sto-3g", mol) - - # set NWChemEx modules as needed submodules - submod_key = "A submodule of my SCF module" - integral_key = "Some integral needed to run SCF" - mm.change_submod(key, submod_key, integral_key) - - # Test our module - egy = self.mm.run_as(energy_pt, key, mol, bs) - self.assertAlmostEqual(egy, 3.14159265359, places=6) - - def test_another_module(self): - # Add more tests where appropriate - pass - - def setUp(self): - self.mm = ModuleManager() - nwchemex.load_modules(mm) # Also loads out SCF modules diff --git a/docs/source/testing/performance.rst b/docs/source/testing/performance.rst deleted file mode 100644 index 3ea7a61c..00000000 --- a/docs/source/testing/performance.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. 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. - -.. _writing_performance_tests: - -###################################### -Writing Performance Tests for NWChemEx -###################################### - -TODO: Write me!!!! diff --git a/docs/source/testing/unit.rst b/docs/source/testing/unit.rst deleted file mode 100644 index 613ce0bb..00000000 --- a/docs/source/testing/unit.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. 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. - -.. _writing_unit_tests: - -############################### -Writing Unit Tests for NWChemEx -############################### - -Within the first party NWChemEx libraries, we aim for extensive unit testing to -ensure functionality and correctness. All classes, functions, and modules added -to any of the first party libraries will be expected to have corresponding unit -tests. Testing of functions (as well as Plugin modules) should minimally ensure -that all return routes and errors are checked. Tests for classes should do the -same for all member functions, while additionally testing that the state of all -instances is consistent at construction and after modifications. Generally, the -unit tests should be able to run quickly, and use simplified data with the -minimum level of complexity need to ensure completeness in the testing. - -The C++ unit tests use the `Catch2 framework `_, -while python tests use the `unittest framework `_. -Assume the following class and related comparison function are intended to be -added to one of the first party libraries: - -.. tabs:: - - .. tab:: C++ - - .. code-block:: c++ - :linenos: - - #include - - class ToBeTested { - private: - using value_type = int; - value_type my_value_; - - public: - ToBeTested(value_type a_value = 0) : my_value_(a_value) {} - - value_type check_my_value() { return my_value_; } - - void change_my_value(value_type new_value) { - if(new_value == 13) throw std::runtime_error("Unlucky Number"); - my_value_ = new_value; - } - - bool operator==(const ToBeTested& rhs) const noexcept { - return my_value_ == rhs.my_value_; - } - - }; // ToBeTested - - inline bool operator!=(const ToBeTested& lhs, const ToBeTested& rhs) { - return !(lhs == rhs); - } - - .. tab:: Python - - .. code-block:: python - :linenos: - - class ToBeTested(): - - def __init__(self, a_value = 0): - self.__my_value = a_value - - def check_my_value(self): - return self.__my_value - - def change_my_value(self, new_value): - if new_value == 13: - raise RuntimeError("Unlucky Number") - self.__my_value = new_value - - def __eq__(self, other): - if not isinstance(other, ToBeTested): - return NotImplemented - return self.__my_value == other.__my_value - -An example unit test for the above looks like: - -.. tabs:: - - .. tab:: C++ - - .. code-block:: c++ - :linenos: - - #include "to_be_tested.hpp" - #include - - TEST_CASE("ToBeTested") { - auto defaulted = ToBeTested(); - auto with_value = ToBeTested(3); - - SECTION("Comparisons") { - SECTION("operator==") { - REQUIRE(defaulted == ToBeTested()); - REQUIRE(with_value == ToBeTested(3)); - REQUIRE_FALSE(defaulted == with_value); - } - SECTION("operator!=") { - REQUIRE(defaulted != with_value); - } - } - - SECTION("check_my_value") { - REQUIRE(defaulted.check_my_value() == 0); - REQUIRE(with_value.check_my_value() == 3); - } - - SECTION("change_my_value") { - SECTION("Not Unlucky") { - defaulted.change_my_value(7); - REQUIRE(defaulted.check_my_value() == 7); - } - SECTION("Unlucky") { - REQUIRE_THROWS_AS(defaulted.change_my_value(13), - std::runtime_error); - } - } - } - - .. tab:: Python - - .. code-block:: python - :linenos: - - from to_be_tested import ToBeTested - import unittest - - class TestNewClass(unittest.TestCase): - def setUp(self): - self.defaulted = ToBeTested() - self.with_value = ToBeTested(3) - - def test_equality(self): - self.assertEqual(self.defaulted, ToBeTested()) - self.assertEqual(self.with_value, ToBeTested(3)) - self.assertNotEqual(self.defaulted, self.with_value) - - def test_check_my_value(self): - self.assertEqual(self.defaulted.check_my_value(), 0) - self.assertEqual(self.with_value.check_my_value(), 3) - - def test_change_my_value(self): - self.defaulted.change_my_value(7) - self.assertEqual(self.defaulted.check_my_value(), 7) - - with self.assertRaises(RuntimeError) as context: - self.defaulted.change_my_value(13) - self.assertTrue("Unlucky Number" in str(context.exception))