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, которая задает свойства и поведение экземпляра блока 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-функции Уровня 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 инициализирует экземпляр соответствующего блока 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 в модели, скопируйте экземпляр Уровня 2 MATLAB S-Functionblock в модель. Откройте диалоговое окно 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-функции Уровня 2 MATLAB обеспечивают набор самодокументирования моделей, которые иллюстрируют использование Уровня 2 S-функции MATLAB. Введите sfundemos
в командной строке MATLAB, чтобы просмотреть примеры.
Уровень 2 S-функции MATLAB не поддерживают обнаружение пересечения нулем.
Вы не можете инициировать подсистему вызова функций от Уровня 2 S-функция MATLAB.
Level-2 MATLAB S-Function | MATLAB Function | S-Function | S-Function Builder