B.2 Функции демонстрации

имя_демонстрации

имя_демонстрации n

демонстрация ("имя")

демонстрация ("имя", n)

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

Если 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. Обычно не нужно использовать 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.

имя_примера

имя_примера n

пример ("имя")

пример ("имя", n)

[s, idx] = пример (…)

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

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

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

См. demo для полного объяснения.

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

rundemos ()

rundemos (директория)

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

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

Если директория не указана, операции выполняются для всех директорий в пути поиска Octave для функций.

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

runtests ()

runtests (директория)

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

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

Если директория не указана, операции выполняются для всех директорий в пути поиска Octave для функций.

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

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

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

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

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

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 и вторая версия с FFT, то можно сравнить скорость выполнения для различных лагов следующим образом, или для фиксированного лага с различной длиной векторов следующим образом:

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, это сравнит их скорость и выходные значения. Обратите внимание, что версия FFT не точна, поэтому необходимо указать допустимую погрешность сравнения 100*eps. В этом случае сравнение должно быть вычислено относительно, как abs ((x - y) ./ y) , а не абсолютно как abs (x - y).

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