А.Г.Трифонов. Преобразование старых кодов в синтаксис Версии 2

С целью удобства использования новых выполняемых функций и уточнения значений входных и выходных параметров в синтаксисе Версии 2 были изменено большинство имен функций и вызывающих к их обращению последовательностей.

В конечном итоге, если требуется использовать новые версии старых функций, следует провести корректировки всех кодов с заменой старых имен функций и вызывающих последовательностей

Далее в таблице приводится список функций из тулбокса оптимизация с указанием имен, претерпевших изменение в Версии 2.

В данном разделе

приводится описание как произвести замену установки принимаемых по умолчанию параметров применительно к новым функциям optimset и optimget;

объясняется причина введения новых вызывающих последовательностей, а также их способ преобразования старых кодов;

приводятся детальные примеры перезаписи обращения к функции constr с целью вызова новой функции fmincon.

Дополнительно в данном разделе приводятся сведения по дополнению справки из М-файлов применительно к описанию значений аргументов. Например, что бы посмотреть справку к функции fmincon, следует набрать команду:

help fmincon.

Использование команд optimset и optimget

Функция optimset заменяет команду foptions по установке основных принимаемых по умолчанию параметров. По детальному описанию optimset и optimget следует обращаться к разделу Изменение принимаемых по умолчанию параметров.

Новые вызывающие последовательности

В версии 2 данного тулбокса реализованы следующие изменения в вызывающих последовательностях:

Ограничения в виде равенств, так и ограничения в виде неравенств в данном случае приводятся как отдельные входные параметры.

Линейные ограничения, так и нелинейные ограничения в данном случае приводятся как отдельные входные параметры.

Градиент целевой функции рассчитывается в той же самой функции, где и сама целевая функция, а не в отдельной функции, что обеспечивает более эффективный расчет (поскольку градиент и целевая функция часто содержат одни и те же компьютерные расчеты). Аналогично, в случае нелинейных ограничений градиент рассчитывается (в отдельном месте) совместно с функцией с нелинейными ограничениями.

Матрица Гессе может задаваться при помощи целевой функции ( данная матрица используется только в случае новых алгоритмов большой размерности).

Каждая функция определяет структуру options, что необходимо для корректировки параметров в функциях оптимизации (смотри описание функций optimset, optimget).

Флаги необходимы для указания необходимости в дополнительной информации. Данные флаги являются неотъемлемой частью структуры options:

Установка GradObj как 'on' указывает на наличие задаваемого пользователем градиента целевой функции.

Установка GradConstr как 'on' указывает на наличие задаваемого пользователем градиента ограничений данной функции.

Установка параметра Гессеr как 'on' указывает на наличие задаваемого пользователем матрицы Гессе для целевой функции.

В новых принимаемых по умолчанию выходных данных содержится информация об окончании расчетов. Введен новый принимаемый по умолчанию параметр отображения 'final'.

Каждая функция возвращает флаг окончания (exitflag), что указывает на состояние прекращения расчетов.

За исключением функции fsolve по умолчанию, когда это возможно, принимается новый метод большой размерности. Если есть необходимость в использовании прежних алгоритмов (обозначенных в других разделах данного руководства пользователя как алгоритмы средней размерности), то при помощи функции optimset параметр LargeScale устанавливается как 'off'. В случае программы fsolve по умолчанию принимается алгоритм средней размерности. Для применения алгоритма большой размерности для программы fsolve параметр LargeScale устанавливается как 'on'.

Алгоритмы условий прекращения расчетов имеет более точную настройку. Условия останова для алгоритмов большой размерности относятся к параметрам TolX and TolFun, а для кодов средней размерности эти условия присоединяются при помощи функци OR заместо AND для функций : fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve и lsqnonlin. В результате чего возможно более четко задать точность расчетов, а принимаемые по умолчанию значения отображают эти изменения.

Каждая функция теперь содержит выходную структуру, в которую включена информация о решении поставленной задачи с учетом используемой функции.

Параметр lambda сейчас является структурой, в которой каждое поле содержит множители Лагранжа для заданного типа ограничений. Для большей информации следует обращаться в раздел описания отдельных функций.

