Add SASA collection to xtb and minor fixes. (#179)

Related Issues: #173 #154
Requested Reviewers: @lukasturcani 
*Note for Reviewers: If you accept the review request add a 👍 to this
post*

1. Adds a minor feature to collect the SASA from xTB output
2. Makes some utilities used by other codes public
3. uses `parents=True` in all `pathlib.Path.mkdir` statements

docs/source/index.rst

@@ -1,8 +1,9 @@
 .. toctree::
    :hidden:
    :caption: stko
-   :maxdepth: 2
+   :maxdepth: 1
 
+   Video Tutorials <video_tutorials>
    Molecular <molecular>
    Calculators <calculators>
    Optimizers <optimizers>

docs/source/video_tutorials.rst

@@ -0,0 +1,107 @@
+Video Tutorials
+===============
+
+Below is a list of video tutorials made by `Andrew Tarzia`__, which
+provide a thorough introduction to :mod:`.stk` and :mod:`.stko`.
+More videos can be found here__.
+
+__ https://github.com/andrewtarzia
+__ https://youtube.com/@andrewtarzia1790
+
+Basics of *stk*
+---------------
+
+`Video 1`__ is an overview of the 2021 publication covering the
+capability of :mod:`.stk` and the docs of :mod:`.stk`. The
+Jupyter notebook is available here__.
+
+__ https://www.youtube.com/watch?v=mPr9D7nCQ84&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=1
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Functional Groups in *stk*
+--------------------------
+
+`Video 2`__ is an overview of defining :class:`.FunctionalGroup`
+instances in :mod:`.stk`. It includes an example of the versatility of
+:mod:`.stk` for unique problems. The Jupyter notebook is available
+here__.
+
+__ https://www.youtube.com/watch?v=IaLIN7jXyKQ&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=2
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Cage Building
+-------------
+
+`Video 3`__ is an overview of organic and metal-organic cage
+construction in :mod:`.stk`. This example covers how :mod:`.stk`
+handles isomerism and the concept of hierarchical construction. The
+Jupyter notebook is available here__.
+
+__ https://www.youtube.com/watch?v=sc1Kf6vzTSA&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=3
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Hierarchical Construction with *stk*
+------------------------------------
+
+`Video 4`__ expands on the use of hierarchical construction in
+:mod:`.stk`. It includes an implementation of the example from the
+2021 publication and the construction of a rotaxane/cage hybrid!
+The Jupyter notebbok is available here__.
+
+__ https://www.youtube.com/watch?v=WB9oAqA8m4o&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=4
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Using *stko* with *stk*
+-----------------------
+
+`Video 5`__ shows the usage of the stko__ package to optimize and
+calculate the properties of :mod:`.stk` molecules. The Jupyter
+notebook is available here__.
+
+__ https://www.youtube.com/watch?v=vvmS43dVPe4&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=5
+__ https://github.com/JelfsMaterialsGroup/stko
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Databases and *stk-vis* in *stk*
+--------------------------------
+
+`Video 6`__ is a short introduction to databasing and the use of
+*StkVis* with :mod:`.stk` molecules! The Jupyter notebook is
+available here__.
+
+__ https://www.youtube.com/watch?v=ESfmmLpHVmE&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=6
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+Host-Guest Conformers with *stk*
+--------------------------------
+
+`Video 7`__ shows an example of the generation of :mod:`.stk`
+host-guest complexes using the software SpinDry__. The Jupyter
+notebook is available here__.
+
+__ https://www.youtube.com/watch?v=1BBhPeIRV_E&list=PLIWYdPQ9hLzVngMF8NOkiApMtgc_ZwZgO&index=7
+__ https://github.com/andrewtarzia/SpinDry
+__ https://github.com/andrewtarzia/stk-examples/tree/main/notebooks_from_videos
+
+
+Swapping Hosts and Guests in Complexes
+--------------------------------------
+
+`The new video`__ shows an example of loading an existing host-guest
+complex into :mod:`.stk`, extracting the different molecules
+(with :mod:`networkx`), and then building new complexes from that.
+The code is available here__.
+
+__ https://youtu.be/J29eoc9CZ98?si=vOEH45GPp_W0f5k4
+__ https://github.com/andrewtarzia/stk-examples/blob/main/replace_guest/replace_guest.py
+
+
+Processing *stk* building blocks before construction
+----------------------------------------------------
+
+`This video`__ shows the use of the new :mod:`bbprepared` library__
+that helps to process automatically generated :mod:`stk` BuildingBlock
+conformers to be better fit for construction.
+
+__ https://youtu.be/dbQwhlpf5Jc?si=7l9Y_ISEmFlY2FtV
+__ https://github.com/andrewtarzia/bbprepared

examples/aligner_example.py

@@ -8,8 +8,7 @@
 def main() -> None:
     """Run the example."""
     examples_output = Path("aligner_directory")
-    if not examples_output.exists():
-        examples_output.mkdir()
+    examples_output.mkdir(parents=True, exist_ok=True)
 
     bb1 = stk.BuildingBlock("NCCN", [stk.PrimaryAminoFactory()])
     bb2 = stk.BuildingBlock(

examples/basic_example.py

@@ -18,8 +18,7 @@ def main() -> None:
     )
 
     examples_output = Path("output_directory")
-    if not examples_output.exists():
-        examples_output.mkdir()
+    examples_output.mkdir(parents=True, exist_ok=True)
 
     # Run optimisations.
     uff = stko.UFF()

examples/calculators_example.py

@@ -44,6 +44,9 @@ def main() -> None:
             output_dir=Path("output_directory") / "example_xtb_out",
             unlimited_memory=True,
             calculate_ip_and_ea=True,
+            write_sasa_info=True,
+            solvent="dmso",
+            solvent_model="alpb",
         )
 
         xtb_results = xtb.get_results(bb1)
