diff --git a/.github/workflows/build_nwx_buildenv_image.yaml b/.github/workflows/build_nwx_buildenv_image.yaml index b77f00d8..aa0cf928 100644 --- a/.github/workflows/build_nwx_buildenv_image.yaml +++ b/.github/workflows/build_nwx_buildenv_image.yaml @@ -39,4 +39,3 @@ jobs: docker tag nwx_buildenv:latest ghcr.io/nwchemex/nwx_buildenv:latest docker push ghcr.io/nwchemex/nwx_buildenv:latest shell: bash - \ No newline at end of file diff --git a/.github/workflows/check_formatting.yaml b/.github/workflows/check_formatting.yaml index 96b498ac..78d5b151 100644 --- a/.github/workflows/check_formatting.yaml +++ b/.github/workflows/check_formatting.yaml @@ -63,11 +63,11 @@ jobs: - name: Checkout Source uses: actions/checkout@v4 - name: Check C++ Formatting - uses: DoozyX/clang-format-lint-action@v0.18 + uses: DoozyX/clang-format-lint-action@v0.20 with: source: ${{ inputs.cpp_source_dirs }} extensions: "hpp,cpp,ipp,h,c" - clangFormatVersion: 12 + clangFormatVersion: 20 inplace: False # Check Python formatting. @@ -80,9 +80,9 @@ jobs: - uses: actions/setup-python@v2 with: python-version: "3.x" - - name: Install yapf - run: pip install yapf + - name: Install black + run: pip install black shell: bash - name: Check Python Formatting - run: yapf -r -q . + run: black --check --line-length=79 . shell: bash diff --git a/.github/workflows/deploy_nwx_docs.yaml b/.github/workflows/deploy_nwx_docs.yaml index 8492ca02..71e01ca0 100644 --- a/.github/workflows/deploy_nwx_docs.yaml +++ b/.github/workflows/deploy_nwx_docs.yaml @@ -30,7 +30,7 @@ on: jobs: deploy_docs: runs-on: ubuntu-latest - container: + container: image: ghcr.io/nwchemex/nwx_buildenv:latest steps: - name: Fail if Target is Blank @@ -44,7 +44,7 @@ jobs: # These next two steps will configure CMake if required - name: Configure Only Docs if: | - inputs.generate_module_docs == false && + inputs.generate_module_docs == false && inputs.doc_target != 'Sphinx' run: | cmake -Bbuild -H. -GNinja -DBUILD_DOCS=ON -DONLY_BUILD_DOCS=ON @@ -90,4 +90,4 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} - publish_dir: ./docs/build/html + publish_dir: ./docs/build/html diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml index 22a057f0..ebdd2060 100644 --- a/.github/workflows/pull_request.yaml +++ b/.github/workflows/pull_request.yaml @@ -24,7 +24,7 @@ jobs: check_formatting: uses: ./.github/workflows/check_formatting.yaml with: - license_config: "" # Skip license check here + license_config: ".licenserc.yaml" cpp_source_dirs: "" # Skip clang-format check test_nwx_docs: diff --git a/.github/workflows/test_nwx_docs.yaml b/.github/workflows/test_nwx_docs.yaml index d2812dee..a4d5a728 100644 --- a/.github/workflows/test_nwx_docs.yaml +++ b/.github/workflows/test_nwx_docs.yaml @@ -28,13 +28,13 @@ on: type: boolean required: false default: true - - + + jobs: test_build_docs: runs-on: ubuntu-latest - container: + container: image: ghcr.io/nwchemex/nwx_buildenv:latest steps: - name: Fail if Target is Blank @@ -73,4 +73,3 @@ jobs: fi make html SPHINXOPTS="${SPHINX_OPTS}" shell: bash - diff --git a/.gitignore b/.gitignore index 08b7f94e..f16fb6d1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,17 @@ +# 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. + # This is where VSCode stores its settings .vscode @@ -7,4 +21,4 @@ venv/ # This is the default build directory for the docs docs/build -.DS_Store \ No newline at end of file +.DS_Store diff --git a/.licenserc.yaml b/.licenserc.yaml new file mode 100644 index 00000000..621b0809 --- /dev/null +++ b/.licenserc.yaml @@ -0,0 +1,28 @@ +# 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. +# +header: + license: + spdx-id: Apache-2.0 + copyright-owner: NWChemEx-Project + + paths-ignore: + - .github/ + - docs/Makefile + - docs/source/bibliography/software.bib + - LICENSE + - docs/requirements.txt + - version.txt + + comment: never diff --git a/README.md b/README.md index 3a7ed531..1bf091b1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,18 @@ + + # .github GitHub Settings for the NWChemEx Organization diff --git a/assets/logos/README.md b/assets/logos/README.md index 4d7ce704..5bebef9f 100644 --- a/assets/logos/README.md +++ b/assets/logos/README.md @@ -1,3 +1,19 @@ + + # NWChemEx Branding Images (Logos for short) This directory contains images used to define the NWChemEx and NWChemEx diff --git a/docs/README.md b/docs/README.md index 714704d3..f58b4627 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,19 @@ + + Source Files for Developer Documentation ======================================== diff --git a/docs/requirements.txt b/docs/requirements.txt index 1c01d05e..2110383a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ docutils<=0.16 sphinx sphinx_rtd_theme -sphinxcontrib.bibtex sphinx_tabs +sphinxcontrib.bibtex diff --git a/docs/source/BuildValidation.md b/docs/source/BuildValidation.md index c371cb3d..9799773f 100644 --- a/docs/source/BuildValidation.md +++ b/docs/source/BuildValidation.md @@ -1,3 +1,19 @@ + + NWChemEx Build Validation Policy ================================ @@ -56,4 +72,4 @@ releases. 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? \ No newline at end of file + parameters? diff --git a/docs/source/TestRequirements.md b/docs/source/TestRequirements.md index d2d520f8..c36c5ebb 100644 --- a/docs/source/TestRequirements.md +++ b/docs/source/TestRequirements.md @@ -1,3 +1,19 @@ + + Testing Requirements for New Pull Requests ========================================== @@ -15,7 +31,7 @@ There are outstanding questions regarding the test requirements: - 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 + - 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 @@ -32,4 +48,3 @@ There are outstanding questions regarding the test requirements: 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/coding/cxx/cxx_development_workflow.rst b/docs/source/coding/cxx/cxx_development_workflow.rst index 9c6a875e..7148126b 100644 --- a/docs/source/coding/cxx/cxx_development_workflow.rst +++ b/docs/source/coding/cxx/cxx_development_workflow.rst @@ -1,3 +1,17 @@ +.. 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 ************************ diff --git a/docs/source/coding/ides/index.rst b/docs/source/coding/ides/index.rst index 8310587e..b73fc1d8 100644 --- a/docs/source/coding/ides/index.rst +++ b/docs/source/coding/ides/index.rst @@ -1,3 +1,17 @@ +.. 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: ######################### diff --git a/docs/source/coding/ides/vscode/assets/click_explorer.svg b/docs/source/coding/ides/vscode/assets/click_explorer.svg index d8a831b3..ab7d0a4c 100644 --- a/docs/source/coding/ides/vscode/assets/click_explorer.svg +++ b/docs/source/coding/ides/vscode/assets/click_explorer.svg @@ -1,4 +1,20 @@ + + + + `__. +items?itemName=ms-python.python>`__. 1. Install the `yapf extension `__. @@ -65,8 +79,8 @@ 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 +items?itemName=njpwerner.autodocstring>`__ extension. Once the extension is +installed, set the ``autoDocstring.docstringFormat`` setting to "sphinx" to match current NWX team :ref:`python-coding-conventions`. .. note:: diff --git a/docs/source/coding/ides/vscode/developing_docker.rst b/docs/source/coding/ides/vscode/developing_docker.rst index d537db66..85565f0e 100644 --- a/docs/source/coding/ides/vscode/developing_docker.rst +++ b/docs/source/coding/ides/vscode/developing_docker.rst @@ -1,9 +1,23 @@ +.. 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 +system (OS) / file system. "Local" is contrasted with "Docker", which means the OS and file system being used in a Docker container. **** @@ -24,19 +38,19 @@ 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 +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 `__. +- 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 @@ -44,20 +58,20 @@ 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 +- 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. - +- 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 @@ -66,12 +80,12 @@ Creating the Container .. figure:: assets/docker/select_options.png :align: center - Follow the prompts the Dev Containers Extension raises. + 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" +- 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 @@ -81,10 +95,10 @@ Creating the Container 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 + 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). @@ -98,7 +112,7 @@ Creating the Container - 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". @@ -106,4 +120,4 @@ Creating the Container Sources ******* -- `Dev Containers Extension `__. \ No newline at end of file +- `Dev Containers Extension `__. diff --git a/docs/source/coding/ides/vscode/faqs.rst b/docs/source/coding/ides/vscode/faqs.rst index f4217e4c..6ea0bb0d 100644 --- a/docs/source/coding/ides/vscode/faqs.rst +++ b/docs/source/coding/ides/vscode/faqs.rst @@ -1,3 +1,17 @@ +.. 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 ==== @@ -30,9 +44,9 @@ the command palette. Then select ``Python: Select Interpreter``. Navigate to 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 +you probably don't. To fix this add to the ``launch.json`` file for your debugging session: - + .. code-block:: json "sourceFileMap": { @@ -48,7 +62,7 @@ debugging session: 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 index e3312861..4f0d74ce 100644 --- a/docs/source/coding/ides/vscode/index.rst +++ b/docs/source/coding/ides/vscode/index.rst @@ -1,3 +1,17 @@ +.. 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 ****** diff --git a/docs/source/coding/ides/vscode/setup.rst b/docs/source/coding/ides/vscode/setup.rst index 1f563ae6..b2f2aa6e 100644 --- a/docs/source/coding/ides/vscode/setup.rst +++ b/docs/source/coding/ides/vscode/setup.rst @@ -1,3 +1,17 @@ +.. 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 ########################### diff --git a/docs/source/coding/ides/vscode/setup_mac.rst b/docs/source/coding/ides/vscode/setup_mac.rst index a3bbcd19..3b9d1c08 100644 --- a/docs/source/coding/ides/vscode/setup_mac.rst +++ b/docs/source/coding/ides/vscode/setup_mac.rst @@ -1,3 +1,17 @@ +.. 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 ########################## @@ -29,7 +43,7 @@ screen. 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 @@ -45,7 +59,7 @@ screen. Install the Python extension. - - If you have not previously installed "command line developer tools" follow + - If you have not previously installed "command line developer tools" follow the prompts. .. figure:: assets/mac_setup/install_command_line_tools.png @@ -55,11 +69,11 @@ screen. Python. - Tune your settings. Click "Open Settings". - + .. figure:: assets/mac_setup/tune_settings.png :align: center - Tune VSCode's settings to your liking. + 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. @@ -75,8 +89,8 @@ screen. .. 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. + 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) @@ -123,7 +137,7 @@ Adding Repositories :align: center Step 2. (With git installed) click "Clone Repository". - + .. figure:: assets/mac_setup/clone_from_github.png :align: center @@ -131,14 +145,14 @@ Adding Repositories .. 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 + 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 @@ -151,13 +165,13 @@ Adding Repositories .. 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 @@ -165,21 +179,21 @@ Adding Repositories (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 + 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 + 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:: @@ -238,42 +252,42 @@ assumes you have Clang and are creating a Clang kit. .. 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 + :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) + 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 + + 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 + This step assumes you did not skip the :ref:`creating_a_cmake_toolchain_file` section. - Another good idea, assuming you have Ninja installed + Another good idea, assuming you have Ninja installed (``brew install ninja``) is to add it to your kit via: .. code-block:: @@ -296,7 +310,7 @@ Configuring a Project .. 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 @@ -314,9 +328,9 @@ Troubleshooting 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 + 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.: @@ -327,20 +341,20 @@ Troubleshooting 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 + :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, +- 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 @@ -381,7 +395,7 @@ Committing Changes Back to GitHub .. figure:: assets/mac_setup/stage_changes.png :align: center - Step 2. (Optional) select the file(s) you want to stage by clicking on the + 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. @@ -413,7 +427,7 @@ Troubleshooting :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: @@ -427,7 +441,7 @@ Troubleshooting .. figure:: assets/mac_setup/set_git_name.png :align: center - How to set the email and user name for git. + How to set the email and user name for git. - When attempting to synchronize with GitHub you get a cryptic error like: @@ -436,8 +450,8 @@ Troubleshooting :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 + 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 index d5ab1a1f..ace3a2e7 100644 --- a/docs/source/coding/ides/vscode/tips_and_tricks.rst +++ b/docs/source/coding/ides/vscode/tips_and_tricks.rst @@ -1,3 +1,17 @@ +.. 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 ========================== diff --git a/docs/source/coding/index.rst b/docs/source/coding/index.rst index 3405cb05..d4b9d95b 100644 --- a/docs/source/coding/index.rst +++ b/docs/source/coding/index.rst @@ -1,3 +1,17 @@ +.. 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 ################### diff --git a/docs/source/coding/preliminaries.rst b/docs/source/coding/preliminaries.rst index 99ae413f..32f09599 100644 --- a/docs/source/coding/preliminaries.rst +++ b/docs/source/coding/preliminaries.rst @@ -1,3 +1,17 @@ +.. 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: ############# @@ -50,7 +64,7 @@ Installing Dependencies With Homebrew the dependencies and corresponding terminal commands are: -- python3 +- python3 - git ``brew install git``. - C and C++ compilers (MacOS comes with ``clang`` and ``clang++``) - CMake ``brew install cmake``. diff --git a/docs/source/coding/python/python_development_workflow.rst b/docs/source/coding/python/python_development_workflow.rst index d6b9ff8b..02d3f0f7 100644 --- a/docs/source/coding/python/python_development_workflow.rst +++ b/docs/source/coding/python/python_development_workflow.rst @@ -1,3 +1,17 @@ +.. 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: ########################### diff --git a/docs/source/conf.py b/docs/source/conf.py index 7093422b..8ba49cf3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,4 +1,18 @@ # -*- 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. # @@ -10,12 +24,12 @@ # -- Project information ----------------------------------------------------- -project = u'Developer Documentation' -copyright = u'2020, NWChemEx Team' -author = u'NWChemEx Team' +project = "Developer Documentation" +copyright = "2020, NWChemEx Team" +author = "NWChemEx Team" # TODO: get version from git -version = '1.0.0' +version = "1.0.0" # The full version, including alpha/beta/rc tags release = version @@ -34,32 +48,37 @@ # 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' + "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'] +# 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' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' +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' +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -67,7 +86,7 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" numfig = True @@ -76,18 +95,18 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +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'} +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'] +# html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -101,16 +120,16 @@ # 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/', + "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' +htmlhelp_basename = project + "doc" # -- Options for LaTeX output ------------------------------------------------ @@ -118,15 +137,12 @@ # 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', @@ -146,8 +162,8 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True -# -- Options for bibtex -------------------------------------------------------- +# -- Options for bibtex ------------------------------------------------------ -bibtex_bibfiles = ['bibliography/software.bib'] -bibtex_reference_style = 'super' -bibtex_default_style = 'plain' +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 index 3bebc9a7..a6eefbec 100644 --- a/docs/source/continuous_deployment/ci_maintainer_notes.rst +++ b/docs/source/continuous_deployment/ci_maintainer_notes.rst @@ -1,32 +1,46 @@ +.. 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 +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 +- `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) +#. ``.github`` (This is our configuration repository) #. ``ChemCache`` -#. ``Chemist`` +#. ``Chemist`` #. ``Integrals`` -#. ``Mokup`` -#. ``NWChemEx`` +#. ``Mokup`` +#. ``NWChemEx`` #. ``ParallelZone`` #. ``PluginPlay`` #. ``SimDE`` @@ -38,12 +52,12 @@ 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 +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 +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 @@ -119,9 +133,9 @@ 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 +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 +``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/documentation.rst b/docs/source/continuous_deployment/documentation.rst index 42a3837f..e6e8e0c4 100644 --- a/docs/source/continuous_deployment/documentation.rst +++ b/docs/source/continuous_deployment/documentation.rst @@ -1,3 +1,17 @@ +.. 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 ************************ @@ -22,7 +36,7 @@ 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 +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 diff --git a/docs/source/continuous_deployment/index.rst b/docs/source/continuous_deployment/index.rst index 94574f0e..a3458416 100644 --- a/docs/source/continuous_deployment/index.rst +++ b/docs/source/continuous_deployment/index.rst @@ -1,3 +1,17 @@ +.. 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 ##################### diff --git a/docs/source/conventions/cxx_conventions.rst b/docs/source/conventions/cxx_conventions.rst index c4726aba..7388684b 100644 --- a/docs/source/conventions/cxx_conventions.rst +++ b/docs/source/conventions/cxx_conventions.rst @@ -1,3 +1,17 @@ +.. 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: ********************** @@ -8,7 +22,7 @@ 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 +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. diff --git a/docs/source/conventions/doxygen_conventions.rst b/docs/source/conventions/doxygen_conventions.rst index 623310ab..cfb9ceaf 100644 --- a/docs/source/conventions/doxygen_conventions.rst +++ b/docs/source/conventions/doxygen_conventions.rst @@ -1,3 +1,17 @@ +.. 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: ************************************* diff --git a/docs/source/conventions/file_structure.rst b/docs/source/conventions/file_structure.rst index e46c20d6..fbe49943 100644 --- a/docs/source/conventions/file_structure.rst +++ b/docs/source/conventions/file_structure.rst @@ -51,7 +51,7 @@ File Naming Conventions 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 ``*``, ``?``, ``(``, ``)``, ``'``, + only. Notably avoid symbols like ``*``, ``?``, ``(``, ``)``, ``'``, and ``"``. Extensions @@ -61,7 +61,7 @@ Extensions - 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``. +- (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``. diff --git a/docs/source/conventions/index.rst b/docs/source/conventions/index.rst index f758ef58..80f80593 100644 --- a/docs/source/conventions/index.rst +++ b/docs/source/conventions/index.rst @@ -1,3 +1,17 @@ +.. 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 ################################# @@ -7,7 +21,7 @@ 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 +repository conventions). For organization maintainers, some internal notes on organizational decisions can be found in the NWChemEx Google Drive folder. ****************** @@ -21,6 +35,7 @@ Coding Conventions python_conventions doxygen_conventions rst_conventions + pre_commit ********************** Repository Conventions @@ -30,4 +45,3 @@ Repository Conventions :maxdepth: 2 file_structure - diff --git a/docs/source/conventions/pre_commit.rst b/docs/source/conventions/pre_commit.rst new file mode 100644 index 00000000..9608370d --- /dev/null +++ b/docs/source/conventions/pre_commit.rst @@ -0,0 +1,155 @@ +.. 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 index 7f522046..887af3d4 100644 --- a/docs/source/conventions/python_conventions.rst +++ b/docs/source/conventions/python_conventions.rst @@ -1,3 +1,17 @@ +.. 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: ************************* @@ -7,13 +21,13 @@ 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. +.. 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 +When possible, ``yapf`` (`PyPI link `__) will +be used to enforce code conventions. In general, Python code should be `PEP 8 compliant `__. Docstrings @@ -24,10 +38,10 @@ 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 +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:: - +.. 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 index cfae82e8..eaf6223b 100644 --- a/docs/source/conventions/rst_conventions.rst +++ b/docs/source/conventions/rst_conventions.rst @@ -1,3 +1,17 @@ +.. 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: ########################################## diff --git a/docs/source/design/energy_workflow.rst b/docs/source/design/energy_workflow.rst index 40ab96a9..209320ce 100644 --- a/docs/source/design/energy_workflow.rst +++ b/docs/source/design/energy_workflow.rst @@ -1,3 +1,17 @@ +.. 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 *************** diff --git a/docs/source/design/faqs.rst b/docs/source/design/faqs.rst index 2d88f0fb..27e59b4b 100644 --- a/docs/source/design/faqs.rst +++ b/docs/source/design/faqs.rst @@ -1,3 +1,17 @@ +.. 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 #### diff --git a/docs/source/design/index.rst b/docs/source/design/index.rst index 8ff8790b..de3d143d 100644 --- a/docs/source/design/index.rst +++ b/docs/source/design/index.rst @@ -1,3 +1,17 @@ +.. 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 #################### diff --git a/docs/source/design/nwx_ecosystem.rst b/docs/source/design/nwx_ecosystem.rst index d6af23a0..5ee00e94 100644 --- a/docs/source/design/nwx_ecosystem.rst +++ b/docs/source/design/nwx_ecosystem.rst @@ -1,3 +1,17 @@ +.. 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 ################## diff --git a/docs/source/design/overall_design.rst b/docs/source/design/overall_design.rst index bdb7cbb6..688b3ab3 100644 --- a/docs/source/design/overall_design.rst +++ b/docs/source/design/overall_design.rst @@ -1,3 +1,17 @@ +.. 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 ############## diff --git a/docs/source/design/overall_justifications/index.rst b/docs/source/design/overall_justifications/index.rst index c0d4f86f..18888a2d 100644 --- a/docs/source/design/overall_justifications/index.rst +++ b/docs/source/design/overall_justifications/index.rst @@ -1,3 +1,17 @@ +.. 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 ############################ diff --git a/docs/source/design/overall_justifications/one_repo_vs_many.rst b/docs/source/design/overall_justifications/one_repo_vs_many.rst index a9836dc7..79a96441 100644 --- a/docs/source/design/overall_justifications/one_repo_vs_many.rst +++ b/docs/source/design/overall_justifications/one_repo_vs_many.rst @@ -1,3 +1,17 @@ +.. 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? ################################# diff --git a/docs/source/design/overall_justifications/py_bindings.rst b/docs/source/design/overall_justifications/py_bindings.rst index cb751a8d..135ddab0 100644 --- a/docs/source/design/overall_justifications/py_bindings.rst +++ b/docs/source/design/overall_justifications/py_bindings.rst @@ -1,3 +1,17 @@ +.. 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 ######################################### diff --git a/docs/source/design/overall_justifications/why_chemcache.rst b/docs/source/design/overall_justifications/why_chemcache.rst index ffb30220..579c2fa2 100644 --- a/docs/source/design/overall_justifications/why_chemcache.rst +++ b/docs/source/design/overall_justifications/why_chemcache.rst @@ -1,3 +1,17 @@ +.. 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? ######################### diff --git a/docs/source/design/overall_justifications/why_cxx.rst b/docs/source/design/overall_justifications/why_cxx.rst index 15bb05ac..178d985d 100644 --- a/docs/source/design/overall_justifications/why_cxx.rst +++ b/docs/source/design/overall_justifications/why_cxx.rst @@ -1,3 +1,17 @@ +.. 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: ############################################ diff --git a/docs/source/design/overall_justifications/why_mokup.rst b/docs/source/design/overall_justifications/why_mokup.rst index 0a9bf188..7a5d79cf 100644 --- a/docs/source/design/overall_justifications/why_mokup.rst +++ b/docs/source/design/overall_justifications/why_mokup.rst @@ -1,3 +1,17 @@ +.. 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? ##################### diff --git a/docs/source/design/overall_justifications/why_oop.rst b/docs/source/design/overall_justifications/why_oop.rst index be66580d..389abc40 100644 --- a/docs/source/design/overall_justifications/why_oop.rst +++ b/docs/source/design/overall_justifications/why_oop.rst @@ -1,3 +1,17 @@ +.. 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: ################################ diff --git a/docs/source/design/overall_justifications/why_pluginplay.rst b/docs/source/design/overall_justifications/why_pluginplay.rst index 8fcafbc1..bbdd2f77 100644 --- a/docs/source/design/overall_justifications/why_pluginplay.rst +++ b/docs/source/design/overall_justifications/why_pluginplay.rst @@ -1,3 +1,17 @@ +.. 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: ########################## diff --git a/docs/source/design/overall_justifications/why_python.rst b/docs/source/design/overall_justifications/why_python.rst index bcfaba38..4b8534a8 100644 --- a/docs/source/design/overall_justifications/why_python.rst +++ b/docs/source/design/overall_justifications/why_python.rst @@ -1,3 +1,17 @@ +.. 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: ########################################## diff --git a/docs/source/design/overall_justifications/why_simde.rst b/docs/source/design/overall_justifications/why_simde.rst index 11248159..bcb9dca2 100644 --- a/docs/source/design/overall_justifications/why_simde.rst +++ b/docs/source/design/overall_justifications/why_simde.rst @@ -1,3 +1,17 @@ +.. 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? ##################### diff --git a/docs/source/design/overall_justifications/why_this_partitioning.rst b/docs/source/design/overall_justifications/why_this_partitioning.rst index 27d149f4..95eb29f8 100644 --- a/docs/source/design/overall_justifications/why_this_partitioning.rst +++ b/docs/source/design/overall_justifications/why_this_partitioning.rst @@ -1,3 +1,17 @@ +.. 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? ############################################## diff --git a/docs/source/design/overall_justifications/why_two_tensor_libraries.rst b/docs/source/design/overall_justifications/why_two_tensor_libraries.rst index 7f43cd91..2db46fca 100644 --- a/docs/source/design/overall_justifications/why_two_tensor_libraries.rst +++ b/docs/source/design/overall_justifications/why_two_tensor_libraries.rst @@ -1,3 +1,17 @@ +.. 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? ############################################### diff --git a/docs/source/design/overall_justifications/will_this_perform.rst b/docs/source/design/overall_justifications/will_this_perform.rst index d0cbcd71..dcf7b35d 100644 --- a/docs/source/design/overall_justifications/will_this_perform.rst +++ b/docs/source/design/overall_justifications/will_this_perform.rst @@ -1,3 +1,17 @@ +.. 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? ############################################### diff --git a/docs/source/design/philosophy.rst b/docs/source/design/philosophy.rst index bbc86c56..68d99bb8 100644 --- a/docs/source/design/philosophy.rst +++ b/docs/source/design/philosophy.rst @@ -1,3 +1,17 @@ +.. 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: ################### diff --git a/docs/source/design/ui_design.rst b/docs/source/design/ui_design.rst index 0164a851..ee9119a6 100644 --- a/docs/source/design/ui_design.rst +++ b/docs/source/design/ui_design.rst @@ -1,3 +1,17 @@ +.. 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 ###################### @@ -44,13 +58,13 @@ 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. +when something goes wrong, guiding users to resolve issues effectively. Tool-friendly ============= @@ -105,7 +119,7 @@ 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. +requires forgoing the UI and dropping down to PluginPlay's API. Minimal dependencies ==================== @@ -124,7 +138,7 @@ facilitating reproducibility. ************************************* 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 @@ -136,30 +150,30 @@ 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. + 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. + 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. @@ -215,7 +229,7 @@ calculation for a hydrogen molecule using the PsiAPI mode. import psi4 mol = psi4.geometry('H 0. 0. 0. \n H 0. 0. 1.') - energy= psi4.energy('scf/sto-3g') + 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 @@ -224,7 +238,7 @@ 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. +argument. QCEngine ======== @@ -285,14 +299,14 @@ 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. +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 + 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 @@ -309,7 +323,7 @@ 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 @@ -318,14 +332,14 @@ workflow in two different ways: # 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 + d = 1. + rank * 0.1 # Alternative 1 - # Initialize NWChemEx runtime with the sub-communicator + # 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 @@ -338,7 +352,7 @@ workflow in two different ways: Not In Scope ************* -**Graphical user interface (GUI)** +**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 @@ -354,4 +368,4 @@ objects. - 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. \ No newline at end of file + negate this as NWChemEx developers must support all optional features. diff --git a/docs/source/design/vision.rst b/docs/source/design/vision.rst index 9ba549a6..9d66243e 100644 --- a/docs/source/design/vision.rst +++ b/docs/source/design/vision.rst @@ -1,3 +1,17 @@ +.. 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 ################ diff --git a/docs/source/documenting/contributing_to_documentation.rst b/docs/source/documenting/contributing_to_documentation.rst index a3e2fe09..de026632 100644 --- a/docs/source/documenting/contributing_to_documentation.rst +++ b/docs/source/documenting/contributing_to_documentation.rst @@ -1,3 +1,17 @@ +.. 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: ************************************** @@ -12,25 +26,25 @@ 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. +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 +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 +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 +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. @@ -39,8 +53,8 @@ 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 +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``: @@ -51,8 +65,8 @@ with the linux command ``vi``: 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 +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 @@ -64,8 +78,8 @@ possible conflicts in the base environment. One can run the linux commands 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 +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 @@ -75,7 +89,7 @@ After all packages are successfully installed, one can run 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 +One can also choose other formats, for example, .pdf, for the generated documentation files by running .. code-block:: console @@ -83,7 +97,7 @@ documentation files by running make latexpdf In this case the installation of additional packages such as ``latexmk`` might -be necessary. +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`` +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/rst_cheatsheet.rst b/docs/source/documenting/rst_cheatsheet.rst index 2d616d9a..e32bcb8f 100644 --- a/docs/source/documenting/rst_cheatsheet.rst +++ b/docs/source/documenting/rst_cheatsheet.rst @@ -1,3 +1,17 @@ +.. 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 **************** diff --git a/docs/source/documenting/writing_tutorials.rst b/docs/source/documenting/writing_tutorials.rst index b34f8e59..742ec3a6 100644 --- a/docs/source/documenting/writing_tutorials.rst +++ b/docs/source/documenting/writing_tutorials.rst @@ -1,3 +1,17 @@ +.. 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 ***************** diff --git a/docs/source/index.rst b/docs/source/index.rst index 15a8b199..6032c6c2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,3 +1,17 @@ +.. 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 ################################## diff --git a/docs/source/resources/github/git_tutorial.rst b/docs/source/resources/github/git_tutorial.rst index 4b0d98d1..4d4b0bff 100644 --- a/docs/source/resources/github/git_tutorial.rst +++ b/docs/source/resources/github/git_tutorial.rst @@ -1,3 +1,17 @@ +.. 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: diff --git a/docs/source/resources/recommended_development_resources.rst b/docs/source/resources/recommended_development_resources.rst index 7a5fb0e1..89aed659 100644 --- a/docs/source/resources/recommended_development_resources.rst +++ b/docs/source/resources/recommended_development_resources.rst @@ -1,3 +1,17 @@ +.. 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 ################################# diff --git a/docs/source/testing/integration.rst b/docs/source/testing/integration.rst index 34ab4626..62361c74 100644 --- a/docs/source/testing/integration.rst +++ b/docs/source/testing/integration.rst @@ -19,13 +19,13 @@ 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. +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: @@ -38,8 +38,8 @@ tests to run quickly. 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 +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 @@ -56,7 +56,7 @@ don't break interoperability with the others. :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 + library they test, and the top-level NWChemEx library. Arrows point from a dependency to the dependent library. @@ -149,4 +149,3 @@ needed by a module in our project. def setUp(self): self.mm = ModuleManager() nwchemex.load_modules(mm) # Also loads out SCF modules - diff --git a/docs/source/testing/unit.rst b/docs/source/testing/unit.rst index d452ae69..613ce0bb 100644 --- a/docs/source/testing/unit.rst +++ b/docs/source/testing/unit.rst @@ -18,19 +18,19 @@ Writing Unit Tests for NWChemEx ############################### -Within the first party NWChemEx libraries, we aim for extensive unit testing to +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 +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 +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 +Assume the following class and related comparison function are intended to be added to one of the first party libraries: .. tabs:: @@ -51,12 +51,12 @@ added to one of the first party libraries: 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_; } @@ -74,14 +74,14 @@ added to one of the first party libraries: class ToBeTested(): - def __init__(self, a_value = 0): + 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: + if new_value == 13: raise RuntimeError("Unlucky Number") self.__my_value = new_value @@ -112,8 +112,8 @@ An example unit test for the above looks like: REQUIRE(with_value == ToBeTested(3)); REQUIRE_FALSE(defaulted == with_value); } - SECTION("operator!=") { - REQUIRE(defaulted != with_value); + SECTION("operator!=") { + REQUIRE(defaulted != with_value); } } diff --git a/nwx_build_environment/add_catch2.dockerfile b/nwx_build_environment/add_catch2.dockerfile index f3c6ae31..9535f72e 100644 --- a/nwx_build_environment/add_catch2.dockerfile +++ b/nwx_build_environment/add_catch2.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=3.6.0 diff --git a/nwx_build_environment/add_cereal.dockerfile b/nwx_build_environment/add_cereal.dockerfile index 51ec7c5f..38abde0f 100644 --- a/nwx_build_environment/add_cereal.dockerfile +++ b/nwx_build_environment/add_cereal.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=1.3.0 diff --git a/nwx_build_environment/add_exachem.dockerfile b/nwx_build_environment/add_exachem.dockerfile index 6c9aa0c7..e629e530 100644 --- a/nwx_build_environment/add_exachem.dockerfile +++ b/nwx_build_environment/add_exachem.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=main @@ -8,4 +22,4 @@ RUN cd /tmp \ && cd exachem \ && git checkout ${VERSION} \ && bash /scripts/tamm_command.sh \ - && rm -rf /tmp/exachem \ No newline at end of file + && rm -rf /tmp/exachem diff --git a/nwx_build_environment/add_gauxc.dockerfile b/nwx_build_environment/add_gauxc.dockerfile index 93ec8280..e3004195 100644 --- a/nwx_build_environment/add_gauxc.dockerfile +++ b/nwx_build_environment/add_gauxc.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=master diff --git a/nwx_build_environment/add_libfort.dockerfile b/nwx_build_environment/add_libfort.dockerfile index b47765da..9af47283 100644 --- a/nwx_build_environment/add_libfort.dockerfile +++ b/nwx_build_environment/add_libfort.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=0.4.2 diff --git a/nwx_build_environment/add_libint.dockerfile b/nwx_build_environment/add_libint.dockerfile index f601e942..0773d543 100644 --- a/nwx_build_environment/add_libint.dockerfile +++ b/nwx_build_environment/add_libint.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=2.9.0 diff --git a/nwx_build_environment/add_madness.dockerfile b/nwx_build_environment/add_madness.dockerfile index 400cdfbc..e2d90a9c 100644 --- a/nwx_build_environment/add_madness.dockerfile +++ b/nwx_build_environment/add_madness.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=3d585293f0094588778dbd3bec24b65e7bbe6a5d @@ -9,7 +23,7 @@ RUN cd /tmp \ && cd madness \ && git checkout ${VERSION}\ && cmake -Bbuild -H. -GNinja \ - -DENABLE_UNITTESTS=OFF \ + -DENABLE_UNITTESTS=OFF \ -DMADNESS_BUILD_MADWORLD_ONLY=ON \ -DMADNESS_ENABLE_CEREAL=ON \ -DENABLE_MKL=OFF \ diff --git a/nwx_build_environment/add_spdlog.dockerfile b/nwx_build_environment/add_spdlog.dockerfile index 8a4c8403..ee33e03a 100644 --- a/nwx_build_environment/add_spdlog.dockerfile +++ b/nwx_build_environment/add_spdlog.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=ad0e89cbfb4d0c1ce4d097e134eb7be67baebb36 diff --git a/nwx_build_environment/add_tamm.dockerfile b/nwx_build_environment/add_tamm.dockerfile index ae1b22a8..843380f4 100644 --- a/nwx_build_environment/add_tamm.dockerfile +++ b/nwx_build_environment/add_tamm.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=main @@ -8,4 +22,4 @@ RUN cd /tmp \ && cd TAMM \ && git checkout ${VERSION} \ && bash /scripts/tamm_command.sh \ - && rm -rf /tmp/TAMM \ No newline at end of file + && rm -rf /tmp/TAMM diff --git a/nwx_build_environment/add_tiledarray.dockerfile b/nwx_build_environment/add_tiledarray.dockerfile index c169d06a..b6bfede4 100644 --- a/nwx_build_environment/add_tiledarray.dockerfile +++ b/nwx_build_environment/add_tiledarray.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM nwx_buildenv:latest ARG VERSION=63e180bf55849c173585a734c5e7456cbf31a986 diff --git a/nwx_build_environment/buildenv.sh b/nwx_build_environment/buildenv.sh index 15cb7917..e85827f6 100755 --- a/nwx_build_environment/buildenv.sh +++ b/nwx_build_environment/buildenv.sh @@ -1,3 +1,17 @@ +# 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. + docker build -t nwx_buildenv -f nwx_buildenv.dockerfile . # Build dependencies with both GCC and Clang diff --git a/nwx_build_environment/nwx_buildenv.dockerfile b/nwx_build_environment/nwx_buildenv.dockerfile index 7da18afd..c5f192c2 100644 --- a/nwx_build_environment/nwx_buildenv.dockerfile +++ b/nwx_build_environment/nwx_buildenv.dockerfile @@ -1,3 +1,17 @@ +# 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. + FROM ubuntu:jammy RUN apt-get update \ @@ -27,4 +41,3 @@ RUN apt-get update \ COPY toolchains /toolchains COPY scripts /scripts - diff --git a/nwx_build_environment/scripts/generate_module_dox.py b/nwx_build_environment/scripts/generate_module_dox.py index e83b5d16..714f90f5 100644 --- a/nwx_build_environment/scripts/generate_module_dox.py +++ b/nwx_build_environment/scripts/generate_module_dox.py @@ -1,7 +1,22 @@ -import os +# 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. + import glob -import sys import importlib +import os +import sys + """This script will generate the module api documentation for a plugin library. Usage @@ -12,7 +27,7 @@ usage: generate_module_dox.py library_name positional arguments: - library_name The name of the library for which the documentation is + library_name The name of the library for which the documentation is supposed to be generated. This script checks that only one library name is passed and that it can import diff --git a/nwx_build_environment/scripts/tamm_command.sh b/nwx_build_environment/scripts/tamm_command.sh index 7ddca6e4..1b636808 100644 --- a/nwx_build_environment/scripts/tamm_command.sh +++ b/nwx_build_environment/scripts/tamm_command.sh @@ -1,3 +1,17 @@ +# 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. + CC=gcc CXX=g++ FC=gfortran cmake -Bbuild -H. -DCMAKE_INSTALL_PREFIX=/nwx_dependencies/gcc-11 -DCMAKE_BUILD_TYPE=Release -DBLAS_INT4=ON -DMODULES="CC" -DCMAKE_TOOLCHAIN_FILE=/toolchains/tamm.cmake -DUSE_LIBNUMA=OFF cd build make -j2 diff --git a/nwx_build_environment/toolchains/clang-14.cmake b/nwx_build_environment/toolchains/clang-14.cmake index 4acb1f44..a610da1c 100644 --- a/nwx_build_environment/toolchains/clang-14.cmake +++ b/nwx_build_environment/toolchains/clang-14.cmake @@ -1,3 +1,17 @@ +# 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. + set(CMAKE_C_COMPILER clang-14) set(CMAKE_CXX_COMPILER clang++-14) diff --git a/nwx_build_environment/toolchains/error_flag.cmake b/nwx_build_environment/toolchains/error_flag.cmake index 8b602c75..85f665e2 100644 --- a/nwx_build_environment/toolchains/error_flag.cmake +++ b/nwx_build_environment/toolchains/error_flag.cmake @@ -1 +1,15 @@ -set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Werror") \ No newline at end of file +# 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. + +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Werror") diff --git a/nwx_build_environment/toolchains/gcc-11.cmake b/nwx_build_environment/toolchains/gcc-11.cmake index fcad3c19..23818e4c 100644 --- a/nwx_build_environment/toolchains/gcc-11.cmake +++ b/nwx_build_environment/toolchains/gcc-11.cmake @@ -1,2 +1,16 @@ +# 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. + set(CMAKE_C_COMPILER gcc-11) set(CMAKE_CXX_COMPILER g++-11) diff --git a/nwx_build_environment/toolchains/nwx_base.cmake b/nwx_build_environment/toolchains/nwx_base.cmake index 152cce1e..274980fc 100644 --- a/nwx_build_environment/toolchains/nwx_base.cmake +++ b/nwx_build_environment/toolchains/nwx_base.cmake @@ -1,3 +1,17 @@ +# 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. + set(BUILD_TESTING ON) set(CMAKE_CXX_STANDARD 17) set(CMAKE_POSITION_INDEPENDENT_CODE TRUE) diff --git a/nwx_build_environment/toolchains/nwx_clang-14.cmake b/nwx_build_environment/toolchains/nwx_clang-14.cmake index be935ab0..728ad773 100644 --- a/nwx_build_environment/toolchains/nwx_clang-14.cmake +++ b/nwx_build_environment/toolchains/nwx_clang-14.cmake @@ -1,2 +1,16 @@ +# 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. + include(/toolchains/clang-14.cmake) include(/toolchains/nwx_base.cmake) diff --git a/nwx_build_environment/toolchains/nwx_gcc-11.cmake b/nwx_build_environment/toolchains/nwx_gcc-11.cmake index cb9a38c3..aacbc273 100644 --- a/nwx_build_environment/toolchains/nwx_gcc-11.cmake +++ b/nwx_build_environment/toolchains/nwx_gcc-11.cmake @@ -1,2 +1,16 @@ +# 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. + include(/toolchains/gcc-11.cmake) include(/toolchains/nwx_base.cmake) diff --git a/nwx_build_environment/toolchains/tamm.cmake b/nwx_build_environment/toolchains/tamm.cmake index 145d97f8..f3c3872b 100644 --- a/nwx_build_environment/toolchains/tamm.cmake +++ b/nwx_build_environment/toolchains/tamm.cmake @@ -1 +1,15 @@ -list(APPEND CMAKE_PREFIX_PATH "/nwx_dependencies/gcc-11") \ No newline at end of file +# 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. + +list(APPEND CMAKE_PREFIX_PATH "/nwx_dependencies/gcc-11") diff --git a/profile/README.md b/profile/README.md index e932ad1e..85cf9ac5 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,3 +1,19 @@ + + About the NWChemEx Community ============================