Далее в разделе приводится описание как перейти от предыдущих имен функций и вызывающих последовательностей к новым спецификациям. Такие обращения приведены для наиболее общих случаев с привлечением всех возможных значений входных и выходных аргументов. Отметим, что большинство из этих аргументов является произвольными, для большей информации следует обращаться в соответствующие разделы по описанию данных функций.

Переход от attgoal к fgoalattain

В Версии 1.5  для функции attgoal использовалось следующее обращение:

OPTIONS = foptions;
[X,OPTIONS] = attgoal('FUN',x0,GOAL, WEIGHT, OPTIONS, VLB, VUB,
'GRADFUN', P1, P2,...);

при

 [F] = FUN(X,P1,...)  и  [DF] = GRADFUN(X,P1,...).

В Версии 2 обращение к функции fgoalattain будет типа как:

OPTIONS = optimset('fgoalattain');
[X,FVAL,ATTAINFACTOR,EXITFLAG,OUTPUT,LAMBDA] =
fgoalattain(@FUN,x0,GOAL,WEIGHT,A,B,Aeq,Beq,VLB,VUB,
@NONLCON,OPTIONS,P1,P2,...);

при 

[F,DF] = FUN(X,P1,P2,...)  и NONLCON = [].

Функция fgoalattain допускает нелинейные ограничения, то поэтому обращение к функции можно определить как:

 [Cineq,Ceq,DCineq,DCeq] = NONLCON(X,P1,...)

Переход от conls к lsqlin

В Версии 1.5  для функции attgoal использовалось следующее обращение:

[X,LAMBDA,HOW] = conls(A,b,C,d,VLB,VUB,X0,N,DISPLAY);

Согласно Версии 2, перевод входных аргументов в корректный вид для функции lsqlin проводится 
путем разделения ограничений типа равенст и типа неравенств:

Ceq = C(1:N,:);
deq = d(1:N);
C = C(N+1:end,:);
d = d(N+1:end,:);

Теперь обращение к lsqlin будет как

OPTIONS = optimset('Display','final');
[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT,LAMBDA] =
lsqlin(A,b,C,d,Ceq,deq,VLB,VUB,X0,OPTIONS);

Переход от constr к fmincon

В Версии 1.5  для функции constr использовалось следующее обращение:

[X,OPTIONS,LAMBDA,HESS] =
constr('FUN',x0,OPTIONS,VLB,VUB,'GRADFUN',P1,P2,...);

при  

[F,C] = FUN(X,P1,...) и [G,DC] = GRADFUN(X,P1,...).

Согласно Версии 2, FUN иGRADFUN заменяются двумя новыми функциями:

OBJFUN, которая возвращает целевую функцию, градиент (первую производную) этой функции и матрицу 
Гессе (вторую производную).

 [F,G,H] = OBJFUN(X,P1,...)

NONLCON, которая возвращает функции для нелинейных ограничений (как ограничений типа неравенств,
 так и ограничений типа равенств) и их градиентов

 [C,Ceq,DC,DCeq] = NONLCON(X,P1,...)

Теперь обращение к fmincon будет как

% OBJFUN задает градиенти матрицу Гессе для целевой функции
% NONLCON задает градиент огрничений.
OPTIONS =
optimset('GradObj','on','GradConstr','on','Hessian','on');
[X,FVAL,EXITFLAG,OUTPUT,LAMBDA,GRAD,HESSIAN] =
fmincon(@OBJFUN,x0,A,B,Aeq,Beq,VLB,VUB,@NONLCON,OPTIONS,
P1,P2,...);

В качестве более детального примера можно обратиться к разделу "Пример перехода от constr к fmincon" 

Переход от curvefit к lsqcurvefit 

В Версии 1.5  для функции curvefit использовалось следующее обращение:

 [X,OPTIONS,FVAL,JACOBIAN] =
curvefit('FUN',x0,XDATA,YDATA,OPTIONS,'GRADFUN',P1,P2,...);

при

 F = FUN(X,P1,...) и G = GRADFUN(X,P1,...).

