Add debug guide document (v0).

documentation/Debugging_Guide.ipynb

@@ -0,0 +1,130 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# So I've tried doing some of the tutorials and am having trouble producing a structure I like - what should I do!\n",
+    "\n",
+    "This can depend quite a bit on what type of system you are looking for and what type of errors you are okay with.\n",
+    "\n",
+    "This document is intended to be a living document with actual examples where debugging is/was necessary - along with what was done to resolve.\n",
+    "\n",
+    "Generally each cell represents a different type of error and lists inside each cell are ordered by frequency of issues."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 1 - No structures were produced!\n",
+    "\n",
+    "This is quite common when looking at more complex systems and may be due to a number of factors.\n",
+    "\n",
+    "## a. Unphysical input\n",
+    "\n",
+    "Problem: Architector will try and build whatever you give it - sometimes for highly-coordinated systems this can result in overcrowding of the metal center and overlapping atoms. \n",
+    "Solution: Double check your input and ligand definitions - we have had trouble getting this to work in cases where the metal-coordinating atoms were mislabelled, resulting in Architector attemping unphysical ligand conformations.\n",
+    "\n",
+    "## b. XTB dependency\n",
+    "\n",
+    "Problem: Most of the time Architector will use XTB (GFN2-xTB) as a backend for evaluation of energies, structures, and forces. Occassionally, XTB will not perform well on systems resulting in consistent compression of bond lengths, or very strange relative conformer energetic rankings.\n",
+    "\n",
+    "Solutions:\n",
+    "1. Switch \"relax\" parameter to False. This will stop geometric deviations resulting from xTB relaxation - but will also not allow for an xTB relaxation meaning your produced conformer will often be more distorted at the end.\n",
+    "2. Check xTB convergence parameters. \"xtb_electronic_temperature\" can be set to higher (e.g. 1000K) to encourage convergence. Adding a solvent (e.g. \"sovlent\":\"water\") is another way to encourage more physical conformers because it screens the surface of ligand molecules forcing them to be closer to the metal in most cases.\n",
+    "3. Switch the methods involved in molcule construction. \"assemble_method\":\"GFN-FF\" or \"assemble_method\":\"UFF\" will be much faster but less accurate than GFN2-xTB. These are both viable parameters for the \"full_method\" key as well.\n",
+    "\n",
+    "## c. Conformer rankings ruling out sane geometries\n",
+    "\n",
+    "Problem: Architector defaults are limiting the scope of metal center symmetries sampled so that the \"correct\" one is not there.\n",
+    "\n",
+    "Solution: Increase \"n_conformers\" to generate additional metal center symmetries at each core geometry before relaxing only the lowest-energy conformer. Increase \"n_symmetries\" to relax additional metal center symmetries sampled from \"n_conformers\" to their ground-state conformation. \"n_symmetries\" should always be less than or equal to \"n_conformers\". In many cases this an easy way to get more sampling required to find a \"sane\" conformer.\n",
+    "\n",
+    "## d. Still nothing\n",
+    "\n",
+    "Problem: Still nothing is being produced.\n",
+    "\n",
+    "Solutions:\n",
+    "1. Play with sanity check cutoffs. You can turn off final an intermediate sanity checks with \"full_sanity_checks\":False, and \"assemble_sanity_checks\":False, respectively. You can also tune the actual cutoff values as well : \"full_graph_sanity_cutoff\":1.7 - can be tuned higher to allow for looser constraints, \"full_smallest_dist_cutoff\":0.55 - can be tuned lower for closer interatomic distances, and \"full_min_dist_cutoff\":3.5 - can be tuned higher to allow for more isolated atoms.\n",
+    "2. Metal van-der-waals radii (\"vdwrad_metal\") and covalent radii (\"covrad_metal\") can be manually tuned in cases where a very distinct oxiation state is used. \n",
+    "3. A last-dich effort can be made to simply force Architector to return basically anything with \"force_generation\":True. This can be useful to determine if something is going wrong internally in Architector. It is not recommended to use this option for production (multiple-structures runs)."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 2 - Only a couple structures were produced? I wanted a bunch!\n",
+    "\n",
+    "This is common when looking at smaller homogenous coordination spheres (e.g. Water-coordiantion spheres)\n",
+    "\n",
+    "## a. Similar small ligands.\n",
+    "\n",
+    "Problem: Only one or two structures produced when many desired.\n",
+    "\n",
+    "Solution: Often this results from the complexes converging to very similar structures near the metal center - which architector will remove by default with duplicate checks. To resolve this I will usually turn off the duplicate checks \"skip_duplicate_checks\":True. \n",
+    "\n",
+    "## b. Only 1 or 2 unique solutions exist.\n",
+    "\n",
+    "Problem: With rigid ligands such as bipyridine or terpyradine, multiple unique structures are often unfeasible.\n",
+    "\n",
+    "Solution: None! Possibly look at functionalizations that result in more distinct chemistries.\n",
+    "\n",
+    "## c. Architector only samples a specified number of unique symmetries.\n",
+    "\n",
+    "Problem: By default architector will only check 10 different symmetries and relax only 1 for output. \n",
+    "\n",
+    "Solution: Increase \"n_conformers\" to generate additional metal center symmetries at each core geometry before relaxing only the lowest-energy conformer. Increase \"n_symmetries\" to relax additional metal center symmetries sampled from \"n_conformers\" to their ground-state conformation. \"n_symmetries\" should always be less than or equal to \"n_conformers\". In many cases this an easy way to get more sampling required to find a \"sane\" conformer.\n",
+    "\n",
+    "Any/all of these debugging tips can help give more structures as output - whether these are \"good\" remains up to the users to determine!"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 3 - I wanted cis-actinyl oxos.\n",
+    "\n",
+    "This is a more fringe issue for many. By default if you run generation with an Actinide in the (V) or (VI) oxidation state Architector will force the OXO-groups to be trans since this is the much more commonly-observed configuration for actinyl groups. \n",
+    "\n",
+    "If you'd like the cis- structures as well simply run with \"force_trans_oxos\":False."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# More ideas: Please raise an issue on github or email the team to let us know if there's another issue that should be handled by Architector. We will update this document with more best \"debugging\" practices in addressing your issues!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "architector",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.8"
+  },
+  "orig_nbformat": 4,
+  "vscode": {
+   "interpreter": {
+    "hash": "d9faeb2a2170f4e60184b23dad276426e7089557c3539d9a2d03922f9a550f86"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}