Задайте свойства входных параметров функции точки входа

Почему вы должны задать входные свойства

Поскольку C и C++ являются статическими языками, MATLAB^® Coder™ должны определить свойства всех переменных в файлах MATLAB во время компиляции. Чтобы вывести свойства переменных в файлах MATLAB, MATLAB Coder должен быть в состоянии идентифицировать свойства входов в первичную функцию, также известную как функция верхнего уровня или точки входа. Поэтому, если ваша первичная функция имеет входы, необходимо задать свойства этих входов для MATLAB Coder. Если ваша первичная функция не имеет входных параметров, MATLAB Coder может скомпилировать ваш файл MATLAB без изменений. Вам не нужно задавать свойства входов в локальные функции или внешние функции, вызываемые основной функцией.

Если вы используете символ tilde (~), чтобы задать неиспользованные входные параметры функции:

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

Свойства, которые нужно задать

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

Для	Задайте свойства
	Класс	Размер	Сложность	numerictype	fimath
Входы с фиксированной точкой
Каждое поле в структуре входа	Задайте свойства для каждого поля в соответствии с его классом Когда первичный входной параметр является структурой, генератор кода обрабатывает каждое поле как отдельный вход. Поэтому необходимо задать свойства для всех полей первичной структуры входа в том порядке, в котором они появляются в определении структуры: Для каждого поля входа структур задайте класс, размер и сложность. Для каждого поля, которое является классом с фиксированной точкой, также задайте `numerictype`, и `fimath`.
Другие входы

Значения свойств по умолчанию

MATLAB Coder присваивает следующие значения по умолчанию для свойств входных параметров первичной функции.

Свойство	Дефолт
класс	`double`
размер	`scalar`
сложность	`real`
`numerictype`	По умолчанию нет
`fimath`	MATLAB по умолчанию `fimath` объект

Определение значений по умолчанию для структурных полей. В большинстве случаев, когда вы явным образом не задаете значения для свойств, MATLAB Coder использует значения по умолчанию, кроме структурных полей. Единственный способ назвать поле в структуре - задать хотя бы одно из его свойств. Поэтому может потребоваться задать значения по умолчанию для свойств структурных полей. Для примеров смотрите Задание класса и размера скалярной структуры и Определение класса и размера массива структур.

Определение значений fimath по умолчанию для MEX-функций. MEX-функции, сгенерированные с помощью MATLAB Coder, используют fimath по умолчанию значение, действующее во время компиляции. Если вы не задаете fimath по умолчанию значение, MATLAB Coder использует MATLAB по умолчанию fimath. Фабрика MATLAB по умолчанию имеет следующие свойства:

RoundingMethod: Nearest
OverflowAction: Saturate
ProductMode: FullPrecision
SumMode: FullPrecision
CastBeforeSum: true

Для получения дополнительной информации смотрите fimath для Совместного использования правил Арифметики (Fixed-Point Designer).

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

Например, предположим, что вы задаете следующую функцию MATLAB test:

function y = test %#codegen
y = fi(0);

Функция test создает fi объект без явного указания fimath объект. Поэтому test полагается на значение по умолчанию fimath объект, действующий во время компиляции. В подсказке MATLAB сгенерируйте MEX-функцию text_mex для использования заводской настройки MATLAB по умолчанию fimath:

codegen test
% codegen generates a MEX function, test_mex, 
% in the current folder

Далее запустите test_mex отображение MATLAB по умолчанию fimath значение:

test_mex
 
ans =
 
     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

Теперь создайте локальный MATLAB fimath значение. поэтому вы больше не используете настройку по умолчанию:

F = fimath('RoundingMethod','Floor');

Наконец, очистите MEX-функцию от памяти и перезапустите его:

clear test_mex
test_mex

Несоответствие обнаружено и вызывает ошибку:

??? This function was generated with a different default
fimath than the current default.

Error in ==> test_mex

