feature/SOF-8072 Feature: SE for a Ti adatom on a 5×5 TiN island, descent energetics of Fig. 6 (MACE and DFT)

config.yml

@@ -66,7 +66,7 @@ notebooks:
       - ipywidgets
       - tabulate==0.9.0
       - mat3ra-utils
-      - mat3ra-api-client>=2026.10.8.post0
+      - emfs:/drive/packages/mat3ra_api_client-2026.11.4.post1.dev7+gb5f25f7-py3-none-any.whl
   - name: dataframe
     packages_pyodide:
       - jinja2
@@ -79,7 +79,7 @@ notebooks:
       - emfs:/drive/packages/pydantic-2.7.1-py3-none-any.whl
       - mat3ra-standata
       - mat3ra-ide
-      - mat3ra-api-client>=2026.10.8.post0
+      - emfs:/drive/packages/mat3ra_api_client-2026.11.4.post1.dev7+gb5f25f7-py3-none-any.whl
       - requests
       - mat3ra-ade
       - mat3ra-mode

other/materials_designer/specific_examples/Introduction.ipynb

@@ -35,6 +35,7 @@
     "| `D-3D-AMO`   | Amorphous                      | *To be added*                                                                                                        | —             | — |\n",
     "| `D-2D-ADA`   | Adatom                         | [Pt Adatom/Island on MoS₂](defect_point_adatom_island_molybdenum_disulfide_platinum.ipynb)                           | *To be added* | [[10]](#ref10) |\n",
     "| `D-2D-ADA`   | Adatom                         | [Adatom on Graphene](defect_surface_adatom_graphene.ipynb)                                                           | *To be added* | [[11]](#ref11) |\n",
+    "| `D-2D-ADA`   | Adatom                         | [Ti Adatom on a 5×5 TiN Island](defect_point_adatom_island_titanium_nitride.ipynb)                                   | [Ti Adatom Descent on a 5×5 TiN Island (MACE and DFT)](defect_point_adatom_island_titanium_nitride_SIMULATION.ipynb) | [[14]](#ref14) |\n",
     "| `D-2D-GBP`   | Grain Boundary Planar          | [Grain Boundary in 3D FCC Cu](defect_planar_grain_boundary_3d_fcc_metals_copper.ipynb)                               | *To be added* | [[13]](#ref13) |\n",
     "| `D-2D-ISL`   | Island                         | [TiN Island on Surface](defect_surface_island_titanium_nitride.ipynb)                                                | *To be added* | [[14]](#ref14) |\n",
     "| `D-2D-TER`   | Terrace                        | [Step/Terrace on Pt Surface](defect_surface_step_platinum.ipynb)                                                     | *To be added* | [[15]](#ref15) |\n",

other/materials_designer/specific_examples/defect_point_adatom_island_titanium_nitride.ipynb

