{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Region facing surfaces\n",
    "\n",
    "For two regions, sometimes it is necessary to find whether there are any facing surfaces. If there are, along which axis and at what coordinates.\n",
    "\n",
    "As an example let us set up two regions \"stacked\" in the $z$-direction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import discretisedfield as df  # df is here chosen to be an alias for discretisedfield\n",
    "\n",
    "p11 = (0, 0, 0)\n",
    "p12 = (100e-9, 50e-9, 20e-9)\n",
    "region1 = df.Region(p1=p11, p2=p12)\n",
    "\n",
    "p21 = (0, 0, 20e-9)\n",
    "p22 = (100e-9, 50e-9, 30e-9)\n",
    "region2 = df.Region(p1=p21, p2=p22)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To find the facing surfaces, we use the `facing_surface` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('z',\n",
       " Region(pmin=[0.0, 0.0, 0.0], pmax=[1e-07, 5e-08, 2e-08], dims=['x', 'y', 'z'], units=['m', 'm', 'm']),\n",
       " Region(pmin=[0.0, 0.0, 2e-08], pmax=[1e-07, 5e-08, 3e-08], dims=['x', 'y', 'z'], units=['m', 'm', 'm']))"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "region1.facing_surface(region2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a result, we get a length-3 tuple. The first element is the axis the facing surfaces are perpendicular to. In our example, it is the $z$ axis. Now, if we start moving along the $z$-axis (e.g. from minus infinity) the first region we are going to enter is the region which is the second element of our tuple. When we leave that region, we enter the second region, which is the third element of our tuple.\n",
    "\n",
    "If no facing surfaces can be identified, `TypeError` is raised. For instance, if we have overlapping regions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Exception raised.\n"
     ]
    }
   ],
   "source": [
    "p11 = (0, 0, 0)\n",
    "p12 = (100e-9, 50e-9, 20e-9)\n",
    "region1 = df.Region(p1=p11, p2=p12)\n",
    "\n",
    "p21 = (0, 0, 10e-9)\n",
    "p22 = (100e-9, 50e-9, 30e-9)\n",
    "region2 = df.Region(p1=p21, p2=p22)\n",
    "\n",
    "try:\n",
    "    region1.facing_surface(region2)\n",
    "except ValueError:\n",
    "    print(\"Exception raised.\")"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "2940b2f637ab9684f43d9709170b64af8bd4a8fb93490cb82c1b85cca32aed36"
  },
  "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
}