Установка нескольких сигнатур для MEX-функции. Чтобы сгенерировать мультисигнатурную MEX-функцию из функции точки входа, предоставьте несколько -args спецификации для той же функции точки входа. Сгенерированная MEX-функция работает с несколькими сигнатурами, которые вы предоставляете во время генерации кода. Для получения дополнительной информации о мультисигнатуре MEX смотрите Сгенерируйте одну MEX-функцию для нескольких сигнатур.

Поддерживаемые классы

В следующей таблице представлены имена классов, поддерживаемые MATLAB Coder.

Имя класса	Описание
`logical`	Логический массив истинных и ложных значений
`char`	Символьный массив
`int8`	8-битный целочисленный массив со знаком
`uint8`	8-битный массив беззнаковых целых чисел
`int16`	16-битный целочисленный массив со знаком
`uint16`	16-битный массив беззнаковых целых чисел
`int32`	32-битный целочисленный массив со знаком
`uint32`	32-битный массив беззнаковых целых чисел
`int64`	64-битный целочисленный массив со знаком
`uint64`	64-разрядный массив беззнаковых целых чисел
`single`	Массив с одной точностью с плавающей точкой или с фиксированной точкой
`double`	Массив чисел с двойной точностью с плавающей точкой или с фиксированной точкой
`struct`	Массив структур
`embedded.fi`	Массив номеров с фиксированной точкой

Правила определения свойств Первичных входных параметров

При определении свойств первичных входных параметров следуйте следующим правилам:

Порядок элементов массива ячеек должен соответствовать порядку, в котором входы появляются в сигнатуре основной функции. Для примера первый элемент массива ячеек определяет свойства первого первичного входного параметра функции.
Чтобы сгенерировать меньше аргументов, чем те, которые происходят в функции MATLAB, задайте свойства только для количества аргументов, которые вы хотите в сгенерированной функции.
Если функция MATLAB имеет входные параметры, чтобы сгенерировать функцию, которая не имеет входных параметров, передайте пустой массив ячеек в -args.
Для каждого первичного входного параметра функции, чей класс является фиксированной точкой (fi), задайте вход numerictype и fimath свойства.
Для каждого первичного входного параметра функции, чей класс structзадайте свойства каждого из его полей в том порядке, в котором они появляются в определении структуры.

Методы определения свойств Первичных входных параметров

Метод	Преимущества	Недостатки
Задайте свойства входных параметров функции точки входа используя приложение	Если вы работаете в проекте MATLAB Coder, легко использовать Не изменяет оригинальный код MATLAB MATLAB Coder сохраняет определения в файле проекта	Не эффективен для определения интенсивных входов памяти, таких как большие структуры и массивы
Задайте входные свойства по примеру в командной строке Примечание Если вы программно задаете входные свойства в файле MATLAB, вы не можете использовать этот метод	Легкий в использовании Не изменяет оригинальный код MATLAB Предназначен для прототипирования функции, которая имеет несколько первичных входных параметров	Необходимо задавать в командной строке каждый раз, когда вы вызываете `codegen`(если вы не используете скрипт) Не эффективен для определения интенсивных входов памяти, таких как большие структуры и массивы
Задайте входные свойства программно в файле MATLAB	Интеграция с кодом MATLAB; не нужно переопределять свойства каждый раз, когда вы вызываете MATLAB Coder Предоставляет документацию спецификаций свойств в коде MATLAB Эффективен для определения интенсивных входов памяти, таких как большие структуры	Использует комплексный синтаксис Файлы проекта MATLAB Coder в настоящее время не распознают свойства, заданные программно. При использовании проекта необходимо повторно ввести типы входа в проект.

Задайте входные свойства по примеру в командной строке

Опция командной строки -args
Правила использования опции -args
Определение свойств Первичных входных параметров по примеру в командной строке
Определение свойств первичных входов с фиксированной точкой по примеру в командной строке

Опция командной строки -args

