OOPDE — An object oriented approach to finite elements inMATLAB

Quickstart Guide

Uwe Prüfert∗

August 2014

Abstract

OOPDE (Object Oriented PDEtoolkit) is a collection of classes for solving (systems of) partial differentialequations (PDE) This quickstart guide provides a step-by-step introduction into the use of this toolkit and thephilosophy behind this software. A brief introduction into the finite element method (FEM) is also included. Themain part is a collection of examples for scalar PDE problems as well as examples for systems of PDEs, bothlinear and non-linear. Finally, a detailed description of the application programmers interface (API) of the toplevel classes is given.

Contents1 Introduction 1

2 Finite-Elements in a Nutshell 3

3 Excursion. Definition of the boundary conditions 4

4 Examples 64.1 Single PDEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.1.1 A heat transfer problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2 Burger’s equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.1.3 A parabolic PDE with time dependent data . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.2 Systems of PDEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2.1 An optimal control problem without inequality constraints . . . . . . . . . . . . . . . . . 124.2.2 Reacting Flow — A system of PDEs with non linear coupling . . . . . . . . . . . . . . . 144.2.3 KKT system for a problem with control constraints . . . . . . . . . . . . . . . . . . . . . 19

4.3 Derive geometry classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.3.1 Adapted L-shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5 Class reference 275.1 class pde . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.2 class lagrange1XD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.3 Common methods for all gridxD classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.4 grid1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315.5 grid2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.6 grid3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33∗Technische Universität Bergakademie Freiberg, Institute for Numerical Analysis and Control, Freiberg, Germany

1 IntroductionThe idea behind OOPDE was to extend MATLABs old PDE toolbox. The users—intentionally undergraduatestudents—should be able to solve simple PDE and PDE constrained optimal control problems without a deeperknowledge in FEM or advanced programming in MATLAB. However, a welcome add-on should be the possibilityto solve 1D problems (rather trivial) with the same syntax as the 2D PDE toolbox as well as to solve also problemswith convection term, what is not implemented in the PDE toolbox at all.

Since R2010b, Matlab offers a “new” syntax to write object oriented code. This re-implementation of OOP inMATLAB provides now the possibility to write clean, robust and readable code in a C++ like syntax.

To add one-and-one, it is obviously a good idea to combine both and write a system of classes, that providesan user-friendly, open, readable, powerful MATLAB code, that helps students to solve PDE problems and e.g.optimality systems of PDE constraint optimal control problems.

Solving PDE problems numerically has a typical work flow:

(i) define the domain,

(ii) define the boundary conditions,

(iii) choose suitable finite elements,

(iv) define the PDE problem,

(v) solve the linear system and

(vi) post process the solution.

Now, the idea is to define classes for the domain, the finite element method and the PDE that provides all methodsneeded to solve the problem, and to post process the data etc., but also to hide them from the common user.

As an example we solve the simple Heat transfer problem

−∆u+u = 10 (1)

on Ω = (0,1)2 and with the Dirichlet boundary condition

u = 0

on the boundary ∂Ω. We set the dimension of the problem to 2d and define — only for simplicity — Ω as the unitsquare. Using OOPDE, the following code solves the problem.

First we define a user class that defines the problem.

1 classdef heatTransfer < pde2 methods(Access = protected)3 function dy = df(obj ,~,y)4 l = obj.fem.stiffSpring(obj.K+obj.M);5 dy = -(obj.K+obj.M+...6 l*(obj.H'*obj.H))*y + ...7 obj.F+l*(obj.H'*obj.R);8 end9 end

10 end

User of the pde-toolbox (and femlab, or early comsol multiphisics user) may understand this code immediately,but for all others we will explain it in detail.

line meaning

1 The class heatTransfer is derived from the OOPDE class pde. The pde class will give us all methodsneeded to solve the problem.

2 We declare the methods as “protected”. This is claimed by the OOPDE class pde.

3–7 We define the method df, the RHS of the PDE. OOPDE prefers the form

0 = f (y,x)

1

for stationary problems orddt

y = f (y, t,x)

for transient problems. obj.K, obj.M, obj.H, obj.F and obj.R are the matrices resp. vectors related tothe finite elements method. Here K is the stiffness matrix, M is the mass matrix, F is the source vectorand Q,H,G and R are the discrete counterparts to the boundary integrals in the weak formulation ofthe PDE.

7–8 The number l is the “stiff spring” coefficient to model Dirichlet-Boundary conditions.

That is all user code we have to write for this example. The following “main program” uses exclusively methodsprovided by OOPDE:

1 pde = heatTransfer ();23 pde.fem = lagrange12D ();45 pde.grid = grid2D ();6 pde.grid.unitSquare (0.05)7 pde.grid.refineMesh ();89 pde.grid.makeBoundaryMatrix(pde.grid.dirichletBC('0'));

1011 pde.initialize (1 ,[0;0] ,1 ,10);1213 pde.solve('LINEAR ')14 pde.grid.plot(pde.y)

Again, we comment the code line by line:

line Meaning

1 Declare pde as from class heatTransfer. Note that we have now in MATLAB a variable declaration!

3 Declare pde.fem as lagrange12D. This is point (iii) in our agenda.

5 Declare pde.grid a grid2D. grid2D is also a class provided by OOPDE. This is together with line 6 and7 point (i) in the agenda.

6 Mesh the units-square with meshsize 0.05.

7 Refine the mesh uniformly.

9 Create the dirichlet boundary conditions. The units-square has four boundary, we can define it onesfor all or separately. This is point (iii) in our agenda.

11 Call pde.initialize. Here OOPDE computes all necessary matrices. Note that this is the full parametercall, in our example we have no convection term such that we must set b as zero. The matrices usedin the df-method are computed here. obj.K etc. are properties of the class pde.

13 Solve the problem using the “LINEAR” option. This is point (v) in the agenda, while point (iv) isdone defining the class from Listing 1.

14 Plot the solution. Item (vi) on our agenda.

In contrast to most MATLAB PDE software, e.g. the MATLAB pde toolbox, in OOPDE there is no pre-definedPDE problem where the user has only provide some coefficients. The definition of the PDE itself lays in the handof the user. It must be done coding a user class derived from the OOPDE class pde, cf. the listing above. This is acompromise between flexibility with respect the problem class that can be solved and an user friendly coding.

Note that in further section of these guide we will improve the heatTransfer class also by changing the interfaceof the initialize method by overwriting it.

If the user keeps in mind some basic rules, OOPDE offers him the opportunity to use this “tool box” to solve awide variety of PDE problems like convection-diffusion problems, coupled systems of PDEs, vector-valued PDEs,and much more.

2

As you can see in Listing of the driver script, the pde class method initialize computes without any additionaluser input the matrices needed to solve simple problems involving mass, stiffness, and convection matrices, aswell as Dirichlet and Neumann boundary conditions matrices. With this at hand, the user can solve problems likeBurger’s equation out of the box.

However, we have a general rule: “The more individual the problem, the deeper you must understand thesoftware”

In summary, OOPDE provides

a) a unique interface for 1D, 2D, 3D PDE problems

b) Lagrange elements of order one for dimension 1–3. This can be easily extended by the user sinceOOPDE offers an open interface for that purpose.

c) a wide variety to define PDE coefficients, scalar, matrices, functions, etc.

d) a user friendly interface to boundary conditions.

e) a geometry based definition of boundary segments.

In this mini tutorial we will show all this properties in some examples. For a deeper insight in the philosophybehind OOPDE we refer the OOPDE users guide and the OOPDE class reference.

2 Finite-Elements in a NutshellLet be Ω ⊂ Rn, n = 1,2,3, open and let be Γ the boundary of Ω. We consider the partial differential equation(PDE)

dddt

u−∇(c∇u)+~b∇u+au = f in Ω (2)

~n(c∇u)+qu = g on Γ, (3)u = u0 in Ω (4)

where c is a positive definite matrix c : Ω→ Rn,n. Note that for n = 1 the ∇-operator means ddx and all coefficients

a scalar functions. ~n · (c∇u) means the outward normal derivative. By bold letters we denote here the data. Alldata can depend on the spatial variable x and—if applicable—on the time t. Note that by this dependencies thecharacter of this equation can change by time. Data can be identical zero, e.g. with c = a≡ 0, (3) is a hyperbolicequation, and by d = 0 we have a elliptic type equation.

By multiplying (2) with a test function v ∈ H1(Ω) :=V and using Green’s formula we obtain the week formu-lation