Согласно Версии 2 FUN и GRADFUN заменяются одной единственной функцией, которая возвращает оба
 значения F и J, целевую функцию и Якобиан (Якобиан является транспонированной функцией от градиента).

 [F,J] = OBJFUN(X,P1,...)


Теперь обращение к lsqcurvefit будет как:

OPTIONS = optimset('Jacobian','on'); % Задается Якобиан
VLB = []; VUB = []; % Нет новых аргументов в curvefit
[X,RESNORM,F,EXITFLAG,OUTPUT,LAMBDA,JACOB] =
lsqcurvefit(@OBJFUN,x0,XDATA,YDATA,VLB,VUB,OPTIONS,
P1,P2,...);

Переход от fmin  к fminbndt 

В Версии 1.5  для функции fmin использовалось следующее обращение:

 [X,OPTIONS] = fmin('FUN',x1,x2,OPTIONS,P1,P2,...);

Согласно Версии 2 обращение к fminbnd будет как:

 [X,FVAL,EXITFLAG,OUTPUT] = fminbnd(@FUN,x1,x2,...
OPTIONS,P1,P2,...);

Переход от fmins к fminsearch

В Версии 1.5  для функции fmins использовалось следующее обращение:

 [X,OPTIONS] = fmins('FUN',x0,OPTIONS,[],P1,P2,...);

Согласно Версии 2 обращение к fminsearch будет как:

 [X,FVAL,EXITFLAG,OUTPUT] = fminsearch(@FUN,x0,...
OPTIONS,P1,P2,...);

Переход от fminu к fminunc 

В Версии 1.5  для функции fminu использовалось следующее обращение:

 [X,OPTIONS] = fminu('FUN',x0,OPTIONS,'GRADFUN',P1,P2,...);

при

F = FUN(X,P1, ...) и G = GRADFUN(X,P1, ...).

Согласно Версии 2 FUN и GRADFUN заменяются одной единственной функцией, 
которая которая возвращает оба значения F и G, а так же целевую функцию и градиент.

 [F,G] = OBJFUN(X,P1, ...)

(Данная функция так же возвращает матрицу Гессе в качестве третьего выходного аргумента)

Согласно Версии 2 обращение к fminunc будет как:

OPTIONS = optimset('GradObj','on'); % Задается градиент
[X,FVAL,EXITFLAG,OUTPUT,GRAD,HESSIAN] =
fminunc(@OBJFUN,x0,OPTIONS,P1,P2,...);

Если имеются FUN и GRADFUN и нет необходимости в их перезаписи, 
то их обоих можно передать в fminunc путем их замены на поэлементные матрицы 

OPTIONS = optimset('GradObj','on'); % Задается градиент
[X,FVAL,EXITFLAG,OUTPUT,GRAD,HESSIAN] =
fminunc ({@FUN,@GRADFUN},x0,OPTIONS,P1,P2,...);

Переход к обращению для новой fsolve

В Версии 1.5  для функции fsolve использовалось следующее обращение:

 [X,OPTIONS] =
fsolve('FUN',x0,XDATA,YDATA,OPTIONS,'GRADFUN',P1,P2,...);

при

 F = FUN(X,P1,...) и G = GRADFUN(X,P1,...).

Согласно Версии 2 FUN и GRADFUN заменяются одной единственной функцией, 
которая которая возвращает оба значения F и G, а так же целевую функцию и градиент.

[F,G] = OBJFUN(X,P1, ...)

Согласно Версии 2 обращение к fsolve будет:

OPTIONS = optimset('GradObj','on'); % задается градиент
[X,FVAL,EXITFLAG,OUTPUT,JACOBIAN] =
fsolve(@OBJFUN,x0,OPTIONS,P1,P2,...);

Если имеются FUN и GRADFUN и нет необходимости в их перезаписи, то их обоих можно передать 
fsolve путем их замены на поэлементные матрицы 

OPTIONS = optimset('GradObj','on'); % задается градиент 
[X,FVAL,EXITFLAG,OUTPUT,JACOBIAN] =
fsolve({@FUN,@GRADFUN},x0,OPTIONS,P1,P2,...);

Переход к обращению для новой fzero

В Версии 1.5  для функции fzero использовалось следующее обращение:

