{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Mesh plane and line\n",
    "\n",
    "It is sometimes necessary to get the coordinates of points, which are equally spaced on a line. Those values can then be used for sampling fields. In `discretisedfield`, this can be obtained using `line`.\n",
    "\n",
    "`line` takes 3 input arguments:\n",
    "\n",
    "- points `p1` and `p2` between which the line spans,\n",
    "- the number of points on the line `n`.\n",
    "\n",
    "The mesh we are going to use as an example is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import discretisedfield as df\n",
    "\n",
    "p1 = (0, 0, 0)\n",
    "p2 = (100e-9, 50e-9, 20e-9)\n",
    "n = (20, 10, 4)\n",
    "\n",
    "region = df.Region(p1=p1, p2=p2)\n",
    "mesh = df.Mesh(region=region, n=n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us say we want to get the coordinates of 11 (`n=11`) points on the line, which spans between $(0, 0, 0)$ and $(100\\,\\text{nm}, 0, 20\\,\\text{nm})$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<generator object Mesh.line at 0x7f856491c970>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "mesh.line(p1=(0, 0, 0), p2=(100e-9, 0, 20e-9), n=11)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This method returns a generator, which we can use as an iterator (for instance, in `for` loops). The coordinates of points are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(0.0, 0.0, 0.0),\n",
       " (1e-08, 0.0, 2e-09),\n",
       " (2e-08, 0.0, 4e-09),\n",
       " (3.0000000000000004e-08, 0.0, 6.000000000000001e-09),\n",
       " (4e-08, 0.0, 8e-09),\n",
       " (5e-08, 0.0, 1e-08),\n",
       " (6.000000000000001e-08, 0.0, 1.2000000000000002e-08),\n",
       " (7e-08, 0.0, 1.4000000000000001e-08),\n",
       " (8e-08, 0.0, 1.6e-08),\n",
       " (9e-08, 0.0, 1.8000000000000002e-08),\n",
       " (1e-07, 0.0, 2e-08)]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "line = mesh.line(p1=(0, 0, 0), p2=(100e-9, 0, 20e-9), n=11)\n",
    "list(line)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When asking for a mesh to give us the points on a line, both points `p1` and `p2` must belong to the mesh. For instance, if we ask for the following line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Exception raised.\n"
     ]
    }
   ],
   "source": [
    "p1 = (0, 0, 0)\n",
    "p2 = (100e-9, 100e-9, 100e-9)\n",
    "\n",
    "try:\n",
    "    list(mesh.line(p1=p1, p2=p2, n=10))\n",
    "except ValueError:\n",
    "    print(\"Exception raised.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is because point `p2` does not belong to the mesh region (`mesh.region`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p2 in mesh.region"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plane mesh\n",
    "\n",
    "Similar to the line, we usually need to extract a plane-mesh. This method we later use for slicing fields and extracting the values of a field on the plane.\n",
    "\n",
    "Plane mesh is obtained using `sel` method. The planes allowed must be perpendicular to the geometrical axes. Therefore, to extract a plane, we need to define the axis to which the plane is perpendicular to as well as the point at which the plane intersects the axis. For example, for a three-dimensional geometry, we want to extract the plane perpendicular to the z-axis (in the xy-plane), which intersects it at $2.5\\,\\text{nm}$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>Mesh</strong>\n",
       "<ul>\n",
       "  <li><strong>Region</strong>\n",
       "<ul>\n",
       "  <li>pmin = [0.0, 0.0]</li>\n",
       "  <li>pmax = [1e-07, 5e-08]</li>\n",
       "  <li>dims = ['x', 'y']</li>\n",
       "  <li>units = ['m', 'm']</li>\n",
       "</ul></li>\n",
       "  <li>n = [20, 10]</li>\n",
       "  </ul>"
      ],
      "text/plain": [
       "Mesh(Region(pmin=[0.0, 0.0], pmax=[1e-07, 5e-08], dims=['x', 'y'], units=['m', 'm']), n=[20, 10])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mesh.sel(z=2.5e-9)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This method returns a mesh object, which consists no cells in the z-direction and keeps the same number of cells in x and y directions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([20, 10])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mesh.sel(z=2.5e-9).n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In other words, the discretisation `cell` in the plane mesh is actually two-dimensional with the same x and y dimensions of the `cell` in the original mesh."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The edge lengths of the resulting mesh region is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1.e-07, 5.e-08])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mesh.sel(z=2.5e-9).region.edges"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means that the plane mesh keeps the original dimensions in x and y directions and has no \"thickness\".\n",
    "\n",
    "Another way for asking for a plane mesh is simply by passing a string `'x'`, `'y'`, or `'z'`, without specifying the point. In that case, the mesh is sliced through the middle of the sample: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2.5e-08, 1.0e-08])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plane_mesh = mesh.sel(\"x\")\n",
    "\n",
    "plane_mesh.region.centre"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which is the same as the centre of the original mesh on the yz-plane:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2.5e-08, 1.0e-08])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mesh.region.centre[1:]"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}