API Level 2 MATLAB® S-function позволяет вам использовать язык MATLAB, чтобы создать пользовательские блоки с несколькими портами ввода и вывода и способный к обработке любого типа сигнала, произведенного моделью Simulink®, включая матрицу и сигналы кадра любого типа данных. Уровень 2 API S-функции MATLAB соответствует тесно API для создания C S-функции MEX. Большая часть документации для создания C S-функции MEX применяет также к Уровню 2 S-функции MATLAB. Чтобы избежать дублирования, этот раздел фокусируется на предоставлении информации, которая характерна для записи Уровня 2 S-функций MATLAB.
S-функцией Уровня 2 MATLAB является функция MATLAB, которая задает свойства и поведение экземпляра Уровня 2 Блок s-function MATLAB, который ссылается на функцию MATLAB в модели Simulink. Сама функция MATLAB включает набор методов обратного вызова (см. Уровень 2 Методы Обратного вызова S-функции MATLAB), который механизм Simulink вызывает при обновлении или моделировании модели. Методы обратного вызова выполняют фактическую работу инициализации и вычисления выходных параметров блока, заданного S-функцией.
Чтобы упростить эти задачи, механизм передает объект периода выполнения методам обратного вызова в качестве аргумента. Объект периода выполнения эффективно служит прокси MATLAB для Блока s-function, позволяя методам обратного вызова установить и получить доступ к блочным свойствам во время моделирования или образцового обновления.
Когда механизм Simulink вызывает метод обратного вызова Level 2 MATLAB S-function, он передает экземпляр класса Simulink.MSFcnRunTimeBlock к методу в качестве аргумента. Этот экземпляр, известный как объект периода выполнения для Блока s-function, служит той же цели для Уровня 2 методы обратного вызова S-функции MATLAB как подачи структуры SimStruct для методов обратного вызова S-функции MEX C. Объект позволяет методу обеспечить и получить информацию о различных элементах блочных портов, параметров, состояний, и работать векторы. Метод делает это путем получения или установки свойств или вызова методов блочного объекта периода выполнения. См. документацию для класса Simulink.MSFcnRunTimeBlock для получения информации о получении и установке свойств объекта периода выполнения и вызове методов объекта периода выполнения.
Объекты периода выполнения не поддерживают разреженные матрицы MATLAB. Например, если переменный block является объектом периода выполнения, следующей строкой на Уровне 2, S-функция MATLAB производит ошибку:
block.Outport(1).Data = speye(10);
где команда speye формирует разреженную единичную матрицу.
Другие программы MATLAB помимо S-функций MATLAB могут использовать объекты периода выполнения, чтобы получить информацию о S-функции MATLAB в модели, которая моделирует. Смотрите доступ к Блочным Данным Во время Моделирования в Использовании Simulink для получения дополнительной информации.
Используйте базовый уровень 2 S-шаблона-функции MATLAB msfuntmpl_basic.m, чтобы получить преимущество при создании нового Уровня 2 S-функция MATLAB. Шаблон содержит скелетные реализации необходимых методов обратного вызова, заданных Уровнем 2 API S-функции MATLAB. Чтобы записать более сложную S-функцию, используйте аннотируемый шаблон msfuntmpl.m m.
Чтобы создать S-функцию MATLAB, сделайте копию шаблона и отредактируйте копию по мере необходимости, чтобы отразить желаемое поведение S-функции, которую вы создаете. Следующие два раздела описывают содержимое шаблона кода MATLAB. Раздел Example Записи Уровня 2, который описывает S-функция MATLAB, как записать Уровню 2 S-функцию MATLAB, это моделирует единичную задержку.
API S-функции Уровня 2 MATLAB задает подписи и общие цели методов обратного вызова, которые составляют Уровень 2 S-функция MATLAB. Сама S-функция обеспечивает реализации этих методов обратного вызова. Реализации в свою очередь определяют блочные атрибуты (e. g., порты, параметры и состояния) и поведение (e. g., блок выходные параметры как функция времени и блочных входных параметров, состояний и параметров). Путем создания S-функции с соответствующим набором методов обратного вызова можно задать тип блока, который удовлетворяет определенные требования приложения.
Уровень 2 S-функция MATLAB должен включать следующие методы обратного вызова:
Функция setup, чтобы инициализировать основные характеристики S-функции
Функция Outputs, чтобы вычислить S-функцию выходные параметры
Ваша S-функция может содержать другие методы, в зависимости от требований блока, чтобы S-функция задает. Методы, заданные Уровнем 2 API S-функции MATLAB обычно, соответствуют столь же названным методам, заданным API S-функции MEX C. Для получения информации о том, когда эти методы называются во время моделирования, видят Представление Процесса во Взаимодействии Engine Simulink с S-функциями C. Для получения инструкций по тому, как реализовать каждый метод обратного вызова, см. Методы Обратного вызова Записи.
В следующей таблице перечислены весь Уровень 2 методы обратного вызова S-функции MATLAB и их дубликаты MEX C.
setupТело метода setup на Уровне 2 S-функция MATLAB инициализирует экземпляр соответствующего Уровня 2 Блок s-function MATLAB. В этом отношении метод setup подобен mdlInitializeSizes и методам обратного вызова mdlInitializeSampleTimes, реализованным S-функциями MEX C. Метод setup выполняет следующие задачи:
Инициализация количества портов ввода и вывода блока.
Устанавливая атрибуты, такие как размерности, типы данных, сложность и частоты дискретизации для этих портов.
Определение блочной частоты дискретизации. См. Настройку времени выборки в Использовании Simulink для получения дополнительной информации о том, как задать допустимые частоты дискретизации.
Определение номера диалоговых параметров S-функции.
Регистрация методов обратного вызова S-функции путем передачи указателей локальных функций в S-функции MATLAB к методу RegBlockMethod объекта периода выполнения Блока s-function. См. документацию для Simulink.MSFcnRunTimeBlock для получения информации об использовании метода RegBlockMethod.
Следующие шаги иллюстрируют, как записать простому Уровню 2 S-функцию MATLAB. Когда применимо, шаги включают примеры от примера S-функции msfcn_unit_delay.m, используемый в образцовом msfcndemo_sfundsc2. Все строки кода используют имя переменной block для объекта периода выполнения S-функции.
Скопируйте Уровень 2 S-шаблон-функции MATLAB msfuntmpl_basic.m к вашей рабочей папке. Если вы изменяете имя файла, когда вы копируете файл, меняете имя функции в строке function к тому же имени.
Измените метод setup, чтобы инициализировать атрибуты S-функции. Для этого примера:
Установите свойства NumInputPorts и NumOutputPorts объекта периода выполнения на 1 в порядке инициализировать один входной порт и один выходной порт.
Вызовите методы SetPreCompInpPortInfoToDynamic и SetPreCompOutPortInfoToDynamic объекта периода выполнения, чтобы указать, что порты ввода и вывода наследовали свои скомпилированные свойства (размерности, тип данных, сложность и режим выборки) от модели.
Установите свойство DirectFeedthrough InputPort объекта периода выполнения к false в порядке указать, что входной порт не имеет прямого сквозного соединения. Сохраните значения по умолчанию для всех других свойств портов ввода и вывода, которые установлены в вашей копии шаблонного файла. Набор значений для Dimensions, DatatypeID и свойств Complexity заменяет наследованное использование значений методы SetPreCompOutPortInfoToDynamic и SetPreCompInpPortInfoToDynamic.
Установите свойство NumDialogPrms объекта периода выполнения на 1 в порядке инициализировать один диалоговый параметр S-функции.
Укажите, что S-функция имеет наследованную частоту дискретизации путем устанавливания значения свойства SampleTimes объекта периода выполнения к [-1 0].
Вызовите метод RegBlockMethod объекта периода выполнения, чтобы указать следующие четыре метода обратного вызова, используемые в этой S-функции.
PostPropagationSetup
InitializeConditions
Выходные параметры
Update
Удалите любые другие зарегистрированные методы обратного вызова из своей копии шаблонного файла. В вызовах RegBlockMethod первый входной параметр является именем метода API S-функции, и второй входной параметр является указателем на функцию к связанной локальной функции в S-функции MATLAB.
Следующий метод setup от msfcn_unit_delay.m выполняет предыдущий список шагов:
function setup(block)
%% Register a single dialog parameter
block.NumDialogPrms = 1;
%% Register number of input and output ports
block.NumInputPorts = 1;
block.NumOutputPorts = 1;
%% Setup functional port properties to dynamically
%% inherited.
block.SetPreCompInpPortInfoToDynamic;
block.SetPreCompOutPortInfoToDynamic;
%% Hard-code certain port properties
block.InputPort(1).Dimensions = 1;
block.InputPort(1).DirectFeedthrough = false;
block.OutputPort(1).Dimensions = 1;
%% Set block sample time to [0.1 0]
block.SampleTimes = [0.1 0];
%% Register methods
block.RegBlockMethod('PostPropagationSetup',@DoPostPropSetup);
block.RegBlockMethod('InitializeConditions',@InitConditions);
block.RegBlockMethod('Outputs', @Output);
block.RegBlockMethod('Update', @Update); Если для вашей S-функции нужны непрерывные состояния, инициализируйте количество непрерывных состояний в методе setup с помощью свойства NumContStates объекта периода выполнения. Не инициализируйте дискретные состояния в методе setup.
Инициализируйте дискретные состояния в методе PostPropagationSetup. Уровень 2 S-функция MATLAB хранит информацию дискретного состояния в векторе DWork. Метод PostPropagationSetup по умолчанию в шаблонном файле достаточен для этого примера.
Следующий метод PostPropagationSetup от msfcn_unit_delay.m, названного DoPostPropSetup, инициализирует один вектор DWork с именем x0.
function DoPostPropSetup(block) %% Setup Dwork block.NumDworks = 1; block.Dwork(1).Name = 'x0'; block.Dwork(1).Dimensions = 1; block.Dwork(1).DatatypeID = 0; block.Dwork(1).Complexity = 'Real'; block.Dwork(1).UsedAsDiscState = true;
Если ваша S-функция использует дополнительные векторы DWork, инициализируйте их в методе PostPropagationSetup, также (см. Используя Векторы DWork на Уровне 2 S-функции MATLAB).
Инициализируйте значения дискретных и непрерывных состояний или других векторов DWork в InitializeConditions или методах обратного вызова Start. Используйте метод обратного вызова Start для значений, которые инициализируются однажды в начале моделирования. Используйте метод InitializeConditions для значений, которые должны быть повторно инициализированы каждый раз, когда активированная подсистема, содержащая S-функцию, повторно включена.
Для этого примера используйте метод InitializeConditions, чтобы установить начальное условие дискретного состояния к значению диалогового параметра S-функции. Например, метод InitializeConditions в msfcn_unit_delay.m:
function InitConditions(block) %% Initialize Dwork block.Dwork(1).Data = block.DialogPrm(1).Data;
Для S-функций с непрерывными состояниями используйте метод объекта периода выполнения ContStates, чтобы инициализировать непрерывные данные состояния. Например:
block.ContStates.Data(1) = 1.0;
Вычислите выходные параметры S-функции в методе обратного вызова Outputs. Для этого примера, устанавливает вывод на текущую стоимость дискретного состояния, сохраненного в векторе DWork.
Метод Outputs в msfcn_unit_delay.m:
function Output(block) block.OutputPort(1).Data = block.Dwork(1).Data;
Для S-функции с непрерывными состояниями вычислите производные состояния в методе обратного вызова Derivatives. Объекты периода выполнения хранят производные данные в своем свойстве Derivatives. Например, следующая строка устанавливает первую производную состояния, равную значению первого входного сигнала.
block.Derivatives.Data(1) = block.InputPort(1).Data;
Этот пример не использует непрерывные состояния и, поэтому, не реализует метод обратного вызова Derivatives.
Обновите любые дискретные состояния в методе обратного вызова Update. Для этого примера, установленного значение дискретного состояния к текущей стоимости первого входного сигнала.
Метод Update в msfcn_unit_delay.m:
function Update(block) block.Dwork(1).Data = block.InputPort(1).Data;
Выполните любую очистку, такую как очищающиеся переменные или память, в методе Terminate. В отличие от S-функций MEX C, Уровень 2 S-функция MATLAB не требуются, чтобы иметь метод Terminate.
Для получения информации о дополнительных методах обратного вызова смотрите Уровень 2 Методы Обратного вызова S-функции MATLAB. Для списка свойств объекта периода выполнения смотрите страницу с описанием для Simulink.MSFcnRunTimeBlock и родительского класса Simulink.RunTimeBlock.
Чтобы использовать Уровень 2 S-функция MATLAB в модели, скопируйте экземпляр Уровня 2 MATLAB S-Functionblock в модель. Откройте диалоговое окно Block Parameters для блока и введите имя файла MATLAB, который реализует вашу S-функцию в поле S-имени-функции. Если ваша S-функция использует какие-либо дополнительные параметры, введите значения параметров как список, разделенный запятыми в поле Parameters диалогового окна Block Parameters.
Следующее является модификациями к Уровню 2 шаблон S-функций MATLAB (msfuntmpl_basic.m) и дополнительные операции, которые позволяют вам использовать сигналы переменного размера.
function setup(block)
% Register the properties of the output port
block.OutputPort(1).DimensionsMode = 'Variable';
block.RegBlockMethod('SetInputPortDimensionsMode', @SetInputDimsMode);
function DoPostPropSetup(block)
%Register dependency rules to update current output size of output port a depending on
%input ports b and c
block.AddOutputDimsDependencyRules(a, [b c], @setOutputVarDims);
%Configure output port b to have the same dimensions as input port a
block.InputPortSameDimsAsOutputPort(a,b);
%Configure DWork a to have its size reset when input size changes.
block.DWorkRequireResetForSignalSize(a,true);
function SetInputDimsMode(block, port, dm)
% Set dimension mode
block.InputPort(port).DimensionsMode = dm;
block.OutputPort(port).DimensionsMode = dm;
function setOutputVarDims(block, opIdx, inputIdx)
% Set current (run-time) dimensions of the output
outDimsAfterReset = block.InputPort(inputIdx(1)).CurrentDimensions;
block.OutputPort(opIdx).CurrentDimensions = outDimsAfterReset;
Генерация кода для модели, содержащей Уровень 2, S-функция MATLAB требует, чтобы вы обеспечили соответствующий файл Компилятора выходного языка (TLC). Вам не нужен файл TLC, чтобы ускорить модель, содержащую Уровень 2 S-функция MATLAB. Программное обеспечение Simulink Accelerator™ запускает Уровень 2 S-функции MATLAB в интерпретированном режиме. Однако S-функции M-файла не работают с ускоренным режимом, если S-функция M-файла находится в модели - ссылке. Для получения дополнительной информации о записи файлов TLC для S-функций MATLAB смотрите S-функции Встраивания (Simulink Coder) и Встройте S-функции файла MATLAB (Simulink Coder).
Примеры S-функции Уровня 2 MATLAB обеспечивают набор самодокументирования моделей, которые иллюстрируют использование Уровня 2 S-функции MATLAB. Введите sfundemos в подсказке команды MATLAB, чтобы просмотреть примеры.
Уровень 2 S-функции MATLAB не поддерживают обнаружение пересечения нулем.
Вы не можете инициировать подсистему вызова функций от Уровня 2 S-функция MATLAB.
Уровень 2 S-функция MATLAB | Функция MATLAB | S-функция | Разработчик S-функции