Запишите уровню 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, которая задает свойства и поведение экземпляра блока 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

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

Следующие шаги иллюстрируют, как записать простому Уровню 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 свойства заменяют наследованное использование значений 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 метод.

  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.

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

| | |

Похожие темы

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