X = fzero('F',X,TOL,TRACE,P1,P2,...);

Согласно Версии TRACE и TOL заменяются аргументы со значениями

if TRACE == 0,
val = 'none';
elseif TRACE == 1
val = 'iter';
end
OPTIONS = optimset('Display',val,'TolX',TOL);

Теперь обращение к fzero будет

[X,FVAL,EXITFLAG,OUTPUT] = fzero (@F,X,OPTIONS,P1,P2,...);

Переход от leastsq к lsqnonlin 

В Версии 1.5  для функции leastsq использовалось следующее обращение:

 [X,OPTIONS,FVAL,JACOBIAN] =
leastsq ('FUN',x0,OPTIONS,'GRADFUN',P1,P2,...);

при

 F = FUN(X,P1,...) и G = GRADFUN(X,P1, ...).

Согласно Версии 2 FUN и GRADFUN заменяются одной единственной функцией, 
которая возвращает оба значения F и J, целевую функцию и Якобиан 
(Якобиан является транспонированной функцией от градиента).

[F,J] = OBJFUN(X,P1, ...)

Новое обращение к lsqnonlin будет:

OPTIONS = optimset('Jacobian','on'); % задается Якобиан
VLB = []; VUB = []; % В leastsq нет новых аргументов
[X,RESNORM,F,EXITFLAG,OUTPUT,LAMBDA,JACOBIAN] =
lsqnonlin(@OBJFUN,x0,VLB,VUB,OPTIONS,P1,P2,...);

Переход от lp к linprog

В Версии 1.5  для функции lp использовалось следующее обращение:

[X,LAMBDA,HOW] = lp(f,A,b,VLB,VUB,X0,N,DISPLAY);

Согласно Версии 2 входные аргументы переходят в более корректную форму для linprog 
посредст-вом выделения отдельных значений ограничений типа равенств и типа неравенств

Aeq = A(1:N,:);
beq = b(1:N);
A = A(N+1:end,:);
b = b(N+1:end,:);
if DISPLAY
val = 'final';
else
val = 'none';
end
OPTIONS = optimset('Display',val);

Теперь новое обращение call linprog к  будет

[X,FVAL,EXITFLAG,OUTPUT,LAMBDA] =
linprog(f,A,b,Aeq,beq,VLB,VUB,X0,OPTIONS);

Переход от minimax к fminimax

В Версии 1.5  для функции minimax использовалось следующее обращение:

 [X,OPTIONS] =
minimax('FUN',x0,OPTIONS,VLB,VUB,'GRADFUN',P1,P2,...);

при

 F = FUN(X,P1,...) и G = GRADFUN(X,P1,...).

Согласно Версии 2 к функции fminimax можно обратиться как 

OPTIONS = optimset('fminimax');
[X,FVAL,MAXFVAL,EXITFLAG,OUTPUT,LAMBDA] =
fminimax(@OBJFUN,x0,A,B,Aeq,Beq,VLB,VUB,@NONLCON,OPTIONS,
P1,P2,...);

При

 [F,DF] = OBJFUN(X,P1,...) и
[Cineq,Ceq,DCineq,DCeq] = NONLCON(X,P1,...).

Переход от nnls к sqnonneg

В Версии 1.5  для функции nnls использовалось следующее обращение:

 [X,LAMBDA] = nnls(A,b,tol);

Согласно Версии 2 аргументы tol заменяются на: 

OPTIONS = optimset('Display','none','TolX',tol);

Тепрерь обращение к lsqnonneg будет как 

[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT,LAMBDA] =
lsqnonneg(A,b,X0,OPTIONS);

Переход от qp к quadprog

В Версии 1.5  для функции qp использовалось следующее обращение:

[X,LAMBDA,HOW] = qp(H,f,A,b,VLB,VUB,X0,N,DISPLAY);

Согласно Версии 2 входные аргументы переходят в более корректную форму для quadprog 
посред-ством выделения отдельных значений ограничений типа равенств и типа неравенств

Aeq = A(1:N,:);
beq = b(1:N);
A = A(N+1:end,:);
b = b(N+1:end,:);
if DISPLAY
val = 'final';
else
val = 'none';
end
OPTIONS = optimset('Display',val);

