H AMPATH: reference manual.

Jean-Baptiste Caillau, Olivier Cots and Joseph Gergaud.

Abstract This reference introduces the M ATLAB package H AMPATH [5] designed to solve optimal control problem via indirect method. We rst deal with problems where we suppose that the maximization of the Hamiltonian gives us the control u = u(x,p) in the state and the costate, and where we also suppose that the problem is smooth, i.e. that all the functions are smooth and that the relation u(x,p) is also smooth. Bang-Bang problems where the control is piecewise continuous or Singular problems where the control cant be explicitly computed from the maximization of the Hamiltonian can be also treated. H AMPATH compiles the Fortran code implementing the maximized Hamiltonian and the Limits Conditions, into a collection of M ATLAB functions that allow rst of all to solve the shooting equation. However, it is well known that the main difculty to solve such problems with indirect methods based on Newton algorithm is to nd a good initial guess. So a differential path following method has been implemented which makes H AMPATH the natural extension of the M ATLAB package C OTCOT [3]. Finally, it is also possible to compute the Jacobi elds of the Hamiltonian system to check the order two conditions of optimality and seek conjugate points, as C OTCOT does. We invite the reader to refer to [6] to get more explanation on how H AMPATH deals with second order conditions of optimality. Index Terms optimal control; shooting method; differential homotopy; second order conditions; conjugate points.

C ONTENTS I II Introduction Installation on 32/64 bits M AC OSX and L INUX II-A Necessary resources . . . . . . . . . . . . II-B Installation of the H AMPATH package . . II-C Testing your installation . . . . . . . . . . versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3 3 3 3 4 4 5 6 7 8

III

Optimal Control Problems solved by H AMPATH III-A Optimal Control Problem and Pontryagin Maximum Principle III-B Smooth OCP and simple shooting method . . . . . . . . . . . III-C OCP with Bang/Singular arcs and multiple shooting method . III-D OCP depending on parameters and homotopic method . . . . III-E User implementation and the M ATLAB package . . . . . . . .

IV

Examples 12 IV-A Example 1 : a simple problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IV-B Example 2 : a Bang-Bang problem . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 18 29

Appendix References

J-B. Caillau, Institut de Math matiques de Bourgogne, UMR CNRS 5584, 9 Avenue Alain Savary, BP 47 870 F-21078 DIJON Cedex e FRANCE (jean-baptiste.caillau@u-bourgogne.fr). O. Cots, Institut de Math matiques de Bourgogne, UMR CNRS 5584, 9 Avenue Alain Savary, BP 47 870 F-21078 DIJON Cedex FRANCE e (olivier.cots@u-bourgogne.fr). J. Gergaud, IRIT (UMR CNRS 5505) and ENSEEIHT Applied Math. & Comp. Science Dept. (joseph.gergaud@enseeiht.fr).

HAMPATH MANUAL.

I. I NTRODUCTION Consider this simple optimal control problem

