Smooth gradient heterogeneities (ionic adjustment)

See code in GitLab.
Author: Patrick Boyle pmjboyle@gmail.com

This example details how to assign a gradient of cell-scale properties using the adjustments interface. To run the experiments of this example change directories as follows:

cd ${TUTORIALS}/02_EP_tissue/05E_Smooth_Gradient_Heterogeneities

Problem Setup

This example will run one simulation using a 2D sheet model (1 cm x 1 cm) in which all elements and nodes are in the same imp_region[] and gregion[] but heterogeneity in cell-scale dynamics is imposed at the cell scale in gradient patterns using the adjustments interface.

By default, \(I_\mathrm{Kr}\) is modulated from 0x to 5x from left to right and \(I_\mathrm{to}\) is modulated from 0x to 5x from bottom to top. Both gradients are linear. The resulting pattern of excitation is shown below:

The stars are colour-coded and indicate the approximate locations from which the action potential traces shown below were extracted:

As expected, \(I_\mathrm{to}\) modulation leads to an abolished notch along the bottom edge of the sheet but an exaggerated notch along the top edge. \(I_\mathrm{kr}\) modulation in the sheet leads to a progressive shortening of action potential duration from left to right as more repolarizing current becomes available to the cells.

Usage

The following optional arguments are available (default values are indicated):

./run.py --help
  --xgrad_var         Options: {GCaL,GKs,GKr,Gto}, Default: GKr
                      parameter that should be varied along the left-to-right (X) gradient
  --xgrad_left_scf    Default: 0.0
                      scaling factor at left side of the X gradient
  --xgrad_right_scf   Default: 5.0
                      scaling factor at right side of the Y gradient
  --xgrad_flip        left becomes right, right becomes left

  --ygrad_var         Options: {GCaL,GKs,GKr,Gto}, Default: Gto
                      parameter that should be varied along the bottom-to-top (Y) gradient
  --ygrad_bottom_scf  Default: 0.0
                      scaling factor at bottom of Y gradient
  --ygrad_top_scf     Default: 5.0
                      scaling factor at top of Y gradient
  --ygrad_flip        down becomes up, up becomes down

If the program is run with the --visualize option, meshalyzer will automatically load the \(V_\mathrm{m}(t)\) sequence corresponding to the run simulation. Output files for activation and repolarisation sequences as well as APD are produced for each simulation and can be found in the output directory and loaded into meshalyzer.

The --xgrad[...] and --ygrad[...] parameters can be modified to impose different gradients in the x and y directions (i.e., left-to-right and bottom-to-top, respectively) in four different parameters: \(G_\mathrm{CaL}\), \(G_\mathrm{Ks}\), \(G_\mathrm{Kr}\), and \(G_\mathrm{to}\), which correspond to the L-type \(Ca^{2+}\), slow delayed rectifier \(K^{+}\), rapid delayed rectifier \(K^{+}\), and transient outward \(K^{+}\) currents, respectively.

Notes and Precautions

• The --xgrad_var and --ygrad_var parameters should not be set to the same value, otherwise the simulation will not behave as expected.
• The -adjustments[] interface in openCARP can only be used to modify cell-scale properties that correspond to a state variable in the ionic model being used.

Use the --imp-info argument of bench to find out which variables are eligible to bet set on a nodal basis. There are actually two types of variables listed as state variables, (1) actual state variables which describe the ionic model state and evolve with each time step, and (2) model parameters which affect behaviour but do not change. Thus, state variables can be intialized on a nodal basis. Parameters which can be set on a nodal basis must be listed as parameters, i.e., being listed up top, as well as being listed as state variables. For example, in the case of the tenTusscherPanfilov ionic model used in this example, the following are parameters which can be set nodally:

> bench --imp=tenTusscherPanfilov --imp-info
tenTusscherPanfilov:
[...]
  State variables:
                       GCaL
                       GKr
                       GKs
                       Gto

Under the Hood

In the parameter file, the following options are used to adjust nodal values. First, if you wish to adjust N variables:

num_adjustments = N

For each adjustment structure, i.e., adjustment[0], ..., adjustment[N-1], the following fields are set: