Writing guide for sphinx docs (#65)

writing guide part and adapting the sphinx ofe theme repo

docs/guide.rst

@@ -1,4 +1,17 @@
 Guide to Konnektor
 =====================
 
-More will be here soon!
+.. toctree::
+   :maxdepth: 2
+   :caption: Applications:
+
+   guide/application_network_planning_fe_calculations
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Functionality:
+
+   guide/network_planner
+   guide/node_clusterer
+   guide/edge_intermediator

docs/guide/application_network_planning_fe_calculations.rst

@@ -0,0 +1,50 @@
+==============================================================
+Network Plannnig for Free Energy Calculations in Drug Design
+==============================================================
+
+In this section, we will explore a classical hands-on drug design example,
+specifically the search for the best small molecule to inhibit a protein for drug development.
+Typically, drug design project teams and computational chemists generate a large
+number of molecule designs from which they must determine relevance.
+
+While experimental testing can evaluate various properties of these molecules,
+it is can be more efficient to use computational methods to distinguish between
+relevant and irrelevant candidates.
+The computational chemist usually follows a workflow that starts with very fast
+methods to filter out the obvious molecules (in the range of hundreds of thousands),
+then progresses to more computationally expensive methods that are more accurate
+but can only be applied to smaller sets of molecules (usually in the hundreds).
+
+Relative free energy calculation methods using alchemical MD simulations fall on
+the more computationally expensive side of the spectrum. Therefore, making the calculations
+efficient is crucial to avoid wasting time and computing resources.
+But how can these calculations be made efficient?
+
+This is a multi-layered question, starting with methodological aspects such as
+improving sampling speed or reducing timestep calculation time through parallel
+approaches on GPUs. At a higher level, the required number of calculations can
+also be adjusted. This is where Konnektor comes into play, helping you optimize this process.
+
+In general, there is a trade-off to consider in the calculation network
+between efficiency regarding the number of edges and redundancy within the
+network. Ideally, a minimal number of edges, such as in a Star Network or
+Minimal Spanning Tree (MST) Network, would make calculations most efficient.
+However, sometimes an edge calculation may fail due to poor edge selection,
+leading to a disconnected network, which results in an incomplete molecule
+ranking.
+
+These failures can arise from factors that were not accounted for during the
+selection process, such as unforeseen issues or computational outages, like
+a node crash. To address this, redundancy can help ensure immediate
+resolution of disconnections. Additionally, redundancy can be utilized to
+estimate simulation errors through cycle closure analysis, which can also
+enhance the final results.
+
+More redundant networks include the Twin Star Network, Redundant MST
+Network, N-Node Edges Network, and Cyclic Network. Notably, the Twin Star
+Network and the Cyclic Network focus on constructing a set of cycles.
+
+So in applied cases we suggest the slightly more redundant networks in order to build up a robust network for the calculations.
+
+turorial: :doc:`/tutorial/building_networks`.
+NetworkPlanner: :doc:`/guide/network_planner`.

docs/guide/edge_intermediator.rst

@@ -0,0 +1,9 @@
+==============================================================
+Edge Intermediate Generator
+==============================================================
+
+To overcome large molecular differences, it can be helpful to create an
+intermediate state between two molecules. Classes that perform this task
+are called Intermediator in Konnektor. You can provide them with two
+`Component`s, and they will attempt to construct intermediate states
+between the two `Component`s.

docs/guide/network_planner.rst

@@ -0,0 +1,76 @@
+==============================================================
+Network Planners
+==============================================================
+Building a drug candidate ranking is essentially a graph or network
+construction problem. A connected network, with candidates as nodes, can
+describe all the relationships among each candidate. The relationship
+between two molecules corresponds to an edge in this network, which
+translates to one Relative Binding Free Energy (RBFE) calculation. In
+practice, computational chemists conduct numerous RBFE calculations to
+construct networks that illustrate the relationships of all drug candidates
+to one another.
+
+.. image:: ../_static/img/networks.png
+
+It's important to note that free energy is a thermodynamic state function,
+making it path independent. This means that a network only needs to be
+connected to provide insights into all relationships, provided all RBFE
+calculations are of high quality. For example, if molecule A has a direct
+relation x with molecule C, and they are connected through molecule B,
+using relations y and z, then the sum of y + z will still yield x.
+
+So, what can we do with this? As mentioned, the free energy network should
+be calculated efficiently. Keep in mind that computational chemists utilize
+high-performance computing resources to perform RBFE calculations, which
+can take several hours. Therefore, RBFE calculations are costly, and it is
+typically avoided to conduct too many.
+
+This consideration directly impacts the design of the free energy network.
+To orchestrate the calculations, a plan for which connections to compute is
+generated before the simulations. This is where Konnektor comes into play.
+
+Konnektor is a package that assists in generating the free energy network
+calculation plan. It implements multiple network layouts, each with its
+own advantages and disadvantages. How is such a network plan generated?
+In our RBFE calculation example, each edge can be represented as an
+`AtomMapping`, indicating a common substructure between the two molecules
+to be compared. This `AtomMapping` can then be scored using an
+`AtomMappingScorer`, which indicates the expected difficulty of the
+transformation in terms of convergence or accuracy. But you can also look at
+this more abstract, as an `ComponentMapping` is describing any relation between two
+`Component`s and the difficulty is estimated with a `ComponentMappingScorer`.
+
+A network planning algorithm `NetworkPlanner` can now use these scores along with graph
+construction algorithms to identify the best calculation paths.
+
+Checkout the network tools to see what you can additionally do with networks.
+
+Network Generators
+__________________
+Network Generators are planners that construct networks from a set of
+components. They are usually the starting point for any network planning
+efforts and come in a wide variety of layouts:
+
+The minimal number of edges for ranking can be achieved with the Star
+Network and the Minimal Spanning Tree (MST) Network (N-1). More
+redundant layouts include the Twin Star Network, Redundant MST Network,
+N-Edge Node Network, and Cyclic Graph Network.
+
+The Maximal Network method generates all possible edges and is typically
+used as an initial solution, which then gets reduced to a more efficent layout.
+Additionally, there is the Heuristic Maximal Network, which aims to produce an
+edge-reduced version of the Maximal Network.
+
+.. image:: ../_static/img/network_layouts.png
+
+
+Network Concatenators
+______________________
+NetworkConcatenators address the challenge of connecting two networks that
+do not share any edges. This essentially involves solving a bipartite graph
+matching problem. These planners generate edges between two unconnected,
+non-overlapping networks to create a connected network.
+
+Currently, there are two Network Concatenators in Konnektor: the Maximal
+Concatenator, which yields all possible edges, and the Minimal Spanning
+Tree Concatenator, which utilizes the best-performing edge scores.

docs/guide/node_clusterer.rst

@@ -0,0 +1,12 @@
+==============================================================
+Node Clusterer
+==============================================================
+To separate a collection of Components by a specific property, the
+`Clusterer` classes can be utilized. They serve as powerful tools within
+a workflow and are, for example, part of the Starry Sky Network.
+
+In Konnektor, the following clustering classes are currently available:
+
+* `ChargeClusterer` – separates molecules by net charge changes
+* `ScaffoldClusterer` – separates molecules by shared scaffolds
+* `DiversityClusterer` – uses fingerprints to cluster the different molecules.

docs/install.rst

@@ -10,7 +10,7 @@ Konnektor will be packaged with OpenFE, soon. :)
 Konnektor can be installed via the package following package managers:
 
 ```shell
-pip install konnnektor
+mamba -c -conda-forge install konnektor
 ```
 
 Developer Setup

environment.yml

@@ -31,4 +31,4 @@ dependencies:
   - pip:
     - dill
     - scikit-mol
-    - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@main
+    - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@a45f3edd5bc3e973c1a01b577c71efa1b62a65d6