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