where the nal time is xed, tf  1, the extremities are xed, q p0q  px, v qp0q  p1, q, q ptf q  px, vqptf q  p0, 0q and where u is in R. A standard application of the maximum principle tells us that the so-called normal and regular minimizing curves are the projection of extremals z  pq, pq  px, v, px , pv q R4 such that 9 z  Hr pz q (2) where Hr pz q  H pz, upz qq  p2 {4 vpx vpv is the smooth regular Hamiltonian dened on  R with v upz q  pv {2, and where Hr  pf Hr {f p, f Hr {f q q. Since we have boundary conditions, the extremals we are interested in are BC-extremals. They are zeros of the shooting mapping dened by S, : p0

$ 1 ' M in 0 u2dt ' ' xv ' & 9 pP,q ' v  v u 9 ' xp0q  1; xp1q  0 ' ' % vp0q  ; vp1q  0.

(1)

with expt pz0 q  z pt, z0 q the solution of (2) for the initial condition z0 and : pq, pq q the canonical projection. Note that the solution of the shooting function depends on the parameters and . We call the mapping in (3) an homotopic function as soon as we consider the parameters as variables. Moreover, the (local) optimality of such extremals is checked by a rank test on the subspaces spanned by the Jacobi elds along the trajectory. These elds are solutions of the variationnal equation

pexpt pq0, p0qq qf

f

(3)

fz  dHr pzptqq.fz
9

(4)

with suitable initial conditions. The aim of the code H AMPATH which extends the possibility of the software C OTCOT, is to provide the numerical tools  to integrate Hamiltonian systems such as (2)  to solve the associated shooting equation dened by (3)  to get the zeros path of an homotopic function provided by a shooting mapping depending on parameters  to compute the corresponding Jacobi elds (4) along the extremal  to evaluate the resulting conjugate points, if any. Remark 1. The package H AMPATH extends the software C OTCOT. Moreover it permits to solve efciently homotopic function dened from an optimal control problem (OCP) depending on parameters, and nally to solve OCP where the control solution is non-smooth. The structure of the control may be Bang-Bang or Bang-Singular. We rst review the installation procedure of the software in II. Then, we dene in III all the kind of optimal control problems that can be solved by H AMPATH. After that, we illustrate in IV the way the program works on several examples. Elementary M ATLAB and F ORTRAN code is discussed. Finally we give a synopsis of the M-files which are available in the package. Remark 2. Since a lot of time and effort has gone into H AMPATHs development, please cite the following link if you are using H AMPATH for your own research: J.B. Caillau, O. Cots, and J. Gergaud. H AMPATH : on solving optimal control problems by indirect and path following methods. http://apo.enseeiht.fr/hampath.

HAMPATH MANUAL.

II. I NSTALLATION ON 32/64 BITS M AC OSX AND L INUX VERSIONS A. Necessary resources The package is intended for a standard U NIX system. The following softwares are required : 1) The g95 http://www.g95.org/downloads.shtml or ifort http://software.intel.com/en-us/intel-compilers F ORTRAN compiler. 2) M ATLAB. If you use ifort then you have to indicate it to M ATLAB (see section 3 of the Introduction to MEX-les on http://www.mathworks.com/support/tech-notes/1600/1605.html and the use of the mex -setup command). You have an example of a mexopts.sh le used with ifort at http://apo.enseeiht.fr/hampath/resources/specic/static/mexopts.sh. 3) The TAPENADE [7] package http://www-sop.inria.fr/tropics. B. Installation of the H AMPATH package We note here currentpath the name of the absolute path of your current directory. 1) Retrieve the compressed archive hampath.tar at the following Web address : http://apo.enseeiht.fr/hampath. 2) Unarchive it (tar xvf hampath.tar). You then obtain a directory hampath in your currentpath which contains the directories bin, src and doc and the text le readme.txt. 3) Open your .login (or .profile or .cshrc or .bashrc . . . ) le, create it if necessary, and add the following lines to permit the use of the hampath command For CSH environment : HAMPATH_HOME="currentpath"/hampath setenv PATH "$PATH:$HAMPATH_HOME/bin" For BASH environment : export HAMPATH_HOME=currentpath/hampath export PATH=$PATH:$HAMPATH_HOME/bin 4) Type the shell command (in any directory) hampath -install to nalize the installation. See remark (3) if you get some trouble executing the installation command. C. Testing your installation Download the simple example at http://apo.enseeiht.fr/hampath/resources/specic/dyn/simple example. tar. Uncompress the archive simple_example.tar. Then follow the commands : 1) Go to the simple_example/ directory and compile your fortran sources according to the command hampath (the help is given in the appendix (0a)) 2) Launch M ATLAB 3) Execute the main.m script. You will obtain a long text results and the gure 1.

Fig. 1. Results for the simple example.

HAMPATH MANUAL.

Remark 3. The H AMPATH package uses the command mex to compile the F ORTRAN sources in order to make some functions callable by M ATLAB. It can be possible that the mex command is not from M ATLAB but L ATE X. Type which mex in the shell and if you get something like /usr/texbin/mex then you dont have the right mex command. To x this problem, open your .login (or .profile or .cshrc or .bashrc . . . ) le present in your home directory, and add the M ATLAB bin absolute path in the environment variable PATH according to setenv PATH "$MATLAB_HOME/bin:$PATH" (csh) or export PATH=$MATLAB_HOME/bin:$PATH (bash), where MATLAB_HOME is the M ATLAB absolute path. III. O PTIMAL C ONTROL P ROBLEMS SOLVED BY H AMPATH A. Optimal Control Problem and Pontryagin Maximum Principle The following part is inspired from the course notes [12] of E. Tr lat. In the next part, we prensent an e overview of the Pontryagin maximum principle. See [1] to learn more details on optimal control theory. We consider the following control system in Rn where f : R Rn Rm Rn is C 1 and where the control u is an essentially bounded and measurable function on an interval r0, te puqr of R which takes its values in Rm . Let M0 and M1 be two subsets of Rn . We denote by U the set of admissible controls u which permit to steer the system from an initial point of M0 to a nal point of M1 in a time tpuq te puq. Moreover we dene the cost of a control u on r0, ts C pt, uq  g pt, xptqq where f : R R R R and g : R R (5) associated to the control u.
0 n m n n
9 xptq  f pt, xptq, uptqq

(5)

t
0

f 0 ps, xpsq, upsqqds,

R are C 1, and xp.q is the trajectory solution of

We consider the following optimal control problem : determine a trajectory from M0 to M1 which minimize the cost. The nal time can be xed or not. If the control u U associated to the trajectory xp.q is optimal on r0, T s, then there exists according to the Pontryagin maximum principle an absolutely continuous mapping pp.q : r0, T s Rn called adjoint vector, and a real number p0 0, with ppp.q, p0 q $ p0, 0q, such that for almost every t r0, T s,

"

where H pt, xptq, pptq, p0 , uptqq  xp, f pt, x, uqy p0 f 0 pt, x, uq is the Hamiltonian function, and the maximization condition H pt, xptq, pptq, p0 , uptqq  max H pt, xptq, pptq, p0 , v q (7) holds almost everywhere on r0, T s.
v

9 xptq  fH H pt, xptq, pptq, p0 , uptqq, fp pptq  fH pt, xptq, pptq, p0 , uptqq, 9 fx

(6)

If the nal time to reach the target M1 is free, we have another condition at the nal time T fg max H pT, xpT q, ppT q, p0 , v q  p0 pT, xpT qq. (8) v ft Moreover if M0 or M1 (or both) is a manifold of Rn having tangent spaces in xp0q M0 or xpT q M1 (or both), then the adjoint vector must verify respectively the rst or the second condition (or both) below pp0q

u Txp0qM0

(9)

HAMPATH MANUAL.

ppT q p0

fg pT, xpT qq u T M . xp T q 1 fx fg pT, xpT qq. ft

(10)

Remark 4. If the control u is continuous at time T , the condition (8) can be written H pT, xpT q, ppT q, p0 , upT qq  p0 Remark 5. We have for almost every t r0, T s (11)

fH pt, xptq, pptq, p0, uptqq. d H pt, xptq, pptq, p0 , uptqq  (12) dt ft In particular if the augmented system is autonomous, i.e. if f and f 0 do not depend on t, then H does not depend on t and we have dt r0, T s max H pxptq, pptq, p0, vq  C. v 0 Remark 6. The convention p 0 leads to the maximum principle. The convention p0 0 would imply
that the condition (7) would be a minimum condition. Denition 1. An extremal of the optimal control problem is a quadruple pxp.q, pp.q, p0 , up.qq solution of the equations (6) and (7). If p0  0, the extremal is said to be abnormal and if p0 $ 0 it is said to be normal. Denition 2. The conditions (9) and (10) are called transversality conditions on the adjoint vector. The condition (8) is called condition of transversality on the Hamiltonian. Denition 3. We call true hamiltonian the function Hr pt, xptq, pptqq  H pt, xptq, pptq, p0 , upt, xptq, pptqqq

(13)

When the maximum condition gives the control u in terms of pt, x, pq and with p0 replaced by its value. To solve this optimal control problem, H AMPATH use indirect method as simple or multiple shooting based on the famous Newton algorithm. In the next subsection we present how classic problems are solved by simple shooting. We dene the two points boundary value problem (TPBVP) associated to the optimal control problem and the shooting equation. After that, we present how to deal with nonsmooth control solution. Indeed in the case of Bang-Bang control or Bang-Singular control we need to use multiple shooting. We dene then the multiple boundary value problem (MBVP) and the shooting equation in this case. In the nal subsection of this part we explain what the user has to implement and what is automatically done. But before we introduce the core of the method hampath which consist to replace shooting by the mere integration of an ODE. Indeed, for optimal control problems depending on parameters, differential pathfollowing replaces Newton solving (except for the computation of the starting point where shooting is still needed). B. Smooth OCP and simple shooting method We consider the following optimal control problem
f

$ t ' M in gptf , xptf qq 0 f 0pt, xptq, uptqqdt , xptq Rn ' ' ' ' ' & 9 m pP q ' xptq  f pt, xptq, uptqq , uptq U R ' ' b0 pxp0qq  0 Rn , n0 n ' ' ' % bf ptf , xptf qq  0 Rn , n1 n
0 1

(14)

HAMPATH MANUAL.

Note that there is no condition on the nal time tf , it can be xed or free and the system may be time dependent. The Pontryagin maximum principle gives necessary conditions on the solution and asserts that any optimal trajectory is the projection of an extremal pxp.q, pp.q, p0 , up.qq. If the maximum condition (7) gives a smooth control in terms of pt, xptq, pptqq (i.e. upt, xptq, pptqq  arg maxv H pt, xptq, pptq, p0 , v q) 9 p0 xed, then the extremal system (6) is a differential system of the form z ptq  Hr pt, z ptqq, where z ptq  pxptq, pptqq, Hr is the true hamiltonian (Def. 3) and where p0 is omitted because it has a known value. The PMP gives also some transversality equations (8), (9) and (10) which can be written in the form E pz p0q, z ptf qq  0 R2n if tf is xed and E pz p0q, tf , z ptf qq  0 R2n1 if tf is free. Finally we obtain the two points boundary value problem (TPBVP)

pT P BV P q

"

Let be z pt, z0 q the solution of the Cauchy problem

9 z  H pt, z q E pz p0q, tf , z ptf qq  0

(15)

9 z ptq  Hr pt, z ptqq, z p0q  z0

(16)

and let dene, in the case of xed tf , the simple shooting function S by S : R2n z0 The problem (15) is then equivalent to

R2n E pz0 , z ptf , z0 qq

S pz0 q  0.

Therefore the simple shooting method consists in nding a zero of the function S. We use the fortran Newton method H YBRJ (from the M INPACK library) to solve this non linear equation. A simple example of smooth OCP is detailed in IV-A. Remark 7. If the nal time is free, then tf is one more variable of the shooting function and we add the transversality condition on the Hamiltonian (8). C. OCP with Bang/Singular arcs and multiple shooting method In comparison to simple shooting, multiple shooting splits the interval r0, tf s in N intervals rti , ti1 s and has the values z pti q at the beginning of each sub-interval as unknowns. Then one has to take into account some matching conditions in each instant ti (continuity condition). The goal is to improve the stability of the method. In the case where there are some switchings arcs and where the smoothness of the control u is lost, the multiple shooting is used and the instants ti become the switching times. The Pontryagin maximum principle gives conditions on the limits on the state and the adjoint vector and on the Hamiltonian when tf is free. By limits, we mean at the initial time, the nal time and the switching times. Therefore we write in the case of xed tf this multiple boundary value problem (MBVP)

$ ' ' ' ' ' ' ' ' ' ' ' & pM BV P q ' ' ' ' ' ' ' ' ' ' ' %

9 z ptq  Hi pt, z q

for for for

t rti , ti1 s i  0, . . . , N i  0, . . . , N

z pti q  zi mpz pti1 , ti , zi q, zi1 q  0

1 2
(17)

b0 pz0 q  0 Rn j ptik , zik q  0 with ik bf ptf , z ptf , tN 1 , zN 1 qq  0 Rn .

v0, N w

HAMPATH MANUAL.

with Hi pt, z q the Hamiltonian vector eld on each sub-interval, ti , i  1, . . . , N 1 and zi , i  0, . . . , N 1 the unknowns of the problem. The third equation is the matching conditions where z pti1 , ti , zi q is the solution of the Cauchy problem 9 z ptq  Hi pt, z ptqq, z pti q  zi (18) In general, these matching equations become mpz pti1 , ti , zi q, zi1 q  z pti1 , ti , zi q zi1

0

(19)

and are just continuity conditions. b0 and bf are the boundary equations. Note that the switching conditions are written j ptik , zik q  0, ik v0, N w. It is because you can have more than one condition at a time tik . However, in presence of a Bang-Bang problem, these equations become pti , zi q  0, i  1, . . . , N 1. Let now dene  T i  tt1 , . . . , tN 1 u  Zi  tz0 , . . . , zN 1 u  expZi  tz pt1 , t0 , z0 q, . . . , z ptf , tN 1 , zN 1 qu Then all the conditions m, b0 , bf and l can be put together in an equation function of the form E pZi, T i, expZiq  0 R2nN N 1 if tf is xed. In this case, the multiple shooting function S is S : R2nN N 1 pT i, Ziq

R2nN N 1 E pZi, T i, expZiq

The problem (17) is then equivalent to S pT i, Ziq  0. Therefore the multiple shooting method consists in nding a zero of the function S. We use again H YBRJ to solve this non linear equation. An example with Bang-Bang structure is detailed in IV-B. Remark 8. If the nal time is free, T i  tt1 , . . . , tN 1 , tf u and we add the transversality condition on the Hamiltonian (8). D. OCP depending on parameters and homotopic method The optimal control problem may have some parameters either mathematical or physical. Indeed the difculty of shooting method is to have a good initial point because of the low convergence radius of the Newton algorithm. Continuation method may be used to transform the initial problem, which may be difcult to solve, into a family of easier problems such that the solutions of these problems converge to the initial one. A problem of contrast in imaging by NMR is presented in [4]. The problem is non-smooth and so penalized to get more regularity. The continuation gives an approximation of the solution of the original problem. Homotopy can also be used to catch the structure of a Bang-Bang or Bang-Singular OCP. In [6] is detailed two examples. The rst one presents an orbital transfer where an homotopy from the minimal time problem to the minimum fuel consumption (Bang-Bang) problem is performed. The second example studies the energy minimization problem for two-level dissipative quantum systems and uses continuation on physical parameters which characterize the kind of particles involved. The parameters can be found in any equation or function of the optimal control problem. Finally, the optimal control problems which can be solved by H AMPATH are of the form

$ t ' M in gptf , xptf q, q 0 f 0pt, xptq, uptq, qdt ' ' ' ' ' & 9 m pPq ' xptq  f pt, xptq, uptq, q , uptq U R , R ' ' b0pxp0q, q  0 Rn , n0 n ' ' ' % n
f

(20)

bf ptf , xptf q, q  0 R

, n1

HAMPATH MANUAL.

As a consequence, the shooting function either on the smooth or non-smooth case, depends on the parameter . Let consider the smooth case for a sake of convienence. For now, the goal is not to solve one optimal control problem but to compute the zeros path of the homotopic function S : R2n r0, 1s pz0, q

R2n S pz0, q

where S is nonlinear and smooth (even with non-smooth control). Assuming that 0 is a regular value for S, the solution set of S pcq  0, c  pz0 , q is made of smooth curves. Thanks to arc length parametrization 9 and some regularity conditions on the jacobian of S, the tangent vector cpsq of the path can be computed and it is unique modulo the sign. Finally, H AMPATH uses D OPRI 5 from E. Hairer and G. Wanner [8] [9], for the numerical integration of the following (IVP):

pIV P q

"

9 cpsq  T pcpsqq 0 cp0q  pz0 , 0q

Until sf such as psf q  1 (the dense output of the integrator is used). The time s is the arc length. To compute the tangent vector, the jacobian of the homotopic function S is needed. There is still one call to the shooting method for the intial point in  0. Then there is no correction like in the well known Prediction-Correction method (Allgower and Georg. [2]). The following diagram represents the zeros path of the homotopic function.
f pz0 , 1q

c s 9

pq

0 pz0 , 0q

z0

Remark 9. The OCP may depend on a vector parameter Rk , k 1. As a consequence, we replace the notation P by P . An homotopy on several parameters (from 0 to f for instance) can be computed using a scalar reparametrization. This can be done by adding a scalar parameter such as  0 when  0 and  f when  1. The afne homotopic function pq  p1 q0 f is a simple example of such a parametrization. You can nd more details on homotopy on several parameters at the end of III-E. Remark 10. The mathematical framework of homotopic method in H AMPATH is discussed in [6]. In this paper, regular control problems in the sense of Legendre condition are dened, and second order necessary and sufcient optimality conditions in this class are reviewed. Adding a scalar homotopy parameter, differential pathfollowing is introduced. The previous sufcient conditions ensure the deniteness and regularity of the path. The role of automatic differentiation for the implementation of this approach is discussed, and two examples excerpted from quantum and space mechanics are detailed. E. User implementation and the M ATLAB package The user only needs to code in F ORTRAN the true Hamiltonian Hr of the system (2) and the function E dened in III-B and III-C . Before that, he must have applied the Pontryagin maximum principle to get the control upx, pq and the transversality conditions if any. The le hfun.f90 must contain the true Hamiltonian and efun.f90 the function E. Then while compiling using the command hampath in the

HAMPATH MANUAL.

problem directory (try hampath -help (0a) for documentation) H AMPATH generates the M ATLAB functions which code, among others, the shooting function and its jacobian (by automatic differenciation and using variationnal equations) and the shooting and homotopic method. At A are detailed all the M-files created. The code of the fortran subroutine hfun (in hfun.f90) is :
Subroutine hfun(t,n,z,nbarc,iarc,lpar,par,H) implicit none integer :: n,lpar,iarc,nbarc real(kind=8) :: t real(kind=8), dimension(2*n) :: z real(kind=8), dimension(lpar) :: par real(kind=8) :: H IF (nbarc.NE.0) THEN CALL MEXERRMSGTXT(Error: number of arcs should be 0.) END IF IF (n.NE.0) THEN CALL MEXERRMSGTXT(Error: state dimension should be 0.) END IF IF (lpar.NE.0) THEN CALL MEXERRMSGTXT(Error: par dimension should be 0.) END IF H = ... end subroutine hfun

where : t is the current time. n is the dimension of the state x. z is a vector containing the state and the adjoint vector : z  px, pq. nbarc is the number or different arcs. In the smooth case nbarc  1. 9 iarc is the index of the current arc : z ptq  Hiarc pt, z q. lpar is the number of additionnal parameters. par is a vector containing the lpar parameters. Under the notation Rk , par H is the only output. It returns the value of the true Hamiltonian Hr,iarc pt, z q.

 and lpar  k.

Obviously, the Hamiltonian may be time dependent. Moreover, additional parameters may be used (see remark 13). Note that, for the sake of robustness, dimensions are checked (MEXERRMSGTXT calls). The code of the fortran subroutine efun (in efun.f90) is :
Subroutine efun(nbarc,n,Ti,Zi,expZi,lpar,par,ne,E) implicit none integer :: nbarc,n,ne,lpar real(kind=8), dimension(nbarc+1) :: Ti real(kind=8), dimension(2*n,nbarc) :: Zi real(kind=8), dimension(2*n,nbarc) :: expZi real(kind=8), dimension(lpar) :: par real(kind=8), dimension(ne) :: E IF (ne.NE.0) THEN CALL MEXERRMSGTXT(Error: equations dimension should be 0.) END IF IF (nbarc.NE.0) THEN CALL MEXERRMSGTXT(Error: number of arcs should be 0.) END IF

HAMPATH MANUAL.

10

IF (n.NE.0) THEN CALL MEXERRMSGTXT(Error: state dimension should be 0.) END IF IF (lpar.NE.0) THEN CALL MEXERRMSGTXT(Error: par dimension should be 0.) END IF E = ... end subroutine efun

where : nbarc is the number or different arcs. In the smooth case nbarc  1. n is the dimension of the state x. Ti is a vector containing the different instants : T i  pt0 , t1 , . . . , tnbarc1 , tf q. Note that t0 is xed, tf may be xed or free and all others instants are free. Zi is a matrix containing all the states and the adjoint vectors at each instant except tf : Zi  pz0, . . . , znbarc1q. expZi is a matrix containing all the extremals : expZi  pz pt1 , t0 , z0 q, . . . , z ptf , tnbarc1 , znbarc1 qq. lpar is the number of additionnal parameters. par is a vector containing the lpar parameters. Under the notation Rk , par  and lpar  k. ne is the dimension of the matrix E, i.e. the number of equations. E is the only output. It represents all the conditions, i.e. the initial, the nal and the matching and the transversality if any.

Finally, from the true hamiltonian and all the conditions, H AMPATH :  produces automatically the state-costate equations (thanks TAPENADE)  computes the shooting function by numerical integration (thanks D OPRI 5)  provides the VARiationnal equations (in [10] are compared variationnal equations with classical nite differences) used in the jacobian of the shooting function (thanks TAPENADE)  integrates the variationnal equations so that this diagram commutes
Numerical integration pIV P q S pz, q 0

Derivative

Derivative

Numerical integration pV ARq

fS fz0 pz0 , q

The following diagram resumes the main functionnalities of the H AMPATH package :

HAMPATH MANUAL.

11

efun E pTi , Zi , expZi, q TAPENADE

hfun Hr pt, z, q

F ORTRAN 90

dE

p ffH , ffH q p x
r r

TAPENADE

dH

D OPRI 5 VAR S pti , zi , q D OPRI 5 VAR D OPRI 5

S I pti , zi , q H YBRJ

T pS I pti , zi , qq D OPRI 5

ssolve shooting method

M ATLAB functions Available for use

hampath continuation method

expdhvf un variational equations

The following M-files are provided with the package (note that you can nd a complete description of the functions in the annexes A) : discont.m expdhvfun.m exphvfun.m hampath.m hampathget.m hampathset.m hfun.m hvun.m hybrd.m hybrdget.m hybrdset.m sfun.m sjac.m ssolve.m : : : : : : : : : : : : : : a discrete homotopic method. integrates the variational (4) and the hamiltonian (2) systems, with a relevant initial conditions. computes the mapping expt p.q and so integrates the hamiltonian (2) system. the differential homotopic method. gets hampath package options. sets options for hampath package. the Hamiltonian Hr . the vector eld Hr . is an interface of the fortran hybrd method from M INPACK which is based on a Newton type algorithm. gets hybrd options. sets hybrd options. the shooting function S. the jacobian of the shooting function S. the shooting method.

Remark 11. Only the hfun subroutine is required. In the case where the efun.f90 le is omitted, then H AMPATH does not produce the M ATLAB functions discont, hampath, sfun, sjac and ssolve. Only hfun, hvfun, exphvfun, expdhvfun, hybrd and the options setting are available. Note that you can perform homotopies on several parameters using a scalar reparametrization of the problem (P ). In this case, it is required to have a function pq, R such that p0q  0 and p1q  f . The function pq can be explicitly written in hfun and/or efun but this implies to add a parameter to the variable par. To avoid the issue of the additionnal parameter , H AMPATH allows the user to implement the function parfun (coding p.q) separately from hfun and efun. The subroutine parfun should be written in a le parfun.f90. However, a default subroutine parfun coding

HAMPATH MANUAL.

12

pq  p1 q0 f is integrated in H AMPATH. As a consequence, the le parfun.f90 is not needed if the user wants to do an afne homotopy on the parameters. The code (where  par) in the default parfun.f90 le is : Subroutine parfun(lambda,lpar,par0,parf,par) implicit none integer :: lpar real(kind=8) :: lambda !current scalar homotopic parameter real(kind=8), dimension(lpar) :: par0 !initial parameters real(kind=8), dimension(lpar) :: parf !final parameters real(kind=8), dimension(lpar) :: par par = (1d0-lambda)*par0 + lambda*parf Homotopy on the nal time tf is possible. The time variable t has to be changed in s such as t  t0 ptf t0 qs  tf s and tf becomes a new parameter of the vector par. The state x and the control u have a new parametrization in s and so xptq  xpsq and uptq  upsq and the problem (20) becomes : end subroutine parfun

$ M in gpt , xp1q, q t .f ps, xpsq, upsq, qds ' ' ' & pP q ' xpsq  t .f ps, xpsq, upsq, q , upsq U R , R ' b pxp0q, q  0 R , n n ' % b pt , xp1q, q  0 R , n n
f 1 0 f 0
9

(21)

n0

n1

IV. E XAMPLES A. Example 1 : a simple problem

We go back to the initial example from I and proceed in 7 steps. Note that it can be downloaded at http://apo.enseeiht.fr/ hampath/resources/specic/dyn/simple example.tar. Let remind the statement of the problem :

pP,

$ ' M in u dt ' xv & q ' v  v u ' xp0q  1; xp1q  0 % vp0q  ; vp1q  0.
1 0 2
9 9

(22)

We rst dene the true Hamiltonian and the conditions according to the Pontryagin maximum principle. Then we solve the problem for  0 and  1 using the shooting method and we compute the zeros path solution of pP, q for r0, 1s and  1. After that, we plot the zeros path and the extremal solution of pP1,1 q with the control associated. Finally we check the order two conditions of optimality by checking a rank condition on a particular matrix. The two rst steps correspond to the F ORTRAN part and the last ve are the M ATLAB steps present in the main.m le.

Dening the true Hamiltonian

The user needs to provide rst the F ORTRAN subroutine hfun coding the true Hamiltonian which is in this case Hr pz q  H pz, upz qq  upz q2 px v pv pv upz qq with upz q  pv {2 and z  pq, pq  px, v, px , pv q R4 . The code essentially amounts to : Subroutine hfun(t,n,z,nbarc,iarc,lpar,par,H) !variables declaration !dimensions checking lambda = par(1) x = z(1) v = z(2) px = z(n+1) !n=2 pv = z(n+2) u = pv/2 H = -u**2 + px * v + pv * (-lambda*v+u) end subroutine hfun

HAMPATH MANUAL.

13

Dening the function E

The second F ORTRAN subroutine required from the user is efun which codes all the limits conditions. In this case, there is no additional transversality conditions because the state is completely xed and the nal time is not free. The main part of the code is : Subroutine efun(nbarc,n,ti,zi,expzi,lpar,par,ne,E) !variables declaration !dimensions checking mu = par(2) x0 = zi(1,1) v0 = zi(2,1) xf = expzi(1,nbarc) !nbarc=1 vf = expzi(2,nbarc) E = (/ x0 + 1, v0 - mu, xf, vf/) !initial and final conditions end subroutine efun For now the command hampath may be used to compile the problem. H AMPATH produces some MEX-files callable from M ATLAB and stored in the current directory. It also creates a startup.m le which adds the HAMPATH_HOME path to the matlab variable path automatically when M ATLAB is launched. Remark 12. The mex compilation is customized in the standard ways, for instance by putting a user dened mexopts.sh le in the problem directory. Remark 13. Almost all the M ATLAB commands provided in the package (sfun, ssolve, exphvfun . . . ) have the variable par which permits to pass the additional parameters to the F ORTRAN subroutines hfun and efun. They can be used as homotopic parameters or constant values.

Dening M ATLAB problem Initialization

We dene the hampath options (see hampathget (0f) and hampathset (0g) functions) for our problem. We set the tolerances, the display but also we make the nal time to be xed. options = hampathset( ... xtol abstol reltol abstolham reltolham lengthstepmin maxsteps normesfunmax ode odeham sfmax densetol freefinaltime display dispiter ,1e-8 , ,1e-14 , ,1e-8 , ,1e-14 , ,1e-8 , ,1e-8 , ,1e5 , ,1e-3 , ,dopri5, ,dopri5, ,1e5 , ,1e-8 , ,false , ,on , ,1 ... ... ... ... ... ... ... ... ... ... ... ... ... ... )

% fixed tf

Computing the solution z0 such that S0,1 pz0 q  0

(see the ssolve (0n) function) t0 = 0.0; lambda0 = 0.0; mu = -1.0; par0 x0i tf = 1.0;

= [lambda0 mu]; = [-1.0 mu] ;

HAMPATH MANUAL.

14

p0i z0i

= [0.0 0.0] ; %the initial guess for the adjoint vector = [x0i p0i];

[ t, z0, s, nfev, njev, iflag] = ssolve([t0 tf],z0i,options,par0);

Computing the zeros path such that S1 pz0 , q  0, r0, 1s

(see the hampath (0e) function) lambdaf = 1.0; parf = [lambdaf mu]; % parf(1) is not equals to par0(1) and parf(2)=par0(2) % => continuation on lambda [ parout, tout, zout, ... ] = hampath([par0 parf],[t0 tf],z0,options);

Plotting solutions
(see the exphvfun (0d) function) lout = parout(1, :); z0f = zout(:,end); parf = parout(:,end); % each lambda at each step of the continuation % the vector z0 at the end of the continuation (lambda=1) % the final vector of parameters : parf = (lambdaf,mu)

% Paths figure; subplot(2,5,1);plot(zout(3,:),lout,k);xlabel(p_1(0));ylabel(\lambda); title(Paths); subplot(2,5,6);plot(zout(4,:),lout,k);xlabel(p_2(0));ylabel(\lambda); % Extremal Solution [ tout, exphv, flag ] = exphvfun([t0 tf], z0f, options, parf); subplot(2,5,2);plot(tout,exphv(1,:),b);xlabel(t);ylabel(x_1(t)); title(State solution); subplot(2,5,3);plot(tout,exphv(3,:),b);xlabel(t);ylabel(p_1(t)); title(Co-state solution); subplot(2,5,7);plot(tout,exphv(2,:),b);xlabel(t);ylabel(x_2(t)); subplot(2,5,8);plot(tout,exphv(4,:),b);xlabel(t);ylabel(p_2(t)); % Control u = control(exphv); subplot(2,5,[4 5]);plot(tout,u,r);xlabel(t);ylabel(u(t)); title(Control);

Computing Jacobi elds and checking optimality

(see the expdhvfun (0c) function) n = k = dz0 dz0 length(z0i)/2; n; = [ zeros(n) ; eye(n)]; = [ z0f dz0 ]; % regular case, k = n : fixed tf

[ tout, expdhv, iflag ] = expdhvfun([t0 tf], dz0, options, parf); z = expdhv(:, 1:(k+1):end); sv=[]; de=[]; for j = 1:length(tout) dx = expdhv(1:n, (2+(j-1)*(k+1)):(j*(k+1)));

HAMPATH MANUAL.

15

sv(j) = min(svd(dx)); de(j) = det(dx); end; subplot(2,5,[9 10]); plot(tout,sv,m) ; hold on; plot(tout,max(sv)*sign(de),k--); hold on; xlabel(t); legend(\sigma_m_i_n,sign(det(\delta x)),location,West); title(Conjugate points); For now you can execute the main.m le in M ATLAB and get some texts results and the gure 1.

B. Example 2 : a Bang-Bang problem

Let consider the optimal control problem (22) with minimal time cost. Note that it can be downloaded at http://apo.enseeiht. fr/hampath/resources/specic/dyn/multiple example.tar. The statement of the problem is :

pP,

$ M in t ' ' xv ' & v q ' vu 1 u | ' xp|0q  1; xpt q  0 ' % vp0q  ; vpt q  0.
f
9 9

(23)

According to the Pontryagin maximum principle, this problem is Bang-Bang and it has at most one switch. Let x the parameters to 0 and to 1. Then the control is uptq  1 for any t r0, t1 s and uptq  1 for any t rt1 , tf s, where t1 is the switching time. The PMP gives us the following conditions we can compare with the results from H AMPATH :

$ p p.q is constant and ' ' p p0q  1 c  1.8164 & c ' t  1 c  2.2247 ' %
x v 2 6 1

equals to

2 c6

 0.8164
(24)

tf

1

6 2

6  3.4494

We rst need to dene the shooting function (according to the description in H. Maurers article [11]). To do that we must code the Hamiltonian Hr and the limits conditions E. Then we use the multiple shooting method to solve the problem P0,1 and we nally plot the curves solution of the problem.

The true Hamiltonian is Hr pt, z q  H pt, z, upt, z qq  1 px v pv pv upt, z qq with upt, z q  1 for any t and upt, z q  1 for any t rt1 , tf s with z  pq, pq  px, v, px , pv q R4 . The code essentially amounts to : Subroutine hfun(t,n,z,nbarc,iarc,lpar,par,H) !variables declaration !dimensions checking lambda = par(1) x = z(1) v = z(2) px = z(n+1) pv = z(n+2) if(iarc.eq.1)then u = 1d0 !t in [0,t1] else u = -1d0 !t in [t1,tf] end if H = -1d0 + px * v + pv * (-lambda*v+u) end subroutine hfun

Dening the true Hamiltonian

r0, t1 s

HAMPATH MANUAL.

16

Dening the function E

The function E contains the initial and the nal conditions on the state, the matching condition at t1 , the switching condition (pv pt1 q  0) and the transversality condition on the Hamiltonian (Hr  0) because the nal time is free. The main part of the code is : Subroutine efun(nbarc,n,ti,zi,expzi,lpar,par,ne,E) !variables declaration !dimensions checking x0 = zi(1,1 ) v0 = zi(2,1 ) xf = expzi(1,nbarc ) vf = expzi(2,nbarc ) z1 = zi(:,nbarc ) pv1 = z1(2+n ) expz1 = expzi(:,nbarc-1) expzf = expzi(:,nbarc ) mu = par(2) call hfun(ti(nbarc+1),n,expzf,nbarc,nbarc,lpar,par,hf) E(1) = x0 + 1 E(2) = v0 - mu E(3) = xf E(4) = vf E(5:8) = z1 - expz1 E(9) = pv1 E(10) = hf end subroutine efun

!matching conditions !switching condition !transversality condition

For now the command hampath may be used to compile the problem.

Dening M ATLAB problem Initialization

We dene the hampath options (see hampathget (0f) and hampathset (0g) functions) for our problem. We set the tolerances, the display but also we make the nal time to be free. options = hampathset( ... xtol abstol reltol ode densetol freefinaltime display ,1e-8 , ,1e-14 , ,1e-8 , ,dopri5, ,1e-8 , ,true , ,on ) ... ... ... ... ... ...

% free tf

Computing the solution pTi , Zi q such that S0,1 pTi , Zi q  0

(see the ssolve (0n) function) lambda mu par t0 t1 tf Ti x0 p0 = 0.0 = -1.0 = [lambda mu] = 0.0 = 1.0 = 2.0 = [t0 t1 tf] = [-1.0 mu] = [ 0.1 0.1] ; ; ; % ;% ;% ;% ; Solution t0 = 0.0 t1 = 1.0+sqrt(6)/2 tf = 1.0+sqrt(6)

; ;% p0 = [2.0/sqrt(6) 1.0+2.0/sqrt(6)]

HAMPATH MANUAL.

17

z0 [ tout, z1 Zi

= [ x0 p0] ; exphv, iflag ] = exphvfun(Ti, z0, Ti, options, par); = exphv(:,2) ; = [ z0 z1] ;

[ Ti, Zi, s, nfev, njev, iflag] = ssolve(Ti,Zi,options,par);

Plotting solutions
(see the exphvfun (0d) function) % Extremal solution z0 = Zi(:,1); tspan = linspace(Ti(1),Ti(2),101) ; tspan = [tspan(1:end-1) linspace(Ti(2),Ti(3),100)]; % tspan = [t0 ... t1 ... tf] and length(tspan)=200 [ tout, exphv, iflag ] = exphvfun(tspan, z0, Ti, options, par); subplot(2,3,6);plot(exphv(1,:),exphv(2,:),b);axis([-2 2 -2 2]);daxes(0,0,k--); xlabel(x(t));ylabel(v(t));title(Phase portrait); subplot(2,3,1);plot(tout,exphv(1,:),b);xlabel(t);ylabel(x(t)) ; title(State solution); subplot(2,3,2);plot(tout,exphv(3,:),b);xlabel(t);ylabel(p_x(t)) ; title(Co-state solution); subplot(2,3,4);plot(tout,exphv(2,:),b);xlabel(t);ylabel(v(t)) ; subplot(2,3,5);plot(tout,exphv(4,:),b);xlabel(t);ylabel(p_v(t)) ; % Control [tout,u] = control(tout,exphv,Ti,par); subplot(2,3,3);plot(tout,u,r);xlabel(t);ylabel(u(t)); title(Control); For now you can execute the main.m le in M ATLAB and get some texts results and the gure 2. H AMPATH provides the following results which match with (24).

$ p p.q is constant and ' & p p0q  1.81649658092773 ' t  2.22474487139159 % t  3.44948974278318
x v 1 f
State solution 0 2 1.5 0.5 p (t) 1 x(t)

equals to 0.816496580927726 (25)

Costate solution 1

Control

0.5 u(t)

0.5 1 0 1.5 0.5 0.5

2 t

2 t

2 t Phase portrait

1.5 1 0.5 v(t) 0 0.5 1

2 1.5 1 p (t) v(t) 0 2 t 4 0.5 0 0.5 1 0 2 t 4 1.5

2 2

0 x(t)

Fig. 2. Results for the multiple example.

HAMPATH MANUAL.

18

A PPENDIX a) hampath -help:

NAME hampath : generates mex files WEB SITE http://apo.enseeiht.fr/hampath VERSION 2011 SYNOPSIS hampath OPTIONS DESCRIPTION hampath generates a bunch of mex files from the fortran files hfun.f90, efun.f90 and parfun.f90 and creates the startup.m. These mex files are called by matlab functions, press help hampathfun in your Matlab program to see all the existing functions (available or not) or check the mex-files present in the output directory. OPTIONS -install Create all static librairies. -hfun file or hfun=file hfun.f90 file. if -hfun option is omitted, hampath search hfun.f90 in the current directory. -efun file or efun=file efun.f90 file. if -efun option is omitted, hampath search efun.f90 in the current directory. if there is no efun.f90 file, some mex-files are not compiled. -parfun file or parfun=file parfun.f90 file. if -parfun option is omitted, hampath search parfun.f90 in the current directory. if there is no parfun.f90 file in the current directory, hampath use the default. -o directory or output=directory output directory where mex files and startup.m are put. if -o option is omitted, hampath put files in the current directory. -m file or mexopts=file mexopts.sh file used for compilation. if -m option is omitted, hampath search mexopts.sh in the current directory. If hampath didnt find it, it lets mex find itself. -help AUTHORS Jean-Baptiste Caillau, Olivier Cots, Joseph Gergaud. REPORTING BUGS olivier.cots@u-bourgogne.fr

HAMPATH MANUAL.

19

b) discont.m:
% discont -- discrete homotopic method (needs efun.f90 and hfun.f90). % % Usage % [ lout, tiout, ziout, normS, flag ] = discont(parspan,ti,zi,options) % % Inputs % parspan real matrix, parspan = [par0 parf] : parspan(:,i) is a vector of parameters given to hfun and efun. Hampath performs an homotopy from par0 to parf. The homotopy is of the form : (1-lambda)*par0 + lambda*par. % ti real row vector, ti = [t0 tf] : simple shooting % , ti = [t0 t1 ... t_nbarc-1 tf] : multiple shooting % zi real matrix, shooting variable, zi = [z(t0) ... z(t_nbarc-1)] % options struct, hampathset options % % Outputs % parout real matrix, parameters at each integration step. % tiout real vector, tiout((k-1)*(nbarc+1):k*(nbarc+1))= ti_k : ti at lout(k) % ziout real matrix, zout(:,(k-1)*nbarc:k*nbarc) = zi_k : zi at lout(k) % normS real vector, |S(z)| at each accepted step % flag integer vector, size(flag) should equal size(lin)-1 % flag(i) should be 1 (ssolve output). % flag(i)==-2 : maxsteps is reached. % flag(i)==-1 : step size became too small (LengthStepMin) % % Description % Matlab interface of discrete homotopic method. % % Options hampathset used % MaxSteps, LengthStepMin and ssolve method options % % See also % ssolve

HAMPATH MANUAL.

20

c) expdhvfun.m:
% expdhvfun -- Exponential of dhv/dz (needs hfun.f90) % % Usage % [ tout, expdhv, flag ] = expdhvfun(tspan, dz0, options, par) % [ tout, expdhv, flag ] = expdhvfun(tspan, dz0, ti, options, par) : multiple shooting % % Inputs % tspan real row vector, tspan = [tspan1 tspan2 ... tspanf], tspan must be sorted and included in ti, if any. % dz0 real matrix, initial flow : dz0 = [z dz] % ti real row vector, ti = [t0 t1 ... t_nbarc-1 tf] in multiple shooting case , ti must be increasing. % options struct vector, hampathset options % par real row vector, parameters given to hfun : par=[] if no parameters % % Outputs % tout real row vector, time at each integration step % (or tout=t if length(t)>2) % expdhv real matrix, flow at time tout % flag integer, flag should be 1 (ODE integrator output). % % Description % Computes the (right) chronological exponential of the variational system associated to hv. % % Options hampathset used % ODE, AbsTol, RelTol, MaxSteps % % See also % hampathset, hampathget

HAMPATH MANUAL.

21

d) exphvfun.m:
% exphvfun -- Exponential of hv (needs hfun.f90) % % Usage % [ tout, exphv, flag ] = exphvfun(tspan, z0, options, par) % [ tout, exphv, flag ] = exphvfun(tspan, z0, ti, options, par) : multiple shooting % % Inputs % tspan real row vector, tspan = [tspan1 tspan2 ... tspanf], tspan must be sorted and included in ti, if any. % z0 real vector, initial flow % ti real row vector, ti = [t0 t1 ... t_nbarc-1 tf] in multiple shooting case , ti must be increasing. % options struct vector, hampathset options % par real row vector, parameters given to hfun : par=[] if no parameters % % Outputs % tout real row vector, time at each integration step % (or tout=t if length(t)>2) % exphv real matrix, exphv(:,i) : flow at tout(i) % flag integer, flag should be 1 (ODE integrator output). % % Description % Computes the chronological exponential of the Hamiltonian % vector field hv defined by h. % % Options hampathset used % ODE, AbsTol, RelTol, MaxSteps % % See also % hampathset, hampathget

