%% Interface Specification Using Bus Objects
% This example shows how to propagate buses into referenced models.
% It also shows how you can simulate the referenced models independently
% using logged signal data from the parent model.

% Copyright 1990-2020 The MathWorks, Inc.

%% Open the Example Model
% Open and simulate the example model |sldemo_mdlref_bus|.

model = 'sldemo_mdlref_bus';
load_system(model);
sim_summary = evalc('sim(model)');
open_system(model);

% The evalc function captures the build summary.

%% Examine the Model
% The model contains a Model block named CounterA that references
% |sldemo_mdlref_counter_bus|, which is a model of a simple counter.
%
% An array of buses named COUNTERBUS feeds the data and the saturation
% limits of the counter into the model. The buses named COUNTERBUS each
% contain two elements: a data signal and a nested bus named LIMITBUS.
% The data is used in counting, and LIMITBUS contains the upper and lower
% limit values of the counter.
%
% The Model block has a second input port that connects to a bus named
% INCREMENTBUS. This bus contains elements that change the increment and
% reset the counter.
%
% The model uses a data dictionary file named |sldemo_mdlref_bus.sldd| that
% contains |<docid:simulink_ref#bvh6_eb-1>| objects that define the
% elements of COUNTERBUS, LIMITBUS, and INCREMENTBUS.
%
% To view the |Bus| objects, open the Bus Editor. In the Simulink(R)
% Toolstrip, on the *Modeling* tab, in the *Design* gallery, click *Bus
% Editor*.
%
% The model uses the |Bus| objects to specify the outputs of the following
% Bus Creator blocks:
%
% * COUNTERBUSCreator1
% * COUNTERBUSCreator2
% * LIMITBUSCreator1
% * LIMITBUSCreator2
% * IncrementBusCreator
%
% The Inport block named counter_input in |sldemo_mdlref_counter_bus|
% specifies the |Bus| object named |COUNTERBUS|. Double-click the block. In
% the Block Parameters dialog box, on the *Signal Attributes* tab, *Data
% type* is set to |Bus: COUNTERBUS|.
%
% The Inport block named increment_input is similarly configured to use
% the |Bus| object named |INCREMENTBUS|.

%% Log Signal Data
% These signals are marked for signal logging:
% 
% * COUNTERBUS
% * INCREMENTBUS
% * OUTERDATA
% * INNERDATA

%%
% After you simulate the model, the logged signals are available in the
% base workspace in the |topOut| variable.

topOut

%% 
% The model uses |Dataset| format for signal logging. To access |Dataset|
% format logged data for a given signal, use the |getElement| method:
%
%  topOut.getElement('COUNTERBUS')

topOut.getElement('COUNTERBUS')

%%
% Bus data is logged as a MATLAB(R) structure in the |Values| field:
%
%  topOut.getElement('COUNTERBUS').Values

topOut.getElement('COUNTERBUS').Values

%%
% This structure contains MATLAB |timeseries| objects for each bus:

%%
%  topOut.getElement('COUNTERBUS').Values(1).data

topOut.getElement('COUNTERBUS').Values(1).data

%%
%  topOut.getElement('COUNTERBUS').Values(2).data

topOut.getElement('COUNTERBUS').Values(2).data

%%
% You can also plot the logged data using the |plot| function:
%
%  topOut.getElement('OUTERDATA').Values.plot()

topOut.getElement('OUTERDATA').Values.plot()

%% Log Referenced Model Signals
% To log signals in the referenced model, select the Model block and click
% *Log Signals* on the *Model Block* tab.
%
% For this model, *Logging Mode* is set to |Log all signals as specified in
% model|. All the signals that are logged when simulating
% |sldemo_mdlref_counter_bus| as a top model are also logged when
% simulating it as a referenced model. To change logging for any of these
% signals or to log a subset of signals:
%
% # Set *Logging Mode* to |Override signals|.
% # In the *Model Hierarchy* pane, clear the *CounterA
% (sldemo_mdlref_counter_bus)* check box to indicate that this model should
% not use the |Log all signals as specified in model| setting.
% # In the table, select the signals to log when simulating the top model.
% # To save the changes, save the top model.

%% Load Data
% Open the referenced model |sldemo_mdlref_counter_bus| as a top model by
% clicking the *Open As Top Model* badge at the lower left corner of the
% Model block.

open_system('sldemo_mdlref_counter_bus')

%%
% The referenced model is configured to read the logged signal data through
% the root Inport blocks. To see this configuration, open the Configuration
% Parameters dialog box. In the Simulink Toolstrip, on the *Modeling* tab,
% click *Model Settings*. On the *Data Import/Export* tab, *Input* uses a
% comma-separated list to specify logged data from |topOut| for the two
% input ports. The *counter_input* port uses an array of structure of
% timeseries to load data for COUNTERBUS, and the *increment_input* port
% uses a structure of timeseries to load data for INCREMENTBUS.
%
% * |topOut.getElement('COUNTERBUS')|
% * |topOut.getElement('INCREMENTBUS')|
%
% You can configure the *Input* field by clicking the *Connect Input*
% button. The Root Inport Mapper tool opens. In this example, the tool uses
% a mapping algorithm to set up the *Input* field from logged data in the
% base workspace.
%
% To select the data to import:
%
% # In the Root Inport Mapper, click *From Workspace*.
% # Select the logged data |topOut| and click *OK*.
% # In the dialog box that opens, specify a file name and click *Save*.
%
% With the data loaded into the Root Inport Mapper tool, you can determine
% the root input port for which to assign input data. Simulink matches
% input data with input ports based on one of these criteria: block name,
% block path, signal name, port order, or a custom algorithm. Because
% |topOut| is logged using signal names from the model, the best choice for
% a mapping criterion is *Signal Name*. Using this criterion, Simulink
% tries to match input data variable names to the names of the input
% signals.
%
% To select this option:
%
% # In the Root Inport Mapper hierarchy pane, select scenario dataset
% |topOut|.
% # Click the *Signal Name* radio button.
% # Click the *Map to Model* button arrow, then click *Map All*.
%
% When mapping data, Simulink evaluates input ports against the input data
% to determine compatibility. The Root Inport Mapper table reflects the
% status of this compatibility with a green check mark, orange warning
% triangle, or red error exclamation mark. In this example, the table shows
% a green status indicating there is no compatibility issue. You can
% simulate the model with this mapping of input data to input ports. The
% mapping also sets *Input* in the *Data Import/Export* tab of the
% Configuration Parameters dialog to the proper comma-separated list of
% inputs. To apply the changes to the model, in the Configuration
% Parameters dialog, click *Apply*.

%% Simulate Model with Imported Data
% Simulate |sldemo_mdlref_counter_bus|.
%
% After simulation, the scopes from |sldemo_mdlref_bus| (|OUTERDATA|) and
% |sldemo_mdlref_counter_bus| (|INNERDATA|) show the same trace.
%
% <<../sldemo_mdlref_bus_scope.png>>
%
% <<../sldemo_mdlref_counter_bus_scope.png>>
%
% The signal feeding the scope in the referenced model is also logged. The
% logged data is available in the MATLAB workspace under the variable
% |subOut|. You can verify that the data in
% |topOut.getElement('OUTERDATA')| and |subOut.getElement('INNERDATA')| is
% the same.