codegen функция обеспечивает опцию командной строки -args для определения свойств входных параметров основной (точки входа) функции как массива ячеек с примерами значений или типов. Массив ячеек может быть переменной или буквальным массивом постоянных значений. Используя эту опцию, вы задаете свойства входов одновременно с генерацией кода для функции MATLAB с codegen.

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

Если у вас есть тестовая функция или скрипт, который вызывает функцию MATLAB точки входа с необходимыми типами, вы можете использовать coder.getArgTypes для определения типов входных параметров функции. coder.getArgTypes возвращает массив ячеек coder.Type объекты, которые можно передать в codegen использование -args опция. Смотрите Определение общих свойств Первичных входных параметров для codegen.

Можно также создать coder.Type объекты в интерактивном режиме с помощью редактора типов кодеров. См. «Создание и редактирование входных типов при помощи редактора типов кодеров».

Правила использования опции -args

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

Порядок элементов массива ячеек должен соответствовать порядку, в котором входы появляются в сигнатуре основной функции. Для примера первый элемент массива ячеек определяет свойства первого первичного входного параметра функции.
Чтобы сгенерировать меньше аргументов, чем те, которые происходят в функции MATLAB, задайте свойства только для количества аргументов, которые вы хотите в сгенерированной функции.
Если функция MATLAB имеет входные параметры, чтобы сгенерировать функцию, которая не имеет входных параметров, передайте пустой массив ячеек в -args.
Для каждого первичного входного параметра функции, чей класс является фиксированной точкой (fi), задайте вход numerictype и fimath свойства.
Для каждого первичного входного параметра функции, чей класс structзадайте свойства каждого из его полей в том порядке, в котором они появляются в определении структуры.

Определение свойств Первичных входных параметров по примеру в командной строке

Рассмотрим функцию MATLAB, которая добавляет два своих входов:

function y = mcf(u,v)
%#codegen
y = u + v;

Следующие примеры показывают, как задать различные свойства первичных входных параметров u и v по примеру в командной строке:

Используйте буквальный массив ячеек констант, чтобы задать, что оба входов являются вещественными скалярами двойными:
```
codegen mcf -args {0,0}
```
Используйте буквальный массив ячеек констант, чтобы задать, что вход u - беззнаковый 16-битный, вектор 1 на 4 и входной v является скалярным двойником:
```
codegen  mcf -args {zeros(1,4,'uint16'),0}
```
Присвоение выборки значения в переменную массива ячеек, чтобы указать, что оба входов являются вещественными, беззнаковыми 8-битными целочисленными векторами:
```
a = uint8([1;2;3;4])
b = uint8([5;6;7;8])
ex = {a,b}
codegen mcf -args ex
```

Определение свойств первичных входов с фиксированной точкой по примеру в командной строке

Чтобы сгенерировать MEX-функцию или код C/C + + для кода MATLAB с фиксированной точкой, необходимо установить программное обеспечение Fixed-Point Designer™.

Рассмотрим функцию MATLAB, которая вычисляет квадратный корень числа с фиксированной точкой:

%#codegen
function y = sqrtfi(x)
y = sqrt(x);

Чтобы задать свойства первичного входного сигнала с фиксированной точкой x например, следуйте следующим шагам:

Определите numerictype свойства для x, для примера:

T = numerictype('WordLength',32,...
                'FractionLength',23,...
                'Signed',true);

Определите fimath свойства для x, для примера:

F = fimath('SumMode','SpecifyPrecision',...
           'SumWordLength',32,...
           'SumFractionLength',23,...
           'ProductMode','SpecifyPrecision',...
           'ProductWordLength',32,...
           'ProductFractionLength',23);

Создайте переменную с фиксированной точкой со numerictype и fimath свойства, которые вы определили, для примера:
```
myeg = { fi(4.0,T,F) };
```
Скомпилируйте функцию sqrtfi использование codegen команда, передающая переменную myeg как аргумент к -args опция, например:
```
codegen sqrtfi -args myeg;
```

