1.0 Release

CMakeLists.txt

@@ -37,7 +37,7 @@ nwx_cxx_api_docs("${SIMDE_SOURCE_DIR}" "${SIMDE_INCLUDE_DIR}")
 ### Options ###
 cmaize_option_list(
     BUILD_TESTING OFF "Should we build the tests?"
-    BUILD_PYBIND11_PYBINDINGS OFF "Build pybind11 python3 bindings?"
+    BUILD_PYBIND11_PYBINDINGS ON "Build pybind11 python3 bindings?"
     ENABLE_EXPERIMENTAL_FEATURES OFF "Build features which are not 1.0-ed yet?"
 )
 
@@ -105,7 +105,7 @@ if("${BUILD_TESTING}")
 
     cmaize_add_tests(
         test_unit_${PROJECT_NAME}
-        SOURCE_DIR "${CXX_TEST_DIR}/unit"
+        SOURCE_DIR "${CXX_TEST_DIR}/unit_tests"
         INCLUDE_DIRS "${SIMDE_SOURCE_DIR}/${PROJECT_NAME}"
         DEPENDS Catch2 ${PROJECT_NAME}
     )

README.md

@@ -14,11 +14,53 @@
   ~ limitations under the License.
 -->
 
-[![Actions](https://github.com/NWChemEx/SimDE/workflows/C_C++_CI/badge.svg)](https://github.com/NWChemEx/SimDE)
+![SimDE Logo](docs/source/assets/logo.png)
 
-[![Codecov](https://codecov.io/github/NWChemEx/PropertyTypes/branch/master/graphs/sunburst.svg?token=pnZIgAq5yN)](https://codecov.io/github/NWChemEx/PropertyTypes/branch/master)
+[Documentation](https://nwchemex.github.io/SimDE)
 
-# Simulation Development Environment (SimDE)
+[![Citation Badge](https://api.juleskreuer.eu/citation-badge.php?doi=10.1109/MCSE.2018.2884921)](https://juleskreuer.eu/projekte/citation-badge/)
 
-The Simulation Development Environment defines a plugin-based framework for
-writing software capable of simulating chemical systems.
+The Simulation Development Environment (SimDE) includes software designed to
+facilitate the creation of modular computational chemistry software. The name
+"Development Environment" is an unfortunate misnomer, as SimDE is really a
+software development kit.
+
+# Features
+
+SimDE functions as a bit of a meta-target in that one of its primary goals is
+to provide a single software package which provides:
+
+- [PluginPlay](https://github.com/NWChemEx/PluginPlay) - a framework for
+  managing modular, performant, scientific software.
+- [Chemist](https://github.com/NWChemEx/Chemist) - a set of high-performance
+  data structures for computational chemistry.
+- Standardized [property types](https://nwchemex.github.io/PluginPlay/background/terminology.html#property-type) for computational chemistry.
+
+In turn, developers need only pull SimDE and they are ready to start writing
+computational chemistry plugins that are compatible with PluginPlay and the
+NWChemEx community's ecosystem.
+
+# Installation
+
+SimDE ultimately uses CMake for configuring and building. This means that
+installation is usually achieved via a variation on:
+
+```.sh
+git clone https://github.com/NWChemEx/simde
+cd simde
+cmake -H. -Bbuild -D...
+cmake --build build --target install
+```
+More detailed install instructions can be found
+[here](https://nwchemex.github.io/simde/install.html).
+
+# Contributing
+
+- [Contributor Guidelines](https://github.com/NWChemEx/.github/blob/1a883d64519f62da7c8ba2b28aabda7c6f196b2c/.github/CONTRIBUTING.md)
+- [Contributor License Agreement](https://github.com/NWChemEx/.github/blob/master/.github/CONTRIBUTING.md#contributor-license-agreement-cla)
+- [Developer Documentation](https://nwchemex.github.io/SimDE/developer/index.html)
+- [Code of Conduct](https://github.com/NWChemEx/.github/blob/master/.github/CODE_OF_CONDUCT.md)
+
+# Acknowledgments
+
+This research was supported by the Exascale Computing Project (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy Office of Science and the National Nuclear Security Administration.

docs/requirements.txt

@@ -1,2 +1,5 @@
-sphinx
-sphinx_rtd_theme
+GitPython
+sphinx==v7.2.6
+sphinx_rtd_theme==1.3.0
+sphinxcontrib-bibtex
+sphinx_tabs

docs/source/background/index.rst

@@ -0,0 +1,30 @@
+.. Copyright 2024 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.
+
+.. _simde_background:
+
+################
+SimDE Background
+################
+
+Topics in this section are designed to familiarize the reader with the SimDE
+project.
+
+.. toctree::
+   :maxdepth: 2
+
+   motivation
+   statement_of_need
+   overview
+   terminology

docs/source/background/motivation.rst

@@ -0,0 +1,60 @@
+.. Copyright 2024 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.
+
+.. _simde_motivation:
+
+################
+SimDE Motivation
+################
+
+Historically scientific software has been developed somewhat *ad hoc*, i.e.,
+without much attention to software engineering practices. Within computational
+chemistry the situation is no different. Starting around the beginning of the
+21st century there was an increasing realization that computational chemistry
+software would tremendously benefit from writing modular and reusable software
+packages.
+
+The power of modularity lies in its ability to encapsulate complexity. With
+well defined interfaces, users of a piece of modular software need not know the
+specifics of the software, i.e., they may treat it as a black-box. This
+facilitates among other things:
+
+- Use by non-experts.
+- Reasoning about consuming code (reader doesn't get bogged down in details).
+- Rapid prototyping (treat modules as building blocks for new algorithms).
+- Adoption (code that is easier to use gets adopted faster).
+- Reusability (easy to call from different contexts).
+
+Compared to monolithic software packages, software packages assembled from
+modular components can face unique challenges. In particular, if each modular
+component is developed in relative isolation (e.g., little to no communication
+among development teams) the resulting modules are unlikely to be compatible
+with each other. Examples of compatibility issues can include the presence of
+different:
+
+- input/return orderings,
+- data structures,
+- implicit conventions,
+- resource management strategies, and
+- parallel runtime systems.
+
+Left unchecked, developers and maintainers can quickly spend a significant
+fraction of their time addressing incompatibilities, thereby negating the
+benefits of writing modular software in the first place. Thankfully there is a
+straightforward solution, i.e., community standards.
+
+Ultimately the NWChemEx Community develops and maintains SimDE to provide a
+resource for members of the computational chemistry community who want to
+develop modular software and ensure that software is compatible with other
+modular software within the NWChemEx Community.

docs/source/background/overview.rst

@@ -0,0 +1,114 @@
+.. Copyright 2024 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.
+
+.. _simde_overview:
+
+##############
+SimDE Overview
+##############
+
+:ref:`simde_statement_of_need` listed the reasons that SimDE was necessary. The
+present section provides a high-level overview of SimDE.
+
+**********************************
+NWChemEx Ecosystem Development Kit
+**********************************
+
+We presume that most users of SimDE are using SimDE as an :term:`SDK` for
+creating plugins and/or modules which are compatible with the NWChemEx
+ecosystem.
+
+.. _fig_simde_sdk:
+
+.. figure:: assets/sdk.png
+   :align: center
+
+   Overview of the SimDE SDK.
+
+:numref:`fig_simde_sdk` summarizes the structure of the SDK provided by SimDE.
+
+At the base of the SDK are three, somewhat independent, libraries:
+
+- `ParallelZone <https://github.com/NWChemEx/ParallelZone>`__ is a parallel
+  runtime system. ParallelZone provides abstractions for interacting with
+  the resources (e.g., GPUs, CPUs, memory, processes, and file system) available
+  to the program.
+- `PluginPlay <https://github.com/NWChemEx/PluginPlay>`__ is an inversion-of-
+  control framework which facilitates creating software packages from modular
+  components. The resulting software package can be easily extended by users
+  and developers by adding new modules.
+- `Chemist <https://github.com/NWChemEx/Chemist>`__ provides data structures
+  for concepts commonly encountered in computational chemistry (e.g. atoms,
+  molecules, and wavefunctions).
+
+Users of SimDE have direct access to all three of these libraries and are
+encouraged to use these libraries directly. Generally speaking SimDE users
+should NOT have to work with the dependencies underpinning ParallelZone,
+PluginPlay, or Chemist.
+
+.. note::
+
+   If you encounter performance issues with any part of SimDE which would
+   require bypassing the abstractions provided by that component please open
+   an issue with the developers.
+
+***********************
+NWChemEx Property Types
+***********************
+
+In addition to serving as a meta-package, SimDE also provides the computational
+chemistry property types used throughout NWChemEx. Property types help ensure
+that modular software that is meant to be interoperable adheres to the same
+interfaces.
+
+.. _fig_property_types:
+
+.. figure:: assets/property_types.png
+   :align: center
+
+   Grouping of property types in SimDE. Within each component are high-level
+   examples of the types of properties property types in that component can
+   compute.
+
+:numref:`fig_property_types` shows the categories of property types presently
+in SimDE and the types of properties which can be computed. These categories
+are summarized below.
+
+Chemical System
+===============
+
+Property types in this category are designed to facilitate the creation of
+objects from the Chemical System component of Chemist. Examples of property
+types in this category include:
+
+- Creation of ``Atom`` instances given the atomic number or atomic symbol.
+- Mapping of string representations of a molecule to ``Molecule`` instances.
+
+Basis Set
+=========
+
+Property types in this category help create molecular basis sets. Examples of
+property types include:
+
+- Creation of ``AtomicBasisSet`` objects from atomic number.
+- Creation of ``AOBasisSet`` objects from ``Molecule`` objects.
+
+Energy
+======
+
+Property types in this category compute energies of chemical systems. Examples
+of property types include:
+
+- Computing the total energy of a ``ChemicalSystem``.
+- Computing the total energy given a ``ChemicalSystem`` and an ``AOBasisSet``.

docs/source/background/statement_of_need.rst

@@ -0,0 +1,85 @@
+.. Copyright 2023 NWChemEx-Project
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. _simde_statement_of_need:
+
+#######################
+SimDE Statement of Need
+#######################
+
+:ref:`simde_motivation` provided some background on developing and working
+with modular software and the importance of community standards. The NWChemEx
+community has developed a number of software products to serve as the
+infrastructure base for developing high-performance computational chemistry
+software. Given that said infrastructure is new to the broader community, it is
+no surprise that the community has yet to develop standards around it. SimDE
+rectifies this problem, by providing a software development kit for writing
+plugins within the NWChemEx ecosystem. The specific needs addressed by SimDE
+are detailed on this page.
+
+*****************************************
+Enforcement of Interoperability Standards
+*****************************************
+
+The end goal of modular scientific software should be reusability. Reusability
+is greatly enhanced by also striving for interoperability, i.e.,the idea that
+two components providing the same feature can be swapped and the code will "just
+work". Community standards for data structures and :term:`APIs <API>` are
+essential to interoperability efforts, and we need tools to help enforce these
+standards.
+
+The establishment of community standards is beyond our scope. Rather we assume
+such standards already exist and focus one enforcing these standards within
+`PluginPlay <https://github.com/NWChemEx/PluginPlay>`__. In PluginPlay
+standardized interfaces are enforced by writing
+`property types <http://tinyurl.com/mpunujh6>`__. Thus we have a need to develop
+infrastructure for writing computational chemistry property types (think type
+traits, for example) and to a need to use this infrastructure to produce
+property types for quantities of interest in computational chemistry.
+
+*********************
+Property Type Hosting
+*********************
+
+PluginPlay strives to make writing property types as easy as possible. Even if
+property types are easy to write, best practice is to avoid having the community
+need to write the same property type multiple times. To this end, we need a
+centralized place for hosting already developed property types. Having a
+centralized repo also makes it easier for developers to check if a property
+type has already been standardized.
+
+*******************************************
+NWChemEx Community Software Development Kit
+*******************************************
+
+The NWChemEx software stack is modular, and layered, in order to promote reuse
+by other projects. While useful from the perspective of reuse, this complicates
+development because developers need to wrangle together several components
+before they can begin development. The traditional solution to this problem is
+to provide developers a software development kit. After installing the software
+development kit, developers are ready to develop, i.e., no need to install the
+pieces individually.
+
+***********************************************
+Developer Tutorials for Writing Plugins/Modules
+***********************************************
+
+PluginPlay is designed to be domain agnostic. Thus we limited PluginPlay's
+tutorials to fundamental science concepts in order to appeal to wide set of
+potential users. That said, we also realize that many developers may prefer
+domain-specific tutorials as they provide less of a cognitive leap from tutorial
+to practice. SimDE is the first place in the NWChemEx Community stack which
+assumes PluginPlay is being used and that the application is computational
+chemistry. SimDE is thus a logical home for tutorials on developing
+plugins/modules which leverage computational chemistry concepts.