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 "external" storage of RMI links when working with Simulink models, as in Managing Requirements Without Modifying Simulink Model Files.
In addition, using the "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.
Open Example Model
This example demonstrates linking between external documents and MATLAB code lines when modeling stimulated spiking in connected neural cells.
Evaluate the following code to open the
slvnvdemo_synaptic_transmission Simulink model in the working directory and set a preference to allow proper communication for files in this example.
There are three Model blocks referencing the same model of a spiking neural cell which can be seen in
slvnvdemo_neuron.slx. Evaluate the code to open the model.
The neural cell model follows a "Leaky Integrators" equation:
For the purpose of simulation, this is converted to:
Two MATLAB Functions between neurons calculate post-synaptic currents. When pre-synaptic depolarization crosses the neurotransmitter release threshold, we increment post-synaptic current by one pulse of given amplitude:
The resulting total current decays exponentially according to:
The next increment is disallowed for a certain time frame after the previous pulse to model the effect of short-term synaptic depression. The model neglects the time delay of axonal transmission.
Simulate Model and View Results
Evaluate the following code to simulate
### Starting serial model reference simulation build. ### Successfully updated the model reference simulation target for: slvnvdemo_neuron Build Summary Simulation targets built: Model Action Rebuild Reason ============================================================================================= slvnvdemo_neuron Code generated and compiled. slvnvdemo_neuron_msf.mexa64 does not exist. 1 of 1 models built (0 models already up to date) Build duration: 0h 0m 40.677s
Manually check the
Scope block for results or evaluate the following code.
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 the
Synaptic current function block. Evaluate the code to navigate to the
Synaptic current block.
The 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 the default parameter values, the third neuron may spike 1 or more times, depending on intentionally introduced random noise in the model, by the
Noise current block in the
slvnvdemo_neuron model. Navigate to the
The same parameter values are assigned for all three neurons and both synapses. Traceability linking is used to justify parameter values and implementation.
Navigate Between Simulink and Standalone MATLAB Files
slvnvdemo_synaptic_transmission model runs an external script
synaptic_params.m to load required parameter values into workspace. If desired, open the script by evaluating the following code:
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.
Stimulation pulse block in the model manually or evaluate the following code.
Right-click the block and select Requirements > 1. "I_inj = 2e-11; % 20 pA" to follow the link and view the relevant highlighted region in the MATLAB code file, or evaluate the following:
open('synaptic_params.m'); % If desired, open the synaptic parameters script
rmidemo_callback('view','slvnvdemo_synaptic_transmission/Stimulation pulse',1); % Follow the Requirements link
Notice that in the
synaptic_params.m script, there is a mismatched parameter value. This is easily detected via Traceability link. Highlight line 12 in the
synaptic_params.m script which reads
V_syn_release = -2e-2; % -20 mV. Right click the selection and in the context menu, click Requirements > 1. slvnvdemo_synaptic_transmission/Synaptic release threshold (Constant). This navigates you back to the Simulink model and highlights the block that is linked to line 12 in
In Simulink, click the Apps tab and open Requirements Manager. Click Highlight links in the Requirements tab to highlight the links that you just created, or evaluate the following code.
Create Traceability Link for Lines of MATLAB Code
Evaluate the following code to make sure that bidirectional linking is enabled so that you can create two-way traceability links in one step.
Synaptic time constant block in the bottom left corner of the model is not yet linked to its related line in
synaptic_params.m. In the Simulink model, select the
Synaptic time constant block. If you can't find this block, evaluate the following code and then select it.
rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic time constant');
Then, in the MATLAB Editor, select the variable name Syn_decay_time at the bottom of the
synaptic_params.m script. Evaluate the following code to open the script, if you haven't already:
Right-click on the selected line and from the context menu, choose Requirements > Link to Selection in Simulink. Test the new links by navigating from MATLAB to Simulink and back to MATLAB.
Create Traceability Link for Lines of Code Inside MATLAB Function Blocks
slvnvdemo_synaptic_transmission model has a MATLAB Function block that you will use trace to parameter value sources to the
Synaptic strength constant block. In the Simulink model, click on the
Synaptic strength constant block or evaluate the following code to locate the block. To select it for linking, right-click the block and click Requirements > Select for Linking with Simulink.
Instead of linking the MATLAB function block itself, open the MATLAB code of this block and link specific lines. In the
slvnvdemo_synaptic_transmission model, navigate to the
Synaptic current block and double click it, or evaluate the following code.
In the MATLAB Function Block Editor, find the occurrence of I_amplitude on line 33 of the MATLAB Function block code. Highlight the line with the cursor to select it and then right-click it. Select Requirements from the context menu, then 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
Ion current calculation MATLAB Function block that belongs to the
Sodium current calculation subsystem of the referenced
slvnvdemo_neuron model, or evaluate the following code:
rmidemo_callback('emlshow','slvnvdemo_neuron/Sodium channel current/Ion current calculation').
Right-click in the MATLAB Function Block Editor and select Requirements > Enable Requirements Highlighting from the context menu to see which lines of code have requirements links.
Right-click on a line of code that's been highlighted to indicate it has a requirements link. From the Requirements context menu, navigate to a numbered link at the top of the menu. The associated Word document opens to the associated text. You can also open the Word document and visually identify the links by looking for an object similar to the MATLAB icon. You can navigate to the linked code by Ctrl+clicking this linked object.
Evaluate the following code to open the Word document:
To create a similar link to the
Ion current calculation Function in
Potassium channel current subsystem, open the Word document and use the Find function (Ctrl+F) to find the phrase "outward current of potassium ions." Select this phrase with your cursor in the Word document. Then, open the
Ion current calculation MATLAB Function block from above, or evaluate the following code:
rmidemo_callback('emlshow','slvnvdemo_neuron/Potassium channel current/Ion current calculation').
In the MATLAB Function Block Editor, select the implementation for outwardCurrent subfunction (lines 34-37). Right-click the selected lines and in the context menu, select Requirements > 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.
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. In the Requirements tab, click Share > Generate Model Traceability Report in the
slvnvdemo_neuron Simulink model. Evaluate the following code to open the model.
Note that the MATLAB Function block links information is present in the report, including quotations of linked MATLAB Code lines.