{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Defining a uniform field\n",
    "\n",
    "## Scalar field\n",
    "\n",
    "In order to define a finite difference field, `discretisedfield.Field` class is used. The main object, a field is built on is the mesh."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import discretisedfield as df\n",
    "\n",
    "p1 = (-50, -50, -50)\n",
    "p2 = (50, 50, 50)\n",
    "n = (2, 2, 2)\n",
    "mesh = df.Mesh(p1=p1, p2=p2, n=n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`discretisedfield.Field` asigns a value to every discretisation cell of the mesh. There are two main parameters of the field that define its value: `dim` and `value`. `dim` is a positive integer which defines the dimension of the value. For instance, if `dim=1`, one number is assigned to each discretisation cell and that field can be considered as a scalar field. On the other hand, if `dim=3`, the value is a three dimensional vector. Let us start with a scalar field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "dim = 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After all these parameters are defined, we can instantiate a field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "field = df.Field(mesh, dim=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We only defined the dimension of the value, but we did not provide any information about what that value actually is. By default, if `value` is not provided, a field is initialised as a \"zero-field\". By calling the field with a point coordinates, we can sample the value at that point."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "point = (2, 3, 5)\n",
    "field(point)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sampling the value of the field always returns a numpy array, whose length equals the dimension of the field. Let us now provide the same value for the field at all its points. This can be achieved by simply passing a number."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "value = 1.23\n",
    "field.value = value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we sample the field now, we can see that we do not have a \"zero-field\" anymore."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.23"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field(point)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The underlying attribute that keeps the values of all points in the field is `discretisedfield.Field.array`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[[[1.23],\n",
       "         [1.23]],\n",
       "\n",
       "        [[1.23],\n",
       "         [1.23]]],\n",
       "\n",
       "\n",
       "       [[[1.23],\n",
       "         [1.23]],\n",
       "\n",
       "        [[1.23],\n",
       "         [1.23]]]])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(field.array == 1.23).all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its shape is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 2, 2, 1)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.array.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first three numbers are the number of discretisation cells in all three dimensions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 2, 2)"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.mesh.n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and the last number is the dimension of the value in the field"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.dim"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vector field\n",
    "\n",
    "So far, we investigated a basic definition of a scalar field. Now, we are going to define a vector field with `dim=3`, so that the vector at each point is pointing in the positive $y$ direction (`value=(0, 1, 0)`). In addition to those values, we are going to provide another parameter which is optional and could serve to distinguish different fields - `name`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "field = df.Field(mesh, dim=3, value=(0, 1, 0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we check the shape of the underlying `array`, we can see that the last number is now 3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 2, 2, 3)"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.array.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The values are now three-dimensional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[[[0., 1., 0.],\n",
       "         [0., 1., 0.]],\n",
       "\n",
       "        [[0., 1., 0.],\n",
       "         [0., 1., 0.]]],\n",
       "\n",
       "\n",
       "       [[[0., 1., 0.],\n",
       "         [0., 1., 0.]],\n",
       "\n",
       "        [[0., 1., 0.],\n",
       "         [0., 1., 0.]]]])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0.0, 1.0, 0.0)"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field(point)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to change the value of the field, we can do it via `discretisedfield.Field.value`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "field.value = [1, 0, -3]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The values are now changed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[[[ 1.,  0., -3.],\n",
       "         [ 1.,  0., -3.]],\n",
       "\n",
       "        [[ 1.,  0., -3.],\n",
       "         [ 1.,  0., -3.]]],\n",
       "\n",
       "\n",
       "       [[[ 1.,  0., -3.],\n",
       "         [ 1.,  0., -3.]],\n",
       "\n",
       "        [[ 1.,  0., -3.],\n",
       "         [ 1.,  0., -3.]]]])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "field.array"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we have used a list instead of a tuple to set a new value. Both give the same result and it is true for any iterable of length 3."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.5"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}