API-функция Level-2 MATLAB ® S-function позволяет использовать язык MATLAB для создания пользовательских блоков с несколькими портами ввода и вывода и может обрабатывать любой тип сигнала, создаваемого моделью Simulink ®, включая матричные и кадровые сигналы любого типа. API S-функции Level-2 MATLAB тесно соответствует API для создания S-функций C MEX. Большая часть документации по созданию S-функций C MEX относится также к Level-2 S-функциям MATLAB. Во избежание дублирования в этом разделе рассматривается предоставление информации, специфичной для записи Level-2 S-функций MATLAB.
Уровень 2 MATLAB S-function - функция MATLAB, которая определяет свойства и поведение случая Уровня 2 MATLAB S-Function block, который ссылается на функцию MATLAB в модели Simulink. Сама функция MATLAB содержит набор методов обратного вызова (см. Level-2 MATLAB S-Function Callback Methods), которые модуль Simulink вызывает при обновлении или моделировании модели. Способы обратного вызова выполняют фактическую работу инициализации и вычисления выходных сигналов блока, определенного S-функцией.
Чтобы облегчить выполнение этих задач, обработчик передает объект времени выполнения методам обратного вызова в качестве аргумента. Объект времени выполнения эффективно служит в качестве прокси MATLAB для блока S-Function, позволяя методам обратного вызова задавать свойства блока и обращаться к ним во время моделирования или обновления модели.
Когда двигатель Simulink призывает метод отзыва Уровня 2 MATLAB S-function, он передает случай Simulink.MSFcnRunTimeBlock класс для метода в качестве аргумента. Этот экземпляр, известный как объект времени выполнения для блока S-Function, служит той же цели для Level-2 методов обратного вызова с S-функцией MATLAB, что и SimStruct структура служит для методов обратного вызова C MEX S-функции. Объект позволяет методу предоставлять и получать информацию о различных элементах блочных портов, параметрах, состояниях и рабочих векторах. Метод выполняет это путем получения или установки свойств или вызова методов объекта времени выполнения блока. См. документацию для Simulink.MSFcnRunTimeBlock для получения информации о получении и установке свойств объекта времени выполнения и вызове методов объекта времени выполнения.
Объекты времени выполнения не поддерживают разреженные матрицы MATLAB. Например, если переменная block является объектом времени выполнения, следующая строка в Level-2 MATLAB S-функции приводит к ошибке:
block.Outport(1).Data = speye(10);
где speye формирует разреженную единичную матрицу.
Примечание
Другие программы MATLAB, помимо S-функций MATLAB, могут использовать объекты времени выполнения для получения информации о S-функции MATLAB в моделируемой модели. Дополнительные сведения см. в разделе Доступ к данным блоков во время моделирования в разделе Использование Simulink.
Используйте базовый уровень 2 шаблона S-функции MATLAB msfuntmpl_basic.m для начала создания новой Level-2 MATLAB S-функции. Шаблон содержит каркасные реализации требуемых методов обратного вызова, определенных Level-2 MATLAB S-function API. Чтобы написать более сложную S-функцию, используйте аннотированный шаблон msfuntmpl.m.
Чтобы создать S-функцию MATLAB, создайте копию шаблона и при необходимости отредактируйте копию, чтобы отразить требуемое поведение создаваемой S-функции. В следующих двух разделах описывается содержимое шаблона кода MATLAB. В разделе «Пример записи Level-2 S-функции MATLAB» описывается способ записи Level-2 S-функции MATLAB, моделирующей единичную задержку.
API Уровня 2 MATLAB S-function определяет подписи и общие цели методов отзыва, которые составляют Уровень 2 MATLAB S-function. Сама S-функция обеспечивает реализацию этих методов обратного вызова. Реализации, в свою очередь, определяют атрибуты блока (например, порты, параметры и состояния) и поведение (например, выходы блока как функцию времени и входы блока, состояния и параметры). Создав S-функцию с соответствующим набором методов обратного вызова, можно определить тип блока, соответствующий конкретным требованиям приложения.
S-функция Level-2 MATLAB должна включать следующие методы обратного вызова:
A setup функция для инициализации основных характеристик S-функции
Один Outputs функция для вычисления выходных сигналов S-функции
S-функция может содержать другие методы, в зависимости от требований блока, определяемого S-функцией. Методы, определенные API Уровня 2 MATLAB S-function обычно, соответствуют столь же названным методам, определенным API MEX S-function C. Сведения о том, когда эти методы вызываются во время моделирования, см. в разделе Представление процесса в модуле Simulink Engine Взаимодействие с C S-функциями.
В следующей таблице перечислены все Level-2 методы обратного вызова S-функции MATLAB и их аналоги C MEX.
setup МетодТело setup метод в Уровне 2 MATLAB S-function инициализирует случай соответствующего Уровня 2 MATLAB S-Function block. В этом отношении setup метод аналогичен mdlInitializeSizes и mdlInitializeSampleTimes методы обратного вызова, реализуемые S-функциями C MEX. setup способ выполняет следующие задачи:
Инициализация количества входных и выходных портов блока.
Установка таких атрибутов, как размеры, типы данных, сложность и время выборки для этих портов.
Задание времени выборки блока. Дополнительные сведения о том, как указать допустимое время выборки, см. в разделе Указание времени выборки в программе Simulink.
Установка количества параметров диалогового окна S-функции.
Регистрация методов обратного вызова S-функции путем передачи дескрипторов локальных функций в S-функции MATLAB в RegBlockMethod метод объекта времени выполнения блока S-Function. См. документацию для Simulink.MSFcnRunTimeBlock для получения информации об использовании RegBlockMethod способ.
Следующие шаги иллюстрируют, как написать простую Level-2 S-функцию MATLAB. Если применимо, шаги включают примеры из примера S-функции msfcn_unit_delay.m используется в модели msfcndemo_sfundsc2. Во всех строках кода используется имя переменной block для объекта времени выполнения S-функции.
Скопируйте шаблон Уровня 2 MATLAB S-function msfuntmpl_basic.m в рабочую папку. При изменении имени файла при копировании измените имя функции в function строка с тем же именем.
Изменение setup метод инициализации атрибутов S-функции. Для этого примера:
Установка объекта времени выполнения NumInputPorts и NumOutputPorts свойства для 1 для инициализации одного входного порта и одного выходного порта.
Вызовите методы SetPreCompInppPortInfoDynamic и SetPreCompOutPortInfoToDynamic объекта времени выполнения, чтобы указать, что входные и выходные порты наследуют свои скомпилированные свойства (размеры, тип данных, сложность и режим выборки) из модели.
Установите DirectFeedthrough свойства объекта времени выполнения InputPort кому false чтобы указать, что входной порт не имеет прямого канала. Сохраните значения по умолчанию для всех других свойств входного и выходного портов, заданных в копии файла шаблона. Значения, установленные для Dimensions, DatatypeID, и Complexity свойства переопределяют значения, унаследованные с помощью SetPreCompInpPortInfoToDynamic и SetPreCompOutPortInfoToDynamic методы.
Установка объекта времени выполнения NumDialogPrms свойство для 1 для инициализации одного параметра диалогового окна S-функции.
Укажите, что S-функция имеет наследуемое время выборки, задав значение объекта среды выполнения SampleTimes свойство для [-1 0].
Вызов объекта времени выполнения RegBlockMethod для регистрации следующих четырех методов обратного вызова, используемых в этой S-функции.
PostPropagationSetup
InitializeConditions
Outputs
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 способ. S-функция Level-2 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 в Level-2 MATLAB S-Functions).
Инициализация значений дискретных и непрерывных состояний или других векторов 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 способ. В отличие от C MEX S-функции, Уровень 2 MATLAB S-function не обязан иметь a Terminate способ.
Для получения информации о дополнительных методах обратного вызова см. раздел Level-2 Методы обратного вызова MATLAB S-Function. Список свойств объекта времени выполнения см. на справочной странице для Simulink.MSFcnRunTimeBlock и родительский класс Simulink.RunTimeBlock.
Чтобы использовать Уровень 2 MATLAB S-function в модели, скопируйте случай Уровня 2 MATLAB S-Functionblock в модель. Откройте диалоговое окно «Параметры блока» и введите имя файла MATLAB, реализующего функцию S, в поле имени функции S. Если в S-функции используются какие-либо дополнительные параметры, введите значения параметров в виде списка, разделенного запятыми, в поле «Параметры» диалогового окна «Параметры блока».
Следующее - модификации к шаблону Уровня 2 MATLAB S-functions (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 MATLAB S-function, требует, чтобы Вы предоставили соответствующий файл Target Language Compiler (TLC). Файл TLC не нужен для ускорения модели, содержащей Level-2 MATLAB S-функцию. Программное обеспечение Simulink Accelerator™ выполняет Level-2 S-функции MATLAB в режиме интерпретации. Однако М-файловые S-функции не работают в ускоренном режиме, если М-файловая S-функция находится в ссылке модели. Дополнительные сведения о записи файлов TLC для S-функций MATLAB см. в разделах Встроенные S-функции (Simulink Coder) и Встроенные S-функции файла MATLAB (Simulink Coder).
Примеры Level-2 S-функций MATLAB предоставляют набор самодокументированных моделей, которые иллюстрируют использование Level-2 S-функций MATLAB. Войти sfundemos в командной строке MATLAB для просмотра примеров.
Level-2 S-функции MATLAB не поддерживают обнаружение пересечения нулей.
Невозможно запустить подсистему вызова функции из Level-2 MATLAB S-функции.
Level-2 S-функция MATLAB | Функция MATLAB | S-функция | Построитель S-функций