Merge pull request #266 from thomas-rocke/DislFixes

Disloc self_consistency bugfix & generalised kink mapping

docs/applications/cylinder_configurations.ipynb

@@ -174,6 +174,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    ":::{note}\n",
+    "In BCC we solve for the displacements self-consistently (note the `disloc SCF` in the above output). This approach can cause unexpected behaviour in rare occurences where atoms get close to divergences in the Continuum Linear Elastic (CLE) solution. The self-consistency can be disabled by passing `self_consistent=False` to `build_cylinder`, or the approach can be bounded to a smaller region close to the dislocation core using e.g. `r_sc=30` to only apply SC to the first 30 Angstrom of atoms around the core. \n",
+    ":::\n",
+    "\n",
     "Now we can use `CubicCrystalDislocation.view_cyl` to look at the created structure with an NGL interactive view. Hovering your mouse over an atom will show chemical symbol of the atom and the structure identified by CNA algorithm. Dislocation is shown with an arrow corresponding to the dislocation line vector $\\vec l$. Hovering over the dislocation will display the dislocation name. Moreover, you can use your mouse to control the view:\n",
     "\n",
     "- Translation: right click + drag\n",
@@ -724,7 +728,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,

docs/applications/disloc_mobility.ipynb

@@ -31,6 +31,7 @@
     "                                                                Holland_Marder_PRL_80_746_Si\n",
     "from matscipy.calculators.manybody import Manybody\n",
     "calc = Manybody(**StillingerWeber(Holland_Marder_PRL_80_746_Si))\n",
+    "import numpy as np\n",
     "\n",
     "# the function accepts any ASE type of calculator\n",
     "alat, C11, C12, C44 = get_elastic_constants(calculator=calc, symbol=\"Si\", verbose=False)\n",
@@ -210,10 +211,6 @@
     "\n",
     "In quadrupoles (using `build_kink_quadrupole_network`), the cell is modified such that the dislocation position at the top of the cell becomes the new dislocation line position at the bottom of the cell. This means that for quadrupoles an extra kink will not be created, and that the example map of `[0, 0, 1, 1]` will create only one kink in the center of the cell.\n",
     "\n",
-    ":::{note}\n",
-    "For the cell shift to always produce the correct crystalstructure, some atoms need to be deleted for some values of `kink_map[-1]`. This means that some kink maps may not conserve stoichiometry for some multispecies systems.\n",
-    ":::\n",
-    "\n",
     "Since the kink map is just a list of integers, it can be more convenient to exploit list addition, and specify kink maps in a form similar to `[0] * 5 + [1] * 5`, which would be identical to the input of `[0, 0, 0, 0, 0, 1, 1, 1, 1, 1]`.\n",
     "\n",
     "### Kink in cylinders"
@@ -260,6 +257,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    ":::{warning}\n",
+    "For the cell shift to always produce the correct crystalstructure, some atoms need to be deleted for some values of `kink_map[-1]`. This means that some kink maps may not conserve stoichiometry for some multispecies systems.\n",
+    ":::\n",
+    "\n",
+    "\n",
     "There is also another routine `build_minimal_kink_quadrupole` for building only the smallest possible kink structures. This is where the kink happens in a single burgers vector cell. Here, the `n_kink` parameter controls the number of glide distances covered by the kink, and the direction of the kink: `n_kink=2` builds a compressed version of the kink map `[0, 2]`, and `n_kink=-1` constructs a compressed version of `[0, -1]`."
    ]
   },
@@ -317,6 +319,92 @@
     "\n",
     "Si_disloc.view_cyl(Si_kink)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Kink in Dissociated Dislocations\n",
+    "\n",
+    "For dissociated dislocations, kinks can nucleate at either core independently, with the energetics of the process largely determined by the burgers vectors of both partial dislocations, and by their separation. Kink can be modelled in such systems by using a 2D kink map, where the 2nd axis is the number of dislocation cores.\n",
+    "\n",
+    "As these structures feature complex 3D geometry, we will hide bulk-coordinated atoms so that the dislocation cores are easily visible."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "kink_map = np.array(\n",
+    "    #   L, R ordering (L = self.left_dislocation, R = self.right_dislocation)\n",
+    "      [[0, 5],] * 2 # Start dissociated\n",
+    "    + [[0, 6],] * 5 # Kink out the right partial by one\n",
+    "    + [[1, 6],] * 5 # Kink out the left partial by one\n",
+    "    + [[0, 5],] * 2 # Wrap back to initial position\n",
+    ") \n",
+    "# Kink map gets wrapped at boundary anyway, but manually specifying the wrapping\n",
+    "# in this way results in an easier-to-read visualisation\n",
+    "\n",
+    "print(kink_map.shape)\n",
+    "\n",
+    "Si_bulk, Si_kink = Si_disloc.build_kink_cylinder(\n",
+    "                    radius=20,\n",
+    "                    kink_map=kink_map\n",
+    "                )\n",
+    "\n",
+    "Si_disloc.view_cyl(Si_kink, hide_bulk=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Bulk-terminated Loops of Dissociated Dislocations\n",
+    "\n",
+    "To push these tools to their limit, let's look at a dislocation loop enclosed in bulk, where the dislocation is able to dissociate. We can use the `Quadrupole` class to easily create a dislocation model with four total dislocation cores: the two partial dislocations forming the left side of the dislocation loop, and the two partials forming the right side of the loop.\n",
+    "\n",
+    "To do this, we specify 4 kink positions per vertical segment, and we construct the loop in vertical slices."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Quadrupole & CubicCrystalDissociatedDislocation have self.left_dislocation and \n",
+    "# self.right_dislocation attributes\n",
+    "# Combining them in this way results in an ordering of:\n",
+    "# LL, LR, RL, RR, where LL is self.left_dislocation.left_dislocation, \n",
+    "# RL is self.right_dislocation.left_dislocation, etc \n",
+    "\n",
+    "\n",
+    "kink_map = np.array(\n",
+    "    #   LL, LR, RL, RR ordering\n",
+    "      [[ 0,  0,  0,  0]] * 7 # Start with perfect bulk (as dislocation cores overlapping)\n",
+    "    + [[-1, -1,  1,  1]] * 5 # Kink out both perfect dislocations\n",
+    "    + [[-2, -2,  2,  2]] * 4 \n",
+    "    + [[-3, -3,  3,  3]] * 4\n",
+    "    + [[-4, -3,  3,  4]] * 4 # Start dissociation of both perfect dislocations\n",
+    "    + [[-5, -3,  3,  5]] * 4\n",
+    "    + [[-6, -3,  3,  6]] * 8 # Full extent of the dislocation loop\n",
+    "    + [[-5, -3,  3,  5]] * 4 # Invert the process, moving cores closer together\n",
+    "    + [[-4, -3,  3,  4]] * 4\n",
+    "    + [[-3, -3,  3,  3]] * 4\n",
+    "    + [[-2, -2,  2,  2]] * 4 \n",
+    "    + [[-1, -1,  1,  1]] * 5\n",
+    "    + [[ 0,  0,  0,  0]] * 7 # End with perfect bulk\n",
+    ")\n",
+    "\n",
+    "Si_bulk, Si_kink = Si_quad.build_kink_cylinder(\n",
+    "                    radius=50,\n",
+    "                    kink_map=kink_map\n",
+    "                )\n",
+    "\n",
+    "Si_disloc.view_cyl(Si_kink, hide_bulk=True)"
+   ]
   }
  ],
  "metadata": {