%% Associate Traceability Information with MATLAB Code Lines in Simulink
% Traceability management support in the MATLAB Editor is an extension of
% the Simulink-based Requirements Management Interface to allow associations
% between MATLAB code lines and external artifacts. This capability does not 
% require editing MATLAB files; all traceability data is stored separately.
% This is similar to <matlab:showdemo('slvnvdemo_powerwindow_external') "external"
% storage of RMI links when working with Simulink models>.
%
% In addition, using "external storage" mode for managing traceability
% information, Simulink and Stateflow users can benefit from finer
% granularity when associating external documents with contents of MATLAB
% Function blocks.
%
% The included example model has traceability data associated both with
% Simulink blocks and individual code lines of MATLAB Function blocks.

% Copyright 2013 The MathWorks, Inc.

%% Open Example Model
% This example demonstrates linking between external documents and MATLAB
% code lines when modeling stimulated spiking in connected neural cells.
%
% <matlab:open_system('slvnvdemo_synaptic_transmission') Open the slvnvdemo_synaptic_transmission model>.
% There are three Model blocks referencing the same 
% <matlab:open_system('slvnvdemo_neuron') model of a spiking neural cell>.
% The neural cell model follows a "Leaky Integrators" equation:
%
% $$ \frac{C_m\rm{d}V}{\rm{d}t} = I_{\rm total} - \frac{V-V_0}{R_m} $$
%
% $$ C_m,R_m - \mbox{capacitance and resistance of cell membrane} $$
%
% $$ I_{\rm total} - \mbox{includes injected stimulation current and all ion channel currents} $$
%
% $$ V_0 - \mbox{resting cross-membrane potential, typically -70mV} $$
%
% For the purpose of simulation, we converted to:
% 
% $$ V \rightarrow V_0 + \int\limits_0^t \frac{1}{C_m} (I_{\rm total} - \frac{V-V_0}{R_m}) \rm{d}t  $$
% 
% Two MATLAB Functions between neurons calculate post-synaptic currents.
% When presynaptic depolarization crosses the neurotransmitter release
% threshold, we increment post-synaptic current by one pulse of given
% amplitude:
%
% $$ I \rightarrow I + I_{\rm amplitude} $$
%
% Resulting total current decays exponentially according to
% 
% $$ \rm{d}I/\rm{d}t = - I * \frac{t}{\tau} $$
%
% We disallow the next increment for a certain timeframe after the
% previous pulse, to model the effect of short-term synaptic depression.
% Our model neglects the time delay of axonal transmission.
%

open_system('slvnvdemo_neuron');
open_system('slvnvdemo_synaptic_transmission');

%% Simulate Model and View Results
% <matlab:sim('slvnvdemo_synaptic_transmission') Simulate>
% slvnvdemo_synaptic_transmission model.
% Check <matlab:open_system('slvnvdemo_synaptic_transmission/Scope') Scope>
% for results. The six plots are: 
%
% * externally injected electrical current pulse,
% * injection-stimulated intracellular voltage spiking of the first neuron,
% * post-synaptic current generated in the second neuron,
% * synaptically stimulated activity of the second neuron,
% * post-synaptic current generated in the third neuron,
% * synaptically stimulated activity of the third neuron.
%
% Observe regular spiking of the upstream neuron (plot 2) while stimulation
% pulse is applied (plot 1). Synaptically induced current in downstream
% neuron (plot 3) skips some action potentials of the upstream neuron due
% to short-term neurotransmitter depletion modeled as a temporary turn-off
% period in 
% <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic%20current')
% Synaptic current function>. Downstream neuron is seen to, sometimes,
% integrate more than one synaptic input to produce a spike (plot 4).
% The third neuron integrates synaptic inputs from the second neuron (plot 5)
% and spikes at a later time (plot 6). With our default parameter values,
% the third neuron may spike 1 or more times, depending on intentionally
% introduced 
% <matlab:rmidemo_callback('locate','slvnvdemo_neuron/Noise%20current')
% random noise> in the model.
%
% We assign same parameter values for all three neurons and both synapses. 
% Traceability linking is used to justify parameter values and implementation.

sim('slvnvdemo_synaptic_transmission');


%% Navigate Between Simulink and Standalone MATLAB Files
% The <matlab:open_system('slvnvdemo_synaptic_transmission') slvnvdemo_synaptic_transmission model> runs
% an <matlab:edit('synaptic_params') external script> to load required
% parameter values into workspace.
% MATLAB code linking allows you to trace from a dependent block in Simulink, not
% only to a script file but to the specific line that defines a value used
% in simulation.
%
% Locate the
% <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Stimulation%20pulse')
% Stimulation pulse> block in the model. Right-click the block and select 
% *Requirements Traceability > 1. "I_inj = 2e-11;  % 20 pA"* to <matlab:rmidemo_callback('view','slvnvdemo_synaptic_transmission/Stimulation%20pulse',1)
% follow the link> and view the relevant highlighted region in the MATLAB code file. 
% Notice the mismatched value so easily detected via Traceability link.
% Right-click another highlighted line in the MATLAB file and navigate back to Simulink by
% selecting the shortcut in the *Requirements Traceability* context menu.

