carputils
Doxygen code documentation for the python framework controlling openCARP
parfile2carputils: turn your openCARP parameter file into a carputils experiment

You have an openCARP experiment, configured with a .par parameter file, and you want to turn it into a carputils workflow?

With the script parfile2carputils included in carputils, you can easily turn such an experiment into a carputils script.

In short, this script creates a basic carputils script which integrates all openCARP options included in your parameter file. You get a carputils experiment reproducing the experiment configured in your parameter file, which you can elaborate on.

Quickstart

From the directory containing your parameter file parameters.par, run the command

parfile2carputils parameters.par

This will produce a carputils script named run.py containing all openCARP options included in your parameter file.

If your openCARP experiment can be run with

openCARP +F parameter.par

Then it can now also be run with

python run.py

Detailed example

Prerequisites

In order to use parfile2carputils, you need to have installed carputils and to have an openCARP experiment parametrized via a parameter file such as the following parameters.par:

#############################################################
simID = Ionic-Variability-Output
meshname = TestSlabMesher2D_i
#############################################################
dt = 20
timedt = 10
spacedt = 1
tend = 80
experiment = 0
parab_solve = 1
mass_lumping = 0
#############################################################
num_imp_regions = 4
#############################################################
imp_region[0].im = MahajanShiferaw
imp_region[0].num_IDs = 1
imp_region[0].ID[0] = 0
imp_region[0].im_param = "GNa*1"
imp_region[1].im = MahajanShiferaw
imp_region[1].num_IDs = 1
imp_region[1].ID[0] = 1
imp_region[1].im_param = "GNa*2"
imp_region[2].im = MahajanShiferaw
imp_region[2].num_IDs = 1
imp_region[2].ID[0] = 2
imp_region[2].im_param = "GNa*4"
imp_region[3].im = MahajanShiferaw
imp_region[3].num_IDs = 1
imp_region[3].ID[0] = 3
imp_region[3].im_param = "GNa*8"
#############################################################
num_gregions = 1
#############################################################
gregion[0].g_il = 1.0
gregion[0].g_it = 1.0
gregion[0].g_in = 1.0
gregion[0].num_IDs = 4
gregion[0].ID[0] = 0
gregion[0].ID[1] = 1
gregion[0].ID[2] = 2
gregion[0].ID[3] = 3
#############################################################
num_stim = 1
#############################################################
stim[0].ptcl.start = 0
stim[0].pulse.strength = 60
stim[0].ptcl.duration = 10
stim[0].crct.type = 0
stim[0].elec.vtx_file = LeftSideStim
#############################################################
num_LATs = 2
#############################################################
lats[0].all = 0
lats[0].method = 1
lats[0].measurand = 0
lats[0].threshold = -75
lats[0].ID = depol
lats[1].all = 0
lats[1].method = 1
lats[1].measurand = 0
lats[1].threshold = -75
lats[1].mode = 1
lats[1].ID = repol

Note: this example is taken from the openCARP example Cellular dynamics heterogeneity.

This experiment is typically run with openCARP using

openCARP +F parameters.par

Generate the carputils script

You can run

parfile2carputils parameters.par

in order to generate a carputils script named run.py, containing all options contained in parameters.par. This script will be independent from the original parameters file.

If your openCARP experiment can be run with

openCARP +F parameter.par

it can now also be run as a carputils experiment with

python run.py

Supplementary options

In order to get help on other options offered by parfile2carputils, you can run

parfile2carputils --help

Read parameters from the .par file

With the option --keep-parfile, you can decide to read parameters from the parameter file instead of copying all options in the carputils script. The parameter file will be copied within the ouput directory, unless a file with the same name already exists.

You can overwrite an existing parameter file with the option --overwrite-parfile.

Customize the output carputils script

Several options allow to customize the ouput carputils script: