Запишите уровню 2 S-функции MATLAB

Об уровне 2 S-функции MATLAB

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

Используйте базовый уровень 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, это моделирует единичную задержку.

Уровень 2 Методы коллбэка S-функции MATLAB

API S-функции Уровня 2 MATLAB задает подписи и общие цели методов коллбэка, которые составляют Уровень 2 S-функция MATLAB. Сама S-функция обеспечивает реализации этих методов коллбэка. Реализации в свою очередь определяют атрибуты блока (например, порты, параметры и состояния) и поведение (например, блок выходные параметры как функция времени и входных параметров блока, состояний и параметров). Путем создания 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

Следующие шаги иллюстрируют, как записать простому Уровню 2 S-функцию MATLAB. Когда применимо, шаги включают примеры от примера S-функции msfcn_unit_delay.m, используемый в модели msfcndemo_sfundsc2. Все строки кода используют имя переменной block для объекта периода выполнения S-функции.

  1. Скопируйте Уровень 2 S-шаблон-функции MATLAB msfuntmpl_basic.m к вашей рабочей папке. Если вы изменяете имя файла, когда вы копируете файл, меняете имя функции в строке function к тому же имени.

  2. Измените метод 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

      • 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.

  3. Инициализируйте дискретные состояния в методе 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).

  4. Инициализируйте значения дискретных и непрерывных состояний или других векторов 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;
  5. Вычислите выходные параметры S-функции в методе коллбэка Outputs. В данном примере установите вывод на текущее значение дискретного состояния, сохраненного в векторе DWork.

    Метод Outputs в msfcn_unit_delay.m:

    function Output(block)
    
      block.OutputPort(1).Data = block.Dwork(1).Data;
    
  6. Для S-функции с непрерывными состояниями вычислите производные состояния в методе коллбэка Derivatives. Объекты периода выполнения хранят производные данные в своем свойстве Derivatives. Например, следующая строка устанавливает первую производную состояния, равную значению первого входного сигнала.

    block.Derivatives.Data(1) = block.InputPort(1).Data;

    Этот пример не использует непрерывные состояния и, поэтому, не реализует метод коллбэка Derivatives.

  7. Обновите любые дискретные состояния в методе коллбэка Update. В данном примере установите значение дискретного состояния к текущему значению первого входного сигнала.

    Метод Update в msfcn_unit_delay.m:

    function Update(block)
    
      block.Dwork(1).Data = block.InputPort(1).Data;
    
  8. Выполните любую очистку, такую как очищение переменных или памяти, в методе Terminate. В отличие от S-функций MEX C, Уровень 2 S-функция MATLAB не требуются, чтобы иметь метод Terminate.

Для получения информации о дополнительных методах коллбэка смотрите Уровень 2 Методы Коллбэка S-функции MATLAB. Для списка свойств объекта периода выполнения смотрите страницу с описанием для Simulink.MSFcnRunTimeBlock и родительского класса Simulink.RunTimeBlock.

Инстанцирование уровня 2 S-функция MATLAB

Чтобы использовать Уровень 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

Генерация кода для модели, содержащей Уровень 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

Примеры S-функции Уровня 2 MATLAB обеспечивают набор самодокументирования моделей, которые иллюстрируют использование Уровня 2 S-функции MATLAB. Введите sfundemos в подсказке команды MATLAB, чтобы просмотреть примеры.

Ограничения S-функции MATLAB

  • Уровень 2 S-функции MATLAB не поддерживают обнаружение пересечения нулем.

  • Вы не можете инициировать подсистему вызова функций от Уровня 2 S-функция MATLAB.

Смотрите также

| | |

Похожие темы

Для просмотра документации необходимо авторизоваться на сайте