Уровень 2 MATLAB® API S-функции позволяет вам использовать язык MATLAB, чтобы создать пользовательские блоки с несколькими портами ввода и вывода и способный к обработке любого типа сигнала, произведенного Simulink® модель, включая матрицу и сигналы системы координат любого типа данных. Уровень 2 API S-функции MATLAB соответствует тесно API для создания C S-функции MEX. Большая часть документации для создания C S-функции MEX применяет также к Уровню 2 S-функции MATLAB. Чтобы избежать дублирования, этот раздел фокусируется на предоставлении информации, которая характерна для записи Уровня 2 S-функций MATLAB.
S-функцией MATLAB Уровня 2 является функция MATLAB, которая задает свойства и поведение экземпляра блока Level-2 MATLAB S-function, который ссылается на функцию 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.
Чтобы создать S-функцию MATLAB, сделайте копию шаблона и отредактируйте копию по мере необходимости, чтобы отразить желаемое поведение S-функции, которую вы создаете. Следующие два раздела описывают содержимое шаблона кода MATLAB. Раздел Example Записи Уровня 2, который описывает S-функция MATLAB, как записать Уровню 2 S-функцию MATLAB, это моделирует единичную задержку.
API S-функции MATLAB Уровня 2 задает подписи и общие цели методов коллбэка, которые составляют Уровень 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 инициализирует экземпляр соответствующего блока Level-2 MATLAB S-function. В этом отношении, 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 свойства заменяют наследованное использование значений 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 метод. Уровень 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 в модели, скопируйте экземпляр блока Level-2 MATLAB S-function в модель. Откройте диалоговое окно Block Parameters для блока и введите имя файла MATLAB, который реализует вашу S-функцию в поле S-function name. Если ваша 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-функции MATLAB Уровня 2 обеспечивают набор самодокументирования моделей, которые иллюстрируют использование Уровня 2 S-функции MATLAB. Введите sfundemos в командной строке MATLAB, чтобы просмотреть примеры.
Уровень 2 S-функции MATLAB не поддерживают обнаружение пересечения нулем.
Вы не можете инициировать подсистему вызова функций от Уровня 2 S-функция MATLAB.
Level-2 MATLAB S-Function | S-Function Builder | S-Function | MATLAB Function