1{ 2 "cells": [ 3 { 4 "cell_type": "markdown", 5 "metadata": {}, 6 "source": [ 7 "# Standalone libCEED examples\n", 8 "\n", 9 "This is a tutorial 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", 10 "\n", 11 "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.readthedocs.io/)." 12 ] 13 }, 14 { 15 "cell_type": "markdown", 16 "metadata": {}, 17 "source": [ 18 "## Common notation\n", 19 "\n", 20 "For most of our examples, the spatial discretization\n", 21 "uses high-order finite elements/spectral elements, namely, the high-order Lagrange\n", 22 "polynomials defined over $P$ non-uniformly spaced nodes, the\n", 23 "Gauss-Legendre-Lobatto (GLL) points, and quadrature points $\\{q_i\\}_{i=1}^Q$, with\n", 24 "corresponding weights $\\{w_i\\}_{i=1}^Q$ (typically the ones given by Gauss\n", 25 "or Gauss-Lobatto quadratures, that are built in the library).\n", 26 "\n", 27 "We discretize the domain, $\\Omega \\subset \\mathbb{R}^d$ (with $d=1,2,3$,\n", 28 "typically) by letting $\\Omega = \\bigcup_{e=1}^{N_e}\\Omega_e$, with $N_e$\n", 29 "disjoint elements. For most examples we use unstructured meshes for which the elements\n", 30 "are hexahedra (although this is not a requirement in libCEED).\n", 31 "\n", 32 "The physical coordinates are denoted by $\\mathbf{x}=(x,y,z)\\in\\Omega_e$,\n", 33 "while the reference coordinates are represented as\n", 34 "$\\boldsymbol{X}=(X,Y,Z) \\equiv (X_1,X_2,X_3) \\in I=[-1,1]^3$\n", 35 "(for $d=3$).\n", 36 "\n", 37 "### Ex1-Volume\n", 38 "\n", 39 "#### Mathematical formulation\n", 40 "\n", 41 "This example is located in the subdirectory `examples/ceed`. It illustrates a\n", 42 "simple usage of libCEED to compute the volume of a given body using a matrix-free\n", 43 "application of the mass operator. Arbitrary mesh and solution orders in 1D, 2D and 3D\n", 44 "are supported from the same code.\n", 45 "\n", 46 "This example shows how to compute line/surface/volume integrals of a 1D, 2D, or 3D\n", 47 "domain $\\Omega$ respectively, by applying the mass operator to a vector of\n", 48 "$1$s. It computes:\n", 49 "\n", 50 "$$\n", 51 " I = \\int_{\\Omega} 1 \\, dV .\n", 52 "$$\n", 53 "\n", 54 "We write here the vector $u(x)\\equiv 1$ in the Galerkin approximation,\n", 55 "and find the volume of $\\Omega$ as\n", 56 "\n", 57 "$$\n", 58 " \\sum_e \\int_{\\Omega_e} v(x) 1 \\, dV\n", 59 "$$\n", 60 "\n", 61 "with $v(x) \\in \\mathcal{V}_p = \\{ v \\in H^{1}(\\Omega_e) \\,|\\, v \\in P_p(\\boldsymbol{I}), e=1,\\ldots,N_e \\}$,\n", 62 "the test functions.\n" 63 ] 64 }, 65 { 66 "cell_type": "markdown", 67 "metadata": {}, 68 "source": [ 69 "#### Executing the example\n", 70 "\n", 71 "Clone or download libCEED by running" 72 ] 73 }, 74 { 75 "cell_type": "code", 76 "execution_count": null, 77 "metadata": {}, 78 "outputs": [], 79 "source": [ 80 "! git clone https://github.com/CEED/libCEED.git" 81 ] 82 }, 83 { 84 "cell_type": "markdown", 85 "metadata": {}, 86 "source": [ 87 "Then move to the libCEED folder" 88 ] 89 }, 90 { 91 "cell_type": "code", 92 "execution_count": null, 93 "metadata": {}, 94 "outputs": [], 95 "source": [ 96 "cd libCEED" 97 ] 98 }, 99 { 100 "cell_type": "markdown", 101 "metadata": {}, 102 "source": [ 103 "And compile the library by running" 104 ] 105 }, 106 { 107 "cell_type": "code", 108 "execution_count": null, 109 "metadata": {}, 110 "outputs": [], 111 "source": [ 112 "! make" 113 ] 114 }, 115 { 116 "cell_type": "markdown", 117 "metadata": {}, 118 "source": [ 119 "Move to the examples folder " 120 ] 121 }, 122 { 123 "cell_type": "code", 124 "execution_count": null, 125 "metadata": {}, 126 "outputs": [], 127 "source": [ 128 "cd examples/" 129 ] 130 }, 131 { 132 "cell_type": "markdown", 133 "metadata": {}, 134 "source": [ 135 "Then move to the standalone libCEED's examples folder" 136 ] 137 }, 138 { 139 "cell_type": "code", 140 "execution_count": null, 141 "metadata": {}, 142 "outputs": [], 143 "source": [ 144 "cd ceed/" 145 ] 146 }, 147 { 148 "cell_type": "markdown", 149 "metadata": {}, 150 "source": [ 151 "And compile the examples by running" 152 ] 153 }, 154 { 155 "cell_type": "code", 156 "execution_count": null, 157 "metadata": {}, 158 "outputs": [], 159 "source": [ 160 "! make" 161 ] 162 }, 163 { 164 "cell_type": "markdown", 165 "metadata": {}, 166 "source": [ 167 "Now run `ex1-volume` by running" 168 ] 169 }, 170 { 171 "cell_type": "code", 172 "execution_count": 1, 173 "metadata": {}, 174 "outputs": [ 175 { 176 "name": "stdout", 177 "output_type": "stream", 178 "text": [ 179 "Selected options: [command line option] : <current value>\n", 180 " Ceed specification [-c] : /cpu/self\n", 181 " Mesh dimension [-d] : 3\n", 182 " Mesh order [-m] : 4\n", 183 " Solution order [-o] : 4\n", 184 " Num. 1D quadr. pts [-q] : 6\n", 185 " Approx. # unknowns [-s] : 262144\n", 186 " QFunction source [-g] : gallery\n", 187 "\n", 188 "Mesh size: nx = 16, ny = 16, nz = 16\n", 189 "Number of mesh nodes : 274625\n", 190 "Number of solution nodes : 274625\n", 191 "Computing the quadrature data for the mass operator ... done.\n", 192 "Computing the mesh volume using the formula: vol = 1^T.M.1 ... done.\n", 193 "Exact mesh volume : 2.3561944901923\n", 194 "Computed mesh volume : 2.3561944901921\n", 195 "Volume error : -2.7444713168734e-13\n" 196 ] 197 } 198 ], 199 "source": [ 200 "! ./ex1-volume -d 3 -g" 201 ] 202 }, 203 { 204 "cell_type": "markdown", 205 "metadata": {}, 206 "source": [ 207 "This example shows how to compute line/surface/volume integrals of a 1D, 2D, or 3D domain Ω respectively, by applying the mass operator to a vector of 1s. The command line option `-d` specifies the dimensionality of the domain Ω. The option `-g` specifies that the mass operator is, in this case, selected from a gallery of available built-in operators in the library." 208 ] 209 }, 210 { 211 "cell_type": "markdown", 212 "metadata": {}, 213 "source": [ 214 "### Ex2-Surface\n", 215 "\n", 216 "#### Mathematical formulation\n", 217 "\n", 218 "This example is located in the subdirectory `examples/ceed`. It computes the\n", 219 "surface area of a given body using matrix-free application of a diffusion operator.\n", 220 "Arbitrary mesh and solution orders in 1D, 2D and 3D are supported from the same code.\n", 221 "\n", 222 "Similarly to the Ex1-Volume example, it computes:\n", 223 "\n", 224 "\\begin{equation}\\label{eq-ex2-surface}\\tag{eq. 1}\n", 225 " I = \\int_{\\partial \\Omega} 1 \\, dS ,\n", 226 "\\end{equation}\n", 227 "\n", 228 "by applying the divergence theorem.\n", 229 "In particular, we select $u(\\mathbf x) = x_0 + x_1 + x_2$, for which $\\nabla u = [1, 1, 1]^T$, and thus $\\nabla u \\cdot \\hat{\\mathbf n} = 1$.\n", 230 "\n", 231 "Given Laplace's equation,\n", 232 "\n", 233 "$$\n", 234 " \\nabla \\cdot \\nabla u = 0, \\textrm{ for } \\mathbf{x} \\in \\Omega ,\n", 235 "$$\n", 236 "\n", 237 "let us multiply by a test function $v$ and integrate by parts to obtain\n", 238 "\n", 239 "$$\n", 240 " \\int_\\Omega \\nabla v \\cdot \\nabla u \\, dV - \\int_{\\partial \\Omega} v \\nabla u \\cdot \\hat{\\mathbf n}\\, dS = 0 .\n", 241 "$$\n", 242 "\n", 243 "Since we have chosen $u$ such that $\\nabla u \\cdot \\hat{\\mathbf n} = 1$, the boundary integrand is $v 1 \\equiv v$. Hence, similar to the previous example, we can evaluate the surface integral by applying the volumetric Laplacian as follows\n", 244 "\n", 245 "$$\n", 246 " \\int_\\Omega \\nabla v \\cdot \\nabla u \\, dV \\approx \\sum_e \\int_{\\partial \\Omega_e} v(x) 1 \\, dS .\n", 247 "$$" 248 ] 249 }, 250 { 251 "cell_type": "markdown", 252 "metadata": {}, 253 "source": [ 254 "### Executing the example\n", 255 "\n", 256 "Assuming the steps above, you should be in the `examples/ceed/` subdirectory and have already compiled the example.\n", 257 "\n", 258 "Now run `ex2-surface` by running " 259 ] 260 }, 261 { 262 "cell_type": "code", 263 "execution_count": 2, 264 "metadata": {}, 265 "outputs": [ 266 { 267 "name": "stdout", 268 "output_type": "stream", 269 "text": [ 270 "Selected options: [command line option] : <current value>\n", 271 " Ceed specification [-c] : /cpu/self\n", 272 " Mesh dimension [-d] : 3\n", 273 " Mesh order [-m] : 4\n", 274 " Solution order [-o] : 4\n", 275 " Num. 1D quadr. pts [-q] : 6\n", 276 " Approx. # unknowns [-s] : 262144\n", 277 " QFunction source [-g] : gallery\n", 278 "\n", 279 "Mesh size: nx = 16, ny = 16, nz = 16\n", 280 "Number of mesh nodes : 274625\n", 281 "Number of solution nodes : 274625\n", 282 "Computing the quadrature data for the diffusion operator ... done.\n", 283 "Computing the mesh surface area using the formula: sa = 1^T.|K.x| ... done.\n", 284 "Exact mesh surface area : 6\n", 285 "Computed mesh surface area : 5.9773703490853\n", 286 "Surface area error : -0.022629650914673\n" 287 ] 288 } 289 ], 290 "source": [ 291 "! ./ex2-surface -d 3 -g" 292 ] 293 }, 294 { 295 "cell_type": "markdown", 296 "metadata": {}, 297 "source": [ 298 "This example computes the surface area of a given body using matrix-free application of a Laplace's (diffusion) operator. The command line option `-d` specifies the dimensionality of the domain Ω. The option `-g` specifies that the Laplace's operator is, in this case, selected from a gallery of available built-in operators in the library." 299 ] 300 } 301 ], 302 "metadata": { 303 "kernelspec": { 304 "display_name": "Python 3", 305 "language": "python", 306 "name": "python3" 307 }, 308 "language_info": { 309 "codemirror_mode": { 310 "name": "ipython", 311 "version": 3 312 }, 313 "file_extension": ".py", 314 "mimetype": "text/x-python", 315 "name": "python", 316 "nbconvert_exporter": "python", 317 "pygments_lexer": "ipython3", 318 "version": "3.8.5" 319 } 320 }, 321 "nbformat": 4, 322 "nbformat_minor": 4 323} 324