Задайте Постоянные Входы в Командной Строке

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

Чтобы указать, что входы являются константами, используйте -args опция командной строки со coder.Constant объект. Чтобы указать, что вход является константой с размером, классом, сложностью и значением constant_input, используйте следующий синтаксис:

-args {coder.Constant(constant_input)}

Вызов функций с постоянными входами

Генератор кода компилирует постоянные входные параметры функции в сгенерированный код. В сгенерированном коде C or C++ сигнатуры функции не содержат постоянных входов. По умолчанию сигнатуры MEX-функций содержат постоянные входы. При вызове MEX-функции необходимо указать значения, которые совпадают со значениями во время компиляции. Можно управлять, включает ли сигнатура MEX-функции постоянные входы, и проверяет ли MEX-функция значения, которые вы обеспечиваете для постоянных входов. См. раздел «Постоянная проверка входных параметров» в MEX-функциях».

Определение структуры как постоянного входа

Предположим, что вы задаете структуру tmp в рабочем пространстве MATLAB, чтобы задать размерности матрицы:

tmp = struct('rows', 2, 'cols', 3);

Следующая функция MATLAB rowcol принимает входной параметр структуры p для определения матричных y:

function y = rowcol(u,p) %#codegen
y = zeros(p.rows,p.cols) + u;

В следующем примере показано, как задать этот первичный входной параметр u является двойной скалярной переменной и первичным входным p является постоянной структурой:

codegen rowcol -args {0,coder.Constant(tmp)}

Задайте входные параметры переменного размера в командной строке

Данные переменного размера - это данные, размер которых может измениться во время выполнения. MATLAB поддерживает ограниченные и неограниченные данные переменного размера для генерации кода. Bounded variable-size data имеет фиксированные верхние границы. Эти данные могут быть выделены статически в стеке или динамически в куче. Unbounded variable-size data не имеет фиксированных верхних границ. Эти данные должны быть выделены на куче. Можно задать входы, чтобы иметь одни или несколько размерностей переменного размера - и задать их верхние границы - используя -args опция и coder.typeof функция:

-args {coder.typeof(example_value, size_vector, variable_dims)}

Задает вход переменного размера с:

Тот же класс и сложность, что и example_value
Размер и верхние границы совпадают с size_vector
Переменные размерности, заданные variable_dims

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

Когда variable_dims является скаляром, применяется ко всем размерностям, за следующими исключениями:

Если размерность равна 1 или 0, которые являются фиксированными.
Если размерность неограниченный, то это всегда переменный размер.

Для получения дополнительной информации см. coder.typeof и Сгенерируйте код для данных переменного размера.

Задание вектора переменного размера Входа

Написание функции, которая вычисляет среднее значение каждого n Элементы массива вектора A и сохраняет их в векторе B:

function B = nway(A,n) %#codegen
% Compute average of every N elements of A and put them in B.

coder.extrinsic('error');
if ((mod(numel(A),n) == 0) && (n>=1 && n<=numel(A)))
    B = ones(1,numel(A)/n);
    k = 1;
    for i = 1 : numel(A)/n
         B(i) = mean(A(k + (0:n-1)));
         k = k + n;
    end
else
    B = zeros(1,0);
    error('n <= 0 or does not divide number of elements evenly');
end

Задайте первый вход A как вектор двойных значений. Его первая размерность остается фиксированным в размере, а второе измерение может вырасти до верхней границы 100. Задайте второй вход n как двойной скаляр.
```
codegen -report nway -args {coder.typeof(0,[1 100],1),1} 
```
В качестве альтернативы присвойте coder.typeof выражение в переменный MATLAB, затем передайте переменную в качестве аргумента в -args:
```
vareg = coder.typeof(0,[1 100],1)
codegen -report nway -args {vareg, 0}
```

Документация