MATLAB: Как создать свой набор инструментов (toolbox)

MATLAB состоит из различных компонентов, которые помимо отдельных продуктов (таких как MATLAB Distributed Computer Server, Simulink или License Manager) состоит из наборов инструментов или так называемых toolbox. Наборы инструментов обычно состоят из функций и графических приложений. Чаще всего мы используем стандартные наборы инструментов, но можно использовать наборы инструментов других разработчиков или свои собственные (чтобы всё было организовано, а не валялось кабы как в одной папке). В данной статье я покажу, как можно создать свой набор инструментов.

Шаг 1. Разработчик: Создание нужных и полезных функций

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

function c = MySum(a, b)
% Вычислить сумму двух чисел
 c = a + b;
end

и

function c = MyMul(a, b)
% Вычислить произведение двух чисел
 c = a * b;
end

Не лишним будет сказать, что каждая функция должна иметь справку. Желательно не только указать, назначение и описание форм вызова и описания параметров.

Справка - это содержимое строк-комментариев, которые находятся сразу после заголовка и продолжаются до первого некомментария. Например:

function c = MyMul(a, b)
% Вычислить произведение двух чисел
%
% Входные данные:
% a - первое число
% b - второе число
%
% Выходные данные:
% c - произведение
%
%   See also prod, MySum. 

 c = a * b;
end

В этом случае пользователь всегда сможет получить красивую и полную справку набрав:

doc ИмяФункции
help ИмяФункции

Вот что получится для нашего примера:

Более подробно об оформлении функций я напишу отдельную статью. Считаем, что функции и документация к ним написаны.

Шаг 2. Разработчик: Создание набора инструментов

Пожалуй, это - самая интересная часть. Каждый набор инструментов - это отдельный каталог с функциями, названием которого является название набора инструментов. В данном случае, наш набор инструментов будет называться MyToolbox, а файлы будут располагаться в одноименном каталоге.

Данный каталог может (и по-правильному должен) содержать файл 'Contents.m'. Желательно соблюдать регистр в имени файла. Хотя некоторые разработчики используют верхний регистра 'CONTENTS.m'. Тем самым этот файл "бросается" в глаза.

Этот файл содержит общее описание набора инструментов, а также назначение функций, входящих в него. Например:

% Невероятно сложные, быстрые и надёжные численные алгоритмы
%
% Files
%   MyMul - Вычислить произведение двух чисел
%   MySum - Вычислить сумму двух чисел

Если набрать команду

doc ИмяНабораИнструментов
help ИмяНабораИнструментов

получим вот такое описание:

которое вы могли видеть, вызывая, например:

doc elfun
doc matfun

Теперь понятен их секрет ;)

Важно понимать, что в как и случае функций, используются первые строки-некомментарии. Поэтому некоторые разработчики добавляют информацию о версии файла следующим образом:

% Elementary math functions.
%
% Trigonometric.
%   sin         - Sine.
%   sind        - Sine of argument in degrees.
...
%   rem         - Remainder after division.
%   sign        - Signum.

%   Copyright 1984-2011 The MathWorks, Inc.
%   $Revision: 5.16.4.4 $  $Date: 2011/12/16 16:32:50 $  

Посмотрев файл c:\Program Files\MATLAB\R2012b\toolbox\matlab\elfun\Contents.m можно понять, как функции логически группируются внутри одного пакета. Это происходит за счёт форматирования файла 'Contents.m' (например, см. группу 'Trigonometric'), а также за счёт ссылок в описании функции (см. 'See also').

Настоятельно рекомендую почитать соответствующий раздел документации: Create Help Summary Files (Contents.m).

Так оказывается можно автоматически создавать файл "Contents.m" и править его:

Рекомендую почитать, посмотреть. Фактически здесь происходит что-то типа:

base = pwd % сохранить путь к текущей папке
cd(targetfolder); % перейти в папку с набором инструментов
makecontentsfile; % создать файл "Contents.m"
cd(base); % вернуться в исходную папку

Шаг 3. Пользователь: Установка набора инструментов

По-хорошему, нужно создать установщик. Но я здесь подробно опишу что происходит "за кулисами".

Пользователь копирует набор инструментов (папку с файлами функций) в определённую папку. Я НЕ рекомендую записывать полученный набор в стандартную папку наборов инструментов - 'c:\Program Files\MATLAB\R2012b\toolbox'. Пусть это будет 'c:\Work\MyToolbox'.

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

графически

(в версиях до R2012b используется меню 'File' > 'Set Path...')

где

• нажимаем "Add Folder...";
• выбираем папку с набором инструментов и нажимаем "Выбор папки"
• нажимаем "Save" (требуются права администратора) и "Close", чтобы закрыть диалоговое окно "Set Path".

или через функцию

addpath('c:\Work\MyToolbox');

Фактически происходит изменение файла "c:\Program Files\MATLAB\R2012b\toolbox\local\pathdef.m", где дописывается ещё одна или несколько строк. В этом плане будет полезна утилита mpath (задумка классная, но как скачать непонятно).

Шаг 4. Пользователь: Использование набора инструментов

По факту, теперь можно использовать функции из набора инструментов, находясь в любой папке. Также можно запрашивать справку по функциям и самому набору инструментов. Примеры были показаны выше (в шаге 3 и 4).