From a0a332c4484e6035f860ccb31bd2508fbe0a68ae Mon Sep 17 00:00:00 2001 From: Benjamin Pritchard Date: Mon, 22 Apr 2024 14:57:07 -0400 Subject: [PATCH] Work on docs --- docs/core-interface.md | 106 +++++++++++++++++++++++++++++++++++ docs/explanation.md | 15 ----- docs/high-level-interface.md | 3 + docs/index.md | 42 ++++++++++---- docs/keywords.md | 38 +++++++++++++ docs/reference.md | 9 --- docs/results.md | 0 docs/tutorials.md | 16 ------ mkdocs.yml | 11 ++-- pyproject.toml | 5 ++ 10 files changed, 187 insertions(+), 58 deletions(-) create mode 100644 docs/core-interface.md delete mode 100644 docs/explanation.md create mode 100644 docs/high-level-interface.md create mode 100644 docs/keywords.md delete mode 100644 docs/reference.md create mode 100644 docs/results.md delete mode 100644 docs/tutorials.md diff --git a/docs/core-interface.md b/docs/core-interface.md new file mode 100644 index 0000000..bbcb4b0 --- /dev/null +++ b/docs/core-interface.md @@ -0,0 +1,106 @@ +# Core Interface + +The core interface of QCManyBody is designed to allow for more flexibility in how the calculations are run. +The primary responsibilities of the core interface are: + +1. Given a molecule and desired levels of MBE, return the fragments and levels that must be computed for each fragment +2. Given a dictionary of the results of those computations, analyze those results and calculate the desired manybody properties + +Note that the user is expected to run the calculations themselves, and the core interface does not provide any tools for +running the calculations. + + +## Using the core interface + +The core interface is accessed through the [`ManyBodyCalculator`][qcmanybody.manybody.ManyBodyCalculator] +class. + +The first step is to create a molecule. This molecule is a QCElemental molecule object, and must contain fragments. + +```python +import qcmanybody as qcmb +import qcelemental as qcel + +# Create a molecule with 3 hydrogen atoms, each as its own fragment +mol = qcel.models.Molecule(symbols=['h', 'h', 'h'], + geometry=[[0,0,0],[0,0,2],[0,0,4]], + fragments=[[0], [1], [2]]) +``` + +Next, create a `ManyBodyCalculator` object. This object is constructed using the molecule, +the desired BSSE correction, levels of MBE, and other options of the MBE. + +```python +mbc = qcmb.ManyBodyCalculator( + molecule=mol, + bsse_type=['cp'], + levels={1: 'mp2/aug-cc-pvtz', 2: 'b3lyp/def2-svp', 3: 'hf/sto-3g'}, + return_total_data=True, + supersystem_ie_only=False +) +``` + +The `levels` option is a dictionary that specifies the n-body level as a key, then an arbitrary +string as the description of the calculation to be performed at the n-body level. This string is +termed the 'model chemistry' is completely arbitrary; it only has meaning to the user, and the user is expected to map these strings +to some meaningful definition of a calculation. + +**Note**: The core interface is less flexible than the high-level interface when it comes to the `levels` option. + In the core interface, all levels must be accounted for (that is, keys must go from 1 to the maximum + nbody you would like to calculate). All levels must be present even if the model chemistry + is the same for all levels. + +For a complete discussion of the other options available in the `ManyBodyCalculator` object, see the +[keywords discussion](keywords.md) +the [`ManyBodyCalculator API documentation`][qcmanybody.manybody.ManyBodyCalculator]. + +The next step is to obtain the calculations to be run from the `ManyBodyCalculator` object. +This is done with a python generator function `iterate_molecules` that returns +a tuple. This tuple contains + +1. The string describing the calculation to be run (the model chemistry string, as defined in the `levels` dictionary) +2. A label for the calculation. This label is opaque to the user but used to identify the calculation when analyzing the results. +3. A `Molecule` object that contains the cluster of fragments to be computed. + +```python +calculation_results = {} +for model_chemistry, label, mol_cluster in mbc.iterate_molecules(): + calculation_results[label] = run_calculation(mol_cluster, model_chemistry) +``` + +Note that it is entirely up to the user to run the calculation somehow - this level of interface +does not provide any tools for running the calculations. + +### Results dictionary + +The data returned from the calculations is expected to be stored in a nested dictionary. +The level is the opaque label as given from the `QCManyBodyCalculator`. +The second level is the name of the property. + +```python +calculation_results = { + 'label1': { + 'energy': -1.0, + 'gradient': [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], + }, + 'label2': { + 'energy': -2.0, + 'gradient': [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]], + }, + 'label3': { + 'energy': -3.0, + 'gradient': [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]], + }, +} +``` + +### Analysis + +This result dictionary is all that is needed to perform the final analysis and calculation +of the MBE properties. + +```python +final_results = mbc.analyze(calculation_results) +``` + +For a discussion about what the results contain, see the [results documentation](results.md). \ No newline at end of file diff --git a/docs/explanation.md b/docs/explanation.md deleted file mode 100644 index f3955a5..0000000 --- a/docs/explanation.md +++ /dev/null @@ -1,15 +0,0 @@ -This part of the project documentation focuses on an -**understanding-oriented** approach. You'll get a -chance to read about the background of the project, -as well as reasoning about how it was implemented. - -> **Note:** Expand this section by considering the -> following points: - -- Give context and background on your library -- Explain why you created it -- Provide multiple examples and approaches of how - to work with it -- Help the reader make connections -- Avoid writing instructions or technical descriptions - here diff --git a/docs/high-level-interface.md b/docs/high-level-interface.md new file mode 100644 index 0000000..7c16d6f --- /dev/null +++ b/docs/high-level-interface.md @@ -0,0 +1,3 @@ +# High-Level Interface + + diff --git a/docs/index.md b/docs/index.md index 021a2c8..aeae495 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,18 +1,36 @@ -# Welcome to MkDocs +# QCManyBody Documentation -For full documentation visit [mkdocs.org](https://www.mkdocs.org). +QCManyBody is a python package for running quantum chemistry manybody expansions and interaction calculations in a +package-independent way. -## Commands +## Installation -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. +Currently, the package is only available on [GitHub](https://github.com/MolSSI/QCManyBody). To install directly +from GitHub, use the following command: -## Table Of Contents +```bash +pip install git+https://github.com/MolSSI/QCManyBody.git +``` -1. [Tutorials](tutorials.md) -2. [How-To Guides](how-to-guides.md) -3. [Reference](reference.md) -4. [Explanation](explanation.md) +## Package Overview +The package has two main interfaces. The high-level interface allows for a comprehensive workflow, where the user +provides complete information about the calculation, including the full specification (method, basis set, etc.) of the +manybody calculation. This is designed to work with [QCEngine](https://github.com/MolSSI/QCEngine) or other packages +that implement the [QCSchema](https://github.com/MolSSI/QCSchema). + +For more information, see (High-level interface)(high-level-interface.md). + +QCManyBody also has a core low-level interface that allows for more flexibility in how the calculations are run. This +interface generally takes a molecule and an arbitrary definition of quantum chemistry specifications, and expects +the user to run them themselves. + +For more information, see (Core interface)(core-interface.md). + +## Table of Contents + +1. [Common Keywords and Options](keywords.md) +2. [High-level Interface](high-level-interface.md) +3. [Core Interface](core-interface.md) +4. [Results](results.md) +5. [How-To Guides](how-to-guides.md) \ No newline at end of file diff --git a/docs/keywords.md b/docs/keywords.md new file mode 100644 index 0000000..890fc9d --- /dev/null +++ b/docs/keywords.md @@ -0,0 +1,38 @@ +# Keywords and options + +## Required + +### Molecule + +### bsse_type + +### levels and max_nbody + +## Keywords and Options + +Both the high-level interface and core interface share the same terminology with respect to options + + +### return_total_data + +When set to true, the manybody calculation will return the total data (energy/gradient/hessian/property) of the system. +If not, the return will only contain interaction data. + +Note that the calculation of counterpoise corrected total properties implies the calculation of the energies of monomers +in the monomer basis, hence specifying `return_total_data = True` may carry out more computations than. +For some properties such as gradients and hessians, `return_total_data = False` is rarely useful. + +### supersystem_ie_only + +Target the supersystem total/interaction energy (IE) data over the many-body expansion (MBE) +analysis, thereby omitting intermediate-body calculations. When false, each n-body level +in the MBE up through `max_nbody` will be computed. When true (only allowed for `max_nbody = nfragments`), +only compute enough for the overall interaction/total energy: max_nbody-body and 1-body. + +When true, properties `INTERACTION {driver} THROUGH {max_nbody}-BODY` will always be available; +`TOTAL {driver} THROUGH {max_nbody}-BODY` will be available depending on `return_total_data`; and +`{max_nbody}-BODY CONTRIBUTION TO {driver}` won't be available (except for dimers). + +This keyword produces no savings for a two-fragment molecule. But for the interaction energy of a three-fragment molecule, for example, 2-body +subsystems can be skipped with `supersystem_ie_only=True` Do not use with `vmfc` in `bsse_type` +as it cannot produce savings. diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index 83fde0a..0000000 --- a/docs/reference.md +++ /dev/null @@ -1,9 +0,0 @@ -This part of the project documentation focuses on -an **information-oriented** approach. Use it as a -reference for the technical implementation of the -`QCManyBody` project code. - -::: qcmanybody.ManyBodyCalculator - -::: qcmanybody.builder.build_nbody_compute_list - diff --git a/docs/results.md b/docs/results.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/tutorials.md b/docs/tutorials.md deleted file mode 100644 index edc0272..0000000 --- a/docs/tutorials.md +++ /dev/null @@ -1,16 +0,0 @@ -This part of the project documentation focuses on a -**learning-oriented** approach. You'll learn how to -get started with the code in this project. - -> **Note:** Expand this section by considering the -> following points: - -- Help newcomers with getting started -- Teach readers about your library by making them - write code -- Inspire confidence through examples that work for - everyone, repeatably -- Give readers an immediate sense of achievement -- Show concrete examples, no abstractions -- Provide the minimum necessary explanation -- Avoid any distractions diff --git a/mkdocs.yml b/mkdocs.yml index ab93c45..0f16c4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: QCManyBody Docs +site_name: QCManyBody Documentation site_url: https://molssi.github.io/QCManyBody/ repo_name: MolSSI/QCManyBody @@ -52,10 +52,9 @@ plugins: - https://molssi.github.io/QCFractal/objects.inv nav: - - QCManyBody Docs: index.md - - tutorials.md - - API Documentation: api.md + - Home: index.md + - high-level-interface.md + - core-interface.md - How-To Guides: how-to-guides.md - - reference.md - - explanation.md + - API Documentation: api.md diff --git a/pyproject.toml b/pyproject.toml index 203542b..1d22afa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,6 +30,11 @@ tests = [ "pytest", "zstandard", ] +docs = [ + "mkdocs", + "mkdocs-material", + "mkdocstrings[python]", +] [tool.setuptools.package-data]