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

: [s, idx] = example (…)

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

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

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

См. 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 и вторая версия с 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).

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