From 9b6cc00aa6fa6b673c690b2eb3fe861758ba471d Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 14 Jul 2009 21:04:59 +0000 Subject: [PATCH] Finish writing documentation. git-svn-id: https://svn.dealii.org/trunk@19081 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/examples/step-36/doc/intro.dox | 123 ++++++++++------- deal.II/examples/step-36/doc/results.dox | 166 ++++++++++++++++++++++- 2 files changed, 234 insertions(+), 55 deletions(-) diff --git a/deal.II/examples/step-36/doc/intro.dox b/deal.II/examples/step-36/doc/intro.dox index 5f665d5ac3..685cdbb8d0 100644 --- a/deal.II/examples/step-36/doc/intro.dox +++ b/deal.II/examples/step-36/doc/intro.dox @@ -7,66 +7,91 @@ Bangerth.

Preamble

The problem we want to solve in this example is an eigenspectrum -problem which no longer contains a single solution, but a set of -solutions for the various eigenfunctions we want to compute. The -problem of finding all eigenvalues (eigenfunctions) of a generalized -eigenvalue problem is a formidable challange; however, most of the -time we are really only interested in a small subset of these values -(functions). Fortunately, the interface to the SLEPc library allows us -to select which portion of the eigenspectrum and how many solutions we -want to solve for. - -To do this, everything here is built on top of classes provided by -deal.II that wrap around the linear algebra implementation of the SLEPc -library; which links to some the underlying features of the PETSc library. +problem. Eigenvalue problems appear in a wide context of problems, for example +in the computation of electromagnetic standing waves in cavities, vibration +modes of drum membranes, or oscillations of lakes and estuaries. One of the +most enigmatic applications is probably the computation of stationary or +quasi-static wave functions in quantum mechanics. The latter application is +what we would like to investigate here, though the general techniques outlined +in this program are of course equally applicable to the other applications +above. + +Eigenspectrum problems have the general form +@f{align*} + L \Psi &= \varepsilon \Psi \qquad &&\text{in}\ \Omega, + \\ + \Psi &= 0 &&\text{on}\ \partial\Omega, +@f} +where the Dirichlet boundary condition on $\Psi=\Psi(\mathbf x)$ could also be +replaced by Neumann or Robin conditions; $L$ is an operator that generally +also contains differential operators. + +Under suitable conditions, above equations have a set of solutions +$\Psi_\ell,\varepsilon_\ell$, $\ell\in {\cal I}$, where $\cal I$ can be a finite or +infinite set. In either case, let us note that there is no longer just a +single solution, but a set of solutions (the various eigenfunctions and +corresponding eigenvalues) that we want to compute. The problem of finding all +eigenvalues (eigenfunctions) of such eigenvalue problems is a formidable +challange; however, most of the time we are really only interested in a small +subset of these values (functions). Fortunately, the interface to the SLEPc +library that we will use for this tutorial program allows us to select which +portion of the eigenspectrum and how many solutions we want to solve for. + +In this program, the eigenspectrum solvers we use are classes +provided by deal.II that wrap around the linear algebra implementation of the +SLEPc library; +SLEPc itself builds on the PETSc library for +linear algebra contents. +

Introduction