rmi('highlightModel', 'slvnvdemo_synaptic_transmission');
rmipref('UnsecureHttpRequests',true);
rmipref('BiDirectionalLinking',true);

%% Create Traceability Link for Lines of MATLAB Code
% The <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic%20time%20constant')
% Synaptic time constant> block in the bottom left corner of the model is not yet linked to
% its related line in <matlab:edit('synaptic_params') parameters script>.
%
% <matlab:rmipref('BiDirectionalLinking',true) Make sure that bidirectional
% linking is enabled>, so that you can create two-way traceability links in one step.
% First, in the Simulink Editor, select the 
% <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic%20time%20constant')
% Synaptic time constant> block. Then, in the MATLAB Editor, select the
% variable name *Syn_decay_time* at the bottom of the <matlab:edit('synaptic_params')
% synaptic_params script>. Right-click on the selected line and from the
% context menu, choose *Requirements Traceability > Link to Selection in Simulink*.
% Test the new links by navigating from MATLAB to Simulink and back to MATLAB.
%
% <<synaptic_params.png>>
%

%% Create Traceability Link for Lines of Code Inside MATLAB Function Blocks
% The <matlab:open_system('slvnvdemo_synaptic_transmission')
% slvnvdemo_synaptic_transmission model> has a
% <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic%20current')
% MATLAB Function block>
% that we will want to trace to parameter value sources. Instead of linking
% the block itself,
% <matlab:rmidemo_callback('emlshow','slvnvdemo_synaptic_transmission/Synaptic%20current')
% open the MATLAB code> of this block and link specific lines. For example, in the 
% Simulink Editor, click on the 
% <matlab:rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic%20strength')
% Synaptic strength> constant block to select it for linking. In the MATLAB
% Editor, find the occurrence of *I_amplitude* on line 33 of the 
% <matlab:rmidemo_callback('emlshow','slvnvdemo_synaptic_transmission/Synaptic%20current')
% MATLAB Function block code>. Right-click the line and from the *Requirements Traceability* context menu, select 
% *Link to Selection in Simulink*.

%% Create Traceability Link Between Lines in MATLAB Code and Microsoft Word
% Until this point we only looked at linking between MATLAB and Simulink.
% Open the
% <matlab:rmidemo_callback('emlshow','slvnvdemo_neuron/Sodium%20channel%20current/Ion%20current%20calculation')
% Ion current calculation MATLAB Function block> that belongs to the 
% <matlab:rmidemo_callback('locate','slvnvdemo_neuron/Sodium%20channel%20current')
% Sodium current calculation subsystem> of the referenced 
% <matlab:open_system('slvnvdemo_neuron') slvnvdemo_neuron model>.
% Right-click on a highlighted line or lines and from the *Requirements Traceability* 
% context menu, navigate a link at the top. The associated Word document opens to
% the associated text.
%
% To create a similar link in another MATLAB Function block of this model, 
% <matlab:rmidemo_callback('locate','slvnvdemo_neuron/Potassium%20channel%20current/Ion%20current%20calculation')
% Ion current calculation Function> in
% <matlab:rmidemo_callback('locate','slvnvdemo_neuron/Potassium%20channel%20current')
% Potassium channel current subsystem>, select the relevant content in the
% Word document (i.e. *outward current of potassium ions*). Then, 
% <matlab:rmidemo_callback('emlshow','slvnvdemo_neuron/Potassium%20channel%20current/Ion%20current%20calculation')
% open the Potassium channel current MATLAB Function block>. In the MATLAB Editor,
% select the implementation for *outwardCurrent* subfunction (lines 34-37).
% Right-click the selected lines and in the context menu, select *Requirements Traceability > Link to Selection in Word*.
% Minimize the Word document, then navigate from the newly
% highlighted lines at the bottom of the MATLAB code to the related description in Word.
% When the correct location is highlighted, use the MATLAB icon to
% navigate back to code.
%
% <<outwardCurrent.png>>
%
% <<outwardDescription.png>>
%

%% Report Traceability Links
% Traceability links associated with MATLAB code lines of MATLAB Function
% blocks are included in the *Requirements Traceability Report* generated for
% the parent Simulink model. Use *Analysis > Requirements Traceability >
% Generate Report* in
% <matlab:open_system('slvnvdemo_neuron') slvnvdemo_neuron model window> to
% generate the 
% <matlab:rmi('report','slvnvdemo_neuron') report>. 
% See MATLAB Function block links information present in the
% report, including quotations of linked MATLAB Code lines.
%
% <<report_command.png>>
%
% <<report_html.png>>
%


displayEndOfDemoMessage(mfilename)


