xref: /libCEED/examples/python/tutorial-5-operator.ipynb (revision 2fc995f6102555f4a428ce850576f23ccfe8b680)

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# libCEED for Python examples\n",
    "\n",
    "This is a tutorial to illustrate the main feautures of the Python interface for [libCEED](https://github.com/CEED/libCEED/), the low-level API library for efficient high-order discretization methods developed by the co-design [Center for Efficient Exascale Discretizations](https://ceed.exascaleproject.org/) (CEED) of the [Exascale Computing Project](https://www.exascaleproject.org/) (ECP).\n",
    "\n",
    "While libCEED's focus is on high-order finite/spectral element method implementations, the approach is mostly algebraic and thus applicable to other discretizations in factored form, as explained in the [user manual](https://libceed.org/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting up libCEED for Python\n",
    "\n",
    "Install libCEED for Python by running"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python -m pip install libceed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## CeedOperator\n",
    "\n",
    "Here we show some basic examples to illustrate the `libceed.Operator` class. In libCEED, a `libceed.Operator` defines the finite/spectral element operator associated to a `libceed.QFunction` (see [the API documentation](https://libceed.org/en/latest/libCEEDapi.html#finite-element-operator-decomposition))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* In the following example, we create and apply a CeedOperator for the mass matrix in 1D. By applying this operator to a vector of 1's, we compute the length of this 1D domain, similar to Ex1-Volume in the [tutorial-6-shell tutorial](./tutorial-6-shell.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libceed\n",
    "import numpy as np\n",
    "\n",
    "ceed = libceed.Ceed()\n",
    "\n",
    "nelem = 15\n",
    "p = 5\n",
    "q = 8\n",
    "nx = nelem + 1\n",
    "nu = nelem*(p-1) + 1\n",
    "\n",
    "# Vectors\n",
    "x = ceed.Vector(nx)\n",
    "x_array = np.zeros(nx)\n",
    "for i in range(nx):\n",
    "  x_array[i] = i / (nx - 1.0)\n",
    "x.set_array(x_array, cmode=libceed.USE_POINTER)\n",
    "\n",
    "qdata = ceed.Vector(nelem*q)\n",
    "u = ceed.Vector(nu)\n",
    "v = ceed.Vector(nu)\n",
    "\n",
    "# Restrictions\n",
    "indx = np.zeros(nx*2, dtype=\"int32\")\n",
    "for i in range(nx):\n",
    "  indx[2*i+0] = i\n",
    "  indx[2*i+1] = i+1\n",
    "rx = ceed.ElemRestriction(nelem, 2, 1, 1, nx, indx, cmode=libceed.USE_POINTER)\n",
    "\n",
    "indu = np.zeros(nelem*p, dtype=\"int32\")\n",
    "for i in range(nelem):\n",
    "  for j in range(p):\n",
    "    indu[p*i+j] = i*(p-1) + j\n",
    "ru = ceed.ElemRestriction(nelem, p, 1, 1, nu, indu, cmode=libceed.USE_POINTER)\n",
    "strides = np.array([1, q, q], dtype=\"int32\")\n",
    "rui = ceed.StridedElemRestriction(nelem, q, 1, q*nelem, strides)\n",
    "\n",
    "# Bases\n",
    "bx = ceed.BasisTensorH1Lagrange(1, 1, 2, q, libceed.GAUSS)\n",
    "bu = ceed.BasisTensorH1Lagrange(1, 1, p, q, libceed.GAUSS)\n",
    "\n",
    "# QFunctions\n",
    "qf_setup = ceed.QFunctionByName(\"Mass1DBuild\")\n",
    "qf_mass = ceed.QFunctionByName(\"MassApply\")\n",
    "\n",
    "# Setup operator\n",
    "op_setup = ceed.Operator(qf_setup)\n",
    "op_setup.set_field(\"dx\", rx, bx, libceed.VECTOR_ACTIVE)\n",
    "op_setup.set_field(\"weights\", libceed.ELEMRESTRICTION_NONE, bx,\n",
    "                   libceed.VECTOR_NONE)\n",
    "op_setup.set_field(\"qdata\", rui, libceed.BASIS_NONE,\n",
    "                   libceed.VECTOR_ACTIVE)\n",
    "op_setup.check()\n",
    "print('Setup operator: ', op_setup)\n",
    "\n",
    "# Mass operator\n",
    "op_mass = ceed.Operator(qf_mass)\n",
    "op_mass.set_field(\"u\", ru, bu, libceed.VECTOR_ACTIVE)\n",
    "op_mass.set_field(\"qdata\", rui, libceed.BASIS_NONE, qdata)\n",
    "op_mass.set_field(\"v\", ru, bu, libceed.VECTOR_ACTIVE)\n",
    "op_mass.check()\n",
    "print('Mass operator: ', op_mass)\n",
    "\n",
    "# Setup\n",
    "op_setup.apply(x, qdata)\n",
    "\n",
    "# Apply mass matrix\n",
    "u.set_value(1)\n",
    "op_mass.apply(u, v)\n",
    "\n",
    "# Check\n",
    "with v.array_read() as v_array:\n",
    "  print('The length of the domain is l = %4.2f'%np.sum(v_array))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* In the next example, we create and apply a CeedOperator for the Poisson operator in 1D. By applying this operator to a vector with a linear function, we compute the 'surface area' of this 1D domain, similar to Ex2-Surface in the [tutorial-6-shell tutorial](./tutorial-6-shell.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libceed\n",
    "import numpy as np\n",
    "\n",
    "ceed = libceed.Ceed()\n",
    "\n",
    "nelem = 15\n",
    "p = 5\n",
    "q = 8\n",
    "nx = nelem + 1\n",
    "nu = nelem*(p-1) + 1\n",
    "\n",
    "# Vectors\n",
    "x = ceed.Vector(nx)\n",
    "x_array = np.zeros(nx)\n",
    "for i in range(nx):\n",
    "  x_array[i] = i / (nx - 1.0)\n",
    "x.set_array(x_array, cmode=libceed.USE_POINTER)\n",
    "\n",
    "qdata = ceed.Vector(nelem*q)\n",
    "u = ceed.Vector(nu)\n",
    "v = ceed.Vector(nu)\n",
    "\n",
    "# Restrictions\n",
    "indx = np.zeros(nx*2, dtype=\"int32\")\n",
    "for i in range(nx):\n",
    "  indx[2*i+0] = i\n",
    "  indx[2*i+1] = i+1\n",
    "rx = ceed.ElemRestriction(nelem, 2, 1, 1, nx, indx, cmode=libceed.USE_POINTER)\n",
    "\n",
    "indu = np.zeros(nelem*p, dtype=\"int32\")\n",
    "for i in range(nelem):\n",
    "  for j in range(p):\n",
    "    indu[p*i+j] = i*(p-1) + j\n",
    "ru = ceed.ElemRestriction(nelem, p, 1, 1, nu, indu, cmode=libceed.USE_POINTER)\n",
    "strides = np.array([1, q, q], dtype=\"int32\")\n",
    "rui = ceed.StridedElemRestriction(nelem, q, 1, q*nelem, strides)\n",
    "\n",
    "# Bases\n",
    "bx = ceed.BasisTensorH1Lagrange(1, 1, 2, q, libceed.GAUSS)\n",
    "bu = ceed.BasisTensorH1Lagrange(1, 1, p, q, libceed.GAUSS)\n",
    "\n",
    "# QFunctions\n",
    "qf_setup = ceed.QFunctionByName(\"Poisson1DBuild\")\n",
    "qf_mass = ceed.QFunctionByName(\"Poisson1DApply\")\n",
    "\n",
    "# Setup operator\n",
    "op_setup = ceed.Operator(qf_setup)\n",
    "op_setup.set_field(\"dx\", rx, bx, libceed.VECTOR_ACTIVE)\n",
    "op_setup.set_field(\"weights\", libceed.ELEMRESTRICTION_NONE, bx,\n",
    "                   libceed.VECTOR_NONE)\n",
    "op_setup.set_field(\"qdata\", rui, libceed.BASIS_NONE,\n",
    "                   libceed.VECTOR_ACTIVE)\n",
    "op_setup.check()\n",
    "print('Setup operator: ', op_setup)\n",
    "\n",
    "# Poisson operator\n",
    "op_poisson = ceed.Operator(qf_mass)\n",
    "op_poisson.set_field(\"du\", ru, bu, libceed.VECTOR_ACTIVE)\n",
    "op_poisson.set_field(\"qdata\", rui, libceed.BASIS_NONE, qdata)\n",
    "op_poisson.set_field(\"dv\", ru, bu, libceed.VECTOR_ACTIVE)\n",
    "op_poisson.check()\n",
    "print('Poisson operator: ', op_poisson)\n",
    "\n",
    "# Setup\n",
    "op_setup.apply(x, qdata)\n",
    "\n",
    "# Apply Poisson operator\n",
    "with u.array_write() as u_array:\n",
    "  [points, _] = ceed.lobatto_quadrature(p)\n",
    "  for elem in range(nelem):\n",
    "      for point in range(p):\n",
    "          u_array[elem * (p - 1) + point] = (1.0 + 2.0 * elem + points[point])/(2.0 * nelem)\n",
    "op_poisson.apply(u, v)\n",
    "\n",
    "# Check\n",
    "with v.array_read() as v_array:\n",
    "  print('The surface area of the domain is dl = %4.2f'%np.sum(abs(v_array)))"
   ]
  }
 ],
 "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.13.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}