-Start with a differential operator equation -@f[ - L(x,y) \Psi = \varepsilon \Psi \quad, -@f] -where $L$ is a differential operator. In the usual way in finite -elements we multiply both sides with a test function and then replace -$\Psi$ and the test function with discrete shape functions. -@f[ - \sum_j (\phi_i, L\phi_j) \tilde{\psi}_j = - \varepsilon \sum_j (\phi_i, \phi_j) \tilde{\psi}_j \quad, -@f] -where $\tilde{\psi}_j$, the reduced wavefunction, are the expansion -coefficients of the approximation - +The basic equation of stationary quantum mechanics is the Schrödinger +equation. The Copenhagen interpretation of quantum mechanics posits that the +motion of particles in an external potential $V(\mathbf x)$ is governed a wave +function $\Psi(\mathbf x)$ that satisfies this Schrödinger +equation of the (non-dimensionalized) form +@f{align*} + [-\Delta + V(\mathbf x)] \Psi(\mathbf x) &= \varepsilon \Psi(\mathbf x) + \qquad &&\text{in}\ \Omega, + \\ + \Psi &= 0 &&\text{on}\ \partial\Omega. +@f} +As a consequence of this eigenvalue problem, this particle can only exist in a +certain number of eigenstates that correspond to the energy eigenvalues +$\varepsilon_\ell$ admitted as solutions of this equation, and if a particle has +energy $\varepsilon_\ell$ then the probability of finding it at location $\mathbf +x$ is proportional to $|\Psi_\ell(\mathbf x)|^2$ where $\Psi_\ell$ is the +eigenfunction that corresponds to this eigenvalue. + +In order to numerically find solutions to this equation, i.e. a set of pairs +of eigenvalue/eigenfunction, we use the usual finite element approach of +multiplying the equation from the left with testfunctions, integrating by +parts, and searching for solutions in finite dimensional spaces by +approximating $\Psi(\mathbf x)\approx\Psi_h(\mathbf x)=\sum_{j}\phi_j(\mathbf +x)\tilde\psi_j$, where $\tilde\psi$ is a vector of expansion coefficients. We +then immediately arrive at the following equation that discretizes the +continuous eigenvalue problem: @f[ - \psi_i = \sum_j \phi_j \tilde{\psi}_j \quad. + \sum_j [(\nabla\phi_i, \nabla\phi_j)+(V(\mathbf x)\phi_i,\phi_j)] + \tilde{\psi}_j = + \varepsilon_h \sum_j (\phi_i, \phi_j) \tilde{\psi}_j. @f] -It can easily be shown that the consequence of this, is that we want -to solve the generalized eigenvalue problem +In matrix and vector notation, this equation then reads: @f[ - A \tilde{\Phi} = \varepsilon M \tilde{\Phi} \quad, + A \tilde{\Psi} = \varepsilon_h M \tilde{\Psi} \quad, @f] -where $A$ si the stiffness matrix arising from the differential +where $A$ is the stiffness matrix arising from the differential operator $L$, and $M$ is the mass matrix. The solution to the -eigenvalue problem is an eigenspectrum $\varepsilon_j$, with -associated eigenfunctions $\tilde{\Phi}=\sum_j \tilde{\phi}_j$. +eigenvalue problem is an eigenspectrum $\varepsilon_{h,\ell}$, with +associated eigenfunctions $\tilde{\Psi}_\ell=\sum_j \phi_j\tilde{\psi}_j$. -To solve an actual physical problem we next define the differential -operator $L$ in a way that mimicks the wave-equation of Schr\"odinger: -@f[ - L({\mathbf x}) = K({\mathbf x}) - + V({\mathbf x})\quad, -@f] -and let $K({\mathbf x}) = \partial^2_{\mathbf x}$, and -@f[ - V({\mathbf x}) = \quad, -@f] +It is this form of the eigenvalue problem that involves both matrices $A$ and +$M$ that we will solve in the current tutorial program. We will want to solve +it for the lowermost few eigenvalue/eigenfunction pairs. -In the parlance of Schroedinger eigenvalue problems, the solutions -sought are the wavefunctions $\phi_j$. In finite elements the -solutions are $\tilde{\phi}_j$, known as a reduced (or tilde-basis) -wavefunctions.

Implementation details

diff --git a/deal.II/examples/step-36/doc/results.dox b/deal.II/examples/step-36/doc/results.dox index 347bc65158..60bc483cce 100644 --- a/deal.II/examples/step-36/doc/results.dox +++ b/deal.II/examples/step-36/doc/results.dox @@ -1,19 +1,173 @@

Results

-

Possibilities for extensions

+

Running the problem

+ +The problem's input is parameterized by an input file step-36.prm +which could, for example, contain the following text: + +@code +set Global mesh refinement steps = 5 +set Number of eigenvalues/eigenfunctions = 5 +set Potential = 0 +@endcode + +Here, the potential is zero inside the domain, and we know that the +eigenvalues are given by $\lambda_{(mn)}=\frac{\pi}{4}(m^2+n^2)$ where +$m,n\in{\mathbb N^+}$. Eigenfunctions are sines and cosines with $m$ and $n$ +periods in $x$ and $y$ directions. This matches the output our program +generates: +@code +examples/step-36> make run +============================ Running step-36 + Number of active cells: 1024 + Number of degrees of freedom: 1089 + + Eigenvalue 0 : 4.93877 + Eigenvalue 1 : 12.3707 + Eigenvalue 2 : 12.3707 + Eigenvalue 3 : 19.8027 + Eigenvalue 4 : 24.837 + +Job done. +@endcode +These eigenvalues are exactly the ones that correspond to pairs $(m,n)=(1,1)$, +$(1,2)$ and $(2,1)$, $(2,2)$, and $(3,1)$. A visualization of the +corresponding eigenfunctions would look like this: + + + + + + + + + + + + + + + + +
+ @image html step-36.default.eigenfunction.0.png + + @image html step-36.default.eigenfunction.1.png +
+ @image html step-36.default.eigenfunction.2.png + + @image html step-36.default.eigenfunction.3.png +
+ @image html step-36.default.eigenfunction.4.png + +
+ + + +

Possibilities for extensions

It is always worth playing a few games in the playground! So here goes with a few suggestions: