News

The parameter handling in openCARP and mesher has been reworked with one goal in mind: make it easier to run, share, and maintain simulations without changing how existing studies are launched. The changes described below are available in builds from the latest state of the master branch and will be included in the next release version.

From a user perspective, the biggest changes are straightforward:

• +F / --file can now read .par, .toml, and .json
• command-line control options are now available in a more familiar --... style in addition to the legacy +... forms
• array-like sections are easier to express in modern formats and array controller fields can now be omitted when their size can be inferred from the provided data
• +Doc <topic> and --doc <topic> give more focused parameter help
• parameter docs can now carry citations and example references

.par files and the old command line interface remain fully supported, so existing workflows do not need to be rewritten.

What Changed for Users?

1. Modern input file formats

Historically, parameter files were written as .par files:

dt = 25
num_imp_regions = 1
imp_region[0].name = tissue
imp_region[0].im = LuoRudy91
imp_region[0].im_param = "flags=EPI"

That format still works, but openCARP can now also read:

• .toml
• .json

The parser is selected automatically from the file suffix when you call:

openCARP --file experiment.par
openCARP --file experiment.toml
openCARP --file experiment.json

This makes it easier to choose the right format for the job:

• use .par when you want full backward compatibility
• use .toml when humans will edit the file regularly
• use .json when the file is generated by scripts or other tools

2. Modern formats are much easier for lists and repeated blocks

The modern formats are especially helpful for repeated sections like imp_region, stim, stimulus, or gregion.

TOML example

dt = 25

[[imp_region]]
name = "endo"
im = "LuoRudy91"
im_param = "flags=ENDO"
ID = [1, 2]

[[imp_region]]
name = "epi"
im = "LuoRudy91"
im_param = "flags=EPI"
ID = [5, 6, 7]

JSON example

{
  "dt": 25,
  "imp_region": [
    {
      "name": "endo",
      "im": "LuoRudy91",
      "im_param": "flags=ENDO",
      "ID": [1, 2]
    },
    {
      "name": "epi",
      "im": "LuoRudy91",
      "im_param": "flags=EPI",
      "ID": [5, 6, 7]
    }
  ]
}

In these formats, repeated parameter groups are naturally expressed as lists of objects instead of manually managing long sequences of indexed assignments.

3. Count fields can be omitted

The old input style requires explicit controller fields such as:

• num_imp_regions
• num_stim
• imp_region[i].num_IDs

The new parser can infer these counts from the actual data.

So instead of writing:

num_imp_regions = 2
imp_region[0].num_IDs = 2
imp_region[1].num_IDs = 3

you can just provide the list content itself and let the parser determine the required sizes.

That makes modern parameter files shorter and less error-prone, especially for large region lists and nested arrays.

4. A More Consistent Command-Line Style

The parser still accepts the traditional +... control syntax, but it now also supports a --... style for the same actions. This makes the interface feel more familiar to users coming from tools such as bench, which uses a gengetopt-style command line.

Examples:

openCARP +F experiment.par
openCARP --file experiment.par

openCARP +Doc dt
openCARP --doc dt

openCARP +Help
openCARP --help

The new long forms currently cover the command-line control actions around files, documentation, help, saving, defaults, and interactive/run modes. The legacy forms remain valid, so existing scripts do not need to change.

5. Better help and scoped documentation

The command-line help path has also been cleaned up.

The legacy forms still work, but you can now also use long options such as:

openCARP --help
openCARP --doc dt
openCARP +Doc dt

Scoped documentation is useful when you only want details for a specific parameter instead of the full help text.

6. Documentation Now Carries More Context

The parameter schema now supports extra metadata that can be surfaced to users:

• citations
• example coverage

That metadata is shown in parameter documentation and is also propagated into the generated XML used for the manual and the website parameter overview.

For users, that means parameter docs can now in principle tell you:

• which publication a feature should be cited with
• which examples already exercise that feature

At runtime, openCARP can also suggest citations at the end of a simulation when you explicitly activated a parameter that carries citation metadata. For now, we have the infrastructure ready and will populate these fields step by step in the future.

Temporary Compatibility Gate During Rollout

During the rollout, openCARP currently evaluates the new parser and the legacy param() path side by side and compares the resulting parameter state before the simulation proceeds.

For legacy-compatible startup input, this comparison is done against the original command line and original .par file input, not against a parser-generated surrogate file.

There are a few cases where no true legacy baseline exists and the comparison is therefore skipped:

• .toml input files
• .json input files
• startup inputs where the new parser had to infer optional count/controller fields that were omitted by the user (num_gregions etc.)

If a mismatch is detected, the simulation stops by default. Users are asked to open an issue on the openCARP GitLab project and include the triggering command line and parameter files:

https://git.opencarp.org/openCARP/openCARP/-/work_items

--run remains available as the explicit run directive, but it does not bypass this mismatch check. If you need to continue temporarily despite a mismatch, use the legacy fallback path instead, either via the command line or via an environment variable:

openCARP --param-fallback=legacy --run --file experiment.par

OPENCARP_PARAM_FALLBACK=legacy openCARP --run --file experiment.par

What Did Not Change

The update is meant to improve usability, not force immediate migration.

• existing .par files still work
• existing command-line driven workflows still work
• legacy parameter semantics are preserved where possible

If you already have a stable workflow, you can keep it. If you are starting a new project, you now have better options.