Теперь обращение к quadprog будет

[X,FVAL,EXITFLAG,OUTPUT,LAMBDA] =
quadprog(H,f,A,b,Aeq,beq,VLB,VUB,X0,OPTIONS);

Переход от seminf к fseminf

В Версии 1.5  для функции seminf использовалось следующее обращение:

[X,OPTIONS] = seminf('FUN',N,x0,OPTIONS,VLB,VUB,P1,P2,...);

при

 [F,C,PHI1,PHI2,...,PHIN,S] = FUN(X,S,P1,P2,...).

Согласно Версии 2 обращение к fseminf будет

[X,FVAL,EXITFLAG,OUTPUT,LAMBDA] =
fseminf(@OBJFUN,x0,N,@NONLCON,A,B,Aeq,Beq,VLB,VUB,OPTIONS,
P1,P2,...);

При

 F = OBJFUN(X,P1,...) 

и

[Cineq,Ceq,PHI1,PHI2,...,PHIN,S] = NONLCON(X,S,P1,...).

Примеры перехода от constr к fmincon

Старое обращение к constr

OPTIONS = foptions;
OPTIONS(13) = 2; % Два ограничения типа равенств
OPTIONS(1) = 1;
OPTIONS(9) = 1;
A1 = [ 1 4 -3]; b1 = 2;
A2 = [ 2 5 0]; b2 = 9;
x0 = [1; .5; .8];
LB = []; UB = [];
[X,OPTIONS,LAMBDA,HESS] = ...
constr('myfuncon',x0,OPTIONS,LB,UB,'mygradcon',A1,b1,A2,b2);

% myfuncon.m
[F, C] = myfuncon(x,A1,b1,A2,b2)
F = x(1) + 0.0009*x(2)^3 + sin(x(3));

C(1,1) = A1*x-b; % линейное ограничение типа равенств
C(2,1) = 3*x(1)^2-1; % нелинейное ограничение типа равенств

C(3,1) = A2*x-b2; % линейное ограничение типа неравенств
C(4,1) = 7*sin(x(2))-1; % нелинейное ограничение типа неравенств 

% mygradcon.m
[G, DC] = mygradcon(x,alpha)
G = [1; % Gradient of the objective
3*0.0009*x(2)^2;
cos(x(3))];

DC(:,1) = A1'; % Градиент ограничений
DC(:,2) = [6*x(1); 0; 0];
DC(:,3) = A2';
DC(:,4) = [0; 7*cos(x(2)); 0];

Новое обращение к fmincon

OPTIONS = optimset(...
'Display', 'iter', ...
'GradCheck', 'on', ... % Проверка градиентов
'GradObj', 'on', ... % задание градиента целевой функции
'GradConstr', 'on'); % задание градиента ограничений

A1 = [ 1 4 -3]; b1 = 2; % Линейные равенства
A2 = [ 2 5 0]; b2 = 9; % Линейные неравенства

x0 = [1; .5; .8];
LB = []; UB = [];

[X,FVAL,EXITFLAG,OUTPUT,LAMBDA,GRAD,HESSIAN] = ...
fmincon(@myfun,x0,A2,b2,A1,b1,LB,UB,@mycon,OPTIONS);

% myfun.m
function [F,G] = myfun(x)
F = x(1) + 0.0009*x(2)^3 + sin(x(3));
G = [1;
3*0.0009*x(2)^2;
cos(x(3))];
% mycon.m
function [C,Ceq,DC,DCeq]= mycon(x)

Ceq(1,1) = 3*x(1)^2-1; % нелинейное ограничение типа равенств
C(1,1) = 7*sin(x(2))-1; % нелинейное ограничение типа неравенств
DCeq(:,1) = [6*x(1); 0; 0]; % Градиент нелинейных ограничений
% типа равенств
DC(:,1) = [0; 7*cos(x(2)); 0]; % Градиент нелинейных ограничений
% типа неравенств

Selected Bibliography

1. Hairer, E., S. P. Norsett, and G. Wanner, Solving Ordinary Differential Equations I - Nonstiff Problems, Springer-Verlag, pp. 183-184.