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.

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.

open('slvnvdemo_synaptic_transmission.slx');
rmipref('UnsecureHttpRequests',true);

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.

open('slvnvdemo_neuron.slx');

The neural cell model follows a "Leaky Integrators" equation:

$$\frac{C_{m}dV}{dt}=I_{total}-\frac{V-V_0}{R_m}$$

$$C_m,R_m-\text{capacitance}\text{and}\text{resistance}\text{of}\text{cell}\text{membrane}$$

$$I_{total}-\text{includes}\text{injected}\text{stimulation}\text{current}\text{and}\text{all}\text{ion}\text{channel}\text{currents}$$

$$V_0-\text{resting}\text{cross}\text{-}\text{membrane}\text{potential,}\text{typically}\text{-}\text{70mV}$$

For the purpose of simulation, this is converted to:

$$V\to V_0+\underset{0}{\overset{t}{\int }}\frac{1}{C_m}(I_{total}-\frac{V-V_0}{R_m})dt$$

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:

$$I\to I+I_{amplitude}$$

The resulting total current decays exponentially according to:

$$\frac{dI}{dt}=-I*\frac{t}{\tau }$$

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 slvnvdemo_synaptic_transmission model.

sim('slvnvdemo_synaptic_transmission');

### Searching for referenced models in model 'slvnvdemo_synaptic_transmission'.
### Found 1 model reference targets to update.
### Starting serial model reference simulation build.
### Successfully updated the model reference simulation target for: slvnvdemo_neuron

Build Summary

Model reference simulation targets:

Model             Build Reason                                         Status                        Build Duration
===================================================================================================================
slvnvdemo_neuron  Target (slvnvdemo_neuron_msf.mexa64) did not exist.  Code generated and compiled.  0h 0m 24.633s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 30.182s

Manually check the Scope block for results or evaluate the following code.

open_system('slvnvdemo_synaptic_transmission/Scope');

The six plots are:

1. externally injected electrical current pulse

2. injection-stimulated intracellular voltage spiking of the first neuron

3. post-synaptic current generated in the second neuron

4. synaptically stimulated activity of the second neuron

5. post-synaptic current generated in the third neuron

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

rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic current');

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 Noise current block.

rmidemo_callback('locate','slvnvdemo_neuron/Noise current');

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

The 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: open('synaptic_params.m').

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 Stimulation pulse block in the model manually or evaluate the following code.

rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Stimulation pulse');

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 synaptic_params.m.

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.

rmi('highlightModel', 'slvnvdemo_synaptic_transmission');

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.

rmipref('BiDirectionalLinking',true);

The 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: open('synaptic_params').

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

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

rmidemo_callback('locate','slvnvdemo_synaptic_transmission/Synaptic strength');

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.

rmidemo_callback('emlshow','slvnvdemo_synaptic_transmission/Synaptic current');

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: open('NeuralSpikeModeling.docx').

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.

open('slvnvdemo_neuron.slx');

Note that the MATLAB Function block links information is present in the report, including quotations of linked MATLAB Code lines.