openCARP Software Management Plan

Project overview

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.

openCARP is developed in a multi-lab effort, partly within the SuLMaSS project (Sustainable Lifecycle Managment for Scientific Software) funded by the German Research Foundation (DFG).

About your software

What software will you write?

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.

Who are the intended users of your software?

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.

How will you make your software available to your users?

openCARP is available via the web page as the central entry point. On this page, we provide binary versions of the software for common operating systems (macOS, Linux, Windows 10). Moreover, the web page links to our Gitlab instance hosting the code repositories for source code access and project management infrastructure.

How will your software contribute to research?

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.

How will you measure its contribution to research?

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.

Your software development infrastructure

What infrastructure will you need?

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 take advantage of the continuous delivery and intergeration pipelines to:

  • Test the software on a regular basis (commit-based)
  • Test new commits ensuring the consistence and quality of the software
  • Create release files

The website is based on Grav, a flat-file content management system. We provide a Q&A system for the community to interact.

Where will your infrastructure be hosted?

Our infrastructure is hosted at the Steinbuch Centre for Computing (SCC) at KIT.

Developing good software

How you will deliver code that can be understood?

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.

How you will deliver good quality code?

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.

How will you choose your test cases?

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.

How will you make it easy to write and run tests?

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.

How will you ensure that your software is tested regularly?

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.

How will you let users know about the tests you do?

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.

How will you help developers to understand, modify, extend and test your software?

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 repository.

Will your software run under multiple environments?

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.

Managing your dependencies

What third-party software, models, tools, libraries and services will you use?

Libraries shipped with openCARP

  • PETSc (BSD 2-clause)
  • openMPI (BSD 3-clasue )
  • MUMPs (permissive CeCILL-C license)
  • HDF5 (BSD 3-clause)
  • VTK (BSD 3-clause)
  • FLTK (LGPL, used in meshalyzer)

Software shipped with openCARP

  • Python (Python Software Foundation PSF license; BSD-style, GPL compatible)
  • Python modules
    • pandas (BSD 3-clause)
    • numpy (BSD 3-clause)
    • scipy (BSD 3-clause)
    • matplotlib (PSF license)
    • toolcompendiumLatex (Copyright (C) 2019 IAM-CMS)

Software for the compilation workflow

  • C++/C compiler
  • CMake
  • Docker
  • gengetopt
  • git
  • make

Code integrated in openCARP

  • cexcept ("permission to do whatever they like")
  • muParser (permissive license)
  • y.tab (no restrictions for integration in non-parser software)

Services

  • GitLab, hosted at SCC (KIT)
  • Web hosting provided by SCC (KIT)
  • Email service (including mailing lists) provided by SCC (KIT)

What third-party data sets and online databases will you use?

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.

What communication protocols and data formats will you use?

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).

How will you document your dependencies?

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.

Managing your software development

What effort will be available to develop your software?

The project is currently funded by the 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. Additional contributions from the groups in Graz and Bordeaux are supporting the project. In future, we hope for contributions from the community. The effort is estimated according to the roadmap established during project conception. Based on the milestone plans maintained in Gitlab, we hold biweekly video meetings to coordinate the efforts.

How will software development roles be assigned?

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.

How you will track who is doing what and when it needs to be done by?

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.

What software development model will you use?

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.

How you will manage releases of your software or updates to your services?

Releases are scheduled when new features are ready (major version) and bugs are fixed (minor version). After pass the test suite, a release can be initiated by assigning a git tag. The release process itself is automated with continuous integration pipelines.

How will you ensure that information is not lost when a developer leaves?

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).

How often will you review and revise your Software Management Plan?

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.

Engaging with your users

How will you promote what your software does and who has used it?

We will disseminate the software and promote its use by:

  • Maintaining the openCARP.org webpage with an introduction to the software and support channels.
  • Publishing a paper to introduce openCARP with a focus on usability.
  • Regularly publishing papers and presenting research based on openCARP at national and international conferences and workshops.
  • Organizing user workshops to train new openCARP users and discuss and engage with the user community.
  • Being active on social media platforms (e.g. #openCARP on Twitter)

Unique selling points of openCARP that will likely attract additional users are in particular:

  • Reproducibility by providing a one-step workflow and creating a repository to share in silico experiments.
  • Video tutorials that guide new users and show the full potential of the software based on examples.
  • Comprehensive user documentation covering all features of openCARP.
  • Developer documentation to ease functionality extension and software maintenance.

How you will support your users when they ask for help?

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.

How will your users be able to contribute to your software?

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.

Intellectual property, copyright and licensing

Who will own the copyright of your software?

The copyright is owned by NumeriCor. Contributions to the software are subject to the Contributor license agreement.

What license will you choose?

The license is the Academic Public License (openCARP, v1.0). For more details on the license please visit the openCARP license webpage.

Where will you publish your copyright and license?

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.

Preserving your software

Do you have a preservation plan?

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.

Where can you deposit your software for long-term preservation?

As part of the SuLMaSS project, SCC at KIT develops a mechanism to automatically build submission information packages for release version of openCARP and store them in the long-term bwDataArchive.

Attribution

The openCARP software management plan was inspired by the SMP guide of the UK Software Sustainability Institute.

© Copyright 2020 openCARP project    Supported by DFG    Contact    Imprint and data protection