HAMPATH MANUAL.

22

e) hampath.m:
% hampath -- homotopic method (needs efun.f90 and hfun.f90) % % Usage % [ lout, tiout, ziout, sout, viout, bifs, dets, normS, ps, flag ] = hampath( parspan,ti,zi,options) % % Inputs % parspan real matrix, parspan = [par0 parf] : parspan(:,i) is a vector of parameters given to hfun and efun. Hampath performs an homotopy from par0 to parf. The homotopy is of the form : (1-lambda)*par0 + lambda*parf, unless a fortran file with the subroutine parfun(lambda,lpar,par0,parf,parout), with lambda from 0 to 1, is provided. % ti real row vector, ti = [t0 tf] : simple shooting % , ti = [t0 t1 ... t_nbarc-1 tf] : multiple shooting % zi real matrix, shooting variable, zi = [z(t0) ... z(t_nbarc-1)] % options struct, hampathset options % % Outputs % parout real matrix, parameters at each integration step. % tiout real vector, tiout((k-1)*(nbarc+1):k*(nbarc+1)) = ti_k : ti at lout(k) % ziout real matrix, zout(:,(k-1)*nbarc:k*nbarc) = zi_k : zi at lout(k) % sout real vector, arc length at each integration step % viout real matrix, viout(:,k) = dot_c(:,k) : tangent vector at lout(k) where c(:,k) = [z0 ... z_nbarc-1 t1 ... t_nbarc-1 tf lambda], no tf if fixed % bifs cell array, bifs{i} is the i-th bifurcation information % bifs{i}.s : arclength % bifs{i}.c : [z0 ... z_nbarc-1 t1 ... t_nbarc-1 tf lambda], no tf if fixed % bifs{i}.v1 : first tangent vector % bifs{i}.v2 : second tangent vector % dets real vector, det(S(c(s)),c(s)) at each integration step % normS real vector, |S(c(s))| at each integration step % ps real vector, <c(s_old),c(s_new)> at each integration step % flag integer, flag should be 1 (ODE integrator output). % if flag==0 then options.Sfmax is too small. % if flag==-1 then input is not consistent. % if flag==-2 then larger options.MaxSteps is needed. % if flag==-3 then step size became too small. % if flag==-4 then problem is problably stiff. % if flag==-5 then |S| is greater than options.NormeSfunMax. % % Description % Matlab interface of homotopic method. % % Options hampathset used % ODE, AbsTol, RelTol, ODEHam, AbsTolHam, RelTolHam, MaxSteps, % Tf, Display, Sfmax, DispIter, DenseTol, NormeSfunMax % % See also % hampathset, hampathget

