B.2 Демонстрационные функции

: demo name

: demo name n

: demo ("name")

: demo ("name", n)

Выполнить блок примера с номером n, связанный с функцией name.

Если n не указан, выполняются все примеры.

Предпочтительное место для блоков кода примеров — непосредственно после кода, который они демонстрируют, во встроенном m-файле скрипта. В качестве альтернативы примеры можно хранить в файле с тем же именем, но без расширения, расположенном в пути поиска Octave. Чтобы отделить примеры от обычного кода скрипта, все строки предваряются %!. Каждый пример также должен начинаться с ключевого слова "demo", выровненного по левому краю относительно префикса без пробелов между ними. Остальная часть примера может содержать произвольный код Octave. Например:

%!demo
%! t = 0:0.01:2*pi;
%! x = sin (t);
%! plot (t, x);
%! title ("one cycle of a sine wave");
%! #-------------------------------------------------
%! # the figure window shows one cycle of a sine wave

Обратите внимание, что код отображается перед выполнением, поэтому для подписи показанного достаточно простого комментария в конце. Для графиков подписи также можно добавить с помощью title или text. Как правило, в demo не требуется использовать disp или printf.

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

%! input ("Press <enter> to continue: ", "s");

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

Наконец, поскольку demo выполняется в контексте функции, определить новые функции в коде невозможно. В большинстве случаев хорошей заменой служат анонимные функции. Если блоки функций необходимо использовать, код eval (example ("function", n)) позволит Octave увидеть их. Однако это создает свои проблемы, поскольку eval выполняет только одну строку или инструкцию за раз. В этом случае объявление функции необходимо заключить в "if 1 <demo stuff> endif", где "if" находится в той же строке, что и "demo". Например:

%!demo if 1
%!  function y = f(x)
%!    y = x;
%!  endfunction
%!  f(3)
%! endif

См. также: rundemos, example, test.

: example name

: example name n

: example ("name")

: example ("name", n)

: [codestr, codeidx] = example (…)

Отобразить код примера с номером n, связанного с функцией name, но не выполнять его.

Если n не указан, отображаются все примеры.

При вызове с выходными аргументами примеры возвращаются в виде строки codestr, а codeidx указывает конечные позиции соответствующих примеров.

Полное описание см. в разделе demo.

См. также: demo, test.

: oruntests ()

: oruntests (directory)

Выполнить встроенные тесты для всех m-файлов в указанном directory.

Также будут выполнены блоки тестов во всех исходных файлах C++ (*.cc), предназначенных для использования с динамически связываемыми функциями oct-файлов.

Если каталог не указан, обработать все каталоги в пути поиска функций Octave.

См. также: rundemos, test, path.

: rundemos ()

: rundemos (directory)

Выполнить встроенные демонстрации для всех m-файлов в указанном directory.

Также будут выполнены блоки демонстраций во всех исходных файлах C++ (*.cc), предназначенных для использования с динамически связываемыми функциями oct-файлов.

Если каталог не указан, обработать все каталоги в пути поиска функций Octave.

См. также: demo, oruntests, path.

: speed (f, init, max_n, f2, tol)

: [order, n, T_f, T_f2] = speed (…)

Определить время выполнения выражения (f) для различных входных значений (n).

Значения n расположены по логарифмической шкале от 1 до max_n. Для каждого n вычисляется выражение инициализации (init), создающее данные, необходимые для теста. Если задано второе выражение (f2), сравнивается время выполнения двух выражений. При вызове без выходных аргументов результаты выводятся в стандартный вывод и отображаются графически.

f

Вычисляемое выражение кода.

max_n

Максимальная продолжительность теста. Значение по умолчанию — 100. В качестве альтернативы используйте [min_n, max_n] или задайте точные значения n с помощью [n1, n2, …, nk].

init

Выражение инициализации значений аргументов функции. Используйте k для номера теста и n для размера теста. Оно должно вычислять значения всех переменных, используемых в f. Обратите внимание, что init сначала вычисляется при k = 0, поэтому значения, неизменные во всей серии тестов, можно вычислить один раз. Значение по умолчанию — x = randn (n, 1).

f2

Альтернативное выражение для вычисления, позволяющее напрямую сравнить скорость двух выражений. Значение по умолчанию — [].

tol

Допуск, используемый для сравнения результатов выражений f и f2. Если tol положителен, допуск является абсолютным. Если tol отрицателен, допуск является относительным. Значение по умолчанию — eps. Если tol равен Inf, сравнение не выполняется.

order

Временная сложность выражения O(a*n^p). Это структура с полями a и p.

n

Значения n, для которых было вычислено выражение И время выполнения оказалось больше нуля.

T_f

Ненулевые значения времени выполнения выражения f, записанные в секундах.

T_f2

Ненулевые значения времени выполнения выражения f2, записанные в секундах. При необходимости среднее отношение времени вычисляется просто как mean (T_f ./ T_f2).

Наклон графика времени выполнения показывает приблизительную степень асимптотической сложности O(n^p). Эта степень отображается для участка, на котором она аппроксимируется (вторая половина графика). Оценка степени не очень точна, но должна позволить определить общий порядок сложности алгоритма. Она может показать, например, что реализация неожиданно имеет сложность O(n^2), а не O(n), поскольку на каждой итерации цикла расширяется вектор вместо предварительного выделения памяти. В текущей версии Octave следующий код имеет сложность не O(n), как можно было бы ожидать.

speed ("for i = 1:n, y{i} = x(i); endfor", "", [1000, 10000])

Но сложность становится такой, если предварительно выделить память для массива ячеек y:

speed ("for i = 1:n, y{i} = x(i); endfor", ...
       "x = rand (n, 1); y = cell (size (x));", [1000, 10000])

Предпринимается попытка оценить стоимость отдельных операций, однако оценка крайне неточна. Стабильность можно несколько повысить, выполняя больше работы за каждый n. Например:

speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])

При сравнении двух различных выражений (f, f2) наклон линии на графике ускорения должен быть больше 1, если новое выражение работает быстрее. У более эффективных алгоритмов наклон меньше. Векторизация алгоритма, как правило, не меняет наклон графика времени выполнения, но сдвигает его относительно исходного графика. Например:

speed ("sum (x)", "", [10000, 100000], ...
       "v = 0; for i = 1:length (x), v += x(i); endfor")

Ниже приведен более сложный пример. Если бы существовала исходная версия xcorr с циклами for и вторая версия с использованием БПФ, можно было бы сравнить скорость выполнения для разных задержек, как показано ниже, или для фиксированной задержки и различных длин вектора:

speed ("xcorr (x, n)", "x = rand (128, 1);", 100,
       "xcorr_orig (x, n)", -100*eps)
speed ("xcorr (x, 15)", "x = rand (20+n, 1);", 100,
       "xcorr_orig (x, n)", -100*eps)

Если одна из двух версий находится в xcorr_orig, этот код сравнит их скорость и выходные значения. Обратите внимание, что версия с БПФ не дает точного результата, поэтому при сравнении необходимо задать допустимый допуск 100*eps. В данном случае сравнение следует выполнять относительно, используя abs ((x - y) ./ y), а не абсолютно, используя abs (x - y).

Введите example ("speed"), чтобы увидеть примеры, или demo ("speed"), чтобы запустить их.