@@ -0,0 +1,325 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Ti Adatom on a 5×5 TiN Island on TiN(001)\n",
+    "\n",
+    "## 0. Introduction\n",
+    "\n",
+    "This tutorial builds the cell of the Ti adatom descent study in the publication:\n",
+    "\n",
+    "> **D. G. Sangiovanni, A. B. Mei, D. Edström, L. Hultman, V. Chirita, I. Petrov, and J. E. Greene**, \"Effects of surface vibrations on interlayer mass transport: Ab initio molecular dynamics investigation of Ti adatom descent pathways and rates from TiN/TiN(001) islands\", Physical Review B 97, 035406 (2018). [DOI: 10.1103/PhysRevB.97.035406](https://doi.org/10.1103/PhysRevB.97.035406)\n",
+    "\n",
+    "The cell (Sec. II.A, Fig. 1b) is a 5×5-atom TiN island, one plane high with Ti corners, on a 12×12×3-atom\n",
+    "TiN(001) slab with 15.3 Å of vacuum: 457 atoms. A Ti adatom is added at each of the sites a, c and i of Fig. 6.\n",
+    "\n",
+    "![Fig. 1(b)](https://github.com/Exabyte-io/documentation/raw/98b0e6b61a7007a4a53e41d894fb56c891ccaaa0/images/tutorials/materials/defects/defect-point-adatom-island-titanium-nitride/0-figure-1b-from-manuscript.webp)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "## 1. Prepare the Environment\n",
+    "### 1.1. Set up defect parameters\n",
+    "\n",
+    "Each entry of `ADATOM_SITES` places one adatom relative to the N atom with the smaller x in the island's\n",
+    "edge row at the largest y, in units of the Ti–N site spacing d = a/2, with Δz = 0 the island plane; to add a\n",
+    "site, add an entry under a new letter to both `ADATOM_SITES` and `ADATOM_MATERIAL_NAMES`.\n",
+    "\n",
+    "`CELL_SIZE` picks the cell: `\"12x12x3\"`, the manuscript's (12×12 sites, 3 slab planes, 457 atoms), or `\"10x10x2\"`\n",
+    "(10×10 sites, 2 slab planes, 225 atoms). With the bottom slab plane frozen, MACE gives E(c) − E(a) = 0.315 and 0.311 eV,\n",
+    "E(i) − E(a) = −2.247 and −2.109 eV, and E_ads(a) = −3.015 and −3.067 eV on the two."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "MATERIAL_NAME = \"Titanium Nitride\"\n",
+    "MILLER_INDICES = (0, 0, 1)\n",
+    "# Thickness counts conventional layers of two (001) planes; bottom planes are removed after the island is added.\n",
+    "SLAB_THICKNESS = 2\n",
+    "VACUUM = 15.3  # Angstrom\n",
+    "NUMBER_OF_ADDED_LAYERS = 0.5\n",
+    "\n",
+    "# Cell sizes as (xy supercell, island box minimum and maximum in crystal coordinates, bottom planes removed);\n",
+    "# x and y minima one site apart put Ti atoms at the island corners\n",
+    "CELL_SIZES = {\n",
+    "    \"12x12x3\": ([[6, 0], [0, 6]], [0.3233, 0.24, 0], [0.7233, 0.64, 1], 1),\n",
+    "    \"10x10x2\": ([[5, 0], [0, 5]], [0.29, 0.19, 0], [0.75, 0.65, 1], 2),\n",
+    "}\n",
+    "CELL_SIZE = \"12x12x3\"\n",
+    "XY_SUPERCELL_MATRIX, ISLAND_MIN_COORDINATE, ISLAND_MAX_COORDINATE, PLANES_REMOVED = CELL_SIZES[CELL_SIZE]\n",
+    "\n",
+    "ADATOM_ELEMENT = \"Ti\"\n",
+    "# Adatom sites as (Δx, Δy, Δz) from the island's edge N atom, in units of the Ti–N site spacing;\n",
+    "# Δz = 0 is the island plane. Fig. 6's b and d–h are NEB images between these sites, not positions.\n",
+    "ADATOM_SITES = {\n",
+    "    \"a\": (0.5, -0.5, 1),  # fourfold hollow on the island beside the edge\n",
+    "    \"c\": (0, 0, 1),       # atop the edge N\n",
+    "    \"i\": (0, 1, 0),       # atop the terrace N in front of the edge\n",
+    "}\n",
+    "\n",
+    "ISLAND_MATERIAL_NAME = f\"TiN(001) {CELL_SIZE} island 5x5\"\n",
+    "ADATOM_MATERIAL_NAMES = {\n",
+    "    \"a\": f\"{ISLAND_MATERIAL_NAME} + Ti a (FFH island)\",\n",
+    "    \"c\": f\"{ISLAND_MATERIAL_NAME} + Ti c (atop-N edge)\",\n",
+    "    \"i\": f\"{ISLAND_MATERIAL_NAME} + Ti i (atop-N terrace)\",\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "### 1.2. Install Packages\n",
+    "The step executes only in Pyodide environment. For other environments, the packages should be installed via `pip install` (see [README](../../README.ipynb))."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mat3ra.notebooks_utils.packages import install_packages\n",
+    "\n",
+    "await install_packages(\"made|specific_examples\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "### 1.3. Load input material"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mat3ra.made.material import Material\n",
+    "from mat3ra.standata.materials import Materials\n",
+    "\n",
+    "material = Material.create(Materials.get_by_name_first_match(MATERIAL_NAME))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "### 1.4. Create and preview Slab"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mat3ra.made.tools.helpers import create_slab\n",
+    "from mat3ra.notebooks_utils.ipython.entity.material.visualize import visualize_materials\n",
+    "\n",
+    "slab = create_slab(\n",
+    "    crystal=material,\n",
+    "    termination_top=None,  # Use default termination\n",
+    "    miller_indices=MILLER_INDICES,\n",
+    "    number_of_layers=SLAB_THICKNESS,\n",
+    "    vacuum=VACUUM,\n",
+    "    use_orthogonal_c=True,\n",
+    "    xy_supercell_matrix=XY_SUPERCELL_MATRIX\n",
+    ")\n",
+    "\n",
+    "visualize_materials(slab)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "## 2. Create the Island"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from mat3ra.made.tools.analyze.other import get_atom_indices_by_layer\n",
+    "from mat3ra.made.tools.convert import to_ase\n",
+    "from mat3ra.made.tools.entities.coordinate import BoxCoordinateCondition\n",
+    "from mat3ra.made.tools.helpers import create_island\n",
+    "from mat3ra.made.tools.modify import filter_by_ids, remove_vacuum\n",
+    "\n",
+    "coordinate_condition = BoxCoordinateCondition(min_coordinate=ISLAND_MIN_COORDINATE, max_coordinate=ISLAND_MAX_COORDINATE)\n",
+    "\n",
+    "slab_with_island = create_island(\n",
+    "    slab=slab,\n",
+    "    condition=coordinate_condition,\n",
+    "    number_of_added_layers=NUMBER_OF_ADDED_LAYERS,\n",
+    "    use_cartesian_coordinates=False,\n",
+    ")\n",
+    "for _ in range(PLANES_REMOVED):\n",
+    "    bottom_plane = get_atom_indices_by_layer(slab_with_island)[0]\n",
+    "    slab_with_island = filter_by_ids(slab_with_island, ids=bottom_plane, invert=True, reset_ids=True)\n",
+    "slab_with_island = remove_vacuum(slab_with_island, fixed_padding=VACUUM)\n",
+    "slab_with_island.name = ISLAND_MATERIAL_NAME\n",
+    "\n",
+    "atoms = to_ase(slab_with_island)\n",
+    "symbols = np.array(atoms.get_chemical_symbols())\n",
+    "planes = get_atom_indices_by_layer(slab_with_island)\n",
+    "island = planes[-1]\n",
+    "island_x, island_y = atoms.positions[island, 0], atoms.positions[island, 1]\n",
+    "is_corner = ((np.isclose(island_x, island_x.min()) | np.isclose(island_x, island_x.max()))\n",
+    "             & (np.isclose(island_y, island_y.min()) | np.isclose(island_y, island_y.max())))\n",
+    "print(f\"{slab_with_island.name}: {len(atoms)} atoms ({sum(symbols == 'Ti')} Ti, {sum(symbols == 'N')} N) \"\n",
+    "      f\"in {len(planes)} planes, c = {atoms.cell[2, 2]:.3f} Å\")\n",
+    "print(f\"Island: {len(island)} atoms, corners {symbols[island][is_corner].tolist()}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "## 3. Add the Adatom at the Sites of Fig. 6\n",
+    "\n",
+    "The paper gives no coordinates for the sites; they follow from the lattice and are measured on the island\n",
+    "built above, from the offsets in `ADATOM_SITES`. Measured from the edge N with the smaller x, a lies between\n",
+    "that N and the edge-centre Ti, the paper's FFH_edge; i is the epitaxial site that extends the island."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mat3ra.made.tools.helpers import create_defect_point_interstitial\n",
+    "\n",
+    "site_spacing = material.lattice.a / 2\n",
+    "edge_y = island_y.max()\n",
+    "edge_nitrogen_x = min(atoms.positions[index, 0] for index in island\n",
+    "                      if symbols[index] == \"N\" and np.isclose(atoms.positions[index, 1], edge_y))\n",
+    "island_z = atoms.positions[island, 2].mean()\n",
+    "\n",
+    "adatom_sites = {\n",
+    "    site: [edge_nitrogen_x + offset_x * site_spacing, edge_y + offset_y * site_spacing, island_z + offset_z * site_spacing]\n",
+    "    for site, (offset_x, offset_y, offset_z) in ADATOM_SITES.items()\n",
+    "}\n",
+    "\n",
+    "materials_with_adatom = []\n",
+    "for site, coordinate in adatom_sites.items():\n",
+    "    material_with_adatom = create_defect_point_interstitial(\n",
+    "        slab_with_island, coordinate, ADATOM_ELEMENT, \"exact_coordinate\", use_cartesian_coordinates=True\n",
+    "    )\n",
+    "    material_with_adatom.name = ADATOM_MATERIAL_NAMES[site]\n",
+    "    materials_with_adatom.append(material_with_adatom)\n",
+    "\n",
+    "    atoms_with_adatom = to_ase(material_with_adatom)\n",
+    "    adatom = len(atoms_with_adatom) - 1\n",
+    "    distances = np.sort(atoms_with_adatom.get_distances(adatom, range(adatom), mic=True))[:3]\n",
+    "    print(f\"{material_with_adatom.name}: {len(atoms_with_adatom)} atoms, \"\n",
+    "          f\"adatom's three shortest distances {np.round(distances, 3)} Å\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13",
+   "metadata": {},
+   "source": [
+    "## 4. Visualize the Result(s)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "visualize_materials([{\"material\": material_to_show, \"title\": material_to_show.name, \"rotation\": \"-45x\"}\n",
+    "                     for material_to_show in [slab_with_island, *materials_with_adatom]])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15",
+   "metadata": {},
+   "source": [
+    "## 5. Pass data to the outside runtime"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "16",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mat3ra.notebooks_utils.io import download_content_to_file\n",
+    "from mat3ra.notebooks_utils.material import set_materials\n",
+    "\n",
+    "materials = [slab_with_island, *materials_with_adatom]\n",
+    "set_materials(materials)\n",
+    "for material_to_save in materials:\n",
+    "    download_content_to_file(material_to_save.to_json(), f\"{material_to_save.name}.json\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "\n",
+    "[1] D. G. Sangiovanni, A. B. Mei, D. Edström, L. Hultman, V. Chirita, I. Petrov, J. E. Greene, \"Effects of surface\n",
+    "vibrations on interlayer mass transport: Ab initio molecular dynamics investigation of Ti adatom descent pathways\n",
+    "and rates from TiN/TiN(001) islands\", Phys. Rev. B 97, 035406 (2018).\n",
+    "[DOI: 10.1103/PhysRevB.97.035406](https://doi.org/10.1103/PhysRevB.97.035406)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}