Ω

dddt

uvdx +

Ω

c∇u∇vdx +

Ω

~b∇uvdx +

Ω

auvdx −

Γ

~nc∇vds =

Ω

fvdx ∀v ∈ V.

Now we can replace the integrand within the boundary integral by the Robin boundary condition (3), i.e.

−

Γ

~n(c∇u)vds =

Γ

(qu−g)vds.

We can write (2) as

Ω

dddt

uvdx +

Ω

c∇u∇vdx +

Ω

~b∇uvdx +

Ω

auvdx +

Γ

quvds =

Ω

fvdx +

Γ

gvds ∀v ∈ V. (5)

while in the case of time dependent problems, i.e. d 6= 0 we additional have u(0) = u0. Next, we replace V by afinite dimensional subspace, Vh ⊂V and consider uh = ∑uiφi, and vh = ∑viφi where the φi are the basis functionsof Vh. The idea is that instead of testing with all v ∈ Vh it is sufficiently to test only with all basis functions of Vh.We choose now φ i such that φi ∈ H1(Ω∆), where Ω∆ are an approximation of Ω by – depending on the dimensionof Ω – intervals, triangles or tetrahedrons. The simplest member of this class of function are piecewise linear, theso called hat-functions. Actually, in three dimensional space it is hard to imagine how they look like. Equation (5)becomes

Ω∆

d(x)ddt ∑u jφ j(x)∑φi(x)dx+

Ω∆

c(x)∇∑u jφ j(x)∇∑φi(x)dx+

Ω∆

~b(x)∇∑u jφ j(x)∑φi(x)dx

+

Ω∆

a(x)∑u jφ j(x)∑φi(x)dx+

Γ∆

q(x)∑u jφ j(x)∑φi(x)ds =

Ω∆

f(x)∑φi(x)dx+

Γ∆

g(x)∑φi(x)ds,

3

i, j = 1, ...,nx, where we assume that all coefficient functions are from L∞(Ω) or L∞(Γ) and can be approximatedby piecewise constant functions on the interior of every single element of Ω∆. Note that e.g. a = a(x) = a(u(x)) isalso covered by this approach. After the evaluation of all integrals we finally obtain the possibly non-linear system

Dddt~u+(K +M+C+Q)~u = (F +G),

with~u = ui, i = 1, ...,np. The matrices and vectors are in detail

Di, j =

Ω∆

d(t,x)φ j(x)φi(x)dx

Ki, j =

Ω∆

c(t,x)∇φ j(x)∇φi(x)dx

Ci, j =

Ω∆

~b(t,x)∇φ j(x)φi(x)dx

Mi, j =

Ω∆

a(t,x)φ j(x)φi(x)dx

Qi, j =

Γ∆

q(t,x)φ j(x)φi(x)ds

Fi =

Ω∆

f(t,x)φi(x)dx

Gi =

Γ∆

g(t,x)φi(x)ds

for i, j = 1, ...,np. Obviously, this holds for Ω∆ ⊂Rn and Γ∆ ⊂Rn−1 with n = 1,2,3. Note that for time dependentdata the related matrices and vectors depend from the time, hence they must be updated in every time step of thetime integration. Similar, for non-linear problems at least on matrix or vectors depends from the solution u and itmust be updated within the solution process, e.g. within a Newton iteration.

Since Ω∆ consists on a finite number of elements we can write the definitions above also as a sum of integralsover the single elements (Ω∆)l , where l = 1, ...,ne. The matrix H and the vector R coming not from the integral but

they define point-wise the Dirichlet boundary conditions, i.e. for H we have H ji =

hi if xi is a Dirichlet point0 otherwise

,

where i = 1, ...,np and j = 1, ...,ne. The vector R is defined analogously.The relation between the coefficients names and the associated matrices may on a first view to be not straight-

forward. While the coefficients d, f, q, g, h and r belong to its matrix and vector capital counterparts, the coefficientc belongs to the Stiffness matrix K, the coefficient a belongs to the Mass matrix M and the coefficient~b belongsto the convection matrix C. The naming in the analytical formulation of our general PDE problem follows theLiterature, e.g. the pdetool user guide. The naming of the matrices is common in textbooks, except C and F whatis named after “convection” and “force”.

3 Excursion. Definition of the boundary conditionsThe method makeBoundaryMatrix

makeBoundaryMatrix from class gridd creates the boundary condition matrix. This matrix cannot beused to involve boundary conditions not can be used to compute boundary conditions directly. It stores only theinformation which boundary conditions is defined for the associated boundary segments. Note that the number ofboundary segments is a property of the geometry respectively of the grid object, that can be changes by the user.

The matrices Q, H and the vectors R, G will be computed by the method assemb from class fem, eventuallyencapsulated in the initialize method from class pde.

How to “read” the boundary condition matrix

Since OOPDE uses some conventions of Matlab’s PDE toolbox pdetool, we cite the manual of pdetool:

“The format of each column is according to the following list:

– Row one contains the dimension N of the system.

4

– Row two contains the number M of Dirichlet boundary conditions.

– Row three to 3+N2−1 contain the lengths for the strings representing q. The lengths are storedin column-wise order with respect to q.

– Row 3+N2 to 3+N2 +N−1 contain the lengths for the strings representing g.

– Row to 3+N2 +N to 3+N2 +N +MN− 1 contain the lengths for the strings representing h.The lengths are stored in column-wise order with respect to h.

– Row 3+N2 +N +NM to 3+N2 +N +MN +M− 1 contain the lengths for the strings repre-senting r.

The following rows contain text expressions representing the actual boundary condition functions.The text strings have the lengths according to above. The MATLAB text expressions are stored incolumn-wise order with respect to h q. There are no separation characters between the strings.” [1]

Example. The boundary condition matrix

b=1 1 1 10 0 0 01 1 1 16 6 6 6

48 48 48 48115 115 115 115105 105 105 105110 110 110 11040 40 40 40

115 115 115 11541 41 41 41

codes the Neumann type boundary condition ~n · (c∇u) = sin(s), i.e. q = 0 and g = sin(s) where the domain hasfour boundary segments. W give a detailed explanation for this example:

– first line: scalar problem, u itself is not a vector. Not relevant in OOPDE, only for compatibility.

– second line: it is not a Dirichlet boundary condition, hence it must be Robin boundary condition.

– third line: the length of the entry for q is one

– fourth line: the length of g is six.

– fifth line is q. We have “48”. It is the code number in ASCII code. Applying char returns

char(48)0

– The next six lines representing g. Applying the function char we get

char([115 105 110 40 115 41])sin(s)

However, despite the fact that Dirichlet-boundary conditions can be approximated by Robin boundary condition ,Matlab’s PDE toolbox can also define Dirichlet boundary conditions hu= r directly. In this case we have the matrixH ′H for the left hand side and on the right hand side the vector H ′R. This formulation is caused by the definitionof Dirichlet boundary conditions as constraints of the PDE, the term H>H and H>R come from the derivative ofthis constraint. The somehow unnatural looking splittings H>H and H>R —this is only a fix matrix and vectorthat could be stored as one—can be use for rapid updating the boundary conditions in the time dependent andnon-linear cases. We demonstrate this in the examples section.

5

4 Examples

4.1 Single PDEs4.1.1 A heat transfer problem

We solve the PDE, a stationary heat transfer problem with constant source,

−∇(c∇u)+u = 10 in Ω

u = 0 on ∂Ω

where the coefficient c is a real number, e.g. here chosen c = 0.1 and the domain Ω is an L-shaped subset of R2.First we (re) define the user class heatTransfer.

1 classdef heatTransfer < pde2 methods(Access = protected)3 function dy = df(obj ,~,y)4 dy = obj.A*y + obj.b;5 end6 function J = jacobian(obj ,~,~)7 J = obj.A;8 end9 end