HAMPATH MANUAL.

23

f) hampathget.m:
% hampathget -- Gets hampath package options. % % Usage % value = hampathget(options, name) % % Inputs % options struct, options % name string, option name % % Outputs % value any, option value % % Description % Options names are: % AbsTol - Absolute error tolerance [ 1e-14 ] % AbsTolHam - Absolute error tolerance for homotopy [ 1e-14 ] % DenseTol - Relative Dense output tolerance [ 1e-8 ] % DispIter - Display each mod(iter,DispIter)==0 [ 0 ] % Display - Display results [ off | {on}] % FreeFinalTime- Problem with fixed or free final time [true | {false}] % LengthStepMin- Step minimum length (for discont) [ 1e-5 ] % MaxSteps - Integrator max steps [ 1e5 ] % NormeSfunMax - Sfun maximal norm for hampath [ 1e-1] % ODE - Integrator name for variational equations % ODEHam - Integrator name for homotopy % - ODE name available [dopri5 ] % RelTol - Relative error tolerance [ 1e-8 ] % RelTolHam - Relative error tolerance for homotopy [ 1e-8 ] % Sfmax - Maximum final arc length [ 1e5 ] % XTol - Relative tolerance between iterates (ssolve) [ 1e-8 ] % % See also % hampathset

HAMPATH MANUAL.

