openCARP is a cardiac electrophysiology simulator freely available for academic purposes.
This Software Management Plan covers openCARP, the needed infrastructure, a description of the documentation files, the developing and testing of the software, as well as the current and future management to ensure continuity of the project.
openCARP comprises the openCARP electrophysiology simulator (written in C++) and the carputils framework (written in Python), a user-friendly abstraction layer supporting the definition and management of in silico experiments. There are also more components like meshtool , meshalyzer , and carputilsGUI in the openCARP ecosystem.
openCARP is developed in a multi-lab effort, partly within the SuLMaSS project (Sustainable Lifecycle Managment for Scientific Software, ended 2021) and the CARPe-diem project (Rolling out the openCARP simulator as a sustainable e-research infrastructure) funded by the German Research Foundation (DFG), partly within the MICROCARD project funded by the European High-Performance Computing Joint Undertaking EuroHPC (JU) under grant agreement No 955495. The JU receives support from the European Union’s Horizon 2020 research and innovation programme and France, Italy, Germany, Austria, Norway, Switzerland.
We provide a high-quality, user-friendly open cardiac electrophysiology simulator software for in-silico experiments. It offers single cell as well as multiscale simulations from ion channel to organ level. Additionally, openCARP includes a wide variety of functions for pre- and post-processing of data as well as visualization.
Our software is designed to be used by researchers in the field of cardiac electrophysiology. Besides computational scientists, we target those working experimentally (integrating their data into the model to quantify their results), pharmaceutical companies (virtually testing the therapeutic potency or arrhythmic risk of new compounds) and regulatory entities (e.g. FDA who are already partly use numerical models for drug testing), medical device companies (understanding measured signals and testing new diagnostic options). Moreover, openCARP can be used in an educational setting in several disciplines (engineering, physics, medicine, computer science) to understand and visualize the complex electrophysiological function of the heart.
openCARP is available via the web page as the central entry point. On this page, we provide binary versions of the software for macOS and Linux systems. We also provide a Docker image, which includes everything for running the software and is runnable on cross-platform (macOS, Linux, and Windows). Moreover, the web page links to our Gitlab instance hosting the code repositories for source code access and project management infrastructure.
The openCARP cardiac electrophysiology simulation software package provides a common framework & pipelines for research groups working on cardiac electrophysiology. For all these groups, we provide an easy way to share and reproduce in-silico experiments, thus fostering open science and supporting reproducibility. Furthermore, the user documentation (including tutorials) and a friendly environment appeal to both experienced and new users alike. Publicy available source code allows for development and adaptation of the core software to the needs of the individual application and supports sharing contributions with the community.
On the one hand, we track the number of citations to the software in scientific publications using an automated workflow. Moreover, the number of active users, merge requests, commits, and issue reports will be used as metrics.
A repository for reliable long-term storage will be utilized to persistently archive openCARP. Our solution will build on an existing research data archive under consideration of the specific requirements of research software, e.g., versioning. To accommodate the needs for permanent access to software and virtual research environments, we will integrate the components for long-term data storage with features for versioning, annotation, and sharing.
We will use a GitLab instance as our main DevOps platform to manage and maintain the project to shorten the time of development and ensure the release of high-quality software. We have taken advantage of the continuous delivery and intergeration pipelines to:
The website is based on Grav, a flat-file content management system. We provide a Q&A system for the community to interact.
Our infrastructure is hosted at the Steinbuch Centre for Computing (SCC) at KIT.
Our software is written in C++ and Python. The openCARP developers aim to write code that is easy to understand and complemented by comments where it is not fully self-explanatory. These languages have well defined standards and are used by a large group of active developers. Generally, the openCARP code is documented with structured comments that are parsed by Doxygen to automatically generate documentation and a software architecture description. Both are available through the website.
Our code is reviewed by one other developer before entering the master branch. Merge request have to be accepted by maintainers as a quality control mechanism. This ensures that knowledge of the code structure and logic is shared between several members of the developer team.
Details on how to contribute, particularly to invite new developers, are outlined in a dedicated CONTRIBUTING document in the repository and the website including our coding conventions.
Once the maintainer reviewed the code and merges the contribution to the master branch, the continuous integration pipeline is triggered. The code is compiled and regression tests are evaluated.
Initial test cases were defined based on the experience of the longterm users of the software. Whenever new functionality is included and whenever unexpected behavior is encountered, the developers will consider to extend the test suite by additional tests to cover this part.
openCARP offers a testing framework based on carputils. This framework provides a wide range of python functionality for setting up, running, and postprocessing and testing the results of openCARP simulations.
Users can easily define new tests and create reference soultions using the provided carputils module for tests. This module will ensure consistency in the input parameters and the validation against the correspoding reference solution. Users can also calculate absolute/relative deviations between their soultion and the reference.
New tests can be written by all contributiors using the tailored test functions in the carputils framework.
All tests are part of our CI/CD pipeline implemented in Gitlab. Relevant tests are run for each commit to the master branch based on the affected files after successful compilation. The entire test set is run for releases. Smaller test sets with limited resource demand are run for commits to all public branches on the central Gitlab instance.
The test definitions are publicly available in the project repository. The results of the test for the different branches and releases will be publicly available on the web page.
As a part of our documentation, we will provide tailored developer-oriented information. Diagrams of the software architecture as well as detailed explanation of function parameters with their corresponding types and ranges are automatically generated (and kept in sync with the code) using Doxygen. This gives new developers an introduction to our software architecture and the possibility to modify and extend the code. The testing environment and reference solutions, which can be used to test new implementations, are available in the openCARP experiments repository.
Our software is cross-platform and runs on macOS and most Linux distributions. Likely it will run on Windows as well but this OS if currently not fully supported. We provide several options to install the software. The user can download the available binary packages for a specific OS, use the automatically provisoned docker containers, or build the software from the sources.
openCARP can read models in the CellML format as e.g. provided in the CellML repository. However, openCARP does not require any third-party data to work.
MPI is a standardized and portable message-passing standard designed to work on a wide variety of parallel computing architectures. openCARP has been written to run in either of two parallel computation modes: a shared memory model, or a distributed memory model. A large common code base is maintained between the two versions and only low-level wrapper functions implement the specific memory model. Parallelization is realized in the shared memory model based on OpenMP directives and native numerical libraries. For distributed memory parallelization, extensive use is made of the PETSc parallel library as well as MPI function calls.
Moreover, the software offers a tool to convert different file formats to the required input format. The output format is one or more IGB files. IGB is a format developed at the University of Montreal and originally used for visualizing regularly spaced data. An IGB file is composed of a 1024-byte long header followed by binary data which is terminated by the ASCII form feed character ( ^L / character 12). Addionally, several input and output file formats are supported. These foster interoperatbility of pre- and postprocess with openCARP using standard file formats (e.g. VTK, HDF5, CellML).
Dependencies will be listed in the documentation (INSTALL.md) as required packages. We explicitly name the version of the dependencies that were used to build the stable version of our software.
The SuLMaSS project was initially funded by the German Research Foundation (DFG) for a period of 3 years (2018-2021) providing human resources to two teams in Karlsruhe and Freiburg. There is one person per team working full time on the project with support from several other team members. From 2023-2026, DFG continues support for openCARP as an electronic research infrastructure in the CARPe-diem project at KIT. Furthermore, the MICROCARD project funded by the European High-Performance Computing Joint Undertaking EuroHPC (JU) under grant agreement No 955495 supports HPC advancement and use of openCARP. The JU receives support from the European Union’s Horizon 2020 research and innovation programme and France, Italy, Germany, Austria, Norway, Switzerland. Additional contributions from the groups in Graz and Bordeaux are supporting the project.
Besides the efforts of the core teams, openCARP welcomes contributions from the community. We hold monthly developer video calls to coordinate the efforts.
openCARP is a meritocratic, consensus-based community project. Anyone with an interest in the project can join the community, contribute to the project design and participate in the decision making process. The roles are defined in our governance document. In brief, there are users, developers, maintainers and the steering committee. Responsible persons for certain action points are assigned in the Gitlab issue tracker.
Using the Gitlab issue board, we monitor milestones that were set and assigned to specific persons or groups. Internally, each team reports to the respective principal investigator. In addition, biweekly video meetings with all teams are organized to coordinate the efforts.
We use agile development, which offers a rapid and continuous delivery of the software. It advocates a lighter and more developer-centric viewpoint than traditional approaches based on iterative cycles of development and feedback. This ensures a goal-oriented development driven by user needs and consideration of the time schedule.
Releases are scheduled when new features are ready (major version) and bugs are fixed (minor version). After passing the test suite, a release can be initiated by assigning a git tag. The release process itself is automated with continuous integration pipelines including persistent archival in the RADAR4KIT repository and DOI assignment according to the FAIR4RS principles.
The primary way to manage openCARP knowledge is through documentation. Therefore, we set up a pipeline to automatically produce documentation based on the versioned code (user documentation for parameters, code documentation). In this way, the additional documentation-related effort for developers is kept to the minimum and it is ensured that the code and the documentation are always synchronized. A sizeable group of maintainers (currently 12) and steering committee members (currently 5) from different research groups are the basis for continuity. Regular developer meetings, which is mainly focused on sharing knowledge of the current and future implementations, are attended by all members of the steering committee ensuring retainability of knowledge. Discussions are held publicly in the related Gitlab issues, which allow to go back to them later and follow up on the reasons why certain decisions were taken (see also GOVERNANCE.md).
This software management plan will be reviewed once a year by the members of the steering committee. Based on this evaluation, appropriate changes are implemented if required.
We will disseminate the software and promote its use by:
Unique selling points of openCARP that will likely attract additional users are in particular:
On the website, we provide a question and answer system. Ideally, users will find an answer to their question based on a previously asked question. If this is not the case, the community tries to answer the question. In particular, one or more maintainers will regularly check unanswered questions and try to answer or redirect the question to a possibly existing solution.
Users can contribute in various ways as detailed in our dedicated CONTRIBUTING document. Code contributions will be considered based on merge requests to the master branch as detailed in our governance model. In brief, requests will be reviewed by one of the maintainers and accepted if they add value to openCARP. The review process also includes the testing pipeline.
The copyright is owned by NumeriCor. Contributions to the software are subject to the Contributor license agreement.
The license is the Academic Public License (openCARP, v1.1). For more details on the license please visit the openCARP license webpage.
The copyright and the license are included in the repositories and available on the openCARP web page. A short version of the copyright and license is included in the header of all code files.
As a first instance, the code and the documentation including their history are stored in the version control system. Moreover, release versions are automatically deposited in a long-term archive (see below) together with the relevant metadata. In this process, a DOI is minted as part of our continiuous deployement pipeline. These archived versions are findable, accessible, preserved, and referenceable according to the FAIR principles.
We developed mechanisms to automatically build submission information packages for release version of openCARP and store them in the long-term research repository RADAR4KIT. These CI pipelines are available for the wider community as part of the openCARP-CI project.
The openCARP software management plan was inspired by the SMP guide of the UK Software Sustainability Institute.
openCARP is a cardiac electrophysiology simulator freely available for academic purposes.
© Copyright 2020 openCARP project Supported by DFG and EuroHPC Contact Imprint and data protection