NGSolve24

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(basics:first-example-in-ngsolve)=\n",
    "# A first example in NGSove\n",
    "\n",
    "This first notebook introduces in few basic steps how to solve a simple PDE problem using NGSolve; each step contains different objects that will be explained in detail in the following notebooks.\n",
    "\n",
    "\n",
    "To solve the problem one need to consider the following steps:\n",
    "\n",
    "1. Define the domain $\\Omega$, name the boundaries and mesh it.\n",
    "2. Define the finite element space and reserve space for the solution.\n",
    "3. Define the linear and bilinear forms and assemble respective matrix and a vector.\n",
    "4. Solve the linear system. (We may need homogeneization techniques)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Poisson problem on the unit square\n",
    "\n",
    "The first problem we are going to solve a problem on the unit square $\\Omega = (0,1)^2$, we call the boundaries $\\Gamma_b, \\Gamma_t, \\Gamma_l, \\Gamma_r$ the bottom, top, left and right boundaries respectively.\n",
    "\n",
    "Find $u$ such that\n",
    "\\begin{align*} -\\Delta u &= 20\\,xy^2 \\quad \\text{in } \\Omega, \\\\ u &= 0 \\quad \\text{on } \\Gamma_b \\cup \\Gamma_l,\\\\ n\\cdot \\nabla u &= 0 \\quad \\text{on } \\Gamma_r \\cup \\Gamma_t, \\end{align*}\n",
    "\n",
    "### Step 0: Import the necessary libraries\n",
    "\n",
    "- `ngsolve` is the library that contains the finite element methods and the solvers.\n",
    "- `Draw` is a function that allows us to visualize the results in the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ngsolve import *\n",
    "from ngsolve.webgui import Draw # Drawing in Jupyter notebook. More about this later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1: Define the domain\n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "netgen_mesh = unit_square.GenerateMesh(maxh=0.2) # generate a netgen mesh from the OCCGeometry class\n",
    "mesh = Mesh(netgen_mesh)                         # create a NGSolve mesh class\n",
    "\n",
    "Draw(mesh); # names are predefined for this case"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Define the finite element space and solution vector\n",
    "We need to create the Lagrange finite element space of order 1 on the mesh, to do so me need to pass a mesh and the essential boundary conditions.\n",
    "\n",
    "The essential boundaries are selected using the `dirichlet` flag. In particular we select the bottom and (united with) the left boundary using the regex `bottom|left`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fes = H1(mesh, order = 1, dirichlet=\"bottom|left\") # define the finite element space"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the use of a finite element space one can create a `GridFunction` that will be used to store the solution.\n",
    "\n",
    "For now you can understand the `GridFunction` as a vector that stores the values of the solution at the nodes of the mesh."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gfu = GridFunction(fes) # define the grid function: store a function on the finite element space\n",
    "\n",
    "# help(gfu) # query the grid function\n",
    "\n",
    "# print(gfu.vec) # print the vector of the grid function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3: Define the symbolic forms\n",
    "\n",
    "Our problem is to find $u $ such that\n",
    "\\begin{align*} \\int_{\\Omega} \\nabla u \\cdot \\nabla v \\,dx &= \\int_{\\Omega} 20\\,xy^2 v \\,dx \\quad \\forall v  \\end{align*}\n",
    "\n",
    "For this specific problem we need to define the bilinear form $a(u,v)$ and the linear form $f(v)$. To write it in a math-like way we make use of the `ProxyFunctions`:\n",
    "- `u`, trial function.\n",
    "- `v`, test function.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "u = fes.TrialFunction() # define the trial function\n",
    "v = fes.TestFunction() # define the test function\n",
    "\n",
    "# u, v = fes.TnT() # one-liner to define the trial and test functions\n",
    "\n",
    "a = BilinearForm(fes) # define the bilinear form\n",
    "a += grad(u) * grad(v) * dx\n",
    "a += u*v * dx \n",
    "\n",
    "# print(a.mat)  # print it ... does not work! \n",
    "\n",
    "a.Assemble();\n",
    "\n",
    "#print(a.mat) # print the matrix of the bilinear form"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "in the biliear form we have the `dx` that represents the integration over the domain $\\Omega$, it is short hand for `DifferentialSymbol(VOL)`.\n",
    "\n",
    "and `grad` that represents the gradient of the symbolic test/trial functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want to declare the right hand side as follows:\n",
    "$$\n",
    "f(v) = \\int_{\\Omega} 20 \\,xy^2\\, v \\, dx.\n",
    "$$\n",
    "To do so we use the `CoefficientFunction`s `x` and `y` that represent the first two coordinate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = LinearForm(fes)\n",
    "f += 20 * x * y ** 2 * v * dx\n",
    "f.Assemble();\n",
    "\n",
    "# print(f.vec) # print the vector of the linear form. RHS is zero so far."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Solve the linear system\n",
    "\n",
    "So far our problem was defined only symbolically, the only computation that was done was in the creation of the mesh. To actively solve the problem we need to assemble the linear system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now invert the matrix and solve the linear system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "inv = a.mat.Inverse(freedofs=fes.FreeDofs()) # compute the inverse of the matrix\n",
    "\n",
    "gfu.vec.data = inv * f.vec  # solve the system"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What freedofs does is to select the degrees of freedom that are not in the essential boundary conditions. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Draw(gfu); # draw the solution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interact with NGSolve\n",
    "\n",
    "\n",
    "* A jupyter notebook (like this one) gives you one way to interact with NGSolve. When you have a complex sequence of tasks to perform, the notebook may not be adequate.\n",
    "\n",
    "\n",
    "* You can write an entire python module in a text editor and call python on the command line. (A script of the above is provided in `poisson.py`.)\n",
    "    ```\n",
    "    python3 poisson.py\n",
    "    ```\n",
    "  \n",
    "* If you want the Netgen GUI, then use `netgen` on the command line:\n",
    "    ```\n",
    "    netgen poisson.py\n",
    "    ```\n",
    "  You can then ask for a python shell from the GUI's menu options (`Solve -> Python shell`).\n",
    "  \n",
    "* One can use the Netgen GUI within a jupyter notebook: `import netgen.gui`. \n",
    "  ```python\n",
    "  import netgen.gui\n",
    "  from ngsolve import *\n",
    "\n",
    "  mesh = Mesh(unit_square.GenerateMesh(maxh=0.2))  # generate a mesh\n",
    "  Draw(mesh);  # draw the mesh\n",
    "  ```\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import netgen.gui\n",
    "# from ngsolve import *\n",
    "\n",
    "# mesh = Mesh(unit_square.GenerateMesh(maxh=0.2))  # generate a mesh\n",
    "# Draw(mesh);  # draw the mesh"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ngspy",
   "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.12.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}