24

g) hampathset.m:
% hampathset -- Sets options for hampath packages. % % Usage % options = hampathset(name1, value1, ...) % % Or % options = hampathset(oldopts, name1, value1,...) creates a copy of % oldopts with the named parameters altered with the specified values. % % Inputs % name1 string, option name % value1 any, option value % ... % % Outputs % options struct, options % % Description % Options names are: % AbsTol - Absolute error tolerance [ 1e-14 ] % AbsTolHam - Absolute error tolerance for homotopy [ 1e-14 ] % DenseTol - Relative Dense output tolerance [ 1e-8 ] % DispIter - Display each mod(iter,DispIter)==0 [ 0 ] % Display - Display results [ off | {on}] % FreeFinalTime- Problem with fixed or free final time [true | {false}] % LengthStepMin- Step minimum length (for discont) [ 1e-5 ] % MaxSteps - Integrator max steps [ 1e5 ] % NormeSfunMax - Sfun maximal norm for hampath [ 1e-1] % ODE - Integrator name for variational equations % ODEHam - Integrator name for homotopy % - ODE name available [dopri5 ] % RelTol - Relative error tolerance [ 1e-8 ] % RelTolHam - Relative error tolerance for homotopy [ 1e-8 ] % Sfmax - Maximum final arc length [ 1e5 ] % XTol - Relative tolerance between iterates (ssolve) [ 1e-8 ] % % See also % hampathget