@@ -57,6 +60,7 @@ def main() -> None:
         full_dipole_moments = xtb_results.get_full_dipole_moments()
         ip = xtb_results.get_ionisation_potential()
         ea = xtb_results.get_electron_affinity()
+        sasa = xtb_results.get_total_sasa()
         print(
             total_energy,
             homo_lumo_gap,
@@ -65,6 +69,7 @@ def main() -> None:
             full_dipole_moments,
             ip,
             ea,
+            sasa,
         )
         # From results, vs from calculator.
         print(xtb.get_energy(bb1), total_energy)

examples/molecule_splitter_example.py

@@ -8,7 +8,7 @@
 def main() -> None:
     """Run the example."""
     examples_output = Path("splitter_output_directory")
-    examples_output.mkdir(exist_ok=True)
+    examples_output.mkdir(parents=True, exist_ok=True)
 
     full_mol = stk.BuildingBlock("C1=CC=NC(=C1)C=NC2=CC=C(C=C2)Br")
     print(full_mol)

examples/obabel_example.py

@@ -154,7 +154,7 @@ def main() -> None:
     )
 
     examples_output = Path("output_directory")
-    examples_output.mkdir(exist_ok=True)
+    examples_output.mkdir(parents=True, exist_ok=True)
 
     structures = [
         ("bb1", bb1),

examples/orca_example.py

@@ -26,7 +26,7 @@ def main() -> None:
     )
 
     examples_output = Path("orca_output_directory")
-    examples_output.mkdir(exist_ok=True)
+    examples_output.mkdir(parents=True, exist_ok=True)
 
     # Run optimisations.
     etkdg = stko.ETKDG()

examples/output_directory/example_xtb_out/charges

@@ -1,20 +1,20 @@
-   -0.40481597
-    0.02420480
-    0.03191379
-   -0.31250607
-    0.03422299
-    0.02776318
-   -0.42774694
-    0.04951489
-    0.05904918
-   -0.04613605
-   -0.01503053
-   -0.00760123
-   -0.06600660
-    0.09746607
-   -0.03619223
-   -0.03266422
-   -0.03730740
-   -0.00770167
-    0.00764826
-    0.06191973
+   -0.41225526
+    0.02147333
+    0.03379662
+   -0.32185978
+    0.03688277
+    0.02672962
+   -0.43558202
+    0.08147761
+    0.05454374
+   -0.03240166
+   -0.00971743
+   -0.00882953
+   -0.06768557
+    0.09513600
+   -0.04115418
+   -0.04174153
+   -0.04101999
+   -0.01006972
+    0.00745474
+    0.06481202

examples/output_directory/example_xtb_out/det_control.in

@@ -1,2 +1,4 @@
 $gbsa
-   gbsagrid=normal
+   gbsagrid=normal
+$write
+   gbsa=true