10 methods(Access = public)11 function initialize(obj ,c,a,f)12 b = zeros(size(obj.grid.p,1) ,1);13 initialize@pde(obj ,1,c,b,a,f);14 l = obj.fem.stiffSpring(obj.K+obj.M)15 obj.A = -(obj.K+obj.M+l*(obj.H'*obj.H)+obj.Q);16 obj.b = obj.F+l*(obj.H'*obj.R)+obj.G;17 end18 end19 end

We explain the code line by line

Line Meaning

1 derive class heatTransfer from OOPDEs class pde

2 declare a methods-block with access protected. This is a demand from pde. A different declarationwill give errors.

3 define the method df. This is the PDE. The interface must be (object,time,solution). Here, the time isnot involved, so we can use the placeholder ~. We define the linear PDE problem abstract as Ay+b.The meaning of A and b will be given in initialize.

6 overwrite the method jacobian. This is optional. If no jacobian method is defined here, the jacobianmethod of the parent class pde is use. There, the Jacobian matrix will be computed numerically. It isalways a good idea to provide the Jacobian if it is known. Here, jacobian is simply A.

10 declare a public method block

11 overwrite the parents class initialize. To simplify the interface, we define it as obj,c,a,f and drop thecoefficient b, cf. the empty vector in Listing ??. (Our heat transfer problem knows no convectionterm)

12 We do not have convection in our problem. By defining a vector 0 ∈ RN we have for every dimensionthe “right” form of b.

6

13 Assemble all matrices by calling the initialize method from pde class. This is an abstract call. Notethe special syntax. The arguments are simply the coefficients d, c,b,a,f of the pde

d∂u∂ t−∇(c∇u)+~b∇u+au = f

where we set b = 0 in Line 14. We assume that our heat transfer problem is normalized, i.e. d = 1.

14 Compute the stiff-spring coefficient for the Dirichlet boundary conditions.

15 Define the property A, linear system matrix. We add simply stiff matrix K, mass matrix M and theboundary condition matrices Q and l ∗H ′ ∗H.

16 Define the vector part of the linear system. Source term F and the boundary condition vectors G andthe stiff spring coefficient appears here.

Note that this class works for every spatial dimension. The real form of boundary conditions is in this code notknown.

The driver code is a Matlab function

1 function testHeat2D ()2 pde = heatTransfer ();3 pde.grid = grid2D ();4 pde.fem = lagrange12D ();56 pde.grid.lshape;7 pde.grid.refineUniformly (4);89 pde.grid.makeBoundaryMatrix(pde.grid.dirichletBC('1','0'));

10 pde.initialize (1,1,10);1112 pde.solve('LINEAR ');1314 figure ()15 pde.grid.plot(pde.y);16 end

We comment Example 1 line by line

Line Meaning

1 Define the “main” function testHeat2D.

2 Declare the problem. initialize a heatTransfer object named pde.

3 Declare pde.grid as 2-D grid by calling grid2D. grid2D is the triangle mesh class.

4 Declare the FEM. Here we need lagrange12D.

6 Call lshape method of class grid2D. It creates (without arguments) a mesh with only six elements.

7 Refine the mesh four times uniformly.

9 Create the boundary condition by a encapsulated call of makeBoundaryMatrix and dirichletBC. Thearguments of dirichletBC are the coefficents h and r in

hu = r

With one argument, makeBoundaryMatrix assumed that on every boundary segment (actually the L-shape geometry has six) holds the same boundary condition.

11 Call initialize with the coefficients c = 1, a = 1, and f = 10.

13 Call the linear solver.

15 Open a figure

7

16 Use method plot from class grid2D. The argument mus be a vector of dimension np× 1, here thesolution stored in pde.y.

Figure 1: Solution of the heat transfer problem

4.1.2 Burger’s equation

We consider Burger’s equation

ut −κuxx +12(u2)x = 0

u = 0u(0) = u0

where Ω⊂ R.The definition of the class burgers is rather simple. We overwrite initialize and define the non linearity as a

method of the class burgers. Because of the homogeneous source and boundary conditions of Burger’s equation inour example, we have no RHS vector at all.

1 classdef burgers < pde2 methods(Access=protected)3 function dy = df(obj ,~,y)4 dy = obj.A*y+obj.nonLin(y);5 end6 end7 methods(Access=public)8 function initialize(obj ,c)9 initialize@pde(obj ,1,c,1,0,0);

10 l = obj.fem.stiffSpring(obj.K)11 obj.A = -(obj.K+l*(obj.H'*obj.H));12 end13 end14 methods(Access=private)15 function y = nonLin(obj ,y)16 y = -0.5*obj.C*(y.*y);17 end18 end19 end

We analyze the code line by line

Line Meaning

1 Derive class burgers from pde parent class.

8

2 Declare a protected methods block

3 Overwrite method df. Abstract definition as linear part plus non linear part.

7 Declare a public methods block

8 Overwrite the initialize method. The only needed parameter is the diffusivity κ , here named by c.

9 Compute all matrices by calling pde.initialize with the argument list of the overwritten method.

10 Define property A. We do not need property b nor any vector because of the homogeneity of ourproblem with respect the to the source and the boundary condition.

13 Declare a private methods block

14 Define the method nonLin. It computes the non linear part

12(u2)x

Note, that we do not overwrite jacobian. OOPDES solver use jacobian from pde class.In the following, we give the main program as a MATLAB function.

1 function testBurgersClass2 pde = burgers ();3 pde.fem = lagrange11D;4 pde.grid = grid1D ();5 pde.grid.interval ([0,pi] ,0.01);6 pde.grid.makeBoundaryMatrix(...7 pde.grid.dirichletBC('1','0'));8 pde.y = sin(2*pde.grid.p(1,:));9 pde.initialize (0.01);

10 pde.time = linspace (0,5,200);11 pde.solve('ODE15S ')12 surf(pde.grid.p,pde.time ,pde.y')13 end

We comment the code line by line

Line Meaning

1 Define the main function testBurgers

2 Declare pde as object of burgers class

3 Declare pde.fem as lagrange11D object. This is the class that implements 1D first order Lagrangeelements.

4 Declare pde.grid

5 Define an interval (0,π) with mesh-width h = 0.01.

6–7 As in the Example 1, we define homogenous Dirichlet boundary conditions.

8 We initialize y(0) = sin(2πx). grid.p contains the coordinates of the mesh points. To be sure that weget the x-values, we should use the first row, because p contains more information as the number ofsub domains of Ω.

9 We call the overwritten initialize with c = 0.01.

10 Define the time to solve.

11 Solve the problem by using pde class’ solve with option ODE15S which calls the ode15s time inte-grator from MATLABs ode suite.

12 We visualize the solution by calling the surf function from MATLAB.

9

0

1

2

3

4 0

2

4

6−1

−0.5

0

0.5

1

Figure 2: Solution of Burger’s equation

4.1.3 A parabolic PDE with time dependent data

This example shows how to incorporate time dependent boundary conditions and time and space dependentsources.

We choose Ω = (0,2π), and our PDE should be

d∂

∂ tu− cuxx +bux +au = f (t,x)

ux(t,0) = 0u(t,2π) = r(t)

u(0,x) = u0

The difficulty here is to write a code that handles the time dependent sources efficiently. Obviously, in thisexample only the RHS of the PDE and the RHS of the Dirichlet boundary condition dependent on time. Hence, wemust update the vectors F and R in every time step. This may lead to a code where assemble methods were calledwithin the df method. This is a correct but not really efficient way to obtain the update of the vectors.

Since R is not an integral, we can write it as R(t) = (H>H) ∗ r(t), where r(t) must be a vector of length ofnumber of mesh points. The vector F contains values of an integral but also we can compute it by F = M ∗ f (t,x).From that we can prepare the matrices H>H and M in the offline phase of our solver, i.e. in initialize and only therather inexpensive matrix times vector operation must be performed online. We introduce for new properties: HHand MM to store the matrices needed for fast RHS update and r and f to store function handles that implementsthe time dependent functions r(t) and f(t). Note that obj.r(t,obj.grid.p(1,:)) and obj.f(t,obj.grid.p(1,:)) evaluatefunctions where the time is determined in general by the ode solver. The code of the class definition is surprisinglyshort. In initialize, we only add the definition of HH and MM. Note that the time dependent Dirichlet part will beadded in df.

classdef convectionDiffusionTimedepBC < pdeproperties(Access=private)

HHMM

end

properties(Access=public)rf

end

methods(Access = protected)function dy = df(obj ,t,y)

dy = obj.A*y + obj.b +...obj.HH*obj.r(t,obj.grid.p(1,:))...+ obj.MM*obj.f(t,obj.grid.p(1,:));

10

end

function J = jacobian(obj ,~,~)J = obj.A;

endend

methods(Access = public)function initialize(obj ,d,c,b,a,f)

initialize@pde(obj ,d,c,b,a,f);l = obj.fem.stiffSpring(obj.K+obj.M+obj.C);obj.A = -(obj.K+obj.M+obj.C+l*(obj.H'*obj.H)+obj.Q);obj.b = obj.G + obj.F;obj.MM = obj.mass;obj.HH = l*obj.H';

endend

end

Important note: In two or three dimensional domains the dependence between spatial variable and time maybe more complex. This offline computing technique works only if we have f (t,x) = f1(t) ∗ f2(x) and r(t,x) =r1(t)∗ r2(x) . If we cannot split f and r in this way, we must assemble the RHS vectors within df method.

We test the code by the following example

∂

∂ tu− cuxx +bux = f (t,x)

ux(t,0) = 0u(t,2π) = r(t)

u(0,x) = u0

with

f (t,x) = 2e−t sin(x)

u0(x) =

sin(t) x < π

0 otherwise

r(t) = sin(t)

and κ = 1, b =−1. the time let be [0,30]The driver program is given as follows:

function testParabolicTimedependentBCspde = convectionDiffusionTimedepBC ();pde.grid = grid1D ();pde.grid.interval ([0,2*pi] ,0.05);pde.fem = lagrange11D;

pde.grid.makeBoundaryMatrix(...pde.grid.neumannBC('0'),...pde.grid.dirichletBC('1'));

pde.initialize (1,1,-1,0,0)

pde.r = @r;pde.f = @f;

pde.time = [0:0.5:30];pde.y = y0(pde.grid.p(1,:));

11

pde.solve('ODE15S ')

figure (1)surf(pde.grid.p(1,:),pde.time ,pde.y',...

'EdgeColor ','None','FaceColor ','Interp ');axis equal

end

% local functionsfunction y = r(t,x)

y = sin(t)*ones(size(x));y = y(:);

endfunction y = f(t,x)

y = 2*exp(-t)*sin(x);y = y(:);

endfunction y = y0(x)

y = zeros(size(x));y(x<=pi) = sin(x(x<=pi));y = y(:);

end

Figure 3: Solution of the transient PDE problem with time dependent sources.

4.2 Systems of PDEs4.2.1 An optimal control problem without inequality constraints

Our first example is the optimal control problem

min12‖y− yd‖2

L2(Ω)+κ

2‖u‖2

L2(Ω)

subject to

−∆y+ y = u in Ω

y = 0 on Γ

12

where yd is the desired state. The function uis here called the control. This problem has a unique solution u. Itsfulfills together with the associated state y and the so called adjoint state p the system of coupled linear PDEs

−∆y+ y− u = 0 in Ω

y = 0 on Γ

κ u+ p = 0 in Ω

−∆ p+ p− y = −yd in Ω

p = 0 on Γ

These are the Karush-Kuhn-Tucker (KKT) conditions.We define a class kkt for defining this system. Again, we derive our class from pde.The linear system will be stored in the property obj.A. The method kkt.df will be the same as for the scalar

linear PDE 4.1.1The definition of the system will be done in kkt.initialize. The state equation y as well as the adjoint equation

for p are up to the source term the identical. Hence we need to compute the matrices K and M only once. Sincewe fix our problem to homogeneous Dirichlet boundary conditions, we can implement the boundary conditionsdirectly in initialize. The linear system is now a one-to-one implementation of the KKT system. Note that we needhere some zero matrices to fill the matrix A with zero blocks and the RHS with zero vectors, respectively. Notefurther that since we do not use here initialize@pde, we need to set obj.initialized = true manually.

1 classdef kkt < pde2 methods (Access = protected)3 function dy = df(obj ,~,y)4 dy = obj.A*y+obj.b;5 end6 function J = jacobian(obj ,~,~)7 J = obj.A;8 end9 end

10 methods(Access = public)11 function initialize(obj ,kappa ,y_d)12 bcState = obj.grid.dirichletBC('1','0.0');13 obj.grid.makeBoundaryMatrix(bcState);14 [~,~,H,~] = obj.fem.assemb(obj.grid);15 [K,M,Fp] = obj.fem.assema(obj.grid ,1,1,...16 -obj.grid.point2Center(y_d));17 l = obj.fem.stiffSpring(K+M);18 N = sparse(obj.grid.nPoints ,obj.grid.nPoints);19 n = sparse(obj.grid.nPoints ,1);2021 obj.A = [-obj.mass N K+M+l*(H'*H);...22 N -kappa*obj.mass -obj.mass;...23 K+M+l*(H'*H) -obj.mass N];2425 obj.b = -[Fp;...26 n;...27 n];2829 obj.y = zeros(obj.grid.nPoints *3,1);30 obj.initialized = true;31 end3233 function plot(obj)34 for k = 1:335 subplot(2,2,k)36 obj.grid.plot(...37 obj.y((k-1)*obj.grid.nPoints +1...38 :k*obj.grid.nPoints ,end));39 view (32 ,80)

13

40 end41 end42 end43 end

To test our class we use the following small program. To obtain a desired function yd with a known control,we solve first a PDE problem with known source. The solution of our optimal control problem should convergefor λ → 0 towards the given source in L2. We cannot expect that we reach the desired state for λ > 0. That is theprice we pay for regularization.

1 function testKKT2 pde = heatTransfer ();3 pde.grid = grid2D ();4 pde.fem = lagrange12D ();56 pde.grid.freeGeometry ([0 0.5 1 1 0.5 0.5 0 0;0 0 0 0.5 0.5 1 1

0.5])7 pde.grid.refineUniformly (3);8 pde.grid.makeBoundaryMatrix(pde.grid.dirichletBC('1','0'));9

10 pde.initialize (1,1,@ source);11 pde.solve('LINEAR ');1213 figure (1)14 clf15 pde.grid.plot(pde.y);1617 kktSystem = kkt();18 kktSystem.grid = pde.grid;19 kktSystem.fem = pde.fem;20 n = zeros(size(pde.y));21 kktSystem.initialize (1e-5,pde.y);22 kktSystem.solve('LINEAR ');23 figure (2)24 clf25 kktSystem.plot262728 function f = source(x,y)29 f = zeros(size(x));30 f(x >0.5) =10;31 f(y >0.5) =10;32 end33 end

4.2.2 Reacting Flow — A system of PDEs with non linear coupling

We take this example from the paper MARCELO BUFFONI and KAREN WILLCOX, Projection-based model reduc-tion for reacting flows. [2].

The flow field is given as constant. The domain is given by Ω = [0,0.9]× [0,1.8] cm. Let be given the chemicalreaction

ν f uelYf uel +νoxidYoxid → νprodYprod

where Yf uel , Yoxid , and Yprod are the mass fractions of the fuel, the oxidizer and the product respectively, andν f uel ,νoxid ,and ν f uel are their related stoichiometric coefficients. The nonlinear reaction source term is of Arrheniustype, i.e. we have

ωi =−νi

((wi)i

ρ

)(ρYf uel

w f uel

)ν f uel(

ρYoxid

woxid

)νoxid

Ae(−E

RT ), i = f uel,oxid, prod.

14

Here A is the pre-exponential factor, wi is the molecular weight for i = f uel,oxid, prod, E is the activation energyand R the universal gas constant, T the temperature. For the temperature we have the source

wT = wprodQ,

where Q is the reaction heat.We consider a system of three chemical species and temperature. The system looks like

∂

∂ tYf uel = −c∆Yf uel +~b∇Yf uel +ω f uel(Yf uel ,Yoxid ,T ) in Ω

∂

∂ tYoxid = −c∆Yoxid +~b∇Yoxid +ωoxid(Yf uel ,Yoxid ,T ) in Ω

∂

∂ tYprod = −c∆Yprod +~b∇Yprod +ωprod(Yf uel ,Yoxid ,T ) in Ω

∂

∂ tT = −c∆T +~b∇T +ρ

∂

∂ tYprod in Ω

~nc∇Yf uel,oxid,prod = 0 on Γ f ree

~nc∇T = 0 on Γ f ree

Yf uel,oxid = Y inf uel,oxid in Γinlet

Yprod = 0 on Γinlet

T = T in on Γinlet

Yf uel,oxid,prod(t0) = Y 0f uel,oxid,prod in Ω

This will be the first example with a complex class definition file. However, the methods df and jacobianare standard except the use of obj.D as mass to integrate the chemical source term obj.w. The chemical sourceterm implements here the (global) reaction 2H2 +O2 → 2H2O. For that reaction, we have ν f uel = 2 νoxid = 1,νprod = −2, A = 5.5 · 1011, E = 4500 ,w f uel = 2.016, woxid = 31.9 and wprod = 18.0 gr/mol. The gas constant isR = 8.314472J/mol/K, the density ρ = 1.39 · 10−3gr/cm3 and the heat Q = 9800K. The implementation of theArrhenius equation is done nearly one-to-one in the method w.

Most of the code is needed by the definition of the chemical source term and the definition of the boundaryconditions, since every species needs its own. It is easy to see that we need for the fuel, oxidizer and temperaturean intake while all other boundary conditions are homogenous Neumann.

The method initialGuess solves the linear part of the system i.e. convection and diffusion to obtain a goodchoice for an initial guess for the non linear solver.

1 classdef reactingFlow < pde2 methods(Access = protected)3 function val = df(obj ,~,y)4 val = obj.A*y+obj.D*obj.w(0,y) + obj.b;5 end67 function J = jacobian(obj , ~,y)8 J = obj.A+obj.D*obj.dw(0,y);9 end

10 end11 methods(Access = public)12 function initialize(obj ,c,b)13 bcTempInlet = obj.grid.boundaryCondition(...14 [],[],'1','min(950,max(300,sin(3*pi.*

s-pi)*3500))');15 bcTempOverall = obj.grid.boundaryCondition ([],[],'0','0')

;16 bcFuel = obj.grid.boundaryCondition(...17 [],[],'1','max(0,sin (3*pi.*s-pi)*0.2)

');18 bcOx = obj.grid.boundaryCondition(...19 [],[],'1','max(0,sin (3*pi.*s-pi)

*0.02) ');

15

20 bcProd = obj.grid.boundaryCondition ([],[],'1','0');21 bcNeuman = obj.grid.boundaryCondition('0','0');2223 obj.grid.makeBoundaryMatrix(bcNeuman ,bcNeuman ,bcNeuman ,

bcFuel);24 [~,~,H,RF] = obj.fem.assemb(obj.grid);2526 obj.grid.makeBoundaryMatrix(bcNeuman ,bcNeuman ,bcNeuman ,

bcOx);27 [~,~,~,RO] = obj.fem.assemb(obj.grid);28 obj.grid.makeBoundaryMatrix(bcNeuman ,bcNeuman ,bcNeuman ,

bcProd);29 [~,~,~,RP] = obj.fem.assemb(obj.grid);3031 obj.grid.makeBoundaryMatrix(bcTempOverall ,bcTempOverall ,

...32 bcTempOverall ,bcTempInlet);33 [~,~,~,RT] = obj.fem.assemb(obj.grid);3435 [K,~,~]= obj.fem.assema(obj.grid ,c,0,0);36 C = obj.fem.convection(obj.grid ,b);3738 M = obj.mass();39 N = sparse(obj.grid.nPoints ,obj.grid.nPoints);4041 obj.A = -[K+C+1e8*(H'*H) N N N;42 N K+C+1e8*(H'*H) N N;43 N N K+C+1e8*(H'*H) N;44 N N N K+C+1e8*(H'*H)];4546 obj.D = [ M N N N;47 N M N N;48 N N M N;49 N N N M];5051 obj.b = [1e8*H'*RT;52 1e8*H'*RF;53 1e8*H'*RO;54 1e8*H'*RP];5556 obj.initialized = true;57 end5859 function d = w(obj ,~,Y)60 A = 5.5 e11;61 E = 4.5e3;62 nu = [2 1 -2]';63 wc= [2.016 31.9 18.0] ';64 R = 8.314472;65 rho = 1.39e-3;66 Q = 9800;6768 np = obj.grid.nPoints;6970 scalar_rate =...71 (rho*Y(np +1:2* np)/wc(1)).^nu(1).*...72 (rho*Y(2*np +1:3* np)/wc(2)).^nu(2)...73 .*A.*exp(-E./(R.*Y(1:np)));

16

7475 dY = -1/rho*[wc(1)*nu(1)*scalar_rate;...76 wc(2)*nu(2)*scalar_rate;...77 wc(3)*nu(3)*scalar_rate ];7879 dT = dY(2*np +1:3*np)*Q;80 d = [dT;dY];81 end8283 function plot(obj)84 for k = 1:485 subplot(2,2,k)86 obj.grid.plot(obj.y((k-1)...87 *obj.grid.nPoints +1:k*obj.grid.nPoints ,end));88 view (0 ,90)89 end90 end9192 function initialGuess(obj)93 obj.y = -obj.A\obj.b;94 end95 end9697 methods(Access = private)98 function d = dw(obj ,~,Y)99 A = 5.5 e11;

100 E = 4.5e3;101 nu = [2 1 -2]';102 wc= [2.016 31.9 18.0] ';103 R = 8.314472;104 rho = 1.39e-3;105 Q = 9800;106 np = obj.grid.nPoints;107 d_rate = [...108 diag( (rho/wc(1)*Y(np+1:2* np)).^(nu(1)).*...109 (rho/wc(2)*Y(2*np+1:3* np)).^nu(2).*...110 (A*exp(-E./(R.*Y(1:np)))).*(E./R./(Y(1:np).^2))),

...111 diag( nu(1)*(rho/wc(1))*(rho*Y(np +1:2*np)/wc(1))

...112 .^(nu(1) -1).*...113 (rho*Y(2*np +1:3* np)/wc(2)).^nu(2).*...114 (A*exp(-E./(R.*Y(1:np))))),...115 diag( nu(2)*(rho/wc(2))*...116 (rho/wc(1)*Y(np+1:2* np)).^(nu

(1)).*...117 (rho/wc(2)*Y(2*np+1:3* np))...118 .^(nu(2) -1).*...119 (A*exp(-E./(R.*Y(1:np))))),...120 sparse(np,np)];121 d =-1/rho* [Q*wc(3)*nu(3)*d_rate ;wc(1)*nu(1)*d_rate ;...122 wc(2)*nu(2)*d_rate ;wc(3)*nu(3)*d_rate ];123 end124 end125 end

The main Program is now again rather short.

1 function testBuffoniWillcox2 pde = reactingFlow ();

17

3 pde.fem = lagrange12D ();4 pde.grid = grid2D ();5 pde.grid.square (0,1.8,0,0.9 ,1);6 pde.grid.refineUniformly (7);7 pde.initialize (2,[50,0]');8 pde.initialGuess;9 pde.solve('STATIONARY ');

10 pde.plot11 end

Line Meaning

1 Define a function testBuffoniWillcox

2 Declare pde as reactingFlow object

3 Declare pde.fem as lagrange12D object.

4 Declare pde.grid as grid2D object.

4 Create a square (0,1.8)× (0,0.9) with initial mesh size h = 1. We obtain a structured grid.

6 Call the method refineUniformly of grid2D class. The parameter is the number of iterations.

7 We call initialize from reactingFlow class with parameter c=1 and~b = [50,0]′. This is the constantflow field.

8 Call the initialGuess method from reactingFlow class. It computes a solution to the non-reacting flowas a initial guess for the non linear solver.

9 Call solve method from pde class with option “STATIONARY”. It uses a newton type solver with an“adaptive”update for the Jacobian matrix.

10 Plot the solution with plot method from reactingFlow class.

Figure 4: Solution of the reacting flow problem. From left up to right down: Temperature, Fuel, Oxidizer, Product.

18

4.2.3 KKT system for a problem with control constraints

As mentioned before, readers not familiar with optimal PDE control should see this as an example for a system ofcoupled nonlinear PDEs. However, we give a short motivation why to consider this problem.

Let be given this optimal control problem:

min12‖y− yd‖2

2 +λ

2‖u‖2

2

subject to

−c∆y+ay = u in Ω

hy = r on Γ

and to the control constraintsu≤ u≤ u in Ω.

The function u ∈ L2(Ω) is the control and the function y ∈C(Ω) is the state. This is an optimization problemwith equality (the PDE) and inequality constraints (the control constraints). We eliminate the equality constraintsby adding the inner product of the constraints with some function p ∈ L2(Ω) to the objective function. The controlconstrains will be eliminated by inserting it in a barrier function and add this also the the objective function.Altogether, this is called Lagrange function. It reads in our case

L(y,u, p) =12(y− yd ,y− yd)L2(Ω)+

λ

2(u,u)L2(Ω)

−(−c∆y+ay−u, p)L2(Ω)− (y, p)L2(Γ)

−σ

Ω

ln(u−u)− ln(u−u)dx

where σ > 0 is a parameter. From Karush-Kuhn-Tucker theory we know, that the set of functions (y, u, p) isthe (in this case unique) solution of the optimal control problem, if and only if it is a solution of the system

∆ p−ap+ y− yd = 0 inΩ

hp = 0 onΓ

λ u+ p− σ

u−u+

σ

u− u= 0 in Ω (6)

∆y−ay+ u = 0 in Ω

hy = r on Γ

Obviously, we have only to solve this nonlinear system. We should discus briefly the role of the parameter σ .Obviously rather large values smooths the nonlinear term in our KKT system, small values allow the control tocomes near the constraints. We should apply an algorithms that starts with rather large σ0 and reduces it within aloop, e.g. σk+1 = sσk with a number s∈ (0,1). The iterates depending on σk should then used as initial guesses forthe next call of the Newton solver. Details you will find in the Literature e.g. under “path following” and “interiorpoint methods”.

To solve the control problem numerically, we write a class kkt. From the problem setting, we identify theadditional properties

– the regularization parametersλand σ , real numbers initialized by ones

– the control constraints u and u, here called u_upper and u_lower, initialized by ±∞.

– the boundary conditions for the state equation. However, since the adjoint equation has boundary conditionwith the same left hand side as the state equation, we do not need to define a boundary condition for theadjoint equation.

Es private properties we want to include the functions y and u. Since we are here interested also in the “technical”adjoint p and in the approximations of the Lagrange multipliers, we add these functions to the private propertiesof our class.

We will call them state, control, adjoint, multiplier_upper and multiplier_lower.The code up to now reads

19

classdef kkt < pdeproperties(Access = public)

bcStatesigma = 1;lambda = 1;u_upper = infu_lower = -inf

endproperties(SetAccess = private)

statecontroladjointmultiplier_uppermultiplier_lower

endend

Within the method df we can split the PDE again in a constant, a linear and a non-linear part. The constant andthe matrix of the linear part can be pre-computed in initialize method. We will call the non-linear part here penalty,it will be a method of class kkt with one additional argument.

methods (Access = protected)function dy = df(obj ,~,y)

dy = obj.A*y+obj.penalty(y)+obj.b;end

end

Within the penalty method we need only the control from the vector obj.y, where we store the solution of thewhole KKT system. We arrange the solution parts state control adjoint in exactly this order in obj.y. The orderof the equations in the KKT system may be the same as in (6), namely adjoint, gradient and state equation, or∂yL(y,u, p), ∂uL(y,u, p), ∂pL(y,u, p). The result giving back by penalty must be of the same size as obj.y. Weinitialize it by a zero vector. The control is now u = y(obj.grid.nPoints+1:2*obj.grid.nPoints,end) and finally wemust take care that the result of the computations must be bring in the position of the gradient equation. The codeis rather simple.

methods(Access = private)function val = penalty(obj ,y)

val = zeros(size(y));u = y(obj.grid.nPoints +1:2* obj.grid.nPoints ,end);val(obj.grid.nPoints +1:2* obj.grid.nPoints) = ...obj.sigma*obj.mass *( -1./(u-obj.u_lower) + 1./( obj.u_upper -u))

;end

end

The method initialize is now straight forward. First we apply makeBoundaryMatrix on the bcState property.Note that for more complex boundary settings one should call this method outside the initialize method. Sincewe have only trivial boundary condition right-hand-sides for the state equation, only one call of obj.fem.assembis needed. The same hold for the call of obj.fem.assema. For speed-up the computation of the jacobian, weshould give the jacobian method the sparsity pattern of the Jacobian. The speed-up depends of the dimension ofthe problem, but it is typically O(nPoints). The code is given by the next Listing. Note that by using assema/bmethods instead of pde.initalize we must set the obj.initialized property here explicitly.

function initialize(obj ,y_d)obj.grid.makeBoundaryMatrix(obj.bcState);[Q,G,H,Ry] = obj.fem.assemb(obj.grid);[K,M,F] = obj.fem.assema(obj.grid ,1,0,...

-y_d);l = obj.fem.stiffSpring(K+M);N = sparse(obj.grid.nPoints ,obj.grid.nPoints);n = sparse(obj.grid.nPoints ,1);

20

obj.A = [obj.mass N -(K+M+l*(H'*H)+Q);...

N obj.lambda*obj.mass obj.mass;...-(K+M+l*(H'*H)+Q) obj.mass N];

obj.b = [F;...n;...l*H'*Ry+G];

obj.y = ones(obj.grid.nPoints *3,1);obj.pattern = (obj.A~=0);obj.initialized = true;

end

The heart of the solve method is now a call of pde.solve(’STATIONARY’). However, we need a few further(helper) methods.

(i) For the Newton solver used in pde.solve(’STATIONARY’) we need a feasible initial guess. We shouldcompute one by an extra method initialGuess.

(ii) The constraints may be given in different formats, e.g. scalar number and one as a vector of lengthnumber of points in the mesh. To bring them into the same format (vector of lenght number of pointsin the mesh) we use a function expandConstraints, that additionally computes a feasible initial guessfor the control.

(iii) To obtain also a feasible initial guess for the state and the adjoint, i.e. for the whole KKT system, weuse the method initialGuess

(iv) Further, we need a method that checks if a solution is feasible.

All these helper methods will be described later.When we used pde.solve(’STATIONARY’), we solve our KKT system by Newtons method, but for fix smooth-

ing σ . Our aim is to reduce σ sequentially, i.e. to construct a set of σ0, ...,σk→ 0 and associated solutions of theKKT system, here yσk ,uσk , pσk . To construct such path following we establish a loop where we reduce σ by multi-plying it by a fixed parameter s ∈ (0,1). Note that the while loop can be only terminated by using a break or returnstatement or, as in our case, by a exception. We use here a unusual to break the loop. We have three cases:

(i) solve(’STATIONARY’) itself fails by throwing an exception (singular matrix, no convergence, etc.)

(ii) the parameter σ is smaller then its smallest allowed value.

(iii) the solution (iterate) is not feasible.

In (ii) we throw in this sense a “good” exception. The code can be studied in detail in the next Listing.

function solve(obj ,varargin)if ~obj.initialized

obj.notInitialized.throwAsCaller;endobj.initialGuess;while true

y = obj.y;try

solve@pde(obj ,'STATIONARY ');if obj.sigma < 1e-8

MException('kkt3:sigmaneareps ',...'sigma near eps').throw;

endif ~obj.feasible

MException('kkt3:notfeasible ',...'solution is not feasible ').throw;

endobj.sigma = obj.sigma *0.85;

catchobj.y = y;

21

obj.splitSolution;fprintf (['Pathfollowing breaks with sigma = ',...

num2str(obj.sigma),'\n'])return

endend

end

The Listing below shows the complete class kkt, including the helper methods expandConstraints, feasible,splitSolution, initialGuess and a specialized plot that plots the solution and the approximations on the Lagrangemultipliers.

classdef kkt3 < pdeproperties(Access = public)

bcStatesigma = 1;lambda = 1;u_upper = infu_lower = -inf

endproperties(SetAccess = private)

statecontroladjointmultiplier_uppermultiplier_lower

end

methods (Access = protected)function dy = df(obj ,~,y)

dy = obj.A*y+obj.penalty(y)+obj.b;end

end

methods(Access = private)function val = penalty(obj ,y)

val = zeros(size(y));u = y(obj.grid.nPoints +1:2* obj.grid.nPoints ,end);val(obj.grid.nPoints +1:2* obj.grid.nPoints) = ...

obj.sigma*obj.mass *( -1./(u-obj.u_lower) + 1./( obj.u_upper -u));

endend

methods(Access = public)function initialize(obj ,y_d)

obj.grid.makeBoundaryMatrix(obj.bcState);[Q,G,H,Ry] = obj.fem.assemb(obj.grid);[K,M,F] = obj.fem.assema(obj.grid ,1,0,...

-y_d);l = obj.fem.stiffSpring(K+M);N = sparse(obj.grid.nPoints ,obj.grid.nPoints);n = sparse(obj.grid.nPoints ,1);obj.A = [obj.mass N -(K+M+l*(H

'*H)+Q);...N obj.lambda*obj.mass obj.mass;

...-(K+M+l*(H'*H)+Q) obj.mass N];

obj.b = [F;...n;...

22

l*H'*Ry+G];obj.y = ones(obj.grid.nPoints *3,1);obj.pattern = (obj.A~=0);obj.initialized = true;

end

function solve(obj ,varargin)if ~obj.initialized

obj.notInitialized.throwAsCaller;endobj.initialGuess;while true

y = obj.y;try

solve@pde(obj ,'STATIONARY ');if obj.sigma < 1e-8

MException('kkt3:sigmaneareps ',...'sigma near eps').throw;

endif ~obj.feasible

MException('kkt3:notfeasible ',...'solution is not feasible ').throw;

endobj.sigma = obj.sigma *0.85;

catchobj.y = y;obj.splitSolution;fprintf (['Pathfollowing breaks with sigma = ',...

num2str(obj.sigma),'\n'])return

endend

end

function plot(obj)titles = 'State y' 'Control u ' 'Adjoint p';for k = 1:3

subplot(2,3,k)title(titlesk);obj.grid.plot(obj.y((k-1)*obj.grid.nPoints +1:...

k*obj.grid.nPoints ,end),'b');endsubplot (2,3,4)title('multiplier \mu_1');obj.grid.plot(obj.multiplier_lower ,'g');view (0 ,90)

subplot (2,3,5)title('multiplier \mu_2');obj.grid.plot(obj.multiplier_upper ,'b');view (0 ,90)

endend

methods(Access = private)function u = expandConstraints(obj)

if isfinite(obj.u_upper)&& isfinite(obj.u_lower)if isscalar(obj.u_upper)

obj.u_upper = obj.u_upper(ones(obj.grid.nPoints

23

,1));endif isscalar(obj.u_lower)

obj.u_lower = obj.u_lower(ones(obj.grid.nPoints,1));

endu = 0.5*( obj.u_upper+obj.u_lower);return

endif isinf(obj.u_upper)&& isfinite(obj.u_lower)

if isscalar(obj.u_lower)obj.u_lower = obj.u_lower(ones(obj.grid.nPoints

,1));endu = obj.u_lower +1;return

endif ~isfinite(obj.u_lower)&& isfinite(obj.u_upper)

if isscalar(obj.u_upper)obj.u_upper = obj.u_upper(ones(obj.grid.nPoints

,1));endu = obj.u_upper -1;return

endif isinf(obj.u_upper)&&isinf(obj.u_lower)

u = zeros(obj.grid.nPoints ,1);return

endend

function b = feasible(obj)obj.splitSolution;b = all(obj.u_lower < obj.control)&&...

all(obj.control < obj.u_upper);end

function initialGuess(obj)u = expandConstraints(obj);A = obj.A(2*obj.grid.nPoints +1:3* obj.grid.nPoints ,...

1:obj.grid.nPoints);b = obj.b(2*obj.grid.nPoints +1:3* obj.grid.nPoints ,1);y = A\(obj.mass*u+b);p = -u*obj.lambda+obj.sigma ./(u-obj.u_lower)-obj.sigma ./(

obj.u_upper -u);obj.y =[y;u;p];

end

function splitSolution(obj)obj.state = obj.y(1: obj.grid.nPoints ,end);obj.control = obj.y(obj.grid.nPoints +1:2* obj.grid.nPoints

,end);obj.adjoint = obj.y(2* obj.grid.nPoints +1:3* obj.grid.

nPoints ,end);obj.multiplier_upper = obj.sigma ./(obj.u_upper -obj.

control);obj.multiplier_lower = obj.sigma ./(obj.control -obj.

u_lower);

24

endend

end

As an example we solve the problem with u =−50, u = 100 and

yd =

2 for 0.6≤ x≤ 0.80 otherwise

on the interval Ω = (0,1). Further we start at σ = 1 and we use λ = 10−5. As boundary condition for the state wechoose homogeneous Dirichlet boundary conditions, i.e. h = 1 and r = 0.

function testKKT3clf ,clc% define the kkt systemkktSystem = kkt3();kktSystem.grid = grid1D ();kktSystem.grid.intervall ([0 ,1] ,0.01);kktSystem.fem = lagrange11D ();kktSystem.u_lower = -50;kktSystem.u_upper = 100;kktSystem.sigma = 1;

% define the boundary conditionkktSystem.bcState = kktSystem.grid.dirichletBC('0.0');

% define lambdakktSystem.lambda = 1e-5;

yd = fyd(kktSystem.grid);kktSystem.initialize(yd);

% solve KKT SystemkktSystem.solve ();

figure (1)clfkktSystem.plot

function val = fyd(g)val = zeros(size(g.p(1,:)));val(g.p(1,:) >=0.6&g.p(1,:) <0.8) = 2;

endend

25

4.3 Derive geometry classes4.3.1 Adapted L-shape

In general, the user can use all classes (also abstract declared ones) to derive his own classes. However, we willdemonstrate it on an example that uses a to create a L-shaped domain, but with a special ordering of the boundarysegments.

The call

g = grid2D()g.lshape

will create a L-shaped domain, but with six boundary segments. If the user wants to have only one boundarycondition, the call

g.makeBoundaryMatrix(bc);

will define the given boundary condition on every six boundary segments. If the user needs two boundary condi-tions on two boundary segments, he can create his own L-shape class.

Note that by deriving this class from grid2D will inherit also methods that change the shape of the domain, e.gunitSquare etc. Here we have to deal with the phenomena of “restricted inheritance”.

We assume, that we want to have two boundary segments and we will collect the old boundary segments one,two, five and six into the new boundary segment one and to collect the old boundary segments three and four intothe new boundary segment two.

We first derive LShape class from grid2D. Next, we call inside the constructor the inherited method obj.lshape.Correcting of the boundary segment number is done in the next five lines by indexing. We have now already aworking class. However, to prevent the L-Shape for e.g. become a square by calling LShape.square, we overwriteall classes that changes the form of the geometry by empty methods. Setting then Hidden = true will hide themfrom the users eyes.

classdef LShape < grid2Dmethods(Access = public)

function obj = LShape ()obj.lshape;

26

indx3 = obj.e(5,:) == 3;indx4 = obj.e(5,:) == 4;obj.e(5,:) = 1;

obj.e(5,indx3|indx4) = 2;end

endmethods(Access = public , Hidden = true)

function doubleT(obj)end %#ok <*MANU >function freeGeometry(obj)endfunction holeInPlane(obj)endfunction square(obj)endfunction unitCircle(obj)endfunction unitSquare(obj)end

endend

Figure 5: Result of identifyBoundarySegment

5 Class referenceIn this quickstart guide, we will only discuss public properties and methods form the top-level classes, i.e theclasses in the upper box of the diagram below. For the (abstract) low-level classes we refer to the class reference.

27

Abstract classes from OOPDE: finitelElements, gridd, finiteElements1D

finiteElements2D, finiteElements3D, plotUtils3D,...

Public fem classes from OOPDE: lagrange11D, lagrang12D, lagrange13D

Public grid classe from OOPDE: grid1D, grid2D, grid3D

Abstract class from OOPDE: pde

abstract classes not for use by users

User geometies: LShape, etcUser Classes: convectionDiffusion, burgers etc.

Classes that can be used by users

We recommend the user interested in solving PDE problems only to derive classes from the upper class layer(in the figure green classes). Using the p-code version of OOPDE prevents the user from unwanted changes in thebasic classes.

5.1 class pdeProperties with Access=protected, constant To have a unique set identifiers and messages for error handling,we have a couple of constant properties for that purpose.

name value

wrongClassID ’PDE:wrongClass’;

wrongClassStr ’Wrong argument class, it must be ’;

wrongNumberArgumentsID ’PDE:wrongNumberArguments’

wrongNumberArgumentsStr ’Wrong number of arguments, it must be ’;

wrongSizedArgumentID ’PDE:wrongSizeArguments’;

wrongSizedArgumentStr ’Wrong size of Arguments, it must be ’;

invalidOperationID ’PDE:invalidOperation’;

invalidOperationStr ’The operation is not valid: ’;

unknownPropertiesID ’PDE:unknownField’;

unknownPropertiesStr ’Unknown property:’;

wrongInputFormatID ’PDE:wrongInputFormat’;

wrongInputFormatStr ’Wrong input format.’;

Users should use these constants as given in this example

28

MException(wrongNumberArgumentsID,...[wrongNumberArgumentsStr,’three or five’]).throwAsCaller

Additional, we have constant MException objects to be used in user code if needed.

name value

notInitialized MException(’PDE:notInitialized’,...’Object should be initialized.’);

notAllowed MException(’PDE:notAllowed’,...’This operation is not allowed for class pde.’)

Properties with Access = public

name class [default] usage

fem object inherited from finiteElements [] Defines the finite elements method. Must have the same xDflag as the grid property.

grid object inherited from gridd [] defines the mesh. The x must be the dimension of the spatial domain.Example: grid2D defines a two-dimensional grid for meshing some geometry object in the plane.

time double [] time interval, only for time dependent problems

y solution vector (stationary problems) or matrix (transient problems) Time dependent solvers mustprovide a matrix with the same number of columns as the length of obj.time.

Note that this properties behave as public. Actually they are protected and the setting is managed by an overwrittensubsasgn method.

Properties with Access = private

name class [default] usage

pattern logical [] Sparsity Pattern of Jacobian matrix

initialized logical [false] set it true after initializing the object, i.e. the last line of an overwritten initializedmethod should be obj.initialized = true;

D double [] Mass matrix related to d.

K double [] Stiffness matrix related to c,

M double [] Mass matrix related to a,

C double [] Convection matrix, related to~b,

H double [] Dirichlet-boundary condition-matrix,

Q double [] Neumann boundary condition-matrix,

F double [] source vector

G double [] Neumann boundary condition-vector

R double [] RHS Dirichlet vector

A double [] Matrix for storing whole system matrix or to sum the LHS of the linear system

b double [] vector for storing whole RHS of systems or to sum the RHS of linear system

29

Methods with Access = publicname parameter [optional] meaninginitialize [d,] c,b,a,f computes from the coefficient vectors the matrices D, K,

C, M, Q, and H, and the vectors F, G, and R.solve ’SOLVER’ computes the solution of the PDE by using the SOLVER

SOLVER can be e.g. ’ODE15S’, ’STATIONARY’, or’LINEAR’.

stiff returns stiffness matrix forc = 1 Note, that sqrt(uKu) isthe numerical approximation of the H1(Ω) semi-norm.

mass returns Mass matrix for a = 1. Note, that sqrt(uMu) isthe numerical approximation of the L2(Ω) norm.

L2 [double] returns the L2(Ω) norm of obj.y or obj.y minus theargument. The argument must be of same size as obj.y

evaluateAtPoint double returns obj.y at given coordinates given by argument.Argument must be a vector of length of the dimension ofthe spatial domain.

Methods with Access = protected, Abstract = true This method must be overwritten in user classes.name parameters meaningdf t,y defines the RHS of the PDE

d∂u∂ t

= Φ(t,x,u(t,x))

where d might be zero.

Methods with Access = protected This method should, but not must be overwritten in user classes.name parameters meaningjacobian t,y computes the Jacobian matrix of Φ defined by

d∂u∂ t

= Φ(t,x,u(t,x))

where d might be zero. This method uses numerical differentiation. Ifa analytical Jacobion is at hand, the user should overwrite this methodby a code that implements the analytical (“exact”) Jacobian. The speedup factor should be O(np), where np is the number of unknowns in thePDE (system).

5.2 class lagrange1XDAll Lagrange FE classes have a unique set of public methods. Actually, that is why we can write spatial dimensionindependent class definitions. Replace X by the dimension of the spatial domain.

name parameter meaninglagrange1XD class constructorassema grid,c,a,f assembles the matrices obj.K and obj.M and the vector obj.Fconvection grid,b assembles the matrix obj.Cassemb grid assembles the matrices obj.Q and obj.H and the vectors obj.G and

obj.RstiffSpring matrix returns a number that is the stiff-spring multiplier to the Dirichlet

boundary conditions

5.3 Common methods for all gridxD classesIn this section we discuss the methods common for all grid classes. Note that the boundary conditions are propertiesof the grid.

30

name parameters meaningnEdges returns number of edges in meshnElements returns number of elements in meshnPoints returns number of points in meshnBoundarySegments returns number of boundary segments in meshdirichletBC [h],r codes the strings h and r as numbers to store them in a

boundary condition matrix. If only r is given, h=1 willbe assumed.

robinBC q,g codes the strings q and g as numbers to store them in aboundary condition matrix

neumannBC g codes the string g as numbers to store them in aboundary condition matrix.

makeBoundaryMatrix BC[BC,...] writes the boundary condition matrix. the number ofarguments must be one or must be the same asnBoundarySegments returns

point2Center data interpolates data from elements points to the center ofelement. data must be a vector of length Points

5.4 grid1Dname parameters meaninggrid1D class constructorplot [y] plots the points of the mesh, i.e. here an interval, or y over the mesh

points.refineUniformly n refines the mesh n-times uniformlyrefineMesh [index] refines the mesh uniformly or—if given—only in the elements with

number in indexinterval vector, [h] creases an interval. If vector has length two, it uses vector as interval

borders, if vector has length grater two, it uses vector as the points ofthe interval. The optional argument h gives the upper limit for themesh width.

31

5.5 grid2Dname parameters meaninggrid2D class constructorgradient y computes the gradient of y. Syntax:

[dx,dy] = grid2D.gradient(y)plot [y] plots the mesh or the function y over the mesh.quiver dx,dy plots a quiver plot of the vectors dx and dy. Syntax

grid2D.quiver(dx,dy)square [x1,x2,y1,y2[,hmax]] creates a square. Without arguments, a qunit square with

h=0.1 will be created.A call with four arguments will create a squareS = [x1,x2]× [y1,y2] and h=0.1.A call with five arguments will set h.

unitSquare [hmax] creates a unit square, Optional argument is minimalmesh width hmax

circle [R,[hmax,[xshist,yshift]]] creates a circle Syntax:obj.circle() creates unitcircle with hmax = 0.2obj.circle(R) creates circle with Radius = R and hmax =0.2obj.circle(R,hmax) creates circle with Radius = R andmesh width hmaxobj.circle(R,hmax,xshist,yshift)Circle with center = (xshif,yshift), radius R and meshwidth hmax.

unitCircle [hmax] creates a unit circleSyntax:obj.unitcircle() hmax set to 0.2obj.unitcircle(hmax)

doubleT s creates a double-T-shape.Called with no argument, the base hal lenght one and theheight is three. One can scale the whole domain, but notthe proportions. There are 12 boundary segments. Toidentify boundary segment number callobj.identifyBoundarySegment

lshape [hmax] creates a L-shapeSyntax:obj.Lshape() here hmax = 1obj.Lshape(hmax) sets hmax.

freeGeometry outerConstraint,[innerConstraint] creates a polygonial bounded domain. The boundarysare given by the matrices outerConstraint and if there isinnerConstraint. Matrx format [xpoints;ypoints]

identifyBoundarySegment nSegment plots the boundary segment number nSegment in red. Ifthe segment not exists, nothing will be highlighted.

nBoundaryPoints returns the number of boundary pointsmidpts returns the coordinates of the center of all elements in

mesh. The result is a matrix of dimension two timesnumber of elements.

refineMesh [index] refines the mesh uniformly or—if given—only in theelements with number index

32

5.6 grid3Dname parameters meaninggrid3D class constructorunitBall creates a unit ball geometry objectunitCube creates a unit cube geometry objectficheraCube creates a Fishera cube geometry objectcylinder creates a cylinder geometry objectbar creates a 3D bar geometry objectplot plots the 3D meshplotFaces [vector] solid plot of the geometry object . With additional argument the faces

will be colored depending of the value of the vector. It must have thelength grid3D.nPoints

plotIso vector plot iso-surfaces of vector.plotSlices vector slice plot of vector with respect of the given slices in x y and z

coordinatescutawayPlot vector cuts the 3D domain and applies plotFaces on the remaining 3D object

ThanksWe would like to thank all “early users” for testing the software, especially Andreas Himmel (University of Magde-burg) and Pascal Friedrich (UAS Darmstadt) for the “students view” on examples, (German) manual and help files,Hannes Uecker (University of Oldenburg) for discussion on code structure and the initial code of the 3D isosurfmethod, Zhi George Lin (Zhejiang University Hangzhou) not only for testing the code on Mac computer and find-ing a strange bug within the plotting method, and last but not least Martin Ullmann (TUBAF Freiberg) for the realworld application demanding the 3D capabilities we now implemented in OOPDE.

References[1] The MathWorks, Partial Differential Equation Toolbox User’s Guide, The Math Works Inc., 1995.

[2] M. Buffoni, K. Willcox, Projection based model reduction for reacting flows, American Institute of Aeronau-tics and Astronautics .

33