HAMPATH MANUAL.

25

h) hfun.m:
% hfun -- Hamiltonian (needs hfun.f90) % % Usage % h = hfun(t, z, par) % h = hfun(t, z, ti, par) : multiple shooting % % Inputs % t real row vector, t(i) = i-th time % z real matrix, z(:,i) = i-th state and costate % ti real row vector, ti = [t0 t1 ... t_nbarc-1 tf] in multiple shooting case % par real row vector, parameters given to hfun : par=[] if no parameters % % Outputs % h real row vector, Hamiltonian at time t % % Description % Computes the Hamiltonian.

i) hvfun.m:
% hvfun -- Vector field associated to H (needs hfun.f90) % % Usage % hv = hvfun(t, z, par) % hv = hvfun(t, z, ti, par) : multiple shooting % % Inputs % t real row vector, t(i) = i-th time % z real matrix, z(:,i) = i-th state and costate % ti real row vector, ti = [t0 t1 ... t_nbarc-1 tf] in multiple shooting case % par real row vector, parameters given to hfun : par=[] if no parameters % % Outputs % hv real matrix, vector H at time t % % Description % Computes the Hamiltonian vector field associated to H.

HAMPATH MANUAL.

26

j) hybrd.m:
% hybrd -- Hybrid Powell method. % % Usage % [ x, y, iflag, nfev ] = hybrd(nlefun, x0, options, p1, ...) % % Inputs % nlefun string, function y = nlefun(x, p1, ...) % x0 real vector, initial guess % options struct vector, options % p1 any, optional argument passed to nlefun % ... % % Outputs % x real vector, zero % y real vector, value of nlefun at x % iflag integer, hybrd solver output (should be 1) % nfev number of evaluations of nlefun % % Description % Matlab interface of Fortran hybrd. Function nlefun must return % a column vector. % % See also % hybrdset, hybrdget

