openCARP (single-cell bench)

What it simulates

openCARP is a cardiac electrophysiology simulator for tissue and organ models. Its bench tool is the single-cell part. It integrates one cell's ionic model, a set of ordinary differential equations for the membrane voltage, ion channel currents and ion concentrations. A stimulus current is injected at set times, and bench writes the voltage and chosen currents over time.

You pick an ionic model with --imp, such as tenTusscherPanfilov (a human ventricular cell) or OHara. You set the stimulus (strength, duration, count, spacing) and the run length. Units are ms, mV and uA/cm^2.

The example paces one cell twice, 500 ms apart, with a 1 ms stimulus of 30 uA/cm^2, for 1000 ms. The key assumption is that the cell is isolated. There is no coupling to neighbors, so the output shows the cell's own action potential (AP) response to the pacing.

When to use it

Use bench for single-cell questions:

• How long is the action potential for a given model and pacing rate?
• What stimulus strength triggers an action potential?
• How do models differ in their currents, for example ICaL or IKr?

PyLEMS runs models written in LEMS and XPPAUT runs general ODE systems. Use openCARP when you want a curated cardiac ionic model (the recipe lists 16 models for --imp: tenTusscherPanfilov, LuoRudy91, LuoRudy94, Courtemanche, Grandi, OHara, Tomek, Fabbri, MitchellSchaeffer, AlievPanfilov, HodgkinHuxley, Fox, Shannon, Nygren, Maleckar and Skibsbye). Tissue and organ simulations need the full openCARP, which this guide does not cover.

Install it yourself

The conda-forge package is opencarp. A dry run micromamba create -n t --dry-run -c conda-forge -c bioconda opencarp=19.0.0 resolves opencarp 19.0.0 on linux-aarch64. The package license is the openCARP Academic Public License.

conda create -n opencarp -c conda-forge opencarp=19.0.0
conda activate opencarp

The minimal command is the tool's own, with no helper script:

bench --imp tenTusscherPanfilov --stim-curr 30 --stim-dur 1 --duration 1000 \
      --numstim 2 --bcl 500 --dt 0.01 --dt-out 1 --fout=bench_vm

bench --list-imps lists models. bench --imp tenTusscherPanfilov --imp-info prints that model's tunable parameters and state variables. bench --help shows all options. The ones used here: --stim-curr (default 60), --stim-dur (default 1 ms), --numstim (default 1), --bcl (default 1000 ms), --dt (default 0.01 ms), --dt-out (default 1 ms), --fout and --duration.

Reading the output

The command writes three kinds of file, plus the log on standard output.

• bench_vm.txt (44044 bytes) has 1001 lines at 1 ms steps. The first column is time and the second is the voltage. It starts at 0 ms with -86.2 mV. At 3 ms the voltage is +39.4 mV, the peak of the first action potential. A third column follows, which the bench help does not name.
• Trace_0.dat (262588 bytes) is tab-separated with 1001 rows and 17 columns. Column 1 is time. The other 16 are listed in tenTusscherPanfilov_trace_header.txt: sv->CaSR, sv->CaSS, sv->Cai, ICaL, IK1, IKr, IKs, INa, INaCa, INaK, IbCa, IbNa, IpCa, IpK, Ito and V.
• bench_log.txt (273 bytes) holds the timing. The main loop took 0.0525 s for 1000 ms of cell time.

In Trace_0.dat, row 3 (t = 2 ms) has INa at -8.05 uA/cm^2, and the voltage is -56.8 mV, on the way up to the +39.4 mV peak.

Your own runs

Copy the docker run line from the recipe and change values. The reference run keeps the voltage above -20 mV for 275 ms after the first stimulus and 518 ms over both.

1. Another model. Set --imp OHara. The resting voltage was -87.0 mV, against -86.2. The first action potential stayed above -20 mV for 244 ms and the peak was +39.4 mV (39.37 against 39.44 for tenTusscherPanfilov). The run had the same number of files, with a different trace header.
2. Weaker stimulus. Set --stim-curr 5. No action potential fired. The voltage never rose above -81.5 mV, and it was 0 ms above -20 mV. A 5 uA/cm^2 pulse moved the cell about 5 mV.
3. Faster pacing. Set --bcl 300 and --numstim 3. The first beat stayed above -20 mV for 275 ms. At 300 ms the voltage was still -58.2 mV. The second stimulus at 301 ms raised it only to -33.3 mV, and no action potential followed. The third stimulus at 601 ms fired a full action potential of 259 ms above -20 mV.

Pitfalls

• Subthreshold stimuli give no error. The weak run completed with a flat trace. Check the peak voltage in bench_vm.txt.
• Units. Current is in uA/cm^2 (the same as pA/pF), time in ms and voltage in mV. Do not paste current values from papers in other units.
• --duration and --numstim. The last stimulus must fit inside the duration. With 2 stimuli and 500 ms spacing, 1000 ms covers both beats.
• Fast pacing skips beats. At a 300 ms cycle the second stimulus found the cell not yet recovered. Count the beats that fired, because the stimuli sent overcount them.
• Start state. Beat one starts from the model's default initial state, so early beats may differ from later ones.

Further reading

• openCARP site: https://opencarp.org/
• Basic bench example: https://opencarp.org/documentation/examples/01_ep_single_cell/01_basic_bench
• User manual: https://opencarp.org/documentation/user-manual
• Plank G, Loewe A, Neic A, et al. (2021). The openCARP simulation environment for cardiac electrophysiology. Comput Methods Programs Biomed 208:106223. https://doi.org/10.1016/j.cmpb.2021.106223