.. bee documentation master file, created by
   sphinx-quickstart on Tue Jun 14 21:49:37 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Bee Chemical Database
=====================

The **Bee** database allows to store and manage molecules along with
different conformers and properties, including information on the computational source of these data.

The main interface is a :ref:`rest-api` documented by OpenAPI but it includes also
a basic :ref:`cli`.

.. _architecture:

Architecture
------------

For an easier understanding of its concepts, the following diagram shows
their relations:

.. graphviz::
   :alt: Architecture
   :align: center

   digraph T {

     # edge [dir="back"]
     node [fontname="Sans"]

     Molecule [shape=box]
     Simulation [shape=box]
     Workflow [shape=box]
     Recipe [shape=box]
     Conformer [shape=box]
     Properties [shape=box]

      { rank=same Conformer Simulation }

     Molecule -> Conformer [label="contains"]
     Simulation -> Conformer [label="generates"]
     Conformer -> Simulation [label="is source of"]
     Conformer -> Properties [samehead=Properties,label="contains"]
     Simulation -> Properties [samehead=Properties,
                               headlabel="creates",
                               labelangle=18,
                               labeldistance=7.5]
     Molecule -> Recipe [label="contains"]
     Recipe -> Workflow [label="consists of"]
     Workflow -> Simulation [label="consists of"]

   }


*The arrows mean an object referencing another.*

Molecule
   The central database object **Molecule** contains information about the atoms
   and their bonds on a qualitative level - basically all the information which
   can be obtained from a SMILES string. Additionally, there is the information
   about *multiplicity* and optionally *identifiers* and *tags*.

Conformer
   While a **Molecule** stores only the set of atoms and their bonds, each
   **Conformer** contains a representation of the exact coordinates of each
   atom. Upon adding a **Molecule** to the database, **Bee** creates an initial
   **Conformer** using *RDKit*. Optionally, a **Conformer** may contain the
   *trajectory_step* as part of an optimisation, and *tags*. For the sake of
   clarity, a **Conformer** is a technical term, it can represent a minimum structure,
   or an off-equilibrium structure.

Simulation
   Each **Simulation** uses a **Conformer** as its *source* and creates, depending
   on its simulation *type*, **Properties** for this *source* conformer, e.g. in
   case if single point calculations, or it
   creates new **Conformers** in case of e.g. an *optimisation* or a *conformer generation*. A **Simulation**
   contains information about the used *software*, *method*, *basis sets*,
   and *solvent*, as well as additional meta information such as timings and errors.

Properties
   Each **Properties** entry belongs to a **Conformer** and to a **Simulation**
   as its *source*. It contains the computed physical properties of the
   conformer, its atoms and bonds, e.g. *single point energy*, *atom forces*,
   *bond types*, etc.
   Hence, each **Conformer** may contain different sets of **Properties**
   obtained by different **Simulations** using different *methods*,
   *solvents*, etc.

Workflow
   A **Workflow** bundles several **Simulations**, each indexed by a
   *simulation_step*. It also contains the used *software* and meta information
   such has *timestamps*, *errors*, and optionally *tags*.

Recipe
   A **Recipe** is a standard playbook for running several **Workflows** on
   a **Molecule** also allowing customised dependencies.


.. toctree::
   :maxdepth: 1
   :caption: Contents:


.. toctree::
   :maxdepth: 1
   :caption: First steps

   first_steps/running_bee
   first_steps/hello_water
   first_steps/orchestration
   first_steps/search

.. comment
   toctree::
   :maxdepth: 1
   :caption: API in detail

   api_details/molecule
   api_details/conformer
   api_details/simulation
   api_details/properties
   api_details/workflow
   api_details/recipe


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`