HAMPATH MANUAL.

27

hybrdget.m:
% hybrdget -- Gets hybrd options. % % Usage % value = hybrdget(options, name) % % Inputs % options struct, options % name string, option name % % Outputs % value any, option value % % Description % Options are: % xTol - Relative tolerance between iterates % MaxFev - Max number of function evaluations % ml - Number of banded Jacobian subdiagonals % mu - Number of banded Jacobian superdiagonals % EpsFcn - Used for FD step length computation % diag - Used for scaling if mode = 2 % mode - Automatic scaling if 1, manual if 2 % factor - Used for initial step bound % % See also % hybrd, hybrdset

[ 1e-8 [ 800 x (n+1) [ n-1 [ n-1 [ 0 [ [1 ... 1] [ 1 [ 1e2

] ] ] ] ] ] ] ]

k) hybrdset.m:
% hybrdset -- Sets hybrd options. % % Usage % options = hybrdset(name1, value1, ...) % % Inputs % name1 string, option name % value1 any, option value % ... % % Outputs % options struct, options % % Description % Options are: % xTol - Relative tolerance between iterates % MaxFev - Max number of function evaluations % ml - Number of banded Jacobian subdiagonals % mu - Number of banded Jacobian superdiagonals % EpsFcn - Used for FD step length computation % diag - Used for scaling if mode = 2 % mode - Automatic scaling if 1, manual if 2 % factor - Used for initial step bound % % See also % hybrd, hybrdget

[ 1e-8 [ 800 x (n+1) [ n-1 [ n-1 [ 0 [ [1 ... 1] [ 1 [ 1e2

] ] ] ] ] ] ] ]

HAMPATH MANUAL.

28

l) sfun.m:
% sfun -- Shooting function (needs efun.f90 and hfun.f90) % % Usage % [s, flag] = sfun(ti,zi,options,par) % % Inputs % ti real row vector, ti = [t0 tf] : simple shooting % , ti = [t0 t1 ... t_nbarc-1 tf] : multiple shooting % zi real matrix, shooting variable, zi = [z(t0) ... z(t_nbarc-1)] % options struct, hampathset options % par real row vector, par in hfun and efun : par=[] if no parameters % % Outputs % s real vector, shooting value % flag integer, should be 1 (ode output). % % Description % Computes the shooting function % % Options hampathset used % ODE, AbsTol, RelTol, MaxSteps, FreeFinalTime % % See also % hampathset, hampathget

m) sjac.m:
% sjac-- Jacobian of the shooting function (needs efun.f90 and hfun.f90) % % Usage % [fjac, flag] = sjac(ti,zi,options,par) % % Inputs % ti real row vector, ti = [t0 tf] : simple shooting % , ti = [t0 t1 ... t_nbarc-1 tf] : multiple shooting % zi real matrix, shooting variable, zi = [z(t0) ... z(t_nbarc-1)] % options struct, hampathset options % par real row vector, par in hfun and efun : par=[] if no parameters % % Outputs % s real vector, shooting value % flag integer, should be 1 (ode output). % % Description % Computes the shooting function % % Options hampathset used % ODE, AbsTol, RelTol, MaxSteps, FreeFinalTime % % See also % hampathset, hampathget

HAMPATH MANUAL.

29

n) ssolve.m:
% ssolve -- use Hybrid Powell method (needs efun.f90 and hfun.f90) % % Usage % [ tisol, zisol, s, nfev, njev, flag] = ssolve(ti0,zi0,options,par) % % Inputs % ti0 real row vector, intial guess, ti0 = [t0 tf] : simple shooting % , ti0 = [t0 t1 ... t_nbarc-1 tf] : multiple shooting % zi0 real matrix, initial guess, zi0 = [z(t0) ... z(t_nbarc-1)] % options struct vector, hampathset options % par real row vector, par in hfun and efun : par=[] if no parameters % % Outputs % tisol real row vector, ti solution % zisol real matrix, zi solution % s real vector, value of sfun at z0 % nfev integer, number of evaluations of fun % njev integer, number of evaluations of jac % flag integer, solver output (should be 1) % % Description % Matlab interface of Fortran non linear solver (hybrj). % % Options hampathset used % ODE, AbsTol, RelTol, XTol, MaxSteps, Display, FreeFinalTime % % See also % hampathset, hampathget

R EFERENCES
[1] A.A. Agrachev and Y.L. Sachkov. Control theory from the geometric viewpoint. Springer, 87, Encyclopaedia of Mathematical Sciences, 2004. [2] E.L. Allgower and K. Georg. Introduction to numerical continuation methods, volume 45 of Classics In Applied Mathematics. SIAM, 2003. [3] B. Bonnard, J.B. Caillau, and E. Tr lat. C OTCOT : short reference manual. IRIT, 2005. e [4] B. Bonnard, O. Cots, S.J. Glaser, M. Lapert, D. Sugny, and Y. Zhang. Geometric optimal control of the contrast imaging problem in nuclear magnetic resonance. IEEE transactions on automatic and control, 2011. [5] J.B. Caillau, O. Cots, and J. Gergaud. H AMPATH : on solving optimal control problems by indirect and path following methods. apo.enseeiht.fr/hampath. [6] J.B. Caillau, O. Cots, and J. Gergaud. Differential pathfollowing for regular optimal control problems. Optim. Methods Softw., 2011. [7] A. Dervieux, L. Hascoet, and V. Pascal. TAPENADE http://www-sop.inria.fr/tropics/tapenade.html. [8] E. Hairer, S.P. Nrsett, and G. Wanner. Solving Ordinary Differential Equations I, Nonstiff Problems, volume 8 of Springer Serie in Computational Mathematics. Springer-Verlag, second edition, 1993. [9] E. Hairer and G. Wanner. D OPRI 5 http://www.unige.ch/hairer/prog/nonstiff/dopri5.f. [10] P. Martinon and J. Gergaud. Using switching detection and variational equations for the shooting method. Optimal Control Applications and methods, Jan 2007. [11] H. Maurer. Numerical solution of singular control problems using multiple shooting techniques. Journal of optimization theory and applications, 1976. [12] E. Tr lat. Contr le optimal. Math matiques